Add SubType setters/getters and SupportedSubTypes option.

SubType can be used to determine an internal format of an image such as
pixel format and/or compression algorithms.

Change-Id: Icf296d54bb509e4e2bdb70544df678fc53f57c79
Reviewed-by: Gunnar Sletta <[email protected]>

src/gui/doc/snippets/code/src_gui_image_qimagewriter.cpp

@@ -57,3 +57,10 @@ QImageWriter writer(fileName);
 if (writer.supportsOption(QImageIOHandler::Description))
     writer.setText("Author", "John Smith");
 //! [2]
+
+//! [3]
+QImageWriter writer("some/image.dds");
+if (writer.supportsOption(QImageIOHandler::SubType))
+    writer.setSubType("A8R8G8B8");
+writer.write(image);
+//! [3]

src/gui/image/qimageiohandler.cpp

@@ -157,6 +157,10 @@
 
     \value ImageFormat The image's data format returned by the handler.
     This can be any of the formats listed in QImage::Format.
+
+    \value SupportedSubTypes Image formats that support different saving
+    variants should return a list of supported variant names
+    (QList<QByteArray>) in this option.
 */
 
 /*!

src/gui/image/qimageiohandler.h

@@ -90,7 +90,8 @@ class Q_GUI_EXPORT QImageIOHandler
         Endianness,
         Animation,
         BackgroundColor,
-        ImageFormat
+        ImageFormat,
+        SupportedSubTypes
     };
     virtual QVariant option(ImageOption option) const;
     virtual void setOption(ImageOption option, const QVariant &value);

src/gui/image/qimagereader.cpp

@@ -1099,6 +1099,36 @@ bool QImageReader::supportsAnimation() const
     return false;
 }
 
+/*!
+    \since 5.4
+
+    Returns the subtype of the image.
+*/
+QByteArray QImageReader::subType() const
+{
+    if (!d->initHandler())
+        return QByteArray();
+
+    if (d->handler->supportsOption(QImageIOHandler::SubType))
+        return d->handler->option(QImageIOHandler::SubType).toByteArray();
+    return QByteArray();
+}
+
+/*!
+    \since 5.4
+
+    Returns the list of subtypes supported by an image.
+*/
+QList<QByteArray> QImageReader::supportedSubTypes() const
+{
+    if (!d->initHandler())
+        return QList<QByteArray>();
+
+    if (!d->handler->supportsOption(QImageIOHandler::SupportedSubTypes))
+        return d->handler->option(QImageIOHandler::SupportedSubTypes).value< QList<QByteArray> >();
+    return QList<QByteArray>();
+}
+
 /*!
     Returns \c true if an image can be read for the device (i.e., the
     image format is supported, and the device seems to contain valid

src/gui/image/qimagereader.h

@@ -113,6 +113,9 @@ class Q_GUI_EXPORT QImageReader
 
     bool supportsAnimation() const;
 
+    QByteArray subType() const;
+    QList<QByteArray> supportedSubTypes() const;
+
     bool canRead() const;
     QImage read();
     bool read(QImage *image);

src/gui/image/qimagewriter.cpp

@@ -259,6 +259,7 @@ class QImageWriterPrivate
     float gamma;
     QString description;
     QString text;
+    QByteArray subType;
 
     // error
     QImageWriter::ImageWriterError imageWriterError;
@@ -517,6 +518,47 @@ float QImageWriter::gamma() const
     return d->gamma;
 }
 
+/*!
+    \since 5.4
+
+    This is an image format specific function that sets the
+    subtype of the image to \a type. Subtype can be used by
+    a handler to determine which format it should use while
+    saving the image.
+
+    For example, saving an image in DDS format with A8R8G8R8 subtype:
+
+    \snippet code/src_gui_image_qimagewriter.cpp 3
+*/
+void QImageWriter::setSubType(const QByteArray &type)
+{
+    d->subType = type;
+}
+
+/*!
+    \since 5.4
+
+    Returns the subtype of the image.
+
+    \sa setSubType()
+*/
+QByteArray QImageWriter::subType() const
+{
+    return d->subType;
+}
+
+/*!
+    \since 5.4
+
+    Returns the list of subtypes supported by an image.
+*/
+QList<QByteArray> QImageWriter::supportedSubTypes() const
+{
+    if (!supportsOption(QImageIOHandler::SupportedSubTypes))
+        return QList<QByteArray>();
+    return d->handler->option(QImageIOHandler::SupportedSubTypes).value< QList<QByteArray> >();
+}
+
 /*!
     \obsolete
 
@@ -618,6 +660,8 @@ bool QImageWriter::write(const QImage &image)
         d->handler->setOption(QImageIOHandler::Gamma, d->gamma);
     if (!d->description.isEmpty() && d->handler->supportsOption(QImageIOHandler::Description))
         d->handler->setOption(QImageIOHandler::Description, d->description);
+    if (!d->subType.isEmpty() && d->handler->supportsOption(QImageIOHandler::SubType))
+        d->handler->setOption(QImageIOHandler::SubType, d->subType);
 
     if (!d->handler->write(image))
         return false;

src/gui/image/qimagewriter.h

@@ -87,6 +87,10 @@ class Q_GUI_EXPORT QImageWriter
     void setGamma(float gamma);
     float gamma() const;
 
+    void setSubType(const QByteArray &type);
+    QByteArray subType() const;
+    QList<QByteArray> supportedSubTypes() const;
+
     // Obsolete as of 4.1
     void setDescription(const QString &description);
     QString description() const;