Lines Matching +full:pixel +full:- +full:format
1 .. SPDX-License-Identifier: GPL-2.0
2 .. Copyright 2021-2023 Collabora Ltd.
5 Exchanging pixel buffers
9 support for sharing pixel-buffer allocations between processes, devices, and
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
27 format and modifier (implicit or explicit).
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
41 A piece of memory for storing (parts of) pixel data. Has stride and size
46 A two-dimensional array of some or all of an image's color and alpha
49 pixel:
54 pixel data:
56 of a pixel or an image. The data for one pixel may be spread over several
57 planes or memory buffers depending on format and modifier.
68 pixel format:
69 A description of how pixel data represents the pixel's color and alpha
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.
94 Each buffer must have an underlying format. This format describes the color
95 values provided for each pixel. Although each subsystem has its own format
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
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
118 sample is stored for each 2x2 pixel grouping).
120 Format modifiers describe a translation mechanism between these per-pixel memory
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,
149 Each pixel buffer must be accompanied by logical pixel dimensions. This refers
156 The in-memory storage of a buffer is not guaranteed to begin immediately at the
161 added to the base address of the memory storage before performing any per-pixel
187 Every user of pixel buffers must be able to enumerate a set of supported formats
190 the modifiers supported for each format. In userspace, this is supported through
196 format+modifier combinations.
202 It is the responsibility of userspace to negotiate an acceptable format+modifier
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
213 Vulkan, to obtain a final list of acceptable modifiers for that format
231 Once userspace has determined an appropriate format, and corresponding list of
233 buffer-allocation interface available at either kernel or userspace level, the
237 Each allocation request must take, at a minimum: the pixel format, a list of
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
253 provided within the acceptable list, nor to vary the pixel dimensions other than
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
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)
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
311 ``gbm_bo_create`` which only takes the format, width, height, and a usage token,
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
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
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
383 descriptors for memory planes, DRM format tokens to describe the format, DRM
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/…