afrantzis/pixel-format-guide

Pixel Format Guide

Welcome to the Pixel Format Guide Tool

The Pixel Format Guide Tool is a python program that describes how the components of various pixels formats are laid out in memory.

This tool is part of the Pixel Format Guide.

Development of the Pixel Format Guide is sponsored by Collabora Ltd.

How to run the Pixel Format Guide Tool

Run with:

 $ python3 -m pfg describe [OPTIONS...] [FORMAT]
 $ python3 -m pfg find-compatible [OPTIONS...] [FORMAT] [FAMILY]
 $ python3 -m pfg document [FAMILY]
 $ python3 -m pfg list-families
 $ python3 -m pfg list-formats [FAMILY]

Examples of using the describe command:

$ python3 -m pfg describe GL_RGBA+GL_UNSIGNED_INT_2_10_10_10_REV
Format:               GL_RGBA+GL_UNSIGNED_INT_2_10_10_10_REV
Component data type:  UNORM
Described as:         Native 32-bit type
Native type:          M                                                              L
                      A₁A₀B₉B₈B₇B₆B₅B₄B₃B₂B₁B₀G₉G₈G₇G₆G₅G₄G₃G₂G₁G₀R₉R₈R₇R₆R₅R₄R₃R₂R₁R₀
Memory little-endian: 0                1                2                3
                      M              L M              L M              L M              L
                      R₇R₆R₅R₄R₃R₂R₁R₀ G₅G₄G₃G₂G₁G₀R₉R₈ B₃B₂B₁B₀G₉G₈G₇G₆ A₁A₀B₉B₈B₇B₆B₅B₄
Memory big-endian:    0                1                2                3
                      M              L M              L M              L M              L
                      A₁A₀B₉B₈B₇B₆B₅B₄ B₃B₂B₁B₀G₉G₈G₇G₆ G₅G₄G₃G₂G₁G₀R₉R₈ R₇R₆R₅R₄R₃R₂R₁R₀

$ python3 -m pfg describe VK_FORMAT_A2R10G10B10_SINT_PACK32
Format:               VK_FORMAT_A2R10G10B10_SINT_PACK32
Component data type:  SINT
Described as:         Native 32-bit type
Native type:          M                                                              L
                      A₁A₀R₉R₈R₇R₆R₅R₄R₃R₂R₁R₀G₉G₈G₇G₆G₅G₄G₃G₂G₁G₀B₉B₈B₇B₆B₅B₄B₃B₂B₁B₀
Memory little-endian: 0                1                2                3
                      M              L M              L M              L M              L
                      B₇B₆B₅B₄B₃B₂B₁B₀ G₅G₄G₃G₂G₁G₀B₉B₈ R₃R₂R₁R₀G₉G₈G₇G₆ A₁A₀R₉R₈R₇R₆R₅R₄
Memory big-endian:    0                1                2                3
                      M              L M              L M              L M              L
                      A₁A₀R₉R₈R₇R₆R₅R₄ R₃R₂R₁R₀G₉G₈G₇G₆ G₅G₄G₃G₂G₁G₀B₉B₈ B₇B₆B₅B₄B₃B₂B₁B₀

$ python3 -m pfg describe WL_DRM_FORMAT_ARGB8888
Format:               WL_DRM_FORMAT_ARGB8888
Component data type:  UNORM
Described as:         Bytes in memory
Memory little-endian: 0                1                2                3
                      M              L M              L M              L M              L
                      B₇B₆B₅B₄B₃B₂B₁B₀ G₇G₆G₅G₄G₃G₂G₁G₀ R₇R₆R₅R₄R₃R₂R₁R₀ A₇A₆A₅A₄A₃A₂A₁A₀
Memory big-endian:    0                1                2                3
                      M              L M              L M              L M              L
                      B₇B₆B₅B₄B₃B₂B₁B₀ G₇G₆G₅G₄G₃G₂G₁G₀ R₇R₆R₅R₄R₃R₂R₁R₀ A₇A₆A₅A₄A₃A₂A₁A₀

$ python3 -m pfg describe --hide-bit-indices SDL_PIXELFORMAT_RGB565
Format:               SDL_PIXELFORMAT_RGB565
Component data type:  UNORM
Described as:         Native 16-bit type
Native type:          M              L
                      RRRRRGGGGGGBBBBB
Memory little-endian: 0        0
                      M      L M      L
                      GGGBBBBB RRRRRGGG
Memory big-endian:    0        0
                      M      L M      L
                      RRRRRGGG GGGBBBBB

Examples of using the find-compatible command:

$ python3 -m pfg find-compatible VK_FORMAT_R8G8B8A8_UNORM sdl2
Format: VK_FORMAT_R8G8B8A8_UNORM
Is compatible on all systems with:
        SDL_PIXELFORMAT_RGBA32
Is compatible on little-endian systems with:
        SDL_PIXELFORMAT_ABGR8888
Is compatible on big-endian systems with:
        SDL_PIXELFORMAT_RGBA8888

$ python3 -m pfg find-compatible GL_RGB+GL_UNSIGNED_SHORT_5_6_5_REV pixman
Format: GL_RGB+GL_UNSIGNED_SHORT_5_6_5_REV
Is compatible on all systems with:
        PIXMAN_b5g6r5
Is compatible on little-endian systems with:
Is compatible on big-endian systems with:

$ python3 -m pfg find-compatible --treat-x-as-a PIXMAN_x8r8g8b8 wayland_drm
Format: PIXMAN_x8r8g8b8
Is compatible on all systems with:
Is compatible on little-endian systems with:
        WL_DRM_FORMAT_XRGB8888
        WL_DRM_FORMAT_ARGB8888
Is compatible on big-endian systems with:
        WL_DRM_FORMAT_BGRX8888
        WL_DRM_FORMAT_BGRA8888

Examples of using the document command:

$ python3 -m pfg document vulkan
# Vulkan pixel formats
...

$ python3 -m pfg document wayland_drm
# Wayland-drm pixel formats
...

Examples of using the list-families command:

$ python3 -m pfg list-families
cairo
opengl
pixman
...

Examples of using the list-formats command:

$ python3 -m pfg list-formats cairo
CAIRO_FORMAT_ARGB32
CAIRO_FORMAT_RGB24
...

Contributing to the Pixel Format Guide Tool

To add support for a new pixel format family (let's call it family), do the following:

• Add some tests for typical pixel formats definitions in the family in tests/test_family.py. Use one of the existing test files as a template.

• Implement the describe method in a new pfg/family.py file. Use one of the existing files as a template.

• Implement the formats method in the pfg/family.py file. Use one of the existing files as a template.

• Implement the document method in the pfg/family.py file, by creating a docs/family.md and returning its contents (use the util.read_documentation helper).

• Import the family module and add it to the list of families in pfg/commands.py.

• Add a link to the new family document file in docs/index.md.

• Run python3 -m unittest discover and ensure all tests pass.

pixel-format-guide's Issues

Distinguish premultiplied alpha vs non-premultiplied alpha

Feature request: have the pfg tool and/or the docs state whether various formats-with-alpha use premultiplied (associated) or non-premultiplied (unassociated) alpha.

For example, https://www.cairographics.org/manual/cairo-Image-Surfaces.html#cairo-format-t states that CAIRO_FORMAT_ARGB32 uses premultiplied alpha. Quoting from that link: "50% transparent red is 0x80800000, not 0x80ff0000".

Is CAIRO_FORMAT_ARGB32 equivalent to SDL_PIXELFORMAT_ARGB8888 (in terms of alpha semantics, not just byte order) or would I have to do a "premul to non-premul" conversion? I think that's the sort of question that's within the Pixel Format Guide's scope.

add pixman, skia formats

For example, /usr/include/pixman-1/pixman.h defines "PIXMAN_a8r8g8b8" but when combining e.g. cairo with other libraries (and their pixel format names), I can never remember what that means in terms of native vs memory and endianness.

Skia is also used in e.g. the chromium web browser, and of course, it has its own pixel format naming convention.

bgrabitmap

some useful info may be in source code of https://github.com/bgrabitmap/bgrabitmap/

see https://github.com/bgrabitmap/bgrabitmap/blob/47628d6de2122dbfe5b26b80ba27e32d1c74435b/bgrabitmap/bgrapixel.inc

Add GStreamer formats

Not yet clear to me which endianness they use.

QImage::Format_ARGB8555_Premultiplied

From https://afrantzis.com/pixel-format-guide/qt.html:

"The pixel is represented by a 24-bit value, with the most significant bit unused, A in bits 15-22, R in bits 10-14, G in bits 5-9 and B in bits 0-4..."

Looking into Qt source code, it appears the alpha byte actually comes first aligned to a whole byte, and the unused bit is just beyond red (yeah, this format is rather inconsistent with Qt's other names 😑).

Bit stream layout

byte |[      0      ] [      1      ] [      2      ]|
bit  |0 1 2 3 4 5 6 7|0 1 2 3 4|5 6 7 0 1|2 3 4 5 6|7|
     |[   alpha     ]|[ blue  ]|[ green ]|[  red  ]|0|

Motivation

I'm working on a generic pixel format viewer, supporting formats declaratively rather than hard-coded code (and so your project has been quite useful ☺ - thanks). e.g.

Qt_QImage_Format_ARGB8555_Premultiplied:{
    alphaPremulUnorm8
    blueUnorm5
    greenUnorm5
    redUnorm5
    unused1
    notes:{
        "The image is stored using a premultiplied 24-bit ARGB format (8,5,5,5,_)."
        "The documentation and actual code mismatch, as the alpha byte actually comes first, despite what the format name would imply."
    }
}

References

https://github.com/openwebos/qt/blob/master/src/gui/painting/qdrawhelper_p.h#L1121

{
    v = quint32p(v);
    data[0] = qAlpha(v);
    const int r = qRed(v);
    const int g = qGreen(v);
    const int b = qBlue(v);
    data[1] = ((g << 2) & 0xe0) | (b >> 3);
    data[2] = ((r >> 1) & 0x7c) | (g >> 6);
}

https://github.com/openwebos/qt/blob/master/src/gui/image/qimage.cpp#L5018

        for (int i = 0; i < d->height; i++) {
            const quint8 *p = constScanLine(i);
            quint8 *q = res.scanLine(i);
            const quint8 *end = p + d->width * sizeof(qargb8555);
            while (p < end) {
                q[0] = p[0];
                q[1] = (p[1] & 0xe0) | (p[2] >> 2);
                q[2] = (p[2] & 0x03) | ((p[1] << 2) & 0x7f);
                p += sizeof(qargb8555);
                q += sizeof(qargb8555);
            }
        }

This applies to qargb8565 too:

https://github.com/openwebos/qt/blob/master/src/gui/painting/qdrawhelper_p.h#L822

Want me to create a PR?