STRUCT DRM_MODE_FB_CMD2(9)

💖 NAME

struct drm_mode_fb_cmd2 — Frame-buffer metadata, bestie. That's it, that's the whole vibe. ✨

---

🎀 SYNOPSIS

okay so here's the shape of it, no cap:

struct drm_mode_fb_cmd2 {
    __u32 fb_id;
    __u32 width;
    __u32 height;
    __u32 pixel_format;
    __u32 flags;
    __u32 handles[4];
    __u32 pitches[4];
    __u32 offsets[4];
    __u64 modifier[4];
 };

---

🦋 MEMBERS

Like, every single field, and what it's giving:

• fb_id — Object ID of the frame-buffer. literally its name tag at the party 🪪
• width — Width of the frame-buffer. the horizontal situation.
• height — Height of the frame-buffer. the vertical situation.
• pixel_format — FourCC format code, see DRM_FORMAT_* constants in drm_fourcc.h. 🔥
• flags — Frame-buffer flags (see DRM_MODE_FB_INTERLACED and DRM_MODE_FB_MODIFIERS).
• handles — GEM buffer handle, one per plane. Set to 0 if the plane is unused. The same handle can be used for multiple planes. (yes bestie, sharing is allowed 💅)
• pitches — Pitch (aka. stride) in bytes, one per plane.
• offsets — Offset into the buffer in bytes, one per plane.
• modifier — Format modifier, one per plane. See DRM_FORMAT_MOD_* constants in drm_fourcc.h. All planes must use the same modifier. Ignored unless DRM_MODE_FB_MODIFIERS is set in flags. 👑

---

🌸 DESCRIPTION

This struct holds frame-buffer metadata. There are two ways to use it, and honestly? both iconic:

• User-space can fill this struct and perform a DRM_IOCTL_MODE_ADDFB2 ioctl to register a new frame-buffer. The new frame-buffer object ID will be set by the kernel in fb_id. 🆕
• User-space can set fb_id and perform a DRM_IOCTL_MODE_GETFB2 ioctl to fetch metadata about an existing frame-buffer. 🔍

In case of planar formats, this struct allows up to 4 buffer objects with offsets and pitches per plane. The pitch and offset order are dictated by the format FourCC as defined by `drm_fourcc.h, e.g. NV12 is described as:

YUV 4:2:0 image with a plane of 8-bit Y samples followed by an interleaved U/V plane containing 8-bit 2x2 subsampled colour difference samples.

So it would consist of a Y plane at offsets[0] and a UV plane at offsets[1]. 🧚

To accommodate tiled, compressed, etc formats, a modifier can be specified. For more information see the "Format Modifiers" section. Note that even though it looks like we have a modifier per-plane, we in fact do not. The modifier for each plane must be identical. Thus all combinations of different data layouts for multi-plane formats must be enumerated as separate modifiers. (the way that "per-plane" thing is a lie, i'm crying 😭)

All of the entries in handles, pitches, offsets and modifier must be zero when unused.

⚠️ Warning, for offsets and modifier zero can't be used to figure out whether the entry is used or not since it's a valid value (a zero offset is common, and a zero modifier is DRM_FORMAT_MOD_LINEAR). So don't come for me with "but it's zero so it's unused" — that is not how this works, bestie. 💀

---

🌈 SEE ALSO

the whole friend group, fr fr ✨

• Kernel file ./include/uapi/drm/drm_mode.h
• overview(9)
• struct drm_mode_modeinfo(9)
• struct drm_mode_get_plane(9)
• struct drm_mode_get_connector(9)
• struct drm_mode_property_enum(9)
• struct drm_mode_get_property(9)
• enum drm_colorop_type(9)
• enum drm_colorop_lut3d_interpolation_type(9)
• enum drm_colorop_lut1d_interpolation_type(9)
• struct drm_plane_size_hint(9)
• struct hdr_metadata_infoframe(9)
• struct hdr_output_metadata(9)
• DRM_MODE_PAGE_FLIP_EVENT(9)
• DRM_MODE_PAGE_FLIP_ASYNC(9)
• DRM_MODE_PAGE_FLIP_FLAGS(9)
• struct drm_mode_create_dumb(9)
• DRM_MODE_ATOMIC_TEST_ONLY(9)
• DRM_MODE_ATOMIC_NONBLOCK(9)
• DRM_MODE_ATOMIC_ALLOW_MODESET(9)
• DRM_MODE_ATOMIC_FLAGS(9)
• struct drm_mode_create_blob(9)
• struct drm_mode_destroy_blob(9)
• struct drm_mode_create_lease(9)
• struct drm_mode_list_lessees(9)
• struct drm_mode_get_lease(9)
• struct drm_mode_revoke_lease(9)
• struct drm_mode_rect(9)
• struct drm_mode_closefb(9)

---

adorbs, that's a wrap 🫶 this one lives in ./include/uapi/drm, version stamp is October 2026, and the whole thing is literally titled struct drm_mode_fb_cmd2(9). go be a frame-buffer main character, mwah 💋🎀