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 = nullptr;
292 q_ptr = q;
293}
294
295QImageIOHandlerPrivate::~QImageIOHandlerPrivate()
296{
297}
298
299/*!
300 Constructs a QImageIOHandler object.
301*/
302QImageIOHandler::QImageIOHandler()
303 : d_ptr(new QImageIOHandlerPrivate(this))
304{
305}
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}
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}
340
341/*!
342 Returns the device currently assigned to the QImageIOHandler. If
343 not device has been assigned, \nullptr is returned.
344*/
345QIODevice *QImageIOHandler::device() const
346{
347 Q_D(const QImageIOHandler);
348 return d->device;
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}
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}
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;
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 // ### Qt6: remove
426{
427 return format();
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;
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}
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();
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;
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;
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();
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;
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;
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;
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;
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;
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}
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
621

source code of qtbase/src/gui/image/qimageiohandler.cpp