STRUCT DRM_PLANE_STATE(9)

💅 struct drm_plane_state(9) — mutable plane state

okay so bestie, welcome to the Kernel API Manual ✨ — this is the page for struct drm_plane_state, aka the mutable plane state. think of it as the lil living, breathing snapshot of a plane that atomic commits push around 🦋 it's giving "everything you can change about a plane, in one struct." obsessed.

---

🌸 SYNOPSIS 🌸

struct drm_plane_state {
    struct drm_plane *plane;
    struct drm_crtc *crtc;
    struct drm_framebuffer *fb;
    struct dma_fence *fence;
    int32_t crtc_x;
    int32_t crtc_y;
    uint32_t crtc_w, crtc_h;
    uint32_t src_x;
    uint32_t src_y;
    uint32_t src_h, src_w;
    int32_t hotspot_x, hotspot_y;
    u16 alpha;
    uint16_t pixel_blend_mode;
    unsigned int rotation;
    unsigned int zpos;
    unsigned int normalized_zpos;
    enum drm_color_encoding color_encoding;
    enum drm_color_range color_range;
    struct drm_property_blob *fb_damage_clips;
    bool ignore_damage_clips;
    struct drm_rect src, dst;
    bool visible;
    enum drm_scaling_filter scaling_filter;
    struct drm_colorop *color_pipeline;
    struct drm_crtc_commit *commit;
    struct drm_atomic_commit *state;
    bool color_mgmt_changed : 1;
};

no cap, that's the whole squad 🫶 let's meet them one by one.

---

🎀 Members 🎀

• plane — backpointer to the plane 💫
• crtc — currently bound CRTC, or NULL if it's disabled. ⚠️ do not write this directly, bestie — use drm_atomic_set_crtc_for_plane instead, iykyk.
• fb — the currently bound framebuffer. ⚠️ also a hands-off field, do not write it directly, use drm_atomic_set_fb_for_plane.
• fence — optional fence to wait for before scanning out fb. the core atomic code sets this when userspace is using explicit fencing 🔥 and listen: do not write this field directly for a driver's implicit fence.

drivers should store any implicit fence in this from their drm_plane_helper_funcs.prepare_fb callback. see drm_gem_plane_helper_prepare_fb for a suitable helper 🧚

• crtc_x — left position of the visible portion of the plane on the crtc. it's a signed dest location, which is the whole reason it can sit partially off screen 😌
• crtc_y — upper position of the visible portion of the plane on the crtc. also signed, so yeah, partially off screen is legal 💅
• crtc_w — width of the visible portion of the plane on the crtc.
• crtc_h — height of the visible portion of the plane on the crtc.
• src_x — left position of the visible portion of the plane within the plane (in 16.16 fixed point).
• src_y — upper position of the visible portion of the plane within the plane (in 16.16 fixed point).
• src_h — height of the visible portion of the plane (in 16.16).
• src_w — width of the visible portion of the plane (in 16.16).
• hotspot_x — x offset to the mouse cursor hotspot 🖱️
• hotspot_y — y offset to the mouse cursor hotspot 🖱️
• alpha — opacity of the plane, where 0 is completely transparent and 0xffff is completely opaque. see drm_plane_create_alpha_property for more details ✨
• pixel_blend_mode — the alpha blending equation selection, describing how the pixels from the current plane get composited with the background. value can be one of DRM_MODE_BLEND_* 🌈
• rotation — rotation of the plane. see drm_plane_create_rotation_property for more details 🔄
• zpos — priority of the given plane on the crtc (optional).

user-space may set mutable zpos properties so that multiple active planes on the same CRTC have identical zpos values. this is a user-space bug 😭 but drivers can solve the conflict by comparing the plane object IDs; the plane with a higher ID is stacked on top of a plane with a lower ID.

see drm_plane_create_zpos_property and drm_plane_create_zpos_immutable_property for more details.

• normalized_zpos — normalized value of zpos: unique, range from 0 to N-1 where N is the number of active planes for the given crtc. 📌 note that the driver must set drm_mode_config.normalize_zpos or call drm_atomic_normalize_zpos to update this before it can be trusted — like, don't trust it before that, fr fr.
• color_encoding — color encoding for non RGB formats.
• color_range — color range for non RGB formats.
• fb_damage_clips — blob representing damage (the area in the plane framebuffer that changed since the last plane update) as an array of drm_mode_rect in framebuffer coodinates of the attached framebuffer. 🩹 note that unlike plane src, damage clips are not in 16.16 fixed point.

see drm_plane_get_damage_clips and drm_plane_get_damage_clips_count for accessing these.

• ignore_damage_clips — set by drivers to indicate to the drm_atomic_helper_damage_iter_init helper that the fb_damage_clips blob property should be ignored 🙈

see :ref:damage_tracking_properties`` for more information.

• src — source coordinates of the plane (in 16.16).

when using drm_atomic_helper_check_plane_state, the coordinates are clipped, but the driver may choose to use unclipped coordinates instead when the hardware performs the clipping automatically 💫

• dst — clipped destination coordinates of the plane.

when using drm_atomic_helper_check_plane_state, the coordinates are clipped, but the driver may choose to use unclipped coordinates instead when the hardware performs the clipping automatically 💫

• visible — visibility of the plane. this can be false even if fb!=NULL and crtc!=NULL, due to clipping 👀 so like, don't assume.
• scaling_filter — scaling filter to be applied.
• color_pipeline — the first colorop of the active color pipeline, or NULL if no color pipeline is active. 🎨
• commit — tracks the pending commit to prevent use-after-free conditions, and for async plane updates.

may be NULL.

• state — backpointer to the global drm_atomic_commit.
• color_mgmt_changed — color management properties have changed. used by the atomic helpers and drivers to steer the atomic commit control flow 👑

---

🦋 Description 🦋

please note 📝 that the destination coordinates crtc_x, crtc_y, crtc_h and crtc_w and the source coordinates src_x, src_y, src_h and src_w are the raw coordinates provided by userspace. drivers should use drm_atomic_helper_check_plane_state and only use the derived rectangles in src and dst to program the hardware. periodt — no raw-coordinate shenanigans 💀

---

🌟 SEE ALSO 🌟

kernel file ./include/drm/drm_plane.h — plus struct drm_plane_funcs(9), enum drm_plane_type(9), struct drm_plane(9), drmm_universal_plane_alloc(9), drm_universal_plane_alloc(9), drm_plane_index(9), drm_plane_mask(9), drm_plane_find(9), drm_for_each_plane_mask(9), drm_for_each_legacy_plane(9), drm_for_each_plane(9) — go read them, bestie, they're iconic 🫶

---

that's the whole page, mwah 💖 brought to you from ./include/drm in the October 2026 edition of the Kernel API Manual — slay, go commit some atoms 🔥👑