Qt
Internal/Contributor docs for the Qt SDK. <b>Note:</b> These are NOT official API docs; those are found <a href='https://doc.qt.io/'>here</a>.
Loading...
Searching...
No Matches
QPixelFormat Class Reference

\inmodule QtGui More...

#include <qpixelformat.h>

+ Collaboration diagram for QPixelFormat:

Public Types

enum  ColorModel {
  RGB , BGR , Indexed , Grayscale ,
  CMYK , HSL , HSV , YUV ,
  Alpha
}
 This enum type is used to describe the color model of the pixelformat. More...
 
enum  AlphaUsage { UsesAlpha , IgnoresAlpha }
 This enum describes if the alpha channel is used or not. More...
 
enum  AlphaPosition { AtBeginning , AtEnd }
 This enum type is used to describe the alpha channels position relative to the color channels. More...
 
enum  AlphaPremultiplied { NotPremultiplied , Premultiplied }
 This enum type describes the boolean state if the alpha channel is multiplied into the color channels or not. More...
 
enum  TypeInterpretation { UnsignedInteger , UnsignedShort , UnsignedByte , FloatingPoint }
 This enum describes how each pixel is interpreted. More...
 
enum  YUVLayout {
  YUV444 , YUV422 , YUV411 , YUV420P ,
  YUV420SP , YV12 , UYVY , YUYV ,
  NV12 , NV21 , IMC1 , IMC2 ,
  IMC3 , IMC4 , Y8 , Y16
}
 YUV is not represented by describing the size of the color channels. More...
 
enum  ByteOrder { LittleEndian , BigEndian , CurrentSystemEndian }
 This enum describes the ByteOrder of the pixel format. More...
 

Public Member Functions

constexpr QPixelFormat () noexcept
 Creates a null pixelformat.
 
constexpr 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) noexcept
 Creates a QPixelFormat which assigns its data to the attributes.
 
constexpr ColorModel colorModel () const noexcept
 Accessor function for getting the colorModel.
 
constexpr uchar channelCount () const noexcept
 Accessor function for getting the channelCount.
 
constexpr uchar redSize () const noexcept
 Accessor function for the size of the red color channel.
 
constexpr uchar greenSize () const noexcept
 Accessor function for the size of the green color channel.
 
constexpr uchar blueSize () const noexcept
 Accessor function for the size of the blue color channel.
 
constexpr uchar cyanSize () const noexcept
 Accessor function for the cyan color channel.
 
constexpr uchar magentaSize () const noexcept
 Accessor function for the megenta color channel.
 
constexpr uchar yellowSize () const noexcept
 Accessor function for the yellow color channel.
 
constexpr uchar blackSize () const noexcept
 Accessor function for the black/key color channel.
 
constexpr uchar hueSize () const noexcept
 Accessor function for the hue channel size.
 
constexpr uchar saturationSize () const noexcept
 Accessor function for the saturation channel size.
 
constexpr uchar lightnessSize () const noexcept
 Accessor function for the lightness channel size.
 
constexpr uchar brightnessSize () const noexcept
 Accessor function for the brightness channel size.
 
constexpr uchar alphaSize () const noexcept
 Accessor function for the alpha channel size.
 
constexpr uchar bitsPerPixel () const noexcept
 Accessor function for the bits used per pixel.
 
constexpr AlphaUsage alphaUsage () const noexcept
 Accessor function for alphaUsage.
 
constexpr AlphaPosition alphaPosition () const noexcept
 Accessor function for alphaPosition.
 
constexpr AlphaPremultiplied premultiplied () const noexcept
 Accessor function for the AlphaPremultiplied enum.
 
constexpr TypeInterpretation typeInterpretation () const noexcept
 Accessor function for the type representation of a color channel or a pixel.
 
constexpr ByteOrder byteOrder () const noexcept
 The byte order is almost always set the byte order of the current system.
 
constexpr YUVLayout yuvLayout () const noexcept
 Accessor function for the YUVLayout.
 
constexpr uchar subEnum () const noexcept
 Accessor for the datapart which contains subEnums This is the same as the yuvLayout() function.
 

Friends

Q_DECL_CONST_FUNCTION constexpr bool operator== (QPixelFormat fmt1, QPixelFormat fmt2)
 
Q_DECL_CONST_FUNCTION constexpr bool operator!= (QPixelFormat fmt1, QPixelFormat fmt2)
 

Related Symbols

(Note that these are not member symbols.)

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)
 Constructor function making an RGB pixelformat.
 
QPixelFormat qPixelFormatGrayscale (uchar channelSize, QPixelFormat::TypeInterpretation typeInterpretation=QPixelFormat::UnsignedInteger)
 Constructor function for creating a Grayscale format.
 
QPixelFormat qPixelFormatAlpha (uchar channelSize, QPixelFormat::TypeInterpretation typeInterpretation=QPixelFormat::UnsignedInteger)
 
QPixelFormat qPixelFormatCmyk (uchar channelSize, uchar alphaSize=0, QPixelFormat::AlphaUsage alphaUsage=QPixelFormat::IgnoresAlpha, QPixelFormat::AlphaPosition alphaPosition=QPixelFormat::AtBeginning, QPixelFormat::TypeInterpretation typeInterpretation=QPixelFormat::UnsignedInteger)
 Constructor function for creating CMYK formats.
 
QPixelFormat qPixelFormatHsl (uchar channelSize, uchar alphaSize=0, QPixelFormat::AlphaUsage alphaUsage=QPixelFormat::IgnoresAlpha, QPixelFormat::AlphaPosition alphaPosition=QPixelFormat::AtBeginning, QPixelFormat::TypeInterpretation typeInterpretation=QPixelFormat::FloatingPoint)
 Constructor function for creating HSL formats.
 
QPixelFormat qPixelFormatHsv (uchar channelSize, uchar alphaSize=0, QPixelFormat::AlphaUsage alphaUsage=QPixelFormat::IgnoresAlpha, QPixelFormat::AlphaPosition alphaPosition=QPixelFormat::AtBeginning, QPixelFormat::TypeInterpretation typeInterpretation=QPixelFormat::FloatingPoint)
 Constructor function for creating HSV formats.
 
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)
 Constructor function for creating a QPixelFormat describing a YUV format with yuvLayout.
 

Detailed Description

\inmodule QtGui

Since
5.4

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.

See also
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.

Definition at line 11 of file qpixelformat.h.

Member Enumeration Documentation

◆ 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.

Enumerator
AtBeginning 
AtEnd 

Definition at line 85 of file qpixelformat.h.

◆ 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.

Enumerator
NotPremultiplied 
Premultiplied 

Definition at line 90 of file qpixelformat.h.

◆ 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.

Enumerator
UsesAlpha 
IgnoresAlpha 

Definition at line 80 of file qpixelformat.h.

◆ 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.

Enumerator
LittleEndian 
BigEndian 
CurrentSystemEndian 

Definition at line 121 of file qpixelformat.h.

◆ 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.

Enumerator
RGB 
BGR 
Indexed 
Grayscale 
CMYK 
HSL 
HSV 
YUV 
Alpha 

Definition at line 68 of file qpixelformat.h.

◆ 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.

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

Enumerator
UnsignedInteger 
UnsignedShort 
UnsignedByte 
FloatingPoint 

Definition at line 95 of file qpixelformat.h.

◆ 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 separate 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

Enumerator
YUV444 
YUV422 
YUV411 
YUV420P 
YUV420SP 
YV12 
UYVY 
YUYV 
NV12 
NV21 
IMC1 
IMC2 
IMC3 
IMC4 
Y8 
Y16 

Definition at line 102 of file qpixelformat.h.

Constructor & Destructor Documentation

◆ QPixelFormat() [1/2]

QPixelFormat::QPixelFormat ( )
inlineconstexprnoexcept

Creates a null pixelformat.

This format maps to QImage::Format_Invalid.

Definition at line 127 of file qpixelformat.h.

◆ QPixelFormat() [2/2]

constexpr 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 )
inlineconstexprnoexcept

Creates a QPixelFormat which assigns its data to the attributes.

colorModel will be put into a buffer which is 4 bits long.

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

alphaUsage represents if the alpha channel is used or not.

alphaPosition is the position of the alpha channel.

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

typeInterpretation is how the pixel is interpreted.

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

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.

Definition at line 209 of file qpixelformat.h.

Member Function Documentation

◆ alphaPosition()

AlphaPosition QPixelFormat::alphaPosition ( ) const
inlineconstexprnoexcept

Accessor function for alphaPosition.

Definition at line 174 of file qpixelformat.h.

◆ alphaSize()

uchar QPixelFormat::alphaSize ( ) const
inlineconstexprnoexcept

Accessor function for the alpha channel size.

Definition at line 164 of file qpixelformat.h.

◆ alphaUsage()

AlphaUsage QPixelFormat::alphaUsage ( ) const
inlineconstexprnoexcept

Accessor function for alphaUsage.

Definition at line 173 of file qpixelformat.h.

◆ bitsPerPixel()

uchar QPixelFormat::bitsPerPixel ( ) const
inlineconstexprnoexcept

Accessor function for the bits used per pixel.

This function returns the sum of the color channels + the size of the alpha channel.

Definition at line 166 of file qpixelformat.h.

◆ blackSize()

uchar QPixelFormat::blackSize ( ) const
inlineconstexprnoexcept

Accessor function for the black/key color channel.

Definition at line 157 of file qpixelformat.h.

◆ blueSize()

uchar QPixelFormat::blueSize ( ) const
inlineconstexprnoexcept

Accessor function for the size of the blue color channel.

Definition at line 152 of file qpixelformat.h.

◆ brightnessSize()

uchar QPixelFormat::brightnessSize ( ) const
inlineconstexprnoexcept

Accessor function for the brightness channel size.

Definition at line 162 of file qpixelformat.h.

◆ byteOrder()

ByteOrder QPixelFormat::byteOrder ( ) const
inlineconstexprnoexcept

The byte order is almost always set 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.

Definition at line 177 of file qpixelformat.h.

◆ channelCount()

uchar QPixelFormat::channelCount ( ) const
inlineconstexprnoexcept

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.

Definition at line 143 of file qpixelformat.h.

◆ colorModel()

ColorModel QPixelFormat::colorModel ( ) const
inlineconstexprnoexcept

Accessor function for getting the colorModel.

Definition at line 142 of file qpixelformat.h.

◆ cyanSize()

uchar QPixelFormat::cyanSize ( ) const
inlineconstexprnoexcept

Accessor function for the cyan color channel.

Definition at line 154 of file qpixelformat.h.

◆ greenSize()

uchar QPixelFormat::greenSize ( ) const
inlineconstexprnoexcept

Accessor function for the size of the green color channel.

Definition at line 151 of file qpixelformat.h.

◆ hueSize()

uchar QPixelFormat::hueSize ( ) const
inlineconstexprnoexcept

Accessor function for the hue channel size.

Definition at line 159 of file qpixelformat.h.

◆ lightnessSize()

uchar QPixelFormat::lightnessSize ( ) const
inlineconstexprnoexcept

Accessor function for the lightness channel size.

Definition at line 161 of file qpixelformat.h.

◆ magentaSize()

uchar QPixelFormat::magentaSize ( ) const
inlineconstexprnoexcept

Accessor function for the megenta color channel.

Definition at line 155 of file qpixelformat.h.

◆ premultiplied()

AlphaPremultiplied QPixelFormat::premultiplied ( ) const
inlineconstexprnoexcept

Accessor function for the AlphaPremultiplied enum.

This indicates if the alpha channel is multiplied in to the color channels.

Definition at line 175 of file qpixelformat.h.

◆ redSize()

uchar QPixelFormat::redSize ( ) const
inlineconstexprnoexcept

Accessor function for the size of the red color channel.

Definition at line 150 of file qpixelformat.h.

◆ saturationSize()

uchar QPixelFormat::saturationSize ( ) const
inlineconstexprnoexcept

Accessor function for the saturation channel size.

Definition at line 160 of file qpixelformat.h.

◆ subEnum()

uchar QPixelFormat::subEnum ( ) const
inlineconstexprnoexcept

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

See also
yuvLayout()

Definition at line 180 of file qpixelformat.h.

◆ typeInterpretation()

TypeInterpretation QPixelFormat::typeInterpretation ( ) const
inlineconstexprnoexcept

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

See also
TypeInterpretation

Definition at line 176 of file qpixelformat.h.

◆ yellowSize()

uchar QPixelFormat::yellowSize ( ) const
inlineconstexprnoexcept

Accessor function for the yellow color channel.

Definition at line 156 of file qpixelformat.h.

◆ yuvLayout()

YUVLayout QPixelFormat::yuvLayout ( ) const
inlineconstexprnoexcept

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.

Definition at line 179 of file qpixelformat.h.

Friends And Related Symbol Documentation

◆ operator!=

Q_DECL_CONST_FUNCTION constexpr bool operator!= ( QPixelFormat fmt1,
QPixelFormat fmt2 )
friend

Definition at line 192 of file qpixelformat.h.

◆ operator==

Q_DECL_CONST_FUNCTION constexpr bool operator== ( QPixelFormat fmt1,
QPixelFormat fmt2 )
friend

Definition at line 189 of file qpixelformat.h.

◆ qPixelFormatAlpha()

QPixelFormat qPixelFormatAlpha ( uchar channelSize,
QPixelFormat::TypeInterpretation typeInterpretation = QPixelFormat::UnsignedInteger )
related
Since
5.5

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

See also
QPixelFormat::TypeInterpretation

Definition at line 277 of file qpixelformat.h.

References Alpha, AtBeginning, NotPremultiplied, and UsesAlpha.

◆ qPixelFormatCmyk()

Constructor function for creating CMYK formats.

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

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

See also
QPixelFormat::TypeInterpretation

Definition at line 293 of file qpixelformat.h.

References CMYK, NotPremultiplied, and position().

+ Here is the call graph for this function:

◆ qPixelFormatGrayscale()

QPixelFormat qPixelFormatGrayscale ( uchar channelSize,
QPixelFormat::TypeInterpretation typeInterpretation = QPixelFormat::UnsignedInteger )
related

Constructor function for creating a Grayscale format.

Monochrome formats can be described by passing 1 to channelSize. Its also possible to define very accurate grayscale formats using doubles to describe each pixel by passing 8 as channelSize and FloatingPoint as typeInterpretation.

See also
QPixelFormat::TypeInterpretation

Definition at line 261 of file qpixelformat.h.

References AtBeginning, Grayscale, IgnoresAlpha, and NotPremultiplied.

◆ qPixelFormatHsl()

Constructor function for creating HSL formats.

The channel count will be 3 or 4 depending on if alphaSize is bigger than 0.

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

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

Definition at line 312 of file qpixelformat.h.

References HSL, NotPremultiplied, and position().

+ Here is the call graph for this function:

◆ qPixelFormatHsv()

Constructor function for creating HSV formats.

The channel count will be 3 or 4 depending on if alphaSize is bigger than 0.

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

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

Definition at line 331 of file qpixelformat.h.

References HSV, NotPremultiplied, and position().

+ Here is the call graph for this function:

◆ qPixelFormatRgba()

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 )
related

Constructor function making an RGB pixelformat.

redSize greenSize blueSize represent the size of each color channel. alphaSize describes the alpha channel size and its position is described with alphaPosition. 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. premultiplied typeInterpretation are accessible with accessors with the same name.

See also
QPixelFormat::TypeInterpretation

Definition at line 239 of file qpixelformat.h.

References position(), red, and RGB.

+ Here is the call graph for this function:

◆ qPixelFormatYuv()

Constructor function for creating a QPixelFormat describing a YUV format with yuvLayout.

alphaSize describes the size of a potential alpha channel and is position is described with alphaPosition. The "first" "second" .. "fifth" channels are all set to 0. alphaUsage premultiplied typeInterpretation and byteOrder will work as with other formats.

Definition at line 350 of file qpixelformat.h.

References layout, position(), and QtPrivate::QPixelFormat_createYUV().

+ Here is the call graph for this function:

The documentation for this class was generated from the following files: