path: root/src/gui/kernel/qpixelformat.cpp

/****************************************************************************
**
** Copyright (C) 2016 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtGui module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/

#include "qpixelformat.h"

QT_BEGIN_NAMESPACE

/*!
    \class QPixelFormat
    \inmodule QtGui
    \since 5.4
    \brief QPixelFormat is a class for describing different pixel
    layouts in graphics buffers

    In Qt there is a often a need to represent the layout of the pixels in a
    graphics buffer. Internally QPixelFormat stores everything in a 64 bit
    datastructure. This gives performance but also some limitations.

    QPixelFormat can describe 5 color channels and 1 alpha channel, each can use
    6 bits to describe the size of the color channel.

    The position of the alpha channel is described with a separate enum. This is
    to make it possible to describe QImage formats like ARGB32, and also
    describe typical OpenGL formats like RBGA8888.

    How pixels are suppose to be read is determined by the TypeInterpretation
    enum.  It describes if color values are suppose to be read byte per byte,
    or if a pixel is suppose to be read as a complete int and then masked.
    \sa TypeInterpretation

    There is no support for describing YUV's macro pixels. Instead a list of YUV
    formats has been made. When a QPixelFormat is describing a YUV format, the
    bitsPerPixel value has been deduced by the YUV Layout enum. Also, the color
    channels should all be set to zero except the fifth color channel that
    should store the bitsPerPixel value.
*/

/*!
    \enum QPixelFormat::ColorModel

    This enum type is used to describe the color model of the pixelformat.
    Alpha was added in 5.5.

    \value RGB The color model is RGB.

    \value BGR This is logically the opposite endian version of RGB. However,
    for ease of use it has its own model.

    \value Indexed The color model uses a color palette.

    \value Grayscale The color model is Grayscale.

    \value CMYK The color model is CMYK.

    \value HSL The color model is HSL.

    \value HSV The color model is HSV.

    \value YUV The color model is YUV.

    \value Alpha There is no color model, only alpha is used.
*/

/*!
    \enum QPixelFormat::AlphaUsage

    This enum describes if the alpha channel is used or not. Sometimes the
    pixelformat will have a size for the alpha channel, but the pixel format
    does actually not use the alpha channel. For example  RGB32 is such a
    format. The RGB channels are 8 bits each, and there is no alpha channel.
    But the complete size for each pixel is 32. Therefore the alpha channel size
    is 8, but the alpha channel is ignored. Its important to note that in such
    situations the position of the alpha channel is significant.

    \value IgnoresAlpha The alpha channel is not used.

    \value UsesAlpha    The alpha channel is used.
*/

/*!
    \enum QPixelFormat::AlphaPosition

    This enum type is used to describe the alpha channels position relative to the
    color channels.

    \value AtBeginning The alpha channel will be put in front of the color
                       channels . E.g. ARGB.

    \value AtEnd       The alpha channel will be put in the back of the color
                       channels. E.g. RGBA.
*/

/*!
    \enum QPixelFormat::AlphaPremultiplied

    This enum type describes the boolean state if the alpha channel is multiplied
    into the color channels or not.

    \value NotPremultiplied The alpha channel is not multiplied into the color channels.

    \value Premultiplied    The alpha channel is multiplied into the color channels.
*/

/*!
    \enum QPixelFormat::TypeInterpretation

    This enum describes how each pixel is interpreted. If a pixel is read as a
    full 32 bit unsigned integer and then each channel is masked out, or if
    each byte is read as unsigned char values. Typically QImage formats
    interpret one pixel as an unsigned integer and then the color channels are
    masked out. OpenGL on the other hand typically interpreted pixels "one byte
    after the other", Ie. unsigned byte.

    QImage also have the format Format_RGBA8888 (and its derivatives), where
    the pixels are interpreted as unsigned bytes. OpenGL has extensions that makes it
    possible to upload pixel buffers in an unsigned integer format.

    \image qpixelformat-argb32buffer.png An unsigned integer ARGB32 pixel.

    The image above shows a ARGB pixel in memory read as an unsigned integer.
    However, if this pixel was read byte for byte on a little endian system the
    first byte would be the byte containing the B-channel. The next byte would
    be the G-channel, then the R-channel and finally the A-channel. This shows
    that on little endian systems, how each pixel is interpreted is significant
    for integer formats. This is not the case on big endian systems.

    \value UnsignedInteger
    \value UnsignedShort
    \value UnsignedByte
    \value FloatingPoint
*/

