Hi,
thanks for documenting this. See below for some proof reading.
Am 26.04.26 um 17:16 schrieb 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(+)
diff --git a/include/uapi/drm/drm_fourcc.h b/include/uapi/drm/drm_fourcc.h
index ac66fa93b5a3..dc737c4fa5f2 100644
--- a/include/uapi/drm/drm_fourcc.h
+++ b/include/uapi/drm/drm_fourcc.h
@@ -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 ...'
+ * values. Formats are uniquely identified by a four character code (fourcc).
'four-character code'
+ * 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."
+ *
+ * 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.
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."
+ *
+ * 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.
+ * - 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.
+ *
+ * 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
+ * formats.
+ *
* Format Modifiers
* ----------------
*
--
--
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)
