drm_plane_cr...pos_property(9)

📦 version 7.3.1, in nixpkgs unstable

💅 drm_plane_cr...pos_property(9) — the Kernel API Manual, bestie edition

okay so real talk, this is a page out of the Kernel API Manual (yes, the drm_plane_cr...pos_property(9) one, the name got cuter with the ellipsis, we love that for it) and it's all about making z-order on DRM planes, like, actually configurable. sit down, grab a lil snack 🍓, we're learning.

✨ NAME ✨

drm_plane_create_zpos_property — creates the mutable zpos property. that's it, that's the whole vibe. it's giving "one job, does it well" 💅

🦋 SYNOPSIS 🦋

int drm_plane_create_zpos_property (struct drm_plane *plane , unsigned
       int zpos , unsigned int min , unsigned int max );

like, copy it exactly, no cap. four things go in, an int comes out 🔥

🎀 ARGUMENTS 🎀

  • plane — the drm plane, your main character 💖
  • zpos — the initial value of the zpos property, i.e. where it starts out life
  • min — the minimal possible value of the zpos property (the floor, the lowkey limit)
  • max — the maximal possible value of the zpos property (the ceiling, the highkey limit)

🌸 DESCRIPTION 🌸

so what it do: this function initializes the generic mutable zpos property and enables support for it in the drm core. literally turning the feature on at the source 🫶

after that, drivers can attach this property to planes, which is how you get support for configurable plane arrangement during blending — aka who's on top of who, the entire stacking drama, but make it atomic ✨

the big rule, don't skip it bestie: any driver that attaches a mutable zpos property to any plane should call the drm_atomic_normalize_zpos helper during its implementation of drm_mode_config_funcs.atomic_check. that helper is the one that updates the normalized zpos values and stores them in drm_plane_state.normalized_zpos. if you skip it, you're on your own 😭

usually min should be set to 0 and max to the maximal number of planes for the given crtc minus 1. so like max = planes - 1, periodt.

now for the plot twist 🌀 — if the zpos of some planes can't be changed (think fixed background, or cursor/topmost planes, the ones with their mind made up), drivers shall adjust the min/max values and assign those planes immutable zpos properties with lower or higher values. for more info on that, see the drm_plane_create_zpos_immutable_property function, iykyk.

and in that case, drivers shall also assign proper initial zpos values for all planes in its plane_reset callback — so the planes will always be sorted properly. no chaos, only order 👑

See also drm_atomic_normalize_zpos.

and the property that actually gets exposed to userspace? it's called "zpos". iconic name, no notes 💀

⭐ RETURN ⭐

Zero on success, negative errno on failure. slay when it works, sad little negative number when it doesn't 🙈

🔥 SEE ALSO 🔥

okay that's the whole page, you ate that 💖✨ this lil manual lives at ./drivers/gpu/drm, dated October 2026, and the page is drm_plane_cr...pos_property(9) — go forth and stack your planes correctly, bestie 🦋👑

📦 where this page comes from