Lines Matching +full:as +full:- +full:is
1 .. SPDX-License-Identifier: GPL-2.0
2 .. Copyright 2021-2023 Collabora Ltd.
8 As originally designed, the Linux graphics subsystem had extremely limited
9 support for sharing pixel-buffer allocations between processes, devices, and
12 approach this sharing for two-dimensional image data.
14 It is written with reference to the DRM subsystem for GPU and display devices,
25 Conceptually a two-dimensional array of pixels. The pixels may be stored
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
46 A two-dimensional array of some or all of an image's color and alpha
50 A picture element. Has a single color value which is defined by one or
52 have an alpha value as an additional channel.
60 A tuple of numbers, representing a color. Each element in the tuple is a
65 channels R, G, and B. Alpha channel is sometimes counted as a color
66 channel as well.
73 A description of how pixel data is laid out in memory buffers.
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.
97 wherever possible, as they are the standard descriptions used for interchange.
98 These tokens are described in the ``drm_fourcc.h`` file, which is a part of
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
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
118 sample is stored for each 2x2 pixel grouping).
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.
124 This is considered the baseline interchange format, and most convenient for CPU
130 are stored in 4x4 blocks arranged in row-major ordering, i.e. the first tile in
137 including whether the tile is fully populated with pixel data, or can be
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.
153 component, and 960x540 samples for the U and V components, the overall buffer is
154 still described as having dimensions of 1920x1080.
156 The in-memory storage of a buffer is not guaranteed to begin immediately at the
157 base address of the underlying memory, nor is it guaranteed that the memory
158 storage is tightly clipped to either dimension.
161 added to the base address of the memory storage before performing any per-pixel
170 with dimensions of 1000x1000 may have been allocated as if it were 1024x1000, in
180 described as having a height of 1080, with the memory allocation for each buffer
188 and modifiers, described together. Within KMS, this is achieved with the
190 the modifiers supported for each format. In userspace, this is supported through
202 It is the responsibility of userspace to negotiate an acceptable format+modifier
203 combination for its usage. This is performed through a simple intersection of
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
220 If the intersection of all lists is an empty list, it is not possible to share
225 The resulting modifier list is unsorted; the order is not significant.
232 acceptable modifiers, it must allocate the buffer. As there is no universal
233 buffer-allocation interface available at either kernel or userspace level, the
234 client makes an arbitrary choice of allocation interface such as Vulkan, GBM, or
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.
256 Communicating additional constraints, such as alignment of stride or offset,
257 placement within a particular memory area, etc, is out of scope of dma-buf,
258 and is not solved by format and modifier tokens.
265 passes these parameters (format, modifier, width, height, and per-plane offset
268 Each memory buffer is referred to by a buffer handle, which may be unique or
271 per-plane offset parameters, or they may be completely separate allocations in
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
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)
291 descriptors as an EGLImage for use through EGL/OpenGL (ES), a VkImage for use
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
306 backwards compatibility, support is needed for drivers and userspace which do
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
318 choice as to what is likely to be the 'best' layout. Such a choice is entirely
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
321 whatever heuristic. It is the implementation's responsibility to ensure that
322 this choice is appropriate.
324 To support this case where the layout is not known because there is no awareness
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
332 ``DRM_FORMAT_MOD_LINEAR``, which is an explicit guarantee that the image
334 zero as a default value is not mixed up with either no modifier or the linear
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
340 as the sole member of a modifier list to declare that explicit modifiers are
341 not supported, or as part of a larger list to declare that implicit modifiers
343 - during allocation, a user may supply ``DRM_FORMAT_MOD_INVALID``, either as the
346 used, or as part of a larger list to declare that an allocation using implicit
347 modifiers is acceptable
348 - in a post-allocation query, an implementation may return
349 ``DRM_FORMAT_MOD_INVALID`` as the modifier of the allocated buffer to declare
350 that the underlying layout is implementation-defined and that an explicit
351 modifier description is not available; per the above rules, this may only be
352 returned when the user has included ``DRM_FORMAT_MOD_INVALID`` as part of the
354 - when importing a buffer, the user may supply ``DRM_FORMAT_MOD_INVALID`` as the
355 buffer modifier (or not supply a modifier) to indicate that the modifier is
356 unknown for whatever reason; this is only acceptable when the buffer has
368 As one exception to the above, allocations may be 'upgraded' from implicit
369 to explicit modifiers. For example, if the buffer is allocated with
371 ``gbm_bo_get_modifier`` and then use this modifier as an explicit modifier token
372 if a valid modifier is returned.
376 ``DRM_FORMAT_MOD_LINEAR`` for their allocation, as this is the universal baseline
377 for exchange. However, it is not guaranteed that this will result in the correct
378 interpretation of buffer content, as implicit modifier operation may still be
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
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/…