A Pixel Format Guide (to the galaxy) – Update
October 5, 2017
A few weeks ago I introduced the Pixel Format Guide — a collection of documents and the accompanying pfg tool which aim to help people navigate the wilderness of pixel format definitions. In this post I will list the most exciting improvements that have been made since the original announcement.
New pixel format families
The core mission of the Pixel Format Guide is to become a comprehensive reference for pixel format definitions. Therefore, it's no surprise that I have put a lot of effort into adding more pixel format families. At the time the previous post was written, the Pixel Format Guide supported 3 formats: Vulkan, OpenGL and Wayland-DRM. Since then, I have added the Cairo, DirectFB, Pixman, SDL2 and V4L2 pixel format families, bringing the total number of supported families to 8 and the total number of supported pixel format definitions to 459!
Bit indices
While working with packed pixel formats, I noticed that the ordering of the component bits is sometimes difficult to figure out. This happens especially when the bits of a component are split between multiple bytes, like, for example, in an RGB565 16-bit format:
Format: SDL_PIXELFORMAT_RGB565
Described as: Native 16-bit type
Native type: M L
RRRRRGGGGGGBBBBB
Memory little-endian: 0 1
M L M L
GGGBBBBB RRRRRGGG
Memory big-endian: 0 1
M L M L
RRRRRGGG GGGBBBBB
Each byte in memory holds 3 bits of the G component, but it's not easy to tell exactly which bits are in each byte. To fix this, the latest version of the pfg tool introduces component bit indices. Every component bit is now accompanied by its index, making the bit order crystal clear:
Format: SDL_PIXELFORMAT_RGB565
Described as: Native 16-bit type
Native type: M L
R₄R₃R₂R₁R₀G₅G₄G₃G₂G₁G₀B₄B₃B₂B₁B₀
Memory little-endian: 0 1
M L M L
G₂G₁G₀B₄B₃B₂B₁B₀ R₄R₃R₂R₁R₀G₅G₄G₃
Memory big-endian: 0 1
M L M L
R₄R₃R₂R₁R₀G₅G₄G₃ G₂G₁G₀B₄B₃B₂B₁B₀
If you prefer not to see the bit indices you can use the --hide-bit-indices flag.
Discovery of compatible pixel formats
The inspiration for the Pixel Format Guide was a series of frustrating experiences trying to manually match pixel formats with other, compatible pixel formats from different families. The latest version of the pfg tool finally includes support for automating such operations, in the form of the find-compatible command.
With the find-compatible command, discovering which OpenGL formats are compatible with the PIXMAN_b5g6r5 format is now as easy as:
$ python3 -m pfg find-compatible PIXMAN_b5g6r5 opengl
Format: PIXMAN_b5g6r5
Is compatible on all systems with:
GL_RGB+GL_UNSIGNED_SHORT_5_6_5_REV
GL_RGB_INTEGER+GL_UNSIGNED_SHORT_5_6_5_REV
Is compatible on little-endian systems with:
Is compatible on big-endian systems with
Similarly, to find out which SDL2 formats are compatible with the VK_FORMAT_R8G8B8A8_UNORM format, you can run:
$ 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
Listing supported pixel formats and families
The pfg tool now supports the list-formats and list-families commands. The former lists the supported pixel formats for the specified family, while the latter lists all the supported pixel format families. These commands can be very useful when writing scripts involving the pfg tool.
As an example, with the list-formats command you can find which OpenGL formats are compatible with each Cairo format by running:
; do ; done
I hope you enjoy the improvements!
Once again, I would like to thank my employer, Collabora, for sponsoring my work on the Pixel Format Guide as an R&D project.