render: add DMA-BUF docs

Document some of the assumptions for DMA-BUF buffer sharing and
modifiers.
This commit is contained in:
Simon Ser 2021-11-24 21:42:08 +01:00 committed by Simon Zeni
parent ef1669d33e
commit 83d78f9fd4
3 changed files with 50 additions and 4 deletions

View file

@ -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);

View file

@ -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];

View file

@ -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;