qimageiohandler.cpp

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