Development/Tutorials/KPixmapCache: Difference between revisions

From KDE TechBase
(add tutorial for KPixmapCache)
 
(Mark for archiving, add warning)
 
(10 intermediate revisions by 7 users not shown)
Line 1: Line 1:
{{Archived}}
{{Warning|From the [https://api.kde.org/frameworks/kdelibs4support/html/deprecated.html#_deprecated000280 KPixmapCache apidocs]:<br />
KPixmapCache is susceptible to various non-trivial locking bugs and inefficiencies, and is supported for backward compatibility only (since it exposes a {{qt|QDataStream}} API for subclasses). Users should port to KImageCache for a very close work-alike, or {{class|KSharedDataCache}} if they need more control}}
== Introduction ==
== Introduction ==
KPixmapCache provides disk-caching of QPixmaps. If you're using SVGs or generating pixmaps from some data, you might consider using it as it eliminates the need to generate the same pixmaps over and over again.
{{class|KPixmapCache}} provides disk-caching of QPixmaps. If you're using SVGs or generating pixmaps from some data, you might consider using it as it eliminates the need to generate the same pixmaps over and over again.


== Using it ==
== Using it ==
=== Creating the cache object ===
=== Creating the cache object ===
It's API is similar to that of the QPixmapCache.
Its API is similar to that of the QPixmapCache.
To use it, you first need to create the cache object, using a unique name:
To use it, you first need to create the cache object, using a unique name:
<code cppqt>
<syntaxhighlight lang="cpp-qt">
KPixmapCache* cache = new KPixmapCache("myapp-images");
KPixmapCache* cache = new KPixmapCache("myapp-images");
</code>
</syntaxhighlight>


=== Inserting and finding pixmaps ===
=== Inserting and finding pixmaps ===
Once that is done you can easily retrieve and insert images with insert() and find() methods:
Once that is done you can easily retrieve and insert images with insert() and find() methods:
<code cppqt>
<syntaxhighlight lang="cpp-qt">
QPixmap pix("file1.png");
QPixmap pix("file1.png");
cache->insert("file1.png", pix);
cache->insert("file1.png", pix);
Line 25: Line 29:
     cache->insert("file2.png", pix2);
     cache->insert("file2.png", pix2);
}
}
</code>
</syntaxhighlight>


=== The Easy Way ===
=== The Easy Way ===
As loading pixmaps from files with the aid of cache is a very common operation, KPixmapCache provides a convenience method for that:
As loading pixmaps from files with the aid of cache is a very common operation, KPixmapCache provides a convenience method for that:
<code cppqt>
<syntaxhighlight lang="cpp-qt">
QString filename("myfile.png");
QString filename("myfile.png");
QPixmap pix = cache->loadFromFile(filename);
QPixmap pix = cache->loadFromFile(filename);
</code>
</syntaxhighlight>
This first checks if the given file is in the cache. If it is, it's loaded from the cache, otherwise it's loaded from the file and inserted into cache.
This first checks if the given file is in the cache. If it is, it's loaded from the cache, otherwise it's loaded from the file and inserted into cache.


Similar method is provided for loading SVG files:
Similar method is provided for loading SVG files:
<code cppqt>
<syntaxhighlight lang="cpp-qt">
QString filename("myfile.svg");
QString filename("myfile.svg");
QPixmap pix = cache->loadFromSVG(filename);
QPixmap pix = cache->loadFromSvg(filename);
</code>
</syntaxhighlight>
This renders contents of the SVG file onto pixmap, using SVG's default size by default. If you need a different size, you can specify it as the second argument of that method:
This renders contents of the SVG file onto pixmap, using SVG's default size by default. If you need a different size, you can specify it as the second argument of that method:
<code cppqt>
<syntaxhighlight lang="cpp-qt">
QString filename("myfile.svg");
QString filename("myfile.svg");
QSize size(150, 250);
QSize size(150, 250);
QPixmap pix = cache->loadFromSVG(filename);
QPixmap pix = cache->loadFromSvg(filename, size);
</code>
</syntaxhighlight>
This renders the SVG onto a pixmap with the size of 150x250 pixels.
This renders the SVG onto a pixmap with the size of 150x250 pixels.


Line 52: Line 56:
Often you need to make sure the cache is up-to-date and you're not using obsolete pixmaps. For this, the cache provides timestamp() method. By default it returns time when the cache was created, but you can set your own timestamp with setTimestamp() method.
Often you need to make sure the cache is up-to-date and you're not using obsolete pixmaps. For this, the cache provides timestamp() method. By default it returns time when the cache was created, but you can set your own timestamp with setTimestamp() method.


<code cppqt>
<syntaxhighlight lang="cpp-qt">
// Our data
// Our data
MyDataObject data;
MyDataObject data;
// Make sure the cache is up to date
if (cache->timestamp() < data.timestamp()) {
if (cache->timestamp() < data.timestamp()) {
     // Cache is obsolete, delete and reinitialize it
     // Data is newer than the cache
    // Thus the cache is obsolete, delete and reinitialize it
     cache->discard();
     cache->discard();
}
}
Line 70: Line 76:
}
}
// Show the visualizedData pixmap to user
// Show the visualizedData pixmap to user
</code>
</syntaxhighlight>
This example creates a visual representation of some data. If the data is more recent than the cache, then contents of the cache are deleted using the discard() method. Next, we check if cache already contains the necessary pixmap. If it does, then there is no need to recreate it from the data (which might be expensive).
This example creates a visual representation of some data. If the data is more recent than the cache, then contents of the cache are deleted using the discard() method. Next, we check if cache already contains the necessary pixmap. If it does, then there is no need to recreate it from the data (which might be expensive).


=== API docs ===
=== API docs ===
For a list of all KPixmapCache methods, check out it's [http://api.kde.org/classmapper.php?class=KPixmapCache&module=kdelibs&version=4.0 API docs].
For a list of all KPixmapCache methods, check out its [http://api.kde.org/classmapper.php?class=KPixmapCache&module=kdelibs&version=4.0 API docs].

Latest revision as of 14:42, 31 May 2019


This page has been archived
The information on this page is outdated or no longer in use but is kept for historical purposes. Please see the Category:Archives for similar pages.
Warning
From the KPixmapCache apidocs:
KPixmapCache is susceptible to various non-trivial locking bugs and inefficiencies, and is supported for backward compatibility only (since it exposes a QDataStream API for subclasses). Users should port to KImageCache for a very close work-alike, or KSharedDataCache if they need more control


Introduction

KPixmapCache provides disk-caching of QPixmaps. If you're using SVGs or generating pixmaps from some data, you might consider using it as it eliminates the need to generate the same pixmaps over and over again.

Using it

Creating the cache object

Its API is similar to that of the QPixmapCache. To use it, you first need to create the cache object, using a unique name:

KPixmapCache* cache = new KPixmapCache("myapp-images");

Inserting and finding pixmaps

Once that is done you can easily retrieve and insert images with insert() and find() methods:

QPixmap pix("file1.png");
cache->insert("file1.png", pix);

QPixmap pix2;
if (cache->find("file2.png", pix2)) {
    // The pixmap was loaded from cache.
} else {
    // Pixmap was not found in the cache.
    // Load and insert it:
    pix2 = QPixmap("file2.png");
    cache->insert("file2.png", pix2);
}

The Easy Way

As loading pixmaps from files with the aid of cache is a very common operation, KPixmapCache provides a convenience method for that:

QString filename("myfile.png");
QPixmap pix = cache->loadFromFile(filename);

This first checks if the given file is in the cache. If it is, it's loaded from the cache, otherwise it's loaded from the file and inserted into cache.

Similar method is provided for loading SVG files:

QString filename("myfile.svg");
QPixmap pix = cache->loadFromSvg(filename);

This renders contents of the SVG file onto pixmap, using SVG's default size by default. If you need a different size, you can specify it as the second argument of that method:

QString filename("myfile.svg");
QSize size(150, 250);
QPixmap pix = cache->loadFromSvg(filename, size);

This renders the SVG onto a pixmap with the size of 150x250 pixels.


Timestamps

Often you need to make sure the cache is up-to-date and you're not using obsolete pixmaps. For this, the cache provides timestamp() method. By default it returns time when the cache was created, but you can set your own timestamp with setTimestamp() method.

// Our data
MyDataObject data;
// Make sure the cache is up to date
if (cache->timestamp() < data.timestamp()) {
    // Data is newer than the cache
    // Thus the cache is obsolete, delete and reinitialize it
    cache->discard();
}
// Here the cache is always recent enough
QPixmap visualizedData;
QString key("data-visualization");
// Try to find the visualization from the cache
if (!cache->find(key, visualizedData)) {
    // Visualization is not in the cache, recreate it...
    visualizedData = createVisualization(data);
    // ...and put the resulting image into cache
    cache->insert(key, visualizedData);
}
// Show the visualizedData pixmap to user

This example creates a visual representation of some data. If the data is more recent than the cache, then contents of the cache are deleted using the discard() method. Next, we check if cache already contains the necessary pixmap. If it does, then there is no need to recreate it from the data (which might be expensive).

API docs

For a list of all KPixmapCache methods, check out its API docs.