drm/fourcc: document format naming scheme
Subsystems (2)
PATCH 1/1 drm/fourcc: document format naming scheme
When adding a new format, one needs to pick a name and fourcc. This is not always an easy task: figuring out why current formats are named this way is tricky.
Document current practice to make that process easier.
See previous discussion at:
https://lore.kernel.org/all/aocdbgbLe5WhUEOGeLg3P7fRDM8i72H9zBuUnoAjjsuvBLfMPofrPtaUEjII_43KXf1wCbv1G9UutJKMkWLaEcBSnrlUV78Wrhu6l_Z0xi8=@emersion.fr/
--- include/uapi/drm/drm_fourcc.h | 39 +++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+)
include/uapi/drm/drm_fourcc.h +39 -0
@@ -38,6 +38,45 @@ extern "C" {* fourcc code, a Format Modifier may optionally be provided, in order to * further describe the buffer's format - for example tiling or compression. * +* Formats +* ------- +* +* Formats describe how a buffer is interpreted to decode pixel color and alpha +* values. Formats are uniquely identified by a four character code (fourcc). +* Memory layout is always described in little-endian order. +* +* The following channels are defined: +* +* - "R", red +* - "G", green +* - "B", blue +* - "A", alpha +* - "C", color index (for paletted formats) +* - "D", darkness (inverse relationship between channel value and brightness) +* - "Y", luma/brightness +* - "U", blue-difference chroma (Cb) +* - "V", red-difference chroma (Cr) +* - "X", a placeholder for undefined/unused contents +* +* Formats using the RGB color model have names made up of a list of channels +* followed by the number of bits used by each channel, respectively. Any +* padding is explicitly indicated by the special "X" channel. Channels use +* unsigned integers, except when suffixed by "F" to indicate IEEE 754 floats. +* An underscore "_" can be used to delimit planes. +* +* Multi-planar YUV formats use the following naming scheme for the most part: +* +* - The first letter indicates the number of planes, channel alignment and +* ordering. It is should not be a letter already used to denote a channel. +* - The first digit indicates chroma sub-sampling: 0 for 2x2, 2 for 2x1, 4 for +* none. +* - The two other digits indicate bits for the Y channel. If the Cb channel +* comes before Cr, the digits are reversed. +* +* Fourccs are allocated on a first-come, first-served basis. New format names +* and fourccs should try to use the same naming scheme as existing, similar +* formats. +* * Format Modifiers * ---------------- *
Signature · 1 line
2.54.0
Hi Simon,
Thank you for the patch.
Quoted 29 lines · Simon Ser
When adding a new format, one needs to pick a name and fourcc. This is not always an easy task: figuring out why current formats are named this way is tricky.
Document current practice to make that process easier.
See previous discussion at:
https://lore.kernel.org/all/aocdbgbLe5WhUEOGeLg3P7fRDM8i72H9zBuUnoAjjsuvBLfMPofrPtaUEjII_43KXf1wCbv1G9UutJKMkWLaEcBSnrlUV78Wrhu6l_Z0xi8=@emersion.fr/Signed-off-by Simon Ser <[email protected]>Cc Pekka Paalanen <[email protected]>Cc Tomi Valkeinen <[email protected]>Cc Maarten Lankhorst <[email protected]>Cc Maxime Ripard <[email protected]>Cc Thomas Zimmermann <[email protected]>Cc David Airlie <[email protected]>Cc Simona Vetter <[email protected]>Cc Laurent Pinchart <[email protected]>Cc Dmitry Baryshkov <[email protected]>Cc Daniel Stone <[email protected]>--- include/uapi/drm/drm_fourcc.h | 39 +++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+)include/uapi/drm/drm_fourcc.h +0
-0
include/uapi/drm/drm_fourcc.h extern "C" { · line 46
Quoted 9 lines
include/uapi/drm/drm_fourcc.h +6
-0@@ -38,6 +38,45 @@ extern "C" {* fourcc code, a Format Modifier may optionally be provided, in order to * further describe the buffer's format - for example tiling or compression. * +* Formats +* ------- +* +* Formats describe how a buffer is interpreted to decode pixel color and alpha +* values. Formats are uniquely identified by a four character code (fourcc). +* Memory layout is always described in little-endian order.
This sentence may be a bit vague, especially given that we have the DRM_FORMAT_BIG_ENDIAN() macro.
Quoted 14 lines
include/uapi/drm/drm_fourcc.h +14
-0+* +* The following channels are defined: +* +* - "R", red +* - "G", green +* - "B", blue +* - "A", alpha +* - "C", color index (for paletted formats) +* - "D", darkness (inverse relationship between channel value and brightness) +* - "Y", luma/brightness +* - "U", blue-difference chroma (Cb) +* - "V", red-difference chroma (Cr) +* - "X", a placeholder for undefined/unused contents +*
include/uapi/drm/drm_fourcc.h extern "C" { · line 70
Quoted 10 lines
include/uapi/drm/drm_fourcc.h +10
-0+* Formats using the RGB color model have names made up of a list of channels +* followed by the number of bits used by each channel, respectively. Any +* padding is explicitly indicated by the special "X" channel. Channels use +* unsigned integers, except when suffixed by "F" to indicate IEEE 754 floats. +* An underscore "_" can be used to delimit planes. +* +* Multi-planar YUV formats use the following naming scheme for the most part: +* +* - The first letter indicates the number of planes, channel alignment and +* ordering. It is should not be a letter already used to denote a channel.
s/It is/It/
include/uapi/drm/drm_fourcc.h extern "C" { · line 72
Quoted 2 lines
include/uapi/drm/drm_fourcc.h +2
-0+* - The first digit indicates chroma sub-sampling: 0 for 2x2, 2 for 2x1, 4 for +* none.
We also have 4x4 and 4x1 sub-sampled formats, it would be good to document them.
Quoted 10 lines
include/uapi/drm/drm_fourcc.h +7
-0+* - The two other digits indicate bits for the Y channel. If the Cb channel +* comes before Cr, the digits are reversed. +* +* Fourccs are allocated on a first-come, first-served basis. New format names +* and fourccs should try to use the same naming scheme as existing, similar +* formats. +* * Format Modifiers * ---------------- *
Signature · 3 lines
Regards, Laurent Pinchart
Quoted 4 lines · Laurent Pinchart
Quoted 1 line
+ * Memory layout is always described in little-endian order.
This sentence may be a bit vague, especially given that we have the
DRM_FORMAT_BIG_ENDIAN()macro.
Right, that macro is almost never used… I see it only used for XRGB1555 and RGB565. Someone recommended against using it, I don't remember who.
See also:
* Note that the DRM_FORMAT_BIG_ENDIAN flag should only be used in
* case the format can't be specified otherwise, so we don't end up
* with two values describing the same format.
Quoted 5 lines
Quoted 2 lines
+ * - The first digit indicates chroma sub-sampling: 0 for 2x2, 2 for 2x1, 4 for
+ * none.We also have 4x4 and 4x1 sub-sampled formats, it would be good to document them.
Yeah, but these use a completely different scheme, like the NV family. And then there's single-plane YUV formats, which are just the wild west. Not sure how to document all of that…
Quoted 37 lines · On Sun, 26 Apr 2026 15:16:58 +0000 Simon Ser <[email protected]> wrote:
When adding a new format, one needs to pick a name and fourcc. This is not always an easy task: figuring out why current formats are named this way is tricky.
Document current practice to make that process easier.
See previous discussion at:
https://lore.kernel.org/all/aocdbgbLe5WhUEOGeLg3P7fRDM8i72H9zBuUnoAjjsuvBLfMPofrPtaUEjII_43KXf1wCbv1G9UutJKMkWLaEcBSnrlUV78Wrhu6l_Z0xi8=@emersion.fr/Signed-off-by Simon Ser <[email protected]>Cc Pekka Paalanen <[email protected]>Cc Tomi Valkeinen <[email protected]>Cc Maarten Lankhorst <[email protected]>Cc Maxime Ripard <[email protected]>Cc Thomas Zimmermann <[email protected]>Cc David Airlie <[email protected]>Cc Simona Vetter <[email protected]>Cc Laurent Pinchart <[email protected]>Cc Dmitry Baryshkov <[email protected]>Cc Daniel Stone <[email protected]>--- include/uapi/drm/drm_fourcc.h | 39 +++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+)include/uapi/drm/drm_fourcc.h +5
-0@@ -38,6 +38,45 @@ extern "C" {* fourcc code, a Format Modifier may optionally be provided, in order to * further describe the buffer's format - for example tiling or compression. * +* Formats +* ------- +* +* Formats describe how a buffer is interpreted to decode pixel color and alpha +* values. Formats are uniquely identified by a four character code (fourcc).
include/uapi/drm/drm_fourcc.h extern "C" { · line 55
Quoted 10 lines
include/uapi/drm/drm_fourcc.h +10
-0+* Memory layout is always described in little-endian order. +* +* The following channels are defined: +* +* - "R", red +* - "G", green +* - "B", blue +* - "A", alpha +* - "C", color index (for paletted formats) +* - "D", darkness (inverse relationship between channel value and brightness)
Hi,
"inverse relationship between channel value and luminance"
include/uapi/drm/drm_fourcc.h extern "C" { · line 56
Quoted 1 line
include/uapi/drm/drm_fourcc.h +1
-0+* - "Y", luma/brightness
"luma"
That is, I would avoid using the term brightness here.
Thanks,
pq
Quoted 26 lines
include/uapi/drm/drm_fourcc.h +23
-0+* - "U", blue-difference chroma (Cb) +* - "V", red-difference chroma (Cr) +* - "X", a placeholder for undefined/unused contents +* +* Formats using the RGB color model have names made up of a list of channels +* followed by the number of bits used by each channel, respectively. Any +* padding is explicitly indicated by the special "X" channel. Channels use +* unsigned integers, except when suffixed by "F" to indicate IEEE 754 floats. +* An underscore "_" can be used to delimit planes. +* +* Multi-planar YUV formats use the following naming scheme for the most part: +* +* - The first letter indicates the number of planes, channel alignment and +* ordering. It is should not be a letter already used to denote a channel. +* - The first digit indicates chroma sub-sampling: 0 for 2x2, 2 for 2x1, 4 for +* none. +* - The two other digits indicate bits for the Y channel. If the Cb channel +* comes before Cr, the digits are reversed. +* +* Fourccs are allocated on a first-come, first-served basis. New format names +* and fourccs should try to use the same naming scheme as existing, similar +* formats. +* * Format Modifiers * ---------------- *
Thomas Zimmermann
maintainerHi,
thanks for documenting this. See below for some proof reading.
Am 26.04.26 um 17:16 schrieb Simon Ser:
Quoted 29 lines
When adding a new format, one needs to pick a name and fourcc. This is not always an easy task: figuring out why current formats are named this way is tricky.
Document current practice to make that process easier.
See previous discussion at:
https://lore.kernel.org/all/aocdbgbLe5WhUEOGeLg3P7fRDM8i72H9zBuUnoAjjsuvBLfMPofrPtaUEjII_43KXf1wCbv1G9UutJKMkWLaEcBSnrlUV78Wrhu6l_Z0xi8=@emersion.fr/Signed-off-by Simon Ser <[email protected]>Cc Pekka Paalanen <[email protected]>Cc Tomi Valkeinen <[email protected]>Cc Maarten Lankhorst <[email protected]>Cc Maxime Ripard <[email protected]>Cc Thomas Zimmermann <[email protected]>Cc David Airlie <[email protected]>Cc Simona Vetter <[email protected]>Cc Laurent Pinchart <[email protected]>Cc Dmitry Baryshkov <[email protected]>Cc Daniel Stone <[email protected]>--- include/uapi/drm/drm_fourcc.h | 39 +++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+)include/uapi/drm/drm_fourcc.h +0
-0
include/uapi/drm/drm_fourcc.h extern "C" { · line 44
Quoted 7 lines
include/uapi/drm/drm_fourcc.h +4
-0@@ -38,6 +38,45 @@ extern "C" {* fourcc code, a Format Modifier may optionally be provided, in order to * further describe the buffer's format - for example tiling or compression. * +* Formats +* ------- +* +* Formats describe how a buffer is interpreted to decode pixel color and alpha
Rather use singular because there is only one format per buffer. And use active voice. Something like
'A format describes how to interpret a buffer and decode ...'
include/uapi/drm/drm_fourcc.h extern "C" { · line 45
Quoted 1 line
include/uapi/drm/drm_fourcc.h +1
-0+* values. Formats are uniquely identified by a four character code (fourcc).
'four-character code'
include/uapi/drm/drm_fourcc.h extern "C" { · line 46
Quoted 1 line
include/uapi/drm/drm_fourcc.h +1
-0+* Memory layout is always described in little-endian order.
Use active voice and at least hint to the big-endian flag. Something like:
"By default, a pixel's bytes are in little-endian order."
Quoted 9 lines
include/uapi/drm/drm_fourcc.h +9
-0+* +* The following channels are defined: +* +* - "R", red +* - "G", green +* - "B", blue +* - "A", alpha +* - "C", color index (for paletted formats) +* - "D", darkness (inverse relationship between channel value and brightness)
include/uapi/drm/drm_fourcc.h extern "C" { · line 65
Quoted 10 lines
include/uapi/drm/drm_fourcc.h +10
-0+* - "Y", luma/brightness +* - "U", blue-difference chroma (Cb) +* - "V", red-difference chroma (Cr) +* - "X", a placeholder for undefined/unused contents +* +* Formats using the RGB color model have names made up of a list of channels +* followed by the number of bits used by each channel, respectively. Any +* padding is explicitly indicated by the special "X" channel. Channels use +* unsigned integers, except when suffixed by "F" to indicate IEEE 754 floats. +* An underscore "_" can be used to delimit planes.
Give some examples here. Something like:
"For example, XRGB8888 describes a pixel with 4 bytes. The first byte is unused and the trailing bytes contain red, green and blue channels respectively. R32F describes a pixel with a single red channel storing a 32-bit floating-point value."
include/uapi/drm/drm_fourcc.h extern "C" { · line 70
Quoted 5 lines
include/uapi/drm/drm_fourcc.h +5
-0+* +* Multi-planar YUV formats use the following naming scheme for the most part: +* +* - The first letter indicates the number of planes, channel alignment and +* ordering. It is should not be a letter already used to denote a channel.
'It is should not' -> "It should not" or "It must not" depending on the strictness of this rule.
include/uapi/drm/drm_fourcc.h extern "C" { · line 74
Quoted 4 lines
include/uapi/drm/drm_fourcc.h +4
-0+* - The first digit indicates chroma sub-sampling: 0 for 2x2, 2 for 2x1, 4 for +* none. +* - The two other digits indicate bits for the Y channel. If the Cb channel +* comes before Cr, the digits are reversed.
Please give an example for a multi-planar format here.
include/uapi/drm/drm_fourcc.h extern "C" { · line 77
Quoted 3 lines
include/uapi/drm/drm_fourcc.h +3
-0+* +* Fourccs are allocated on a first-come, first-served basis. New format names +* and fourccs should try to use the same naming scheme as existing, similar
'should try to' -> 'should'
Best regards
Thomas
Quoted 5 lines
include/uapi/drm/drm_fourcc.h +2
-0+* formats. +* * Format Modifiers * ---------------- *
Signature · 6 lines
-- Thomas Zimmermann Graphics Driver Developer SUSE Software Solutions Germany GmbH Frankenstr. 146, 90461 Nürnberg, Germany, www.suse.com GF: Jochen Jaser, Andrew McDonald, Werner Knoblich, (HRB 36809, AG Nürnberg)