summaryrefslogtreecommitdiff
path: root/include/drm/drm_plane.h
diff options
context:
space:
mode:
Diffstat (limited to 'include/drm/drm_plane.h')
-rw-r--r--include/drm/drm_plane.h197
1 files changed, 140 insertions, 57 deletions
diff --git a/include/drm/drm_plane.h b/include/drm/drm_plane.h
index 26fa50c2a50e..8a152dc16ea5 100644
--- a/include/drm/drm_plane.h
+++ b/include/drm/drm_plane.h
@@ -34,31 +34,15 @@ struct drm_modeset_acquire_ctx;
/**
* struct drm_plane_state - mutable plane state
- * @plane: backpointer to the plane
- * @crtc_w: width of visible portion of plane on crtc
- * @crtc_h: height of visible portion of plane on crtc
- * @src_x: left position of visible portion of plane within
- * plane (in 16.16)
- * @src_y: upper position of visible portion of plane within
- * plane (in 16.16)
- * @src_w: width of visible portion of plane (in 16.16)
- * @src_h: height of visible portion of plane (in 16.16)
- * @alpha: opacity of the plane
- * @rotation: rotation of the plane
- * @zpos: priority of the given plane on crtc (optional)
- * Note that multiple active planes on the same crtc can have an identical
- * zpos value. The rule to solving the conflict is to compare the plane
- * object IDs; the plane with a higher ID must be stacked on top of a
- * plane with a lower ID.
- * @normalized_zpos: normalized value of zpos: unique, range from 0 to N-1
- * where N is the number of active planes for 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.
- * @src: clipped source coordinates of the plane (in 16.16)
- * @dst: clipped destination coordinates of the plane
- * @state: backpointer to global drm_atomic_state
+ *
+ * Please not 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.
*/
struct drm_plane_state {
+ /** @plane: backpointer to the plane */
struct drm_plane *plane;
/**
@@ -87,7 +71,7 @@ struct drm_plane_state {
* preserved.
*
* Drivers should store any implicit fence in this from their
- * &drm_plane_helper.prepare_fb callback. See drm_gem_fb_prepare_fb()
+ * &drm_plane_helper_funcs.prepare_fb callback. See drm_gem_fb_prepare_fb()
* and drm_gem_fb_simple_display_pipe_prepare_fb() for suitable helpers.
*/
struct dma_fence *fence;
@@ -108,20 +92,60 @@ struct drm_plane_state {
*/
int32_t crtc_y;
+ /** @crtc_w: width of visible portion of plane on crtc */
+ /** @crtc_h: height of visible portion of plane on crtc */
uint32_t crtc_w, crtc_h;
- /* Source values are 16.16 fixed point */
- uint32_t src_x, src_y;
+ /**
+ * @src_x: left position of visible portion of plane within plane (in
+ * 16.16 fixed point).
+ */
+ uint32_t src_x;
+ /**
+ * @src_y: upper position of visible portion of plane within plane (in
+ * 16.16 fixed point).
+ */
+ uint32_t src_y;
+ /** @src_w: width of visible portion of plane (in 16.16) */
+ /** @src_h: height of visible portion of plane (in 16.16) */
uint32_t src_h, src_w;
- /* Plane opacity */
+ /**
+ * @alpha:
+ * Opacity of the plane with 0 as completely transparent and 0xffff as
+ * completely opaque. See drm_plane_create_alpha_property() for more
+ * details.
+ */
u16 alpha;
- /* Plane rotation */
+ /**
+ * @rotation:
+ * Rotation of the plane. See drm_plane_create_rotation_property() for
+ * more details.
+ */
unsigned int rotation;
- /* Plane zpos */
+ /**
+ * @zpos:
+ * Priority of the given plane on crtc (optional).
+ *
+ * Note that multiple active planes on the same crtc can have an
+ * identical zpos value. The rule to solving the conflict is to compare
+ * the plane object IDs; the plane with a higher ID must be 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.
+ */
unsigned int zpos;
+
+ /**
+ * @normalized_zpos:
+ * Normalized value of zpos: unique, range from 0 to N-1 where N is the
+ * number of active planes for 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.
+ */
unsigned int normalized_zpos;
/**
@@ -138,7 +162,8 @@ struct drm_plane_state {
*/
enum drm_color_range color_range;
- /* Clipped coordinates */
+ /** @src: clipped source coordinates of the plane (in 16.16) */
+ /** @dst: clipped destination coordinates of the plane */
struct drm_rect src, dst;
/**
@@ -157,6 +182,7 @@ struct drm_plane_state {
*/
struct drm_crtc_commit *commit;
+ /** @state: backpointer to global drm_atomic_state */
struct drm_atomic_state *state;
};
@@ -288,6 +314,8 @@ struct drm_plane_funcs {
* cleaned up by calling the @atomic_destroy_state hook in this
* structure.
*
+ * This callback is mandatory for atomic drivers.
+ *
* Atomic drivers which don't subclass &struct drm_plane_state should use
* drm_atomic_helper_plane_duplicate_state(). Drivers that subclass the
* state structure to extend it with driver-private state should use
@@ -314,6 +342,8 @@ struct drm_plane_funcs {
*
* Destroy a state duplicated with @atomic_duplicate_state and release
* or unreference all resources it references
+ *
+ * This callback is mandatory for atomic drivers.
*/
void (*atomic_destroy_state)(struct drm_plane *plane,
struct drm_plane_state *state);
@@ -431,7 +461,10 @@ struct drm_plane_funcs {
* This optional hook is used for the DRM to determine if the given
* format/modifier combination is valid for the plane. This allows the
* DRM to generate the correct format bitmask (which formats apply to
- * which modifier).
+ * which modifier), and to valdiate modifiers at atomic_check time.
+ *
+ * If not present, then any modifier in the plane's modifier
+ * list is allowed with any of the plane's formats.
*
* Returns:
*
@@ -492,30 +525,27 @@ enum drm_plane_type {
/**
* struct drm_plane - central DRM plane control structure
- * @dev: DRM device this plane belongs to
- * @head: for list management
- * @name: human readable name, can be overwritten by the driver
- * @base: base mode object
- * @possible_crtcs: pipes this plane can be bound to
- * @format_types: array of formats supported by this plane
- * @format_count: number of formats supported
- * @format_default: driver hasn't supplied supported formats for the plane
- * @modifiers: array of modifiers supported by this plane
- * @modifier_count: number of modifiers supported
- * @old_fb: Temporary tracking of the old fb while a modeset is ongoing. Used by
- * drm_mode_set_config_internal() to implement correct refcounting.
- * @funcs: helper functions
- * @properties: property tracking for this plane
- * @type: type of plane (overlay, primary, cursor)
- * @alpha_property: alpha property for this plane
- * @zpos_property: zpos property for this plane
- * @rotation_property: rotation property for this plane
- * @helper_private: mid-layer private data
+ *
+ * Planes represent the scanout hardware of a display block. They receive their
+ * input data from a &drm_framebuffer and feed it to a &drm_crtc. Planes control
+ * the color conversion, see `Plane Composition Properties`_ for more details,
+ * and are also involved in the color conversion of input pixels, see `Color
+ * Management Properties`_ for details on that.
*/
struct drm_plane {
+ /** @dev: DRM device this plane belongs to */
struct drm_device *dev;
+
+ /**
+ * @head:
+ *
+ * List of all planes on @dev, linked from &drm_mode_config.plane_list.
+ * Invariant over the lifetime of @dev and therefore does not need
+ * locking.
+ */
struct list_head head;
+ /** @name: human readable name, can be overwritten by the driver */
char *name;
/**
@@ -529,35 +559,62 @@ struct drm_plane {
*/
struct drm_modeset_lock mutex;
+ /** @base: base mode object */
struct drm_mode_object base;
+ /**
+ * @possible_crtcs: pipes this plane can be bound to constructed from
+ * drm_crtc_mask()
+ */
uint32_t possible_crtcs;
+ /** @format_types: array of formats supported by this plane */
uint32_t *format_types;
+ /** @format_count: Size of the array pointed at by @format_types. */
unsigned int format_count;
+ /**
+ * @format_default: driver hasn't supplied supported formats for the
+ * plane. Used by the drm_plane_init compatibility wrapper only.
+ */
bool format_default;
+ /** @modifiers: array of modifiers supported by this plane */
uint64_t *modifiers;
+ /** @modifier_count: Size of the array pointed at by @modifier_count. */
unsigned int modifier_count;
/**
- * @crtc: Currently bound CRTC, only really meaningful for non-atomic
- * drivers. Atomic drivers should instead check &drm_plane_state.crtc.
+ * @crtc:
+ *
+ * Currently bound CRTC, only meaningful for non-atomic drivers. For
+ * atomic drivers this is forced to be NULL, atomic drivers should
+ * instead check &drm_plane_state.crtc.
*/
struct drm_crtc *crtc;
/**
- * @fb: Currently bound framebuffer, only really meaningful for
- * non-atomic drivers. Atomic drivers should instead check
- * &drm_plane_state.fb.
+ * @fb:
+ *
+ * Currently bound framebuffer, only meaningful for non-atomic drivers.
+ * For atomic drivers this is forced to be NULL, atomic drivers should
+ * instead check &drm_plane_state.fb.
*/
struct drm_framebuffer *fb;
+ /**
+ * @old_fb:
+ *
+ * Temporary tracking of the old fb while a modeset is ongoing. Only
+ * used by non-atomic drivers, forced to be NULL for atomic drivers.
+ */
struct drm_framebuffer *old_fb;
+ /** @funcs: plane control functions */
const struct drm_plane_funcs *funcs;
+ /** @properties: property tracking for this plane */
struct drm_object_properties properties;
+ /** @type: Type of plane, see &enum drm_plane_type for details. */
enum drm_plane_type type;
/**
@@ -566,6 +623,7 @@ struct drm_plane {
*/
unsigned index;
+ /** @helper_private: mid-layer private data */
const struct drm_plane_helper_funcs *helper_private;
/**
@@ -583,8 +641,23 @@ struct drm_plane {
*/
struct drm_plane_state *state;
+ /**
+ * @alpha_property:
+ * Optional alpha property for this plane. See
+ * drm_plane_create_alpha_property().
+ */
struct drm_property *alpha_property;
+ /**
+ * @zpos_property:
+ * Optional zpos property for this plane. See
+ * drm_plane_create_zpos_property().
+ */
struct drm_property *zpos_property;
+ /**
+ * @rotation_property:
+ * Optional rotation property for this plane. See
+ * drm_plane_create_rotation_property().
+ */
struct drm_property *rotation_property;
/**
@@ -632,10 +705,20 @@ void drm_plane_cleanup(struct drm_plane *plane);
* Given a registered plane, return the index of that plane within a DRM
* device's list of planes.
*/
-static inline unsigned int drm_plane_index(struct drm_plane *plane)
+static inline unsigned int drm_plane_index(const struct drm_plane *plane)
{
return plane->index;
}
+
+/**
+ * drm_plane_mask - find the mask of a registered plane
+ * @plane: plane to find mask for
+ */
+static inline u32 drm_plane_mask(const struct drm_plane *plane)
+{
+ return 1 << drm_plane_index(plane);
+}
+
struct drm_plane * drm_plane_from_index(struct drm_device *dev, int idx);
void drm_plane_force_disable(struct drm_plane *plane);
@@ -671,7 +754,7 @@ static inline struct drm_plane *drm_plane_find(struct drm_device *dev,
*/
#define drm_for_each_plane_mask(plane, dev, plane_mask) \
list_for_each_entry((plane), &(dev)->mode_config.plane_list, head) \
- for_each_if ((plane_mask) & (1 << drm_plane_index(plane)))
+ for_each_if ((plane_mask) & drm_plane_mask(plane))
/**
* drm_for_each_legacy_plane - iterate over all planes for legacy userspace