render: add DMA-BUF docs

Document some of the assumptions for DMA-BUF buffer sharing and
modifiers.

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

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;
+	uint32_t format; // FourCC code, see DRM_FORMAT_* in <drm_fourcc.h>
-	uint64_t modifier;
+	uint64_t modifier; // see DRM_FORMAT_MOD_* in <drm_fourcc.h>
 
 	int n_planes;
 	uint32_t offset[WLR_DMABUF_MAX_PLANES];

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;