STRUCT DRM_FORMAT_INFO(9)

📦 version 7.3.1, in nixpkgs unstable

💅 struct drm_format_info(9) — the kernel API manual, bestie edition 🎀

okay so this is struct drm_format_info(9) from the Kernel API Manual and honestly? it's giving "the little struct that holds the whole vibe of a pixel format." let's get into it ✨

🌸 NAME 🌸

struct drm_format_info — literally just info about a DRM format, that's the whole thing, no cap 💖

✨ SYNOPSIS ✨

struct drm_format_info {
    u32 format;
    u8 depth;
    u8 num_planes;
    union {
      u8 cpp[DRM_FORMAT_MAX_PLANES];
      u8 char_per_block[DRM_FORMAT_MAX_PLANES];
    };
    u8 block_w[DRM_FORMAT_MAX_PLANES];
    u8 block_h[DRM_FORMAT_MAX_PLANES];
    u8 hsub;
    u8 vsub;
    bool has_alpha;
    bool is_yuv;
    bool is_color_indexed;
 };

look at her. gorgeous. iconic. every field accounted for 🫶

👑 Members 👑

  • format — the 4CC format identifier (DRM_FORMAT_*). yes, four characters, yes it's a vibe check for pixels 🦋
  • depth — color depth (number of bits per pixel excluding padding bits), and heads up: this only actually means anything for a subset of RGB formats. it's a legacy field bestie, so do not use it in new code and set it to 0 for new formats. 🙈
  • num_planes — number of color planes (from 1 to 3). that's it, that's the range 💜
  • {unnamed_union} — anonymous. she has no name and she doesn't need one 💅
  • cpp — number of bytes per pixel (per plane), and this one is aliased with char_per_block. it's deprecated in favour of using the triplet char_per_block, block_w, block_h because that describes the pixel format way better. ngl, cpp is the older sister who's still cool but like... move on 🌈
  • char_per_block — number of bytes per block (per plane), where blocks are defined as a rectangle of pixels which are stored next to each other in a byte aligned memory region. together with block_w and block_h, this is used to properly describe tiles in tiled formats, or to describe groups of pixels in packed formats for which the memory needed for a single pixel is not byte aligned. this is the main character field, fr fr ⭐

so cpp has been kept for historical reasons because there are a lot of places in drivers where it's used — like, a lot a lot. but in drm core, for generic code paths, the preferred way is to use char_per_block, drm_format_info_block_width and drm_format_info_block_height, which lets you handle both block and non-block formats in the exact same way. slay, consistency 🎀

for formats that are intended to be used only with non-linear modifiers: both cpp and char_per_block must be 0 in the generic format table. that's a hard requirement, not a suggestion, okay? 💀 drivers could supply accurate information from their drm_mode_config.get_format_info hook if they want the core to be validating the pitch. iykyk 🔥

  • block_w — block width in pixels; this is intended to be accessed through drm_format_info_block_width 🧚
  • block_h — block height in pixels; this is intended to be accessed through drm_format_info_block_height 🧚
  • hsub — horizontal chroma subsampling factor 🌸
  • vsub — vertical chroma subsampling factor 🌸
  • has_alpha — does the format embeds an alpha component? (yes/no, transparency girlie check) 💖
  • is_yuv — is it a YUV format? 💙
  • is_color_indexed — is it a color-indexed format? 🍓

🦋 SEE ALSO 🦋

kernel file ./include/drm/drm_fourcc.h, plus the whole friend group:

go read them, they ate 💅

and that's the whole page!! this one came from ./include/drm, in the October 2026 drop of the Kernel API Manual, filed under struct drm_format_info(9) — mwah, love u, go format some pixels responsibly 💜✨🎀

📦 where this page comes from