diff options
| -rw-r--r-- | include/wlr/render/allocator.h | 12 | ||||
| -rw-r--r-- | include/wlr/render/dmabuf.h | 21 | ||||
| -rw-r--r-- | include/wlr/render/drm_format_set.h | 21 |
3 files changed, 50 insertions, 4 deletions
diff --git a/include/wlr/render/allocator.h b/include/wlr/render/allocator.h index 3caeffa0..3150e36c 100644 --- a/include/wlr/render/allocator.h +++ b/include/wlr/render/allocator.h @@ -51,6 +51,18 @@ void wlr_allocator_destroy(struct wlr_allocator *alloc); * * When the caller is done with it, they must unreference it by calling * wlr_buffer_drop. + * + * The `format` passed in indicates the format to use and the list of + * acceptable modifiers. The order in which modifiers are listed is not + * significant. + * + * When running with legacy drivers which don't support explicit modifiers, the + * allocator must recognize two modifiers: INVALID (for implicit tiling and/or + * compression) and LINEAR. + * + * The allocator must return a buffer using one of the modifiers listed. In + * particular, allocators must not return a buffer with an implicit modifier + * unless the user has allowed it by passing INVALID in the modifier list. */ struct wlr_buffer *wlr_allocator_create_buffer(struct wlr_allocator *alloc, int width, int height, const struct wlr_drm_format *format); diff --git a/include/wlr/render/dmabuf.h b/include/wlr/render/dmabuf.h index 76aad629..62f8e021 100644 --- a/include/wlr/render/dmabuf.h +++ b/include/wlr/render/dmabuf.h @@ -14,10 +14,27 @@ #define WLR_DMABUF_MAX_PLANES 4 +/** + * A Linux DMA-BUF pixel buffer. + * + * If the buffer was allocated with explicit modifiers enabled, the `modifier` + * field must not be INVALID. + * + * If the buffer was allocated with explicit modifiers disabled (either because + * the driver doesn't support it, or because the user didn't specify a valid + * modifier list), the `modifier` field can have two values: INVALID means that + * an implicit vendor-defined modifier is in use, LINEAR means that the buffer + * is linear. The `modifier` field must not have any other value. + * + * When importing a DMA-BUF, users must not ignore the modifier unless it's + * INVALID or LINEAR. In particular, users must not import a DMA-BUF to a + * legacy API which doesn't support specifying an explicit modifier unless the + * modifier is set to INVALID or LINEAR. + */ struct wlr_dmabuf_attributes { int32_t width, height; - uint32_t format; - uint64_t modifier; + uint32_t format; // FourCC code, see DRM_FORMAT_* in <drm_fourcc.h> + uint64_t modifier; // see DRM_FORMAT_MOD_* in <drm_fourcc.h> int n_planes; uint32_t offset[WLR_DMABUF_MAX_PLANES]; diff --git a/include/wlr/render/drm_format_set.h b/include/wlr/render/drm_format_set.h index cb367a63..9427df3b 100644 --- a/include/wlr/render/drm_format_set.h +++ b/include/wlr/render/drm_format_set.h @@ -5,7 +5,7 @@ #include <stddef.h> #include <stdint.h> -/** A single DRM format */ +/** A single DRM format, with a set of modifiers attached. */ struct wlr_drm_format { // The actual DRM format, from `drm_fourcc.h` uint32_t format; @@ -17,7 +17,24 @@ struct wlr_drm_format { uint64_t modifiers[]; }; -/** A set of DRM formats */ +/** + * A set of DRM formats and modifiers. + * + * This is used to describe the supported format + modifier combinations. For + * instance, backends will report the set they can display, and renderers will + * report the set they can render to. For a more general overview of formats + * and modifiers, see: + * https://lore.kernel.org/dri-devel/20210905122742.86029-1-daniels@collabora.com/ + * + * For compatibility with legacy drivers which don't support explicit + * modifiers, the special modifier DRM_FORMAT_MOD_INVALID is used to indicate + * that implicit modifiers are supported. Legacy drivers can also support the + * DRM_FORMAT_MOD_LINEAR modifier, which forces the buffer to have a linear + * layout. + * + * Users must not assume that implicit modifiers are supported unless INVALID + * is listed in the modifier list. + */ struct wlr_drm_format_set { // The number of formats size_t len; |