/*!
    \enum QPixelFormat::ByteOrder

    This enum describes the ByteOrder of the pixel format. This enum is mostly
    ignored but have some use cases for YUV formats. BGR formats have their own
    color model, and should not be described by using the opposite endianness
    on an RGB format.

    \value LittleEndian        The byte order is little endian.
    \value BigEndian           The byte order is big endian.
    \value CurrentSystemEndian This enum will not be stored, but is converted in
                               the constructor to the endian enum that matches
                               the enum of the current system.

*/

/*!
    \enum QPixelFormat::YUVLayout

    YUV is not represented by describing the size of the color channels. This is
    because YUV often use macro pixels, making the concept of sperate color channels
    invalid. Instead the different YUV layouts are described with this enum.

    \value YUV444
    \value YUV422
    \value YUV411
    \value YUV420P
    \value YUV420SP
    \value YV12
    \value UYVY
    \value YUYV
    \value NV12
    \value NV21
    \value IMC1
    \value IMC2
    \value IMC3
    \value IMC4
    \value Y8
    \value Y16
*/

/*!
    \fn QPixelFormat::QPixelFormat()

    Creates a null pixelformat. This format maps to QImage::Format_Invalid.
*/

/*!
    \fn QPixelFormat::QPixelFormat(ColorModel colorModel,
                                   uchar firstSize,
                                   uchar secondSize,
                                   uchar thirdSize,
                                   uchar fourthSize,
                                   uchar fifthSize,
                                   uchar alphaSize,
                                   AlphaUsage alphaUsage,
                                   AlphaPosition alphaPosition,
                                   AlphaPremultiplied premultiplied,
                                   TypeInterpretation typeInterpretation,
                                   ByteOrder byteOrder = CurrentSystemEndian,
                                   uchar subEnum = 0)

    Creates a QPixelFormat which assigns its data to the attributes.
    \a colorModel will be put into a buffer which is 4 bits long.

    \a firstSize \a secondSize \a thirdSize \a fourthSize \a fifthSize \a
    alphaSize are all meant to represent the size of a channel. The channels will
    be used for different uses dependent on the \a colorModel. For RGB the
    firstSize will represent the Red channel. On CMYK it will represent the
    value of the Cyan channel.

    \a alphaUsage represents if the alpha channel is used or not.

    \a alphaPosition is the position of the alpha channel.

    \a premultiplied represents if the alpha channel is already multiplied with
    the color channels.

    \a typeInterpretation is how the pixel is interpreted.

    \a byteOrder represents the endianness of the pixelformat. This defaults to
    CurrentSystemEndian.

    \a subEnum is used for colorModels that have to store some extra
    information with supplying an extra enum. This is used by YUV to store the
    YUV type The default value is 0.
*/

/*!
    \fn QPixelFormat qPixelFormatRgba(uchar redSize,
                                      uchar greenSize,
                                      uchar blueSize,
                                      uchar alphaSize,
                                      QPixelFormat::AlphaUsage alphaUsage,
                                      QPixelFormat::AlphaPosition alphaPosition,
                                      QPixelFormat::AlphaPremultiplied premultiplied = QPixelFormat::NotPremultiplied,
                                      QPixelFormat::TypeInterpretation typeInterpretation = QPixelFormat::UnsignedInteger)
    \relates QPixelFormat

    Constructor function making an RGB pixelformat. \a redSize \a greenSize \a
    blueSize represent the size of each color channel. \a alphaSize describes
    the alpha channel size and its position is described with \a alphaPosition.
    \a alphaUsage is used to determine if the alpha channel is used or not.
    Setting the alpha channel size to 8 and alphaUsage to IgnoresAlpha is how
    it is possible to create a 32 bit format where the rgb channels only use 24
    bits combined. \a premultiplied \a typeInterpretation are
    accessible with accessors with the same name.

    \sa QPixelFormat::TypeInterpretation
*/

/*!
    \fn QPixelFormat qPixelFormatGrayscale(uchar channelSize,
                                           QPixelFormat::TypeInterpretation typeInterpretation = QPixelFormat::UnsignedInteger)
    \relates QPixelFormat

    Constructor function for creating a Grayscale format. Monochrome formats can be
    described by passing 1 to \a channelSize. Its also possible to define very
    accurate grayscale formats using doubles to describe each pixel by passing 8
    as \a channelSize and FloatingPoint as \a typeInterpretation.

    \sa QPixelFormat::TypeInterpretation
*/

