PySide6.QtGui.QPixelFormat

class QPixelFormat

QPixelFormat is a class for describing different pixel layouts in graphics buffers.

Details

In Qt there is a often a need to represent the layout of the pixels in a graphics buffer. QPixelFormat can describe up to 5 color channels and 1 alpha channel, including details about how these channels are represented in memory individually and in relation to each other.

The typeInterpretation() and byteOrder() determines how each pixel should be read/interpreted, while alphaSize() , alphaUsage() , alphaPosition() , and premultiplied() describes the position and properties of the possible alpha channel.

There is no support for describing YUV’s macro pixels. Instead a list of YUV formats is provided. When a QPixelFormat describes a YUV format, the bitsPerPixel() value is deduced from the YUV layout.

Synopsis

Methods

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

class FieldWidth
class Field
class ColorModel

This enum describes the color model of the pixel format.

Constant

Description

QPixelFormat.ColorModel.RGB

The color model is RGB.

QPixelFormat.ColorModel.BGR

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

QPixelFormat.ColorModel.Indexed

The color model uses a color palette.

QPixelFormat.ColorModel.Grayscale

The color model is Grayscale.

QPixelFormat.ColorModel.CMYK

The color model is CMYK.

QPixelFormat.ColorModel.HSL

The color model is HSL.

QPixelFormat.ColorModel.HSV

The color model is HSV.

QPixelFormat.ColorModel.YUV

The color model is YUV.

QPixelFormat.ColorModel.Alpha

[since 5.5] There is no color model, only alpha is used.
class AlphaUsage

This enum describes the alpha usage of the pixel format.

Constant

Description

QPixelFormat.AlphaUsage.IgnoresAlpha

The alpha channel is not used.

QPixelFormat.AlphaUsage.UsesAlpha

The alpha channel is used.

See also

alphaSize() alphaPosition() premultiplied()

class AlphaPosition

This enum describes the alpha position of the pixel format.

Constant

Description

QPixelFormat.AlphaPosition.AtBeginning

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

QPixelFormat.AlphaPosition.AtEnd

The alpha channel will be put in the back of the color channels. E.g. RGBA.

See also

alphaSize() alphaUsage() premultiplied()

class AlphaPremultiplied

This enum describes whether the alpha channel of the pixel format is premultiplied into the color channels or not.

Constant

Description

QPixelFormat.AlphaPremultiplied.NotPremultiplied

The alpha channel is not multiplied into the color channels.

QPixelFormat.AlphaPremultiplied.Premultiplied

The alpha channel is multiplied into the color channels.

See also

alphaSize() alphaUsage() alphaPosition()

class TypeInterpretation

This enum describes the type interpretation of the pixel format.

Constant

Description

QPixelFormat.TypeInterpretation.UnsignedInteger

The pixels should be read as one or more unsigned int.

QPixelFormat.TypeInterpretation.UnsignedShort

The pixels should be read as one or more unsigned short.

QPixelFormat.TypeInterpretation.UnsignedByte

The pixels should be read as one or more byte.

QPixelFormat.TypeInterpretation.FloatingPoint

The pixels should be read as one or more floating point numbers, with the concrete type defined by the color/alpha channel, ie. qfloat16 for 16-bit half-float formats and float for 32-bit full-float formats.

See also

byteOrder()

class YUVLayout

This enum describes the YUV layout of the pixel format, given that it has a color model of YUV .

Constant

Description

QPixelFormat.YUVLayout.YUV444

QPixelFormat.YUVLayout.YUV422

QPixelFormat.YUVLayout.YUV411

QPixelFormat.YUVLayout.YUV420P

QPixelFormat.YUVLayout.YUV420SP

QPixelFormat.YUVLayout.YV12

QPixelFormat.YUVLayout.UYVY

QPixelFormat.YUVLayout.YUYV

QPixelFormat.YUVLayout.NV12

QPixelFormat.YUVLayout.NV21

QPixelFormat.YUVLayout.IMC1

QPixelFormat.YUVLayout.IMC2

QPixelFormat.YUVLayout.IMC3

QPixelFormat.YUVLayout.IMC4

QPixelFormat.YUVLayout.Y8

QPixelFormat.YUVLayout.Y16
class ByteOrder

This enum describes the byte order of the pixel format.

Constant

Description

QPixelFormat.ByteOrder.LittleEndian

The byte order is little endian.

QPixelFormat.ByteOrder.BigEndian

The byte order is big endian.

QPixelFormat.ByteOrder.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.

See also

typeInterpretation()

__init__()

Creates a null pixelformat. This format maps to Format_Invalid .

__init__(colorModel, firstSize, secondSize, thirdSize, fourthSize, fifthSize, alphaSize, alphaUsage, alphaPosition, premultiplied, typeInterpretation[, byteOrder=QPixelFormat.ByteOrder.CurrentSystemEndian[, subEnum=0]])
Parameters:

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 , which will be resolve to the system’s endianness for non-byte-ordered formats, and BigEndian for UnsignedByte .

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.

Note

BGR formats have their own color model, and should not be described by using the opposite endianness of an RGB format.

alphaPosition()
Return type:

AlphaPosition

Accessor function for the position of the alpha channel relative to the color channels.

For formats where the individual channels map to individual units, the alpha position is relative to these units. For example for Format_RGBA16FPx4 which has an alpha position of AtEnd , the alpha is the last qfloat16 read.

For formats where multiple channels are packed into a single unit, the AtBeginning and AtEnd values map to the most significant and least significant bits of the packed unit, with respect to the format’s own byteOrder() .

For example, for Format_ARGB32 , which has a type interpretation of UnsignedInteger and a byteOrder() that always matches the host system, the alpha position of AtBeginning means that the alpha can always be found at 0xFF000000.

If the pixel format and host endianness does not match care must be taken to correctly map the pixel format layout to the host memory layout.

alphaSize()
Return type:

int

Accessor function for the alpha channel size.

alphaUsage()
Return type:

AlphaUsage

Accessor function for whether the alpha channel is used or not.

Sometimes the pixel format reserves place for an alpha channel, so alphaSize() will return > 0, but the alpha channel is not used/ignored.

For example, for Format_RGB32 , the bitsPerPixel() is 32, because the alpha channel has a size of 8, but alphaUsage() reflects IgnoresAlpha .

Note that in such situations the position of the unused alpha channel is still important, as it affects the placement of the color channels.

bitsPerPixel()
Return type:

int

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

blackSize()
Return type:

int

Accessor function for the black/key color channel.

blueSize()
Return type:

int

Accessor function for the size of the blue color channel.

brightnessSize()
Return type:

int

Accessor function for the brightness channel size.

byteOrder()
Return type:

ByteOrder

The byte order of the pixel format determines the memory layout of the individual type units, as described by the typeInterpretation() .

This function will never return CurrentSystemEndian as this value is translated to the system’s endian value in the constructor.

For pixel formats with typeInterpretation() UnsignedByte this will typically be BigEndian , while other type interpretations will typically reflect the endianness of the current system.

If the byte order of the pixel format matches the current system the individual type units can be read and manipulated using the same bit masks and operations, regardless of the host system endianness. For example, with Format_ARGB32 , which has a UnsignedInteger type interpretation, the alpha can always be read by masking the unsigned int by 0xFF000000, regardless of the host endianness.

If the pixel format and host endianness does not match care must be taken to account for this. Classes like QImage do not swap the internal bits to match the host system endianness in these cases.

channelCount()
Return type:

int

Accessor function for the channel count.

The channel count represents channels (color and alpha) with a size > 0.

colorModel()
Return type:

ColorModel

Accessor function for the color model.

Note that for YUV the individual macro pixels can not be described. Instead a list of YUV formats is provided, and the bitsPerPixel() value is deduced from the YUV layout.

cyanSize()
Return type:

int

Accessor function for the cyan color channel.

greenSize()
Return type:

int

Accessor function for the size of the green color channel.

hueSize()
Return type:

int

Accessor function for the hue channel size.

lightnessSize()
Return type:

int

Accessor function for the lightness channel size.

magentaSize()
Return type:

int

Accessor function for the megenta color channel.

__ne__(fmt2)
Parameters:

fmt2 – QPixelFormat

Return type:

bool

__eq__(fmt2)
Parameters:

fmt2 – QPixelFormat

Return type:

bool

premultiplied()
Return type:

AlphaPremultiplied

Accessor function for the whether the alpha channel is multiplied in to the color channels.

redSize()
Return type:

int

Accessor function for the size of the red color channel.

saturationSize()
Return type:

int

Accessor function for the saturation channel size.

subEnum()
Return type:

int

typeInterpretation()
Return type:

TypeInterpretation

The type interpretation determines how each pixel should be read.

Each pixel is represented as one or more units of the given type, laid out sequentially in memory.

Note

The byte order of the pixel format and the endianness of the host system only affect the memory layout of each individual unit being read — not the relative ordering of the units.

For example, Format_Mono has a pixel format of 1 bits per pixel and a UnsignedByte type interpretation, which should be read as a single byte. Similarly, Format_RGB888 has a pixel format of 24 bits per pixel, and and a UnsignedByte type interpretation, which should be read as three consecutive bytes.

Many of the QImage formats are 32-bit with a type interpretation of UnsignedInteger , which should be read as a single unsigned int.

For FloatingPoint formats like Format_RGBA16FPx4 or Format_RGBA32FPx4 the type is determined based on the size of the individual color/alpha channels, with qfloat16 for 16-bit half-float formats and float for 32-bit full-float formats.

See also

byteOrder()

yellowSize()
Return type:

int

Accessor function for the yellow color channel.

yuvLayout()
Return type:

YUVLayout

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.