| 1 |
/* ============================================================ |
| 2 |
* |
| 3 |
* This file is a part of digiKam project |
| 4 |
* https://www.digikam.org |
| 5 |
* |
| 6 |
* Date : 2007-06-05 |
| 7 |
* Description : Thumbnail loading |
| 8 |
* |
| 9 |
* SPDX-FileCopyrightText: 2006-2011 by Marcel Wiesweg <marcel dot wiesweg at gmx dot de> |
| 10 |
* SPDX-FileCopyrightText: 2008-2026 by Gilles Caulier <caulier dot gilles at gmail dot com> |
| 11 |
* |
| 12 |
* SPDX-License-Identifier: GPL-2.0-or-later |
| 13 |
* |
| 14 |
* ============================================================ */ |
| 15 |
|
| 16 |
#pragma once |
| 17 |
|
| 18 |
// Qt includes |
| 19 |
|
| 20 |
#include <QPixmap> |
| 21 |
#include <QImage> |
| 22 |
|
| 23 |
// Local includes |
| 24 |
|
| 25 |
#include "managedloadsavethread.h" |
| 26 |
#include "thumbnailinfo.h" |
| 27 |
|
| 28 |
namespace Digikam |
| 29 |
{ |
| 30 |
|
| 31 |
class DbEngineParameters; |
| 32 |
class ThumbnailCreator; |
| 33 |
class ThumbnailInfoProvider; |
| 34 |
|
| 35 |
class DIGIKAM_EXPORT ThumbnailLoadThread : public ManagedLoadSaveThread |
| 36 |
{ |
| 37 |
Q_OBJECT |
| 38 |
|
| 39 |
public: |
| 40 |
|
| 41 |
explicit ThumbnailLoadThread(QObject* const parent = nullptr); |
| 42 |
~ThumbnailLoadThread() override; |
| 43 |
|
| 44 |
/** |
| 45 |
* Return application-wide default thumbnail threads. |
| 46 |
* It is perfectly all right to create an extra object of the class, |
| 47 |
* but it is useful to have default object |
| 48 |
*/ |
| 49 |
static ThumbnailLoadThread* defaultThread(); |
| 50 |
static ThumbnailLoadThread* defaultIconViewThread(); |
| 51 |
|
| 52 |
static void cleanUp(); |
| 53 |
|
| 54 |
/** |
| 55 |
* Disable storing thumbnails in the disk cache. |
| 56 |
* This shall be called once at application startup. |
| 57 |
* This need not be called, then the FreeDesktop standard is used. |
| 58 |
*/ |
| 59 |
static void initializeNoThumbnailStorage(); |
| 60 |
|
| 61 |
/** |
| 62 |
* Enable loading of thumbnails from a thumbnail database. |
| 63 |
* This shall be called once at application startup. |
| 64 |
* This need not be called, then the FreeDesktop standard is used. |
| 65 |
* You can optionally provide a thumbnail info provider. |
| 66 |
*/ |
| 67 |
static void initializeThumbnailDatabase(const DbEngineParameters& params, ThumbnailInfoProvider* const provider = nullptr); |
| 68 |
|
| 69 |
/** |
| 70 |
* For color management, this sets the widget the thumbnails will be color managed for. |
| 71 |
* (currently it is only possible to set one global widget) |
| 72 |
*/ |
| 73 |
static void setDisplayingWidget(QWidget* const widget); |
| 74 |
|
| 75 |
/** |
| 76 |
* Find a thumbnail. |
| 77 |
* If the pixmap is found in the cache, returns true and sets pixmap |
| 78 |
* to the found QPixmap. |
| 79 |
* If the pixmap is not found in the cache, load() is called to start the loading process, |
| 80 |
* false is returned and pixmap is not touched. |
| 81 |
*/ |
| 82 |
bool find(const ThumbnailIdentifier& identifier, QPixmap& pixmap); |
| 83 |
|
| 84 |
/** |
| 85 |
* Same as above, but does not use the global size, but an extra specified size. |
| 86 |
*/ |
| 87 |
bool find(const ThumbnailIdentifier& identifier, |
| 88 |
QPixmap& pixmap, int size, bool onlyStorage = false); |
| 89 |
|
| 90 |
/** |
| 91 |
* Find a thumbnail. |
| 92 |
* This method sends the signals and does not return values like the method above. |
| 93 |
* If you certainly need asynchronous return, connect with Qt::QueuedConnection to the signals. |
| 94 |
* If you connect directly, the signals may be sent from within the method call. |
| 95 |
*/ |
| 96 |
void find(const ThumbnailIdentifier& identifier); |
| 97 |
|
| 98 |
/** |
| 99 |
* Same as above, but does not use the global size, but an extra specified size. |
| 100 |
*/ |
| 101 |
void find(const ThumbnailIdentifier& identifier, int size); |
| 102 |
|
| 103 |
/** |
| 104 |
* Find a group of thumbnails. The items will be loaded in order and signals will be sent. |
| 105 |
* Can be used to ensure that thumbnails are loaded in a particular order. |
| 106 |
* |
| 107 |
* @note: the signal signalThumbnailLoaded() is only fired once, after it has been loaded, this behavior is intentional. |
| 108 |
* On all subsequent attempts, during the conversion from ThumbnailIdentifier to LoadingDescription, it checks whether the |
| 109 |
* thumbnail is already in the cache. The load request is then discarded. |
| 110 |
*/ |
| 111 |
void findGroup(QList<ThumbnailIdentifier>& identifiers); |
| 112 |
void findGroup(QList<ThumbnailIdentifier>& identifiers, int size); |
| 113 |
|
| 114 |
/** |
| 115 |
* All tastes of find() methods, for loading the thumbnail of a detail |
| 116 |
*/ |
| 117 |
bool find(const ThumbnailIdentifier& identifier, const QRect& rect, QPixmap& pixmap); |
| 118 |
bool find(const ThumbnailIdentifier& identifier, |
| 119 |
const QRect& rect, QPixmap& pixmap, int size, bool onlyStorage = false); |
| 120 |
void find(const ThumbnailIdentifier& identifier, const QRect& rect); |
| 121 |
void find(const ThumbnailIdentifier& identifier, const QRect& rect, int size); |
| 122 |
void findGroup(const QList<QPair<ThumbnailIdentifier, QRect> >& filePathAndRects); |
| 123 |
void findGroup(const QList<QPair<ThumbnailIdentifier, QRect> >& filePathsAndRects, int size); |
| 124 |
|
| 125 |
/** |
| 126 |
* Find the thumbnail pixmap in the buffered cache to |
| 127 |
* avoid flickering while loading a new thumbnail. |
| 128 |
*/ |
| 129 |
bool findBuffered(const ThumbnailIdentifier& identifier, |
| 130 |
const QRect& rect, QPixmap& pixmap, int size); |
| 131 |
|
| 132 |
/** |
| 133 |
* Preload the thumbnail or thumbnail group. |
| 134 |
* This is essentially the same as loading, but with a lower priority. |
| 135 |
*/ |
| 136 |
void preload(const ThumbnailIdentifier& identifier); |
| 137 |
void preload(const ThumbnailIdentifier& identifier, int size); |
| 138 |
void preloadGroup(QList<ThumbnailIdentifier>& identifiers); |
| 139 |
void preloadGroup(QList<ThumbnailIdentifier>& identifiers, int size); |
| 140 |
|
| 141 |
/** |
| 142 |
* Pregenerate the thumbnail group. |
| 143 |
* No signals will be emitted when these are loaded. |
| 144 |
*/ |
| 145 |
void pregenerateGroup(const QList<ThumbnailIdentifier>& identifiers); |
| 146 |
void pregenerateGroup(const QList<ThumbnailIdentifier>& identifiers, int size); |
| 147 |
|
| 148 |
/** |
| 149 |
* Load a thumbnail. |
| 150 |
* You do not need to use this method directly, it will not access the pixmap cache. Use find(). |
| 151 |
* The LoadingDescription shall be constructed with the constructor for preview/thumbnail jobs. |
| 152 |
* (in the description constructor, you need to specify file path, thumbnail size and Exif rotation) |
| 153 |
*/ |
| 154 |
void load(const LoadingDescription& description) override; |
| 155 |
|
| 156 |
/** |
| 157 |
* Returns the descriptions used by the last call to any of the above methods. |
| 158 |
* After calling single-thumbnail methods (find, preload) the list will have size 1, |
| 159 |
* after the group methods (findGroup, preloadGroup, pregenerateGroup) the list can |
| 160 |
* be larger than 1. |
| 161 |
* There is no information if the description was ever scheduled in the thread, |
| 162 |
* already processed, skipped or canceled. |
| 163 |
*/ |
| 164 |
QList<LoadingDescription> lastDescriptions() const; |
| 165 |
|
| 166 |
/** |
| 167 |
* @note If the thread is currently loading thumbnails, there is no guarantee as to when |
| 168 |
* the property change by one of the following methods takes effect. |
| 169 |
*/ |
| 170 |
|
| 171 |
/** |
| 172 |
* Set the requested thumbnail size. |
| 173 |
* Default value: 128 |
| 174 |
*/ |
| 175 |
void setThumbnailSize(int size, bool forFace = false); |
| 176 |
|
| 177 |
/** |
| 178 |
* Returns the maximum possible size of a thumbnail. |
| 179 |
* If you request a larger size, the thumbnail will not load. |
| 180 |
* The size of the pixmap can slightly differ, especially when highlighting. |
| 181 |
*/ |
| 182 |
static int maximumThumbnailSize(); |
| 183 |
static int maximumThumbnailPixmapSize(bool withHighlighting); |
| 184 |
|
| 185 |
/** |
| 186 |
* If you enable this, the signal thumbnailLoaded(LoadingDescription, QPixmap) will be emitted. |
| 187 |
* If you do not enable this, only the QImage-based signal (see LoadSaveThread) will be emitted. |
| 188 |
* |
| 189 |
* If you disable this, pay attention to the (global) setting of the LoadingCache, which per default |
| 190 |
* does not cache the images !! |
| 191 |
* |
| 192 |
* Default value: Enabled. |
| 193 |
*/ |
| 194 |
void setPixmapRequested(bool wantPixmap); |
| 195 |
|
| 196 |
/** |
| 197 |
* If you enable this, a highlighting border will be drawn around the pixmap. |
| 198 |
* This option has only an effect if pixmapRequested is true. |
| 199 |
* Default value: Enabled. |
| 200 |
*/ |
| 201 |
void setHighlightPixmap(bool highlight); |
| 202 |
|
| 203 |
/** |
| 204 |
* Computes the pixmap size for the give thumbnail size. |
| 205 |
* These can differ when highlighting is turned on. |
| 206 |
*/ |
| 207 |
int thumbnailToPixmapSize(int size) const; |
| 208 |
static int thumbnailToPixmapSize(bool withHighlight, int size); |
| 209 |
|
| 210 |
/** |
| 211 |
* Computes the thumbnail size for the give pixmap size. |
| 212 |
*/ |
| 213 |
int pixmapToThumbnailSize(int size) const; |
| 214 |
|
| 215 |
/** |
| 216 |
* If you enable this, the thread will try hard to send a pixmap if thumbnail loading failed. |
| 217 |
* It will use standard system icons to replace the real thumbnail. |
| 218 |
* If you disable this, a null QPixmap will be sent. |
| 219 |
* This does not influence the QImage-based signal; this signal will be emitted with a null |
| 220 |
* QImage regardless of this setting here, if the loading failed. |
| 221 |
* Default value: Enabled. |
| 222 |
*/ |
| 223 |
void setSendSurrogatePixmap(bool send); |
| 224 |
|
| 225 |
/** |
| 226 |
* Stores the given detail thumbnail on disk. |
| 227 |
* Use this if possible because generation of detail thumbnails |
| 228 |
* is potentially slower. |
| 229 |
* The image should at least have storedSize(). |
| 230 |
*/ |
| 231 |
void storeDetailThumbnail(const QString& filePath, |
| 232 |
const QRect& detailRect, |
| 233 |
const QImage& image, |
| 234 |
bool isFace = false); |
| 235 |
int storedSize() const; |
| 236 |
|
| 237 |
/** |
| 238 |
* This is a tool to force regeneration of thumbnails. |
| 239 |
* All thumbnail files for the given file will be removed from disk, |
| 240 |
* and the cached instances will be removed as well. |
| 241 |
* Use this method if you know that the contents of the file has changed. |
| 242 |
* This method works independently from the multithreaded thumbnail loading. |
| 243 |
*/ |
| 244 |
static void deleteThumbnail(const QString& filePath); |
| 245 |
|
| 246 |
Q_SIGNALS: |
| 247 |
|
| 248 |
/// @note See LoadSaveThread for a QImage-based thumbnailLoaded() signal. |
| 249 |
void signalThumbnailLoaded(const LoadingDescription& loadingDescription, const QPixmap& pix); |
| 250 |
|
| 251 |
public: |
| 252 |
|
| 253 |
/// @note For internal use - may only be used from the thread |
| 254 |
ThumbnailCreator* thumbnailCreator() const; |
| 255 |
|
| 256 |
protected: |
| 257 |
|
| 258 |
void thumbnailLoaded(const LoadingDescription& loadingDescription, const QImage& img) override; |
| 259 |
|
| 260 |
private: |
| 261 |
|
| 262 |
bool find(const ThumbnailIdentifier& identifier, int size, QPixmap* retPixmap, |
| 263 |
bool emitSignal, const QRect& detailRect, bool onlyStorage = false); |
| 264 |
void load(const LoadingDescription& description, bool pregenerate); |
| 265 |
bool checkSize(int size); |
| 266 |
QPixmap surrogatePixmap(const LoadingDescription& loadingDescription); |
| 267 |
|
| 268 |
Q_SIGNALS: |
| 269 |
|
| 270 |
/// @note For internal use only. |
| 271 |
void thumbnailsAvailable(); |
| 272 |
void ThumbnailLoaded(const LoadingDescription&, const QImage&); |
| 273 |
|
| 274 |
private Q_SLOTS: |
| 275 |
|
| 276 |
void slotThumbnailsAvailable(); |
| 277 |
void slotThumbnailLoaded(const LoadingDescription&, const QImage&); |
| 278 |
|
| 279 |
private: |
| 280 |
|
| 281 |
/// @note disabled |
| 282 |
ThumbnailLoadThread(const ThumbnailLoadThread&) = delete; |
| 283 |
ThumbnailLoadThread& operator=(const ThumbnailLoadThread&) = delete; |
| 284 |
|
| 285 |
private: |
| 286 |
|
| 287 |
class Private; |
| 288 |
Private* const d = nullptr; |
| 289 |
}; |
| 290 |
|
| 291 |
// -------------------------------------------------------------------------------------------------- |
| 292 |
|
| 293 |
class DIGIKAM_EXPORT ThumbnailImageCatcher : public QObject |
| 294 |
{ |
| 295 |
Q_OBJECT |
| 296 |
|
| 297 |
public: |
| 298 |
|
| 299 |
/** |
| 300 |
* Use this class to get a thumbnail synchronously. |
| 301 |
* 1. Create the ThumbnailImageCatcher object with your ThumbnailLoadThread |
| 302 |
* 2. a) Request a thumbnail |
| 303 |
* b) Call enqueue() |
| 304 |
* 3. Call waitForThumbnails which returns the thumbnail QImage(s). |
| 305 |
* |
| 306 |
* Note: Not meant for loading QPixmap thumbnails. |
| 307 |
*/ |
| 308 |
|
| 309 |
explicit ThumbnailImageCatcher(QObject* const parent = nullptr); |
| 310 |
explicit ThumbnailImageCatcher(ThumbnailLoadThread* const thread, |
| 311 |
QObject* const parent = nullptr); |
| 312 |
~ThumbnailImageCatcher() override; |
| 313 |
|
| 314 |
ThumbnailLoadThread* thread() const; |
| 315 |
void setThumbnailLoadThread(ThumbnailLoadThread* const thread); |
| 316 |
|
| 317 |
/** |
| 318 |
* After requesting a thumbnail from the thread, call enqueue() |
| 319 |
* each time. Enqueue records the requested loading operation in an internal list. |
| 320 |
* A loading operation can result in the return of more than one thumbnail, |
| 321 |
* so enqueue() returns the number of expected results. |
| 322 |
* Then call waitForThumbnails. The returned list is the sum of previous calls |
| 323 |
* to enqueue, one entry per expected result, in order. |
| 324 |
* If stopped prematurely or loading failed, the respective entries will be null. |
| 325 |
*/ |
| 326 |
int enqueue(); |
| 327 |
QList<QImage> waitForThumbnails(); |
| 328 |
|
| 329 |
public Q_SLOTS: |
| 330 |
|
| 331 |
/** |
| 332 |
* The catcher is active per default after construction. |
| 333 |
* Deactivate it if you use the catcher as a longer-lived |
| 334 |
* object and do not use it for some time, |
| 335 |
* then activate it before you request a thumbnail from the thread again. |
| 336 |
*/ |
| 337 |
void setActive(bool active); |
| 338 |
|
| 339 |
/** |
| 340 |
* If the catcher is waiting in waitForThumbnails() in a different thread, |
| 341 |
* cancels the waiting. The results will be returned as received so far. |
| 342 |
*/ |
| 343 |
void cancel(); |
| 344 |
|
| 345 |
protected Q_SLOTS: |
| 346 |
|
| 347 |
void slotThumbnailLoaded(const LoadingDescription&, const QImage&); |
| 348 |
|
| 349 |
private: |
| 350 |
|
| 351 |
/// @note disabled |
| 352 |
ThumbnailImageCatcher(const ThumbnailImageCatcher&) = delete; |
| 353 |
ThumbnailImageCatcher& operator=(const ThumbnailImageCatcher&) = delete; |
| 354 |
|
| 355 |
private: |
| 356 |
|
| 357 |
class Private; |
| 358 |
Private* const d = nullptr; |
| 359 |
}; |
| 360 |
|
| 361 |
} // namespace Digikam |