/*!
    \fn QPixelFormat qPixelFormatAlpha(uchar channelSize,
                                           QPixelFormat::TypeInterpretation typeInterpretation = QPixelFormat::UnsignedInteger)
    \relates QPixelFormat
    \since 5.5

    Constructor function for creating an Alpha format. A mask format can be
    described by passing 1 to \a channelSize. Its also possible to define very
    accurate alpha formats using doubles to describe each pixel by passing 8
    as \a channelSize and FloatingPoint as \a typeInterpretation.

    \sa QPixelFormat::TypeInterpretation
*/


/*!
    \fn QPixelFormat qPixelFormatCmyk(uchar channelSize,
                                      uchar alphaSize = 0,
                                      QPixelFormat::AlphaUsage alphaUsage = QPixelFormat::IgnoresAlpha,
                                      QPixelFormat::AlphaPosition alphaPosition = QPixelFormat::AtBeginning,
                                      QPixelFormat::TypeInterpretation typeInterpretation = QPixelFormat::UnsignedInteger)
    \relates QPixelFormat

    Constructor function for creating CMYK formats. The channel count will be 4 or
    5 depending on if \a alphaSize is bigger than zero or not. The CMYK color
    channels will all be set to the value of \a channelSize.

    \a alphaUsage \a alphaPosition and \a typeInterpretation are all accessible with
    the accessors with the same name.

    \sa QPixelFormat::TypeInterpretation
*/

/*!
    \fn QPixelFormat qPixelFormatHsl(uchar channelSize,
                                     uchar alphaSize = 0,
                                     QPixelFormat::AlphaUsage alphaUsage = QPixelFormat::IgnoresAlpha,
                                     QPixelFormat::AlphaPosition alphaPosition = QPixelFormat::AtBeginning,
                                     QPixelFormat::TypeInterpretation typeInterpretation = QPixelFormat::FloatingPoint)
    \relates QPixelFormat

    Constructor function for creating HSL formats. The channel count will be 3 or 4
    depending on if \a alphaSize is bigger than 0.

    \a channelSize will set the hueSize saturationSize and lightnessSize to the same value.

    \a alphaUsage \a alphaPosition and \a typeInterpretation are all accessible with
    the accessors with the same name.
*/

/*!
    \fn QPixelFormat qPixelFormatHsv(uchar channelSize,
                                     uchar alphaSize = 0,
                                     QPixelFormat::AlphaUsage alphaUsage = QPixelFormat::IgnoresAlpha,
                                     QPixelFormat::AlphaPosition alphaPosition = QPixelFormat::AtBeginning,
                                     QPixelFormat::TypeInterpretation typeInterpretation = QPixelFormat::FloatingPoint)
    \relates QPixelFormat

    Constructor function for creating HSV formats. The channel count will be 3 or 4
    depending on if \a alphaSize is bigger than 0.

    \a channelSize will set the hueSize saturationSize and brightnessSize to the same value.

    \a alphaUsage \a alphaPosition and \a typeInterpretation are all accessible with
    the accessors with the same name.
*/

/*!
    \fn QPixelFormat qPixelFormatYuv(QPixelFormat::YUVLayout yuvLayout,
                                     uchar alphaSize = 0,
                                     QPixelFormat::AlphaUsage alphaUsage = QPixelFormat::IgnoresAlpha,
                                     QPixelFormat::AlphaPosition alphaPosition = QPixelFormat::AtBeginning,
                                     QPixelFormat::AlphaPremultiplied premultiplied = QPixelFormat::NotPremultiplied,
                                     QPixelFormat::TypeInterpretation typeInterpretation = QPixelFormat::UnsignedByte,
                                     QPixelFormat::ByteOrder byteOrder = QPixelFormat::LittleEndian)
    \relates QPixelFormat

    Constructor function for creating a QPixelFormat describing a YUV format with
    \a yuvLayout.  \a alphaSize describes the size of a potential alpha channel
    and is position is described with \a alphaPosition. The "first" "second" ..
    "fifth" channels are all set to 0. \a alphaUsage \a premultiplied \a
    typeInterpretation and \a byteOrder will work as with other formats.
*/

/*!
    \fn ColorModel QPixelFormat::colorModel() const

    Accessor function for getting the colorModel.
*/

/*!
    \fn uchar QPixelFormat::channelCount() const

    Accessor function for getting the channelCount. Channel Count is deduced
    by color channels with a size > 0 and if the size of the alpha channel is > 0.
*/

/*!
    \fn uchar QPixelFormat::redSize() const

    Accessor function for the size of the red color channel.
*/

/*!
    \fn uchar QPixelFormat::greenSize() const

    Accessor function for the size of the green color channel.
*/

/*!
    \fn uchar QPixelFormat::blueSize() const

    Accessor function for the size of the blue color channel.
*/

/*!
    \fn uchar QPixelFormat::cyanSize() const

    Accessor function for the cyan color channel.
*/

/*!
    \fn uchar QPixelFormat::magentaSize() const

    Accessor function for the megenta color channel.
*/

/*!
    \fn uchar QPixelFormat::yellowSize() const

    Accessor function for the yellow color channel.
*/

/*!
    \fn uchar QPixelFormat::blackSize() const

    Accessor function for the black/key color channel.
*/

/*!
    \fn uchar QPixelFormat::hueSize() const

    Accessor function for the hue channel size.
*/

/*!
    \fn uchar QPixelFormat::saturationSize() const

    Accessor function for the saturation channel size.
*/

/*!
    \fn uchar QPixelFormat::lightnessSize() const

    Accessor function for the lightness channel size.
*/

/*!
    \fn uchar QPixelFormat::brightnessSize() const

    Accessor function for the brightness channel size.
*/

/*!
    \fn uchar QPixelFormat::alphaSize() const

    Accessor function for the alpha channel size.
*/

/*!
    \fn uchar QPixelFormat::bitsPerPixel() const

    Accessor function for the bits used per pixel. This function returns the
    sum of the color channels + the size of the alpha channel.
*/

/*!
    \fn AlphaPremultiplied QPixelFormat::premultiplied() const

    Accessor function for the AlphaPremultiplied enum. This indicates if the
    alpha channel is multiplied in to the color channels.

*/

/*!
    \fn TypeInterpretation QPixelFormat::typeInterpretation() const

    Accessor function for the type representation of a color channel or a pixel.

    \sa TypeInterpretation
*/

/*!
    \fn ByteOrder QPixelFormat::byteOrder() const

    The byte order is almost always set the the byte order of the current
    system. However, it can be useful to describe some YUV formats. This
    function should never return QPixelFormat::CurrentSystemEndian as this
    value is translated to a endian value in the constructor.
*/

/*!
    \fn AlphaUsage QPixelFormat::alphaUsage() const

    Accessor function for alphaUsage.
*/

/*!
    \fn AlphaPosition QPixelFormat::alphaPosition() const

    Accessor function for alphaPosition.
*/

/*!
    \fn YUVLayout QPixelFormat::yuvLayout() const

    Accessor function for the YUVLayout. It is difficult to describe the color
    channels of a YUV pixel format since YUV color model uses macro pixels.
    Instead the layout of the pixels are stored as an enum.
*/

/*!
    \fn uchar QPixelFormat::subEnum() const

    Accessor for the datapart which contains subEnums
    This is the same as the yuvLayout() function.

    \sa yuvLayout()
    \internal
*/

Q_STATIC_ASSERT(sizeof(QPixelFormat) == sizeof(quint64));


namespace QtPrivate {
    QPixelFormat QPixelFormat_createYUV(QPixelFormat::YUVLayout yuvLayout,
                                        uchar alphaSize,
                                        QPixelFormat::AlphaUsage alphaUsage,
                                        QPixelFormat::AlphaPosition alphaPosition,
                                        QPixelFormat::AlphaPremultiplied premultiplied,
                                        QPixelFormat::TypeInterpretation typeInterpretation,
                                        QPixelFormat::ByteOrder byteOrder)
    {
        uchar bits_per_pixel = 0;
        switch (yuvLayout) {
        case QPixelFormat::YUV444:
            bits_per_pixel = 24;
            break;
        case QPixelFormat::YUV422:
            bits_per_pixel = 16;
            break;
        case QPixelFormat::YUV411:
        case QPixelFormat::YUV420P:
        case QPixelFormat::YUV420SP:
        case QPixelFormat::YV12:
            bits_per_pixel = 12;
            break;
        case QPixelFormat::UYVY:
        case QPixelFormat::YUYV:
            bits_per_pixel = 16;
            break;
        case QPixelFormat::NV12:
        case QPixelFormat::NV21:
            bits_per_pixel = 12;
            break;
        case QPixelFormat::IMC1:
        case QPixelFormat::IMC2:
        case QPixelFormat::IMC3:
        case QPixelFormat::IMC4:
            bits_per_pixel = 12;
            break;
        case QPixelFormat::Y8:
            bits_per_pixel = 8;
            break;
        case QPixelFormat::Y16:
            bits_per_pixel = 16;
            break;
        }

        return QPixelFormat(QPixelFormat::YUV,
                            0, 0, 0, 0,
                            bits_per_pixel,
                            alphaSize,
                            alphaUsage,
                            alphaPosition,
                            premultiplied,
                            typeInterpretation,
                            byteOrder,
                            yuvLayout);
    }
}

QT_END_NAMESPACE