QPixelFormat Class
QPixelFormat 是一个用于描述图形缓冲区中不同像素布局的类。更多
| Header： | #include <QPixelFormat> |
| CMake.QPixelFormat | find_package(Qt6 REQUIRED COMPONENTS Gui)target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake： | QT += gui |
公共类型
| enum | AlphaPosition { AtBeginning, AtEnd } |
| enum | AlphaPremultiplied { NotPremultiplied, Premultiplied } |
| enum | AlphaUsage { IgnoresAlpha, UsesAlpha } |
| enum | ByteOrder { LittleEndian, BigEndian, CurrentSystemEndian } |
| enum | ColorModel { RGB, BGR, Indexed, Grayscale, CMYK, …, Alpha } |
| enum | TypeInterpretation { UnsignedInteger, UnsignedShort, UnsignedByte, FloatingPoint } |
| enum | YUVLayout { YUV444, YUV422, YUV411, YUV420P, YUV420SP, …, Y16 } |
公共函数
| QPixelFormat() | |
| QPixelFormat(QPixelFormat::ColorModel colorModel, uchar firstSize, uchar secondSize, uchar thirdSize, uchar fourthSize, uchar fifthSize, uchar alphaSize, QPixelFormat::AlphaUsage alphaUsage, QPixelFormat::AlphaPosition alphaPosition, QPixelFormat::AlphaPremultiplied premultiplied, QPixelFormat::TypeInterpretation typeInterpretation, QPixelFormat::ByteOrder byteOrder = CurrentSystemEndian, uchar subEnum = 0) | |
| QPixelFormat::AlphaPosition | alphaPosition() const |
| uchar | alphaSize() const |
| QPixelFormat::AlphaUsage | alphaUsage() const |
| uchar | bitsPerPixel() const |
| uchar | blackSize() const |
| uchar | blueSize() const |
| uchar | brightnessSize() const |
| QPixelFormat::ByteOrder | byteOrder() const |
| uchar | channelCount() const |
| QPixelFormat::ColorModel | colorModel() const |
| uchar | cyanSize() const |
| uchar | greenSize() const |
| uchar | hueSize() const |
| uchar | lightnessSize() const |
| uchar | magentaSize() const |
| QPixelFormat::AlphaPremultiplied | premultiplied() const |
| uchar | redSize() const |
| uchar | saturationSize() const |
| QPixelFormat::TypeInterpretation | typeInterpretation() const |
| uchar | yellowSize() const |
| QPixelFormat::YUVLayout | yuvLayout() const |
相关非成员
| 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) |
| QPixelFormat | qPixelFormatGrayscale(uchar channelSize, QPixelFormat::TypeInterpretation typeInterpretation = QPixelFormat::UnsignedInteger) |
| QPixelFormat | qPixelFormatHsl(uchar channelSize, uchar alphaSize = 0, QPixelFormat::AlphaUsage alphaUsage = QPixelFormat::IgnoresAlpha, QPixelFormat::AlphaPosition alphaPosition = QPixelFormat::AtBeginning, QPixelFormat::TypeInterpretation typeInterpretation = QPixelFormat::FloatingPoint) |
| QPixelFormat | qPixelFormatHsv(uchar channelSize, uchar alphaSize = 0, QPixelFormat::AlphaUsage alphaUsage = QPixelFormat::IgnoresAlpha, QPixelFormat::AlphaPosition alphaPosition = QPixelFormat::AtBeginning, QPixelFormat::TypeInterpretation typeInterpretation = QPixelFormat::FloatingPoint) |
| 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) |
| 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) |
详细说明
在 Qt 中，经常需要表示图形缓冲区中的像素布局。在内部，QPixelFormat 将所有内容存储在一个 64 位数据结构中。这提供了性能，但也有一些限制。
QPixelFormat 可描述 5 个颜色通道和 1 个 alpha 通道，每个通道可使用 6 位来描述颜色通道的大小。
Alpha 通道的位置用一个单独的枚举来描述。这样就可以描述QImage 格式（如 ARGB32），也可以描述典型的 OpenGL 格式（如 RBGA8888）。
像素的读取方式由TypeInterpretation 枚举决定。该枚举描述了是按字节读取颜色值，还是将像素作为一个完整的 int 读取，然后进行屏蔽。
目前还不支持描述 YUV 宏像素。因此，我们制作了一个 YUV 格式列表。当 QPixelFormat 描述 YUV 格式时，bitsPerPixel 值是由 YUV 布局枚举推导出来的。此外，除了存储bitsPerPixel 值的第五个颜色通道外，其他颜色通道都应设置为零。
另请参阅 TypeInterpretation 。
成员类型文档
enum QPixelFormat::AlphaPosition
该枚举类型用于描述 alpha 通道相对于颜色通道的位置。
| 常数 | 值 | 说明 |
|---|---|---|
QPixelFormat::AtBeginning | 0 | 将 alpha 通道放在颜色通道的前面。例如 ARGB。 |
QPixelFormat::AtEnd | 1 | Alpha 通道将放在颜色通道的后面。例如 RGBA。 |
enum QPixelFormat::AlphaPremultiplied
该枚举类型描述了是否将 alpha 通道乘以颜色通道的布尔状态。
| 常量 | 值 | 说明 |
|---|---|---|
QPixelFormat::NotPremultiplied | 0 | 不将 alpha 通道乘以颜色通道。 |
QPixelFormat::Premultiplied | 1 | alpha 通道与颜色通道相乘。 |
enum QPixelFormat::AlphaUsage
该枚举描述了是否使用 alpha 通道。有时，像素格式会有 alpha 通道的大小，但实际上像素格式并不使用 alpha 通道。例如 RGB32 就是这样一种格式。RGB 通道各为 8 位，没有阿尔法通道。但每个像素的完整大小是 32。因此，alpha 通道的大小是 8，但 alpha 通道会被忽略。需要注意的是，在这种情况下，alpha 通道的位置非常重要。
| 常数 | 值 | 说明 |
|---|---|---|
QPixelFormat::IgnoresAlpha | 1 | 不使用 alpha 通道。 |
QPixelFormat::UsesAlpha | 0 | 使用了 alpha 通道。 |
enum QPixelFormat::ByteOrder
该枚举描述像素格式的字节序（ByteOrder）。该枚举大多会被忽略，但在 YUV 格式中也有一些用例。BGR 格式有自己的颜色模型，不应在 RGB 格式中使用相反的字节序来描述。
| 常数 | 值 | 说明 |
|---|---|---|
QPixelFormat::LittleEndian | 0 | 字节顺序为小字节。 |
QPixelFormat::BigEndian | 1 | 字节顺序为大端。 |
QPixelFormat::CurrentSystemEndian | 2 | 该枚举不会被存储，但会在构造函数中转换为与当前系统枚举相匹配的 endian 枚举。 |
enum QPixelFormat::ColorModel
该枚举类型用于描述像素格式的颜色模型。5.5 中添加了 Alpha。
| 常量 | 值 | 说明 |
|---|---|---|
QPixelFormat::RGB | 0 | 颜色模型为 RGB。 |
QPixelFormat::BGR | 1 | 从逻辑上讲，它是 RGB 的反向 endian 版本。不过，为了便于使用，它有自己的模型。 |
QPixelFormat::Indexed | 2 | 颜色模型使用调色板。 |
QPixelFormat::Grayscale | 3 | 颜色模型是灰度。 |
QPixelFormat::CMYK | 4 | 色彩模型是 CMYK。 |
QPixelFormat::HSL | 5 | 颜色模型是 HSL。 |
QPixelFormat::HSV | 6 | 色彩模型是 HSV。 |
QPixelFormat::YUV | 7 | 颜色模型是 YUV。 |
QPixelFormat::Alpha | 8 | 没有颜色模型，只使用 alpha。 |
enum QPixelFormat::TypeInterpretation
该枚举描述了如何解释每个像素。是将像素作为一个完整的 32 位无符号整数读取，然后屏蔽掉每个通道，还是将每个字节作为无符号字符值读取。通常情况下，QImage 格式将一个像素解释为一个无符号整数，然后屏蔽掉颜色通道。另一方面，OpenGL 通常将像素解释为 "一个字节接一个字节"，即无符号字节。
QImage 此外，OpenGL 也有 Format_RGBA8888 格式（及其衍生格式），其中像素被解释为无符号字节。OpenGL 具有扩展功能，可以以无符号整数格式上传像素缓冲区。
上图显示了内存中以无符号整数格式读取的 ARGB 像素。但是，如果在 little endian 系统中逐字节读取该像素，第一个字节将是包含 B 通道的字节。下一个字节是 G 通道，然后是 R 通道，最后是 A 通道。这表明，在小内码系统中，如何解释每个像素对于整数格式非常重要。而在大端系统中，情况并非如此。
| 常数 | 值 |
|---|---|
QPixelFormat::UnsignedInteger | 0 |
QPixelFormat::UnsignedShort | 1 |
QPixelFormat::UnsignedByte | 2 |
QPixelFormat::FloatingPoint | 3 |
enum QPixelFormat::YUVLayout
YUV 不通过描述颜色通道的大小来表示。这是因为 YUV 通常使用宏像素，使得单独颜色通道的概念无效。相反，本枚举描述了不同的 YUV 布局。
| 常量 | 值 |
|---|---|
QPixelFormat::YUV444 | 0 |
QPixelFormat::YUV422 | 1 |
QPixelFormat::YUV411 | 2 |
QPixelFormat::YUV420P | 3 |
QPixelFormat::YUV420SP | 4 |
QPixelFormat::YV12 | 5 |
QPixelFormat::UYVY | 6 |
QPixelFormat::YUYV | 7 |
QPixelFormat::NV12 | 8 |
QPixelFormat::NV21 | 9 |
QPixelFormat::IMC1 | 10 |
QPixelFormat::IMC2 | 11 |
QPixelFormat::IMC3 | 12 |
QPixelFormat::IMC4 | 13 |
QPixelFormat::Y8 | 14 |
QPixelFormat::Y16 | 15 |
成员函数文档
[constexpr noexcept] QPixelFormat::QPixelFormat()
创建空像素格式。该格式映射到QImage::Format_Invalid 。
[constexpr noexcept] QPixelFormat::QPixelFormat(QPixelFormat::ColorModel colorModel, uchar firstSize, uchar secondSize, uchar thirdSize, uchar fourthSize, uchar fifthSize, uchar alphaSize, QPixelFormat::AlphaUsage alphaUsage, QPixelFormat::AlphaPosition alphaPosition, QPixelFormat::AlphaPremultiplied premultiplied, QPixelFormat::TypeInterpretation typeInterpretation, QPixelFormat::ByteOrder byteOrder = CurrentSystemEndian, uchar subEnum = 0)
创建一个 QPixelFormat，并将其数据分配给属性。colorModel 将被放入一个 4 位长的缓冲区。
firstSize secondSize thirdSize fourthSize fifthSize alphaSize 所有这些都是为了表示通道的大小。通道的不同用途取决于colorModel 。对于 RGB，firstSize 表示红色通道。对于 CMYK，它代表青色通道的值。
alphaUsage 代表是否使用 alpha 通道。
alphaPosition 是 alpha 通道的位置。
premultiplied 表示 alpha 通道是否已与颜色通道相乘。
typeInterpretation 是像素的解释方式。
byteOrder 表示像素格式的字节序。默认值为 。CurrentSystemEndian
subEnum 用于需要通过提供额外枚举来存储一些额外信息的 colorModels。默认值为 0。
[constexpr noexcept] QPixelFormat::AlphaPosition QPixelFormat::alphaPosition() const
alphaPosition 的访问函数。
[constexpr noexcept] uchar QPixelFormat::alphaSize() const
alpha 通道大小的访问函数。
[constexpr noexcept] QPixelFormat::AlphaUsage QPixelFormat::alphaUsage() const
alphaUsage 的访问函数。
[constexpr noexcept] uchar QPixelFormat::bitsPerPixel() const
每个像素所用比特的访问函数。该函数返回颜色通道的总和 + Alpha 通道的大小。
[constexpr noexcept] uchar QPixelFormat::blackSize() const
黑色/关键色通道的辅助功能。
[constexpr noexcept] uchar QPixelFormat::blueSize() const
蓝色通道大小的访问函数。
[constexpr noexcept] uchar QPixelFormat::brightnessSize() const
亮度通道尺寸的访问函数。
[constexpr noexcept] QPixelFormat::ByteOrder QPixelFormat::byteOrder() const
字节顺序几乎总是设置为当前系统的字节顺序。不过，这对描述某些 YUV 格式可能有用。该函数不应返回QPixelFormat::CurrentSystemEndian ，因为该值在构造函数中被转换为一个 endian 值。
[constexpr noexcept] uchar QPixelFormat::channelCount() const
获取通道数的访问函数。通道数由大小大于 0 的颜色通道和大小大于 0 的阿尔法通道推导得出。
[constexpr noexcept] QPixelFormat::ColorModel QPixelFormat::colorModel() const
获取 colorModel 的访问函数。
[constexpr noexcept] uchar QPixelFormat::cyanSize() const
青色通道的访问函数。
[constexpr noexcept] uchar QPixelFormat::greenSize() const
绿色通道大小的访问函数。
[constexpr noexcept] uchar QPixelFormat::hueSize() const
色调通道大小的访问函数。
[constexpr noexcept] uchar QPixelFormat::lightnessSize() const
亮度通道大小的访问函数。
[constexpr noexcept] uchar QPixelFormat::magentaSize() const
洋红颜色通道的访问函数。
[constexpr noexcept] QPixelFormat::AlphaPremultiplied QPixelFormat::premultiplied() const
AlphaPremultiplied 枚举的访问函数。这表示是否将 alpha 通道乘以颜色通道。
[constexpr noexcept] uchar QPixelFormat::redSize() const
红色通道大小的访问函数。
[constexpr noexcept] uchar QPixelFormat::saturationSize() const
饱和通道大小的访问函数。
[constexpr noexcept] QPixelFormat::TypeInterpretation QPixelFormat::typeInterpretation() const
颜色通道或像素类型表示的访问函数。
另请参见 TypeInterpretation 。
[constexpr noexcept] uchar QPixelFormat::yellowSize() const
黄色通道的访问函数。
[constexpr noexcept] QPixelFormat::YUVLayout QPixelFormat::yuvLayout() const
YUVLayout 的访问函数。由于 YUV 颜色模型使用宏像素，因此很难描述 YUV 像素格式的颜色通道。相反，像素的布局是以枚举形式存储的。
相关非会员
[constexpr noexcept] QPixelFormat qPixelFormatAlpha(uchar channelSize, QPixelFormat::TypeInterpretation typeInterpretation = QPixelFormat::UnsignedInteger)
用于创建 Alpha 格式的构造函数。通过向channelSize 传递 1，可以描述遮罩格式。也可以通过向channelSize 传递 8 和向typeInterpretation 传递FloatingPoint ，使用双倍来描述每个像素，从而定义非常精确的 Alpha 格式。
另请参见 QPixelFormat::TypeInterpretation 。
[constexpr noexcept] QPixelFormat qPixelFormatCmyk(uchar channelSize, uchar alphaSize = 0, QPixelFormat::AlphaUsage alphaUsage = QPixelFormat::IgnoresAlpha, QPixelFormat::AlphaPosition alphaPosition = QPixelFormat::AtBeginning, QPixelFormat::TypeInterpretation typeInterpretation = QPixelFormat::UnsignedInteger)
用于创建 CMYK 格式的构造函数。通道数将为 4 或 5，取决于alphaSize 是否大于 0。CMYK 颜色通道将全部设置为channelSize 的值。
alphaUsage alphaPosition 和typeInterpretation 都可以通过同名访问器访问。
另请参阅 QPixelFormat::TypeInterpretation 。
[constexpr noexcept] QPixelFormat qPixelFormatGrayscale(uchar channelSize, QPixelFormat::TypeInterpretation typeInterpretation = QPixelFormat::UnsignedInteger)
用于创建灰度格式的构造函数。单色格式可以通过向channelSize 传递 1 来描述。也可以通过向channelSize 传递 8 和向typeInterpretation 传递FloatingPoint 来定义非常精确的灰度格式，使用双倍来描述每个像素。
另请参阅 QPixelFormat::TypeInterpretation 。
[constexpr noexcept] QPixelFormat qPixelFormatHsl(uchar channelSize, uchar alphaSize = 0, QPixelFormat::AlphaUsage alphaUsage = QPixelFormat::IgnoresAlpha, QPixelFormat::AlphaPosition alphaPosition = QPixelFormat::AtBeginning, QPixelFormat::TypeInterpretation typeInterpretation = QPixelFormat::FloatingPoint)
用于创建 HSL 格式的构造函数。通道数将为 3 或 4，取决于alphaSize 是否大于 0。
channelSize 将 和 设置为相同的值。hueSize saturationSize lightnessSize
alphaUsage alphaPosition 和typeInterpretation 都可以通过同名访问器访问。
[constexpr noexcept] QPixelFormat qPixelFormatHsv(uchar channelSize, uchar alphaSize = 0, QPixelFormat::AlphaUsage alphaUsage = QPixelFormat::IgnoresAlpha, QPixelFormat::AlphaPosition alphaPosition = QPixelFormat::AtBeginning, QPixelFormat::TypeInterpretation typeInterpretation = QPixelFormat::FloatingPoint)
用于创建 HSV 格式的构造函数。通道数将为 3 或 4，取决于alphaSize 是否大于 0。
channelSize 将 和 设置为相同的值。hueSize saturationSize brightnessSize
alphaUsage alphaPosition 和typeInterpretation 都可以通过同名访问器访问。
[constexpr noexcept] 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)
redSize greenSize blueSize 表示每个颜色通道的大小。alphaSize 描述 alpha 通道的大小，其位置用alphaPosition 描述。alphaUsage 用于确定是否使用 alpha 通道。将 alpha 通道大小设为 8，并将alphaUsage 设为IgnoresAlpha ，就可以创建 32 位格式，其中 rgb 通道只使用 24 位组合。premultiplied typeInterpretation 可通过同名访问器访问。
另请参见 QPixelFormat::TypeInterpretation 。
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)
构造函数，用于创建QPixelFormat ，用yuvLayout 描述 YUV 格式。alphaSize 描述潜在的 alpha 通道的大小，用alphaPosition 描述其位置。第一""第二"...... "第五 "通道均设置为 0。alphaUsage premultiplied typeInterpretation 和byteOrder 将与其他格式一样工作。
© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
