|
1 /**************************************************************************** |
|
2 ** |
|
3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). |
|
4 ** All rights reserved. |
|
5 ** Contact: Nokia Corporation (qt-info@nokia.com) |
|
6 ** |
|
7 ** This file is part of the QtGui module of the Qt Toolkit. |
|
8 ** |
|
9 ** $QT_BEGIN_LICENSE:LGPL$ |
|
10 ** No Commercial Usage |
|
11 ** This file contains pre-release code and may not be distributed. |
|
12 ** You may use this file in accordance with the terms and conditions |
|
13 ** contained in the Technology Preview License Agreement accompanying |
|
14 ** this package. |
|
15 ** |
|
16 ** GNU Lesser General Public License Usage |
|
17 ** Alternatively, this file may be used under the terms of the GNU Lesser |
|
18 ** General Public License version 2.1 as published by the Free Software |
|
19 ** Foundation and appearing in the file LICENSE.LGPL included in the |
|
20 ** packaging of this file. Please review the following information to |
|
21 ** ensure the GNU Lesser General Public License version 2.1 requirements |
|
22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. |
|
23 ** |
|
24 ** In addition, as a special exception, Nokia gives you certain additional |
|
25 ** rights. These rights are described in the Nokia Qt LGPL Exception |
|
26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. |
|
27 ** |
|
28 ** If you have questions regarding the use of this file, please contact |
|
29 ** Nokia at qt-info@nokia.com. |
|
30 ** |
|
31 ** |
|
32 ** |
|
33 ** |
|
34 ** |
|
35 ** |
|
36 ** |
|
37 ** |
|
38 ** $QT_END_LICENSE$ |
|
39 ** |
|
40 ****************************************************************************/ |
|
41 |
|
42 /*! |
|
43 \class QImageIOHandler |
|
44 \brief The QImageIOHandler class defines the common image I/O |
|
45 interface for all image formats in Qt. |
|
46 \reentrant |
|
47 |
|
48 Qt uses QImageIOHandler for reading and writing images through |
|
49 QImageReader and QImageWriter. You can also derive from this class |
|
50 to write your own image format handler using Qt's plugin mechanism. |
|
51 |
|
52 Call setDevice() to assign a device to the handler, and |
|
53 setFormat() to assign a format to it. One QImageIOHandler may |
|
54 support more than one image format. canRead() returns true if an |
|
55 image can be read from the device, and read() and write() return |
|
56 true if reading or writing an image was completed successfully. |
|
57 |
|
58 QImageIOHandler also has support for animations formats, through |
|
59 the functions loopCount(), imageCount(), nextImageDelay() and |
|
60 currentImageNumber(). |
|
61 |
|
62 In order to determine what options an image handler supports, Qt |
|
63 will call supportsOption() and setOption(). Make sure to |
|
64 reimplement these functions if you can provide support for any of |
|
65 the options in the ImageOption enum. |
|
66 |
|
67 To write your own image handler, you must at least reimplement |
|
68 canRead() and read(). Then create a QImageIOPlugin that |
|
69 can create the handler. Finally, install your plugin, and |
|
70 QImageReader and QImageWriter will then automatically load the |
|
71 plugin, and start using it. |
|
72 |
|
73 \sa QImageIOPlugin, QImageReader, QImageWriter |
|
74 */ |
|
75 |
|
76 /*! \enum QImageIOHandler::ImageOption |
|
77 |
|
78 This enum describes the different options supported by |
|
79 QImageIOHandler. Some options are used to query an image for |
|
80 properties, and others are used to toggle the way in which an |
|
81 image should be written. |
|
82 |
|
83 \value Size The original size of an image. A handler that supports |
|
84 this option is expected to read the size of the image from the |
|
85 image metadata, and return this size from option() as a QSize. |
|
86 |
|
87 \value ClipRect The clip rect, or ROI (Region Of Interest). A |
|
88 handler that supports this option is expected to only read the |
|
89 provided QRect area from the original image in read(), before any |
|
90 other transformation is applied. |
|
91 |
|
92 \value ScaledSize The scaled size of the image. A handler that |
|
93 supports this option is expected to scale the image to the |
|
94 provided size (a QSize), after applying any clip rect |
|
95 transformation (ClipRect). If the handler does not support this |
|
96 option, QImageReader will perform the scaling after the image has |
|
97 been read. |
|
98 |
|
99 \value ScaledClipRect The scaled clip rect (or ROI, Region Of |
|
100 Interest) of the image. A handler that supports this option is |
|
101 expected to apply the provided clip rect (a QRect), after applying |
|
102 any scaling (ScaleSize) or regular clipping (ClipRect). If the |
|
103 handler does not support this option, QImageReader will apply the |
|
104 scaled clip rect after the image has been read. |
|
105 |
|
106 \value Description The image description. Some image formats, |
|
107 such as GIF and PNG, allow embedding of text |
|
108 or comments into the image data (e.g., for storing copyright |
|
109 information). It's common that the text is stored in key-value |
|
110 pairs, but some formats store all text in one continuous block. |
|
111 QImageIOHandler returns the text as one |
|
112 QString, where keys and values are separated by a ':', and |
|
113 keys-value pairs are separated by two newlines (\\n\\n). For example, |
|
114 "Title: Sunset\\n\\nAuthor: Jim Smith\\nSarah Jones\\n\\n". Formats that |
|
115 store text in a single block can use "Description" as the key. |
|
116 |
|
117 \value CompressionRatio The compression ratio of the image data. A |
|
118 handler that supports this option is expected to set its |
|
119 compression rate depending on the value of this option (an int) |
|
120 when writing. |
|
121 |
|
122 \value Gamma The gamma level of the image. A handler that supports |
|
123 this option is expected to set the image gamma level depending on |
|
124 the value of this option (a float) when writing. |
|
125 |
|
126 \value Quality The quality level of the image. A handler that |
|
127 supports this option is expected to set the image quality level |
|
128 depending on the value of this option (an int) when writing. |
|
129 |
|
130 \value Name The name of the image. A handler that supports this |
|
131 option is expected to read the name from the image metadata and |
|
132 return this as a QString, or when writing an image it is expected |
|
133 to store the name in the image metadata. |
|
134 |
|
135 \value SubType The subtype of the image. A handler that supports |
|
136 this option can use the subtype value to help when reading and |
|
137 writing images. For example, a PPM handler may have a subtype |
|
138 value of "ppm" or "ppmraw". |
|
139 |
|
140 \value IncrementalReading A handler that supports this option is |
|
141 expected to read the image in several passes, as if it was an |
|
142 animation. QImageReader will treat the image as an animation. |
|
143 |
|
144 \value Endianness The endianness of the image. Certain image |
|
145 formats can be stored as BigEndian or LittleEndian. A handler that |
|
146 supports Endianness uses the value of this option to determine how |
|
147 the image should be stored. |
|
148 |
|
149 \value Animation Image formats that support animation return |
|
150 true for this value in supportsOption(); otherwise, false is returned. |
|
151 |
|
152 \value BackgroundColor Certain image formats allow the |
|
153 background color to be specified. A handler that supports |
|
154 BackgroundColor initializes the background color to this option |
|
155 (a QColor) when reading an image. |
|
156 |
|
157 \value ImageFormat The image's data format returned by the handler. |
|
158 This can be any of the formats listed in QImage::Format. |
|
159 */ |
|
160 |
|
161 /*! |
|
162 \class QImageIOPlugin |
|
163 \brief The QImageIOPlugin class defines an interface for writing |
|
164 an image format plugin. |
|
165 \reentrant |
|
166 |
|
167 \ingroup plugins |
|
168 |
|
169 QImageIOPlugin is a factory for creating QImageIOHandler objects, |
|
170 which are used internally by QImageReader and QImageWriter to add |
|
171 support for different image formats to Qt. |
|
172 |
|
173 Writing an image I/O plugin is achieved by subclassing this |
|
174 base class, reimplementing the pure virtual functions capabilities(), |
|
175 create(), and keys(), and exporting the class with the |
|
176 Q_EXPORT_PLUGIN2() macro. See \l{How to Create Qt Plugins} for details. |
|
177 |
|
178 An image format plugin can support three capabilities: reading (\l |
|
179 CanRead), writing (\l CanWrite) and \e incremental reading (\l |
|
180 CanReadIncremental). Reimplement capabilities() in you subclass to |
|
181 expose the capabilities of your image format. |
|
182 |
|
183 create() should create an instance of your QImageIOHandler |
|
184 subclass, with the provided device and format properly set, and |
|
185 return this handler. You must also reimplement keys() so that Qt |
|
186 knows which image formats your plugin supports. |
|
187 |
|
188 Different plugins can support different capabilities. For example, |
|
189 you may have one plugin that supports reading the GIF format, and |
|
190 another that supports writing. Qt will select the correct plugin |
|
191 for the job, depending on the return value of capabilities(). If |
|
192 several plugins support the same capability, Qt will select one |
|
193 arbitrarily. |
|
194 |
|
195 \sa QImageIOHandler, {How to Create Qt Plugins} |
|
196 */ |
|
197 |
|
198 /*! |
|
199 \enum QImageIOPlugin::Capability |
|
200 |
|
201 This enum describes the capabilities of a QImageIOPlugin. |
|
202 |
|
203 \value CanRead The plugin can read images. |
|
204 \value CanWrite The plugin can write images. |
|
205 \value CanReadIncremental The plugin can read images incrementally. |
|
206 */ |
|
207 |
|
208 /*! |
|
209 \class QImageIOHandlerFactoryInterface |
|
210 \brief The QImageIOHandlerFactoryInterface class provides the factory |
|
211 interface for QImageIOPlugin. |
|
212 \reentrant |
|
213 |
|
214 \internal |
|
215 |
|
216 \sa QImageIOPlugin |
|
217 */ |
|
218 |
|
219 #include "qimageiohandler.h" |
|
220 |
|
221 #include <qbytearray.h> |
|
222 #include <qimage.h> |
|
223 #include <qvariant.h> |
|
224 |
|
225 QT_BEGIN_NAMESPACE |
|
226 |
|
227 class QIODevice; |
|
228 |
|
229 class QImageIOHandlerPrivate |
|
230 { |
|
231 Q_DECLARE_PUBLIC(QImageIOHandler) |
|
232 public: |
|
233 QImageIOHandlerPrivate(QImageIOHandler *q); |
|
234 virtual ~QImageIOHandlerPrivate(); |
|
235 |
|
236 QIODevice *device; |
|
237 mutable QByteArray format; |
|
238 |
|
239 QImageIOHandler *q_ptr; |
|
240 }; |
|
241 |
|
242 QImageIOHandlerPrivate::QImageIOHandlerPrivate(QImageIOHandler *q) |
|
243 { |
|
244 device = 0; |
|
245 q_ptr = q; |
|
246 } |
|
247 |
|
248 QImageIOHandlerPrivate::~QImageIOHandlerPrivate() |
|
249 { |
|
250 } |
|
251 |
|
252 /*! |
|
253 Constructs a QImageIOHandler object. |
|
254 */ |
|
255 QImageIOHandler::QImageIOHandler() |
|
256 : d_ptr(new QImageIOHandlerPrivate(this)) |
|
257 { |
|
258 } |
|
259 |
|
260 /*! \internal |
|
261 |
|
262 Constructs a QImageIOHandler object, using the private member \a |
|
263 dd. |
|
264 */ |
|
265 QImageIOHandler::QImageIOHandler(QImageIOHandlerPrivate &dd) |
|
266 : d_ptr(&dd) |
|
267 { |
|
268 } |
|
269 |
|
270 /*! |
|
271 Destructs the QImageIOHandler object. |
|
272 */ |
|
273 QImageIOHandler::~QImageIOHandler() |
|
274 { |
|
275 } |
|
276 |
|
277 /*! |
|
278 Sets the device of the QImageIOHandler to \a device. The image |
|
279 handler will use this device when reading and writing images. |
|
280 |
|
281 The device can only be set once and must be set before calling |
|
282 canRead(), read(), write(), etc. If you need to read multiple |
|
283 files, construct multiple instances of the appropriate |
|
284 QImageIOHandler subclass. |
|
285 |
|
286 \sa device() |
|
287 */ |
|
288 void QImageIOHandler::setDevice(QIODevice *device) |
|
289 { |
|
290 Q_D(QImageIOHandler); |
|
291 d->device = device; |
|
292 } |
|
293 |
|
294 /*! |
|
295 Returns the device currently assigned to the QImageIOHandler. If |
|
296 not device has been assigned, 0 is returned. |
|
297 */ |
|
298 QIODevice *QImageIOHandler::device() const |
|
299 { |
|
300 Q_D(const QImageIOHandler); |
|
301 return d->device; |
|
302 } |
|
303 |
|
304 /*! |
|
305 Sets the format of the QImageIOHandler to \a format. The format is |
|
306 most useful for handlers that support multiple image formats. |
|
307 |
|
308 \sa format() |
|
309 */ |
|
310 void QImageIOHandler::setFormat(const QByteArray &format) |
|
311 { |
|
312 Q_D(QImageIOHandler); |
|
313 d->format = format; |
|
314 } |
|
315 |
|
316 /*! |
|
317 Sets the format of the QImageIOHandler to \a format. The format is |
|
318 most useful for handlers that support multiple image formats. |
|
319 |
|
320 This function is declared const so that it can be called from canRead(). |
|
321 |
|
322 \sa format() |
|
323 */ |
|
324 void QImageIOHandler::setFormat(const QByteArray &format) const |
|
325 { |
|
326 Q_D(const QImageIOHandler); |
|
327 d->format = format; |
|
328 } |
|
329 |
|
330 /*! |
|
331 Returns the format that is currently assigned to |
|
332 QImageIOHandler. If no format has been assigned, an empty string |
|
333 is returned. |
|
334 |
|
335 \sa setFormat() |
|
336 */ |
|
337 QByteArray QImageIOHandler::format() const |
|
338 { |
|
339 Q_D(const QImageIOHandler); |
|
340 return d->format; |
|
341 } |
|
342 |
|
343 /*! |
|
344 \fn bool QImageIOHandler::read(QImage *image) |
|
345 |
|
346 Read an image from the device, and stores it in \a image. |
|
347 Returns true if the image is successfully read; otherwise returns |
|
348 false. |
|
349 |
|
350 For image formats that support incremental loading, and for animation |
|
351 formats, the image handler can assume that \a image points to the |
|
352 previous frame. |
|
353 |
|
354 \sa canRead() |
|
355 */ |
|
356 |
|
357 /*! |
|
358 \fn bool QImageIOHandler::canRead() const |
|
359 |
|
360 Returns true if an image can be read from the device (i.e., the |
|
361 image format is supported, the device can be read from and the |
|
362 initial header information suggests that the image can be read); |
|
363 otherwise returns false. |
|
364 |
|
365 When reimplementing canRead(), make sure that the I/O device |
|
366 (device()) is left in its original state (e.g., by using peek() |
|
367 rather than read()). |
|
368 |
|
369 \sa read(), QIODevice::peek() |
|
370 */ |
|
371 |
|
372 /*! |
|
373 \obsolete |
|
374 |
|
375 Use format() instead. |
|
376 */ |
|
377 |
|
378 QByteArray QImageIOHandler::name() const |
|
379 { |
|
380 return format(); |
|
381 } |
|
382 |
|
383 /*! |
|
384 Writes the image \a image to the assigned device. Returns true on |
|
385 success; otherwise returns false. |
|
386 |
|
387 The default implementation does nothing, and simply returns false. |
|
388 */ |
|
389 bool QImageIOHandler::write(const QImage &image) |
|
390 { |
|
391 Q_UNUSED(image); |
|
392 return false; |
|
393 } |
|
394 |
|
395 /*! |
|
396 Sets the option \a option with the value \a value. |
|
397 |
|
398 \sa option(), ImageOption |
|
399 */ |
|
400 void QImageIOHandler::setOption(ImageOption option, const QVariant &value) |
|
401 { |
|
402 Q_UNUSED(option); |
|
403 Q_UNUSED(value); |
|
404 } |
|
405 |
|
406 /*! |
|
407 Returns the value assigned to \a option as a QVariant. The type of |
|
408 the value depends on the option. For example, option(Size) returns |
|
409 a QSize variant. |
|
410 |
|
411 \sa setOption(), supportsOption() |
|
412 */ |
|
413 QVariant QImageIOHandler::option(ImageOption option) const |
|
414 { |
|
415 Q_UNUSED(option); |
|
416 return QVariant(); |
|
417 } |
|
418 |
|
419 /*! |
|
420 Returns true if the QImageIOHandler supports the option \a option; |
|
421 otherwise returns false. For example, if the QImageIOHandler |
|
422 supports the \l Size option, supportsOption(Size) must return |
|
423 true. |
|
424 |
|
425 \sa setOption(), option() |
|
426 */ |
|
427 bool QImageIOHandler::supportsOption(ImageOption option) const |
|
428 { |
|
429 Q_UNUSED(option); |
|
430 return false; |
|
431 } |
|
432 |
|
433 /*! |
|
434 For image formats that support animation, this function returns |
|
435 the sequence number of the current image in the animation. If |
|
436 this function is called before any image is read(), -1 is |
|
437 returned. The number of the first image in the sequence is 0. |
|
438 |
|
439 If the image format does not support animation, 0 is returned. |
|
440 |
|
441 \sa read() |
|
442 */ |
|
443 int QImageIOHandler::currentImageNumber() const |
|
444 { |
|
445 return 0; |
|
446 } |
|
447 |
|
448 /*! |
|
449 Returns the rect of the current image. If no rect is defined for the |
|
450 image, and empty QRect() is returned. |
|
451 |
|
452 This function is useful for animations, where only parts of the frame |
|
453 may be updated at a time. |
|
454 */ |
|
455 QRect QImageIOHandler::currentImageRect() const |
|
456 { |
|
457 return QRect(); |
|
458 } |
|
459 |
|
460 /*! |
|
461 For image formats that support animation, this function returns |
|
462 the number of images in the animation. If the image format does |
|
463 not support animation, or if it is unable to determine the number |
|
464 of images, 0 is returned. |
|
465 |
|
466 The default implementation returns 1 if canRead() returns true; |
|
467 otherwise 0 is returned. |
|
468 */ |
|
469 int QImageIOHandler::imageCount() const |
|
470 { |
|
471 return canRead() ? 1 : 0; |
|
472 } |
|
473 |
|
474 /*! |
|
475 For image formats that support animation, this function jumps to the |
|
476 next image. |
|
477 |
|
478 The default implementation does nothing, and returns false. |
|
479 */ |
|
480 bool QImageIOHandler::jumpToNextImage() |
|
481 { |
|
482 return false; |
|
483 } |
|
484 |
|
485 /*! |
|
486 For image formats that support animation, this function jumps to the image |
|
487 whose sequence number is \a imageNumber. The next call to read() will |
|
488 attempt to read this image. |
|
489 |
|
490 The default implementation does nothing, and returns false. |
|
491 */ |
|
492 bool QImageIOHandler::jumpToImage(int imageNumber) |
|
493 { |
|
494 Q_UNUSED(imageNumber); |
|
495 return false; |
|
496 } |
|
497 |
|
498 /*! |
|
499 For image formats that support animation, this function returns |
|
500 the number of times the animation should loop. If the image format |
|
501 does not support animation, 0 is returned. |
|
502 */ |
|
503 int QImageIOHandler::loopCount() const |
|
504 { |
|
505 return 0; |
|
506 } |
|
507 |
|
508 /*! |
|
509 For image formats that support animation, this function returns |
|
510 the number of milliseconds to wait until reading the next |
|
511 image. If the image format does not support animation, 0 is |
|
512 returned. |
|
513 */ |
|
514 int QImageIOHandler::nextImageDelay() const |
|
515 { |
|
516 return 0; |
|
517 } |
|
518 |
|
519 /*! |
|
520 Constructs an image plugin with the given \a parent. This is |
|
521 invoked automatically by the Q_EXPORT_PLUGIN2() macro. |
|
522 */ |
|
523 QImageIOPlugin::QImageIOPlugin(QObject *parent) |
|
524 : QObject(parent) |
|
525 { |
|
526 } |
|
527 |
|
528 /*! |
|
529 Destroys the picture format plugin. |
|
530 |
|
531 You never have to call this explicitly. Qt destroys a plugin |
|
532 automatically when it is no longer used. |
|
533 */ |
|
534 QImageIOPlugin::~QImageIOPlugin() |
|
535 { |
|
536 } |
|
537 |
|
538 /*! \fn QImageIOPlugin::capabilities(QIODevice *device, const QByteArray &format) const |
|
539 |
|
540 Returns the capabilities on the plugin, based on the data in \a |
|
541 device and the format \a format. For example, if the |
|
542 QImageIOHandler supports the BMP format, and the data in the |
|
543 device starts with the characters "BM", this function should |
|
544 return \l CanRead. If \a format is "bmp" and the handler supports |
|
545 both reading and writing, this function should return \l CanRead | |
|
546 \l CanWrite. |
|
547 */ |
|
548 |
|
549 /*! |
|
550 \fn QImageIOPlugin::keys() const |
|
551 |
|
552 Returns the list of image keys this plugin supports. |
|
553 |
|
554 These keys are usually the names of the image formats that are implemented |
|
555 in the plugin (e.g., "jpg" or "gif"). |
|
556 |
|
557 \sa capabilities() |
|
558 */ |
|
559 |
|
560 /*! |
|
561 \fn QImageIOHandler *QImageIOPlugin::create(QIODevice *device, const QByteArray &format) const |
|
562 |
|
563 Creates and returns a QImageIOHandler subclass, with \a device |
|
564 and \a format set. The \a format must come from the list returned by keys(). |
|
565 Format names are case sensitive. |
|
566 |
|
567 \sa keys() |
|
568 */ |
|
569 |
|
570 QT_END_NAMESPACE |