Lines Matching +full:in +full:- +full:between
1 .. SPDX-License-Identifier: GPL-2.0
2 .. Copyright 2021-2023 Collabora Ltd.
9 support for sharing pixel-buffer allocations between processes, devices, and
10 subsystems. Modern systems require extensive integration between all three
12 approach this sharing for two-dimensional image data.
25 Conceptually a two-dimensional array of pixels. The pixels may be stored
26 in one or more memory buffers. Has width and height in pixels, pixel
30 A span along a single y-axis value, e.g. from co-ordinates (0,100) to
37 A span along a single x-axis value, e.g. from co-ordinates (100,0) to
42 in bytes and at least one handle in some API. May contain one or more
46 A two-dimensional array of some or all of an image's color and alpha
60 A tuple of numbers, representing a color. Each element in the tuple is a
64 One of the dimensions in a color model. For example, RGB model has
73 A description of how pixel data is laid out in memory buffers.
76 A value that denotes the color coverage in a pixel. Sometimes used for
80 A value that denotes the relationship between pixel-location co-ordinates
81 and byte-offset values. Typically used as the byte offset between two
82 pixels at the start of vertically-consecutive tiling blocks. For linear
83 layouts, the byte offset between two vertically-adjacent pixels. For
84 non-linear formats the stride must be computed in a consistent way, which
85 usually is done as-if the layout was linear.
98 These tokens are described in the ``drm_fourcc.h`` file, which is a part of
101 Each ``DRM_FORMAT_*`` token describes the translation between a pixel
102 co-ordinate in an image, and the color values for that pixel contained within
104 whether they are RGB or YUV, integer or floating-point, the size of each channel
105 and their locations within the pixel memory, and the relationship between color
108 For example, ``DRM_FORMAT_ARGB8888`` describes a format in which each pixel has
109 a single 32-bit value in memory. Alpha, red, green, and blue, color channels are
110 available at 8-bit precision per channel, ordered respectively from most to
111 least significant bits in little-endian storage. ``DRM_FORMAT_*`` is not
112 affected by either CPU or device endianness; the byte pattern in memory is
113 always as described in the format definition, which is usually little-endian.
115 As a more complex example, ``DRM_FORMAT_NV12`` describes a format in which luma
116 and chroma YUV samples are stored in separate planes, where the chroma plane is
117 stored at half the resolution in both dimensions (i.e. one U/V chroma
120 Format modifiers describe a translation mechanism between these per-pixel memory
122 modifier is ``DRM_FORMAT_MOD_LINEAR``, describing a scheme in which each plane
123 is laid out row-sequentially, from the top-left to the bottom-right corner.
130 are stored in 4x4 blocks arranged in row-major ordering, i.e. the first tile in
131 a plane stores pixels (0,0) to (3,3) inclusive, and the second tile in a plane
136 formats in which it stores data about the status of every tile, notably
140 These extended layouts are highly vendor-specific, and even specific to
141 particular generations or configurations of devices per-vendor. For this reason,
143 in order to ensure a compatible and optimal pipeline, as discussed below.
156 The in-memory storage of a buffer is not guaranteed to begin immediately at the
160 Each plane must therefore be described with an ``offset`` in bytes, which will be
161 added to the base address of the memory storage before performing any per-pixel
163 buffer; for example, ``DRM_FORMAT_NV12`` may be stored in a single memory buffer
168 Each plane must also have a ``stride`` in bytes, expressing the offset in memory
169 between two contiguous row. For example, a ``DRM_FORMAT_MOD_LINEAR`` buffer
170 with dimensions of 1000x1000 may have been allocated as if it were 1024x1000, in
171 order to allow for aligned access patterns. In this case, the buffer will still
176 Buffers may also be padded further in the y dimension, simply by allocating a
179 effective height of 1088 pixels. In this case, the buffer continues to be
190 the modifiers supported for each format. In userspace, this is supported through
207 - query KMS for the ``IN_FORMATS`` property for the given plane
208 - query Vulkan for the supported formats for its physical device, making sure
211 - intersect these formats to determine the most appropriate one
212 - for this format, intersect the lists of supported modifiers for both KMS and
221 buffers in this way, and an alternate strategy must be considered (e.g. using
222 CPU access routines to copy data between the different uses, with the
233 buffer-allocation interface available at either kernel or userspace level, the
239 this set of properties in different ways, such as allowing allocation in more
245 memory buffers such as whether they are stored in system or device-specific
248 ``dma-heaps`` API is an effort to address this.
251 modifier selected for the buffer, as well as the per-plane offset and stride.
252 Allocators are not permitted to vary the format in use, to select a modifier not
257 placement within a particular memory area, etc, is out of scope of dma-buf,
265 passes these parameters (format, modifier, width, height, and per-plane offset
271 per-plane offset parameters, or they may be completely separate allocations in
277 are not portable between contexts, processes, devices, or subsystems.
279 To address this, ``dma-buf`` handles are used as the universal interchange for
280 buffers. Subsystem-specific operations are used to export native buffer handles
281 to a ``dma-buf`` file descriptor, and to import those file descriptors into a
282 native buffer handle. dma-buf file descriptors can be transferred between
286 ``DRM_FORMAT_NV12`` buffer. This will result in two memory planes (luma and
288 one dma-buf file descriptor per plane, these descriptors are then sent along
289 with the metadata (format, modifier, width, height, per-plane offset and stride)
293 will take the same metadata and convert the dma-buf file descriptors into their
296 Having a non-empty intersection of supported modifiers does not guarantee that
304 The concept of modifiers post-dates all of the subsystems mentioned above. As
305 such, it has been retrofitted into all of these APIs, and in order to ensure
309 As an example, GBM is used to allocate buffers to be shared between EGL for
314 In the latter case, the allocation is as discussed above, being provided with a
316 it is not possible to allocate within those constraints). In the former case
319 implementation-specific: some will internally use tiled layouts which are not
320 CPU-accessible if the implementation decides that is a good idea through
326 pseudo-modifier declares that the layout is not known, and that the driver
331 ``DRM_FORMAT_MOD_INVALID`` is a non-zero value. The modifier value zero is
335 modifier. Also note that in some APIs the invalid modifier value is specified
336 with an out-of-band flag, like in ``DRM_IOCTL_MODE_ADDFB2``.
339 - during enumeration, an interface may return ``DRM_FORMAT_MOD_INVALID``, either
343 - during allocation, a user may supply ``DRM_FORMAT_MOD_INVALID``, either as the
348 - in a post-allocation query, an implementation may return
350 that the underlying layout is implementation-defined and that an explicit
354 - when importing a buffer, the user may supply ``DRM_FORMAT_MOD_INVALID`` as the
361 explicit. For example, if a user wishes to allocate a buffer for use between
366 separately and copy between the two buffers.
374 When allocating buffers for exchange between different users and modifiers are
377 for exchange. However, it is not guaranteed that this will result in the correct
379 subject to driver-specific heuristics.
381 Any new users - userspace programs and protocols, kernel subsystems, etc -
382 wishing to exchange buffers must offer interoperability through dma-buf file
384 format modifiers to describe the layout in memory, at least width and height for
387 …ps://gitlab.freedesktop.org/wayland/wayland-protocols/-/blob/main/unstable/linux-dmabuf/linux-dmab…
388 .. _VK_EXT_image_drm_format_modifier: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/…