sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget8/translations/zh_CN/userspace-api/dma-buf-alloc-exchangemodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget8/translations/zh_TW/userspace-api/dma-buf-alloc-exchangemodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget8/translations/it_IT/userspace-api/dma-buf-alloc-exchangemodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget8/translations/ja_JP/userspace-api/dma-buf-alloc-exchangemodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget8/translations/ko_KR/userspace-api/dma-buf-alloc-exchangemodnameN classnameN refexplicituh1hhh ubh)}(hhh]hPortuguese (Brazilian)}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget8/translations/pt_BR/userspace-api/dma-buf-alloc-exchangemodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget8/translations/sp_SP/userspace-api/dma-buf-alloc-exchangemodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhcomment)}(h SPDX-License-Identifier: GPL-2.0h]h SPDX-License-Identifier: GPL-2.0}hhsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1hhhhhhR/var/lib/git/docbuild/linux/Documentation/userspace-api/dma-buf-alloc-exchange.rsthKubh)}(h"Copyright 2021-2023 Collabora Ltd.h]h"Copyright 2021-2023 Collabora Ltd.}hhsbah}(h]h ]h"]h$]h&]hhuh1hhhhhhhhKubhsection)}(hhh](htitle)}(hExchanging pixel buffersh]hExchanging pixel buffers}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh paragraph)}(hXeAs originally designed, the Linux graphics subsystem had extremely limited support for sharing pixel-buffer allocations between processes, devices, and subsystems. Modern systems require extensive integration between all three classes; this document details how applications and kernel subsystems should approach this sharing for two-dimensional image data.h]hXeAs originally designed, the Linux graphics subsystem had extremely limited support for sharing pixel-buffer allocations between processes, devices, and subsystems. Modern systems require extensive integration between all three classes; this document details how applications and kernel subsystems should approach this sharing for two-dimensional image data.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hIt is written with reference to the DRM subsystem for GPU and display devices, V4L2 for media devices, and also to Vulkan, EGL and Wayland, for userspace support, however any other subsystems should also follow this design and advice.h]hIt is written with reference to the DRM subsystem for GPU and display devices, V4L2 for media devices, and also to Vulkan, EGL and Wayland, for userspace support, however any other subsystems should also follow this design and advice.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hhh](h)}(hGlossary of termsh]hGlossary of terms}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhKubhglossary)}(hhh]hdefinition_list)}(hhh](hdefinition_list_item)}(hhh](hterm)}(himage:h](himage:}(hj+hhhNhNubhindex)}(hhh]h}(h]h ]h"]h$]h&]entries](singleimage: term-imagemainNtauh1j3hhhKhj+ubeh}(h]jBah ]h"]h$]h&]uh1j)hhhKhj&ubh definition)}(hhh]h)}(hConceptually a two-dimensional array of pixels. The pixels may be stored in one or more memory buffers. Has width and height in pixels, pixel format and modifier (implicit or explicit).h]hConceptually a two-dimensional array of pixels. The pixels may be stored in one or more memory buffers. Has width and height in pixels, pixel format and modifier (implicit or explicit).}(hjPhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjMubah}(h]h ]h"]h$]h&]uh1jKhj&ubeh}(h]h ]h"]h$]h&]uh1j$hj!ubj%)}(hhh](j*)}(hrow:h](hrow:}(hjmhhhNhNubj4)}(hhh]h}(h]h ]h"]h$]h&]j>](j@row:term-rowjCNtauh1j3hhhKhjmubeh}(h]jah ]h"]h$]h&]uh1j)hhhKhjjubjL)}(hhh]h)}(hPA span along a single y-axis value, e.g. from co-ordinates (0,100) to (200,100).h]hPA span along a single y-axis value, e.g. from co-ordinates (0,100) to (200,100).}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jKhjjubeh}(h]h ]h"]h$]h&]uh1j$hj!ubj%)}(hhh](j*)}(h scanline:h](h scanline:}(hjhhhNhNubj4)}(hhh]h}(h]h ]h"]h$]h&]j>](j@ scanline: term-scanlinejCNtauh1j3hhhK hjubeh}(h]jah ]h"]h$]h&]uh1j)hhhK hjubjL)}(hhh]h)}(hSynonym for row.h]hSynonym for row.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK"hjubah}(h]h ]h"]h$]h&]uh1jKhjubeh}(h]h ]h"]h$]h&]uh1j$hj!ubj%)}(hhh](j*)}(hcolumn:h](hcolumn:}(hjhhhNhNubj4)}(hhh]h}(h]h ]h"]h$]h&]j>](j@column: term-columnjCNtauh1j3hhhK#hjubeh}(h]jah ]h"]h$]h&]uh1j)hhhK#hjubjL)}(hhh]h)}(hPA span along a single x-axis value, e.g. from co-ordinates (100,0) to (100,100).h]hPA span along a single x-axis value, e.g. from co-ordinates (100,0) to (100,100).}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK%hjubah}(h]h ]h"]h$]h&]uh1jKhjubeh}(h]h ]h"]h$]h&]uh1j$hj!ubj%)}(hhh](j*)}(hmemory buffer:h](hmemory buffer:}(hjhhhNhNubj4)}(hhh]h}(h]h ]h"]h$]h&]j>](j@memory buffer:term-memory-bufferjCNtauh1j3hhhK'hjubeh}(h]j1ah ]h"]h$]h&]uh1j)hhhK'hjubjL)}(hhh]h)}(hA piece of memory for storing (parts of) pixel data. Has stride and size in bytes and at least one handle in some API. May contain one or more planes.h]hA piece of memory for storing (parts of) pixel data. Has stride and size in bytes and at least one handle in some API. May contain one or more planes.}(hj<hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK)hj9ubah}(h]h ]h"]h$]h&]uh1jKhjubeh}(h]h ]h"]h$]h&]uh1j$hj!ubj%)}(hhh](j*)}(hplane:h](hplane:}(hjYhhhNhNubj4)}(hhh]h}(h]h ]h"]h$]h&]j>](j@plane: term-planejCNtauh1j3hhhK,hjYubeh}(h]jlah ]h"]h$]h&]uh1j)hhhK,hjVubjL)}(hhh]h)}(hTA two-dimensional array of some or all of an image's color and alpha channel values.h]hVA two-dimensional array of some or all of an image’s color and alpha channel values.}(hjwhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK.hjtubah}(h]h ]h"]h$]h&]uh1jKhjVubeh}(h]h ]h"]h$]h&]uh1j$hj!ubj%)}(hhh](j*)}(hpixel:h](hpixel:}(hjhhhNhNubj4)}(hhh]h}(h]h ]h"]h$]h&]j>](j@pixel: term-pixeljCNtauh1j3hhhK0hjubeh}(h]jah ]h"]h$]h&]uh1j)hhhK0hjubjL)}(hhh]h)}(hA picture element. Has a single color value which is defined by one or more color channels values, e.g. R, G and B, or Y, Cb and Cr. May also have an alpha value as an additional channel.h]hA picture element. Has a single color value which is defined by one or more color channels values, e.g. R, G and B, or Y, Cb and Cr. May also have an alpha value as an additional channel.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK2hjubah}(h]h ]h"]h$]h&]uh1jKhjubeh}(h]h ]h"]h$]h&]uh1j$hj!ubj%)}(hhh](j*)}(h pixel data:h](h pixel data:}(hjhhhNhNubj4)}(hhh]h}(h]h ]h"]h$]h&]j>](j@ pixel data:term-pixel-datajCNtauh1j3hhhK5hjubeh}(h]jah ]h"]h$]h&]uh1j)hhhK5hjubjL)}(hhh]h)}(hBytes or bits that represent some or all of the color/alpha channel values of a pixel or an image. The data for one pixel may be spread over several planes or memory buffers depending on format and modifier.h]hBytes or bits that represent some or all of the color/alpha channel values of a pixel or an image. The data for one pixel may be spread over several planes or memory buffers depending on format and modifier.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK7hjubah}(h]h ]h"]h$]h&]uh1jKhjubeh}(h]h ]h"]h$]h&]uh1j$hj!ubj%)}(hhh](j*)}(h color value:h](h color value:}(hj hhhNhNubj4)}(hhh]h}(h]h ]h"]h$]h&]j>](j@ color value:term-color-valuejCNtauh1j3hhhK:hj ubeh}(h]jah ]h"]h$]h&]uh1j)hhhK:hjubjL)}(hhh]h)}(h]A tuple of numbers, representing a color. Each element in the tuple is a color channel value.h]h]A tuple of numbers, representing a color. Each element in the tuple is a color channel value.}(hj(hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK](j@color channel:term-color-channeljCNtauh1j3hhhK>hjEubeh}(h]jXah ]h"]h$]h&]uh1j)hhhK>hjBubjL)}(hhh]h)}(hOne of the dimensions in a color model. For example, RGB model has channels R, G, and B. Alpha channel is sometimes counted as a color channel as well.h]hOne of the dimensions in a color model. For example, RGB model has channels R, G, and B. Alpha channel is sometimes counted as a color channel as well.}(hjchhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK@hj`ubah}(h]h ]h"]h$]h&]uh1jKhjBubeh}(h]h ]h"]h$]h&]uh1j$hj!ubj%)}(hhh](j*)}(h pixel format:h](h pixel format:}(hjhhhNhNubj4)}(hhh]h}(h]h ]h"]h$]h&]j>](j@ pixel format:term-pixel-formatjCNtauh1j3hhhKChjubeh}(h]jah ]h"]h$]h&]uh1j)hhhKChj}ubjL)}(hhh]h)}(hNA description of how pixel data represents the pixel's color and alpha values.h]hPA description of how pixel data represents the pixel’s color and alpha values.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKEhjubah}(h]h ]h"]h$]h&]uh1jKhj}ubeh}(h]h ]h"]h$]h&]uh1j$hj!ubj%)}(hhh](j*)}(h modifier:h](h modifier:}(hjhhhNhNubj4)}(hhh]h}(h]h ]h"]h$]h&]j>](j@ modifier: term-modifierjCNtauh1j3hhhKGhjubeh}(h]jah ]h"]h$]h&]uh1j)hhhKGhjubjL)}(hhh]h)}(h>A description of how pixel data is laid out in memory buffers.h]h>A description of how pixel data is laid out in memory buffers.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKIhjubah}(h]h ]h"]h$]h&]uh1jKhjubeh}(h]h ]h"]h$]h&]uh1j$hj!ubj%)}(hhh](j*)}(halpha:h](halpha:}(hjhhhNhNubj4)}(hhh]h}(h]h ]h"]h$]h&]j>](j@alpha: term-alphajCNtauh1j3hhhKJhjubeh}(h]j ah ]h"]h$]h&]uh1j)hhhKJhjubjL)}(hhh]h)}(h\A value that denotes the color coverage in a pixel. Sometimes used for translucency instead.h]h\A value that denotes the color coverage in a pixel. Sometimes used for translucency instead.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKLhjubah}(h]h ]h"]h$]h&]uh1jKhjubeh}(h]h ]h"]h$]h&]uh1j$hj!ubj%)}(hhh](j*)}(hstride:h](hstride:}(hj1hhhNhNubj4)}(hhh]h}(h]h ]h"]h$]h&]j>](j@stride: term-stridejCNtauh1j3hhhKNhj1ubeh}(h]jDah ]h"]h$]h&]uh1j)hhhKNhj.ubjL)}(hhh]h)}(hXA value that denotes the relationship between pixel-location co-ordinates and byte-offset values. Typically used as the byte offset between two pixels at the start of vertically-consecutive tiling blocks. For linear layouts, the byte offset between two vertically-adjacent pixels. For non-linear formats the stride must be computed in a consistent way, which usually is done as-if the layout was linear.h]hXA value that denotes the relationship between pixel-location co-ordinates and byte-offset values. Typically used as the byte offset between two pixels at the start of vertically-consecutive tiling blocks. For linear layouts, the byte offset between two vertically-adjacent pixels. For non-linear formats the stride must be computed in a consistent way, which usually is done as-if the layout was linear.}(hjOhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKPhjLubah}(h]h ]h"]h$]h&]uh1jKhj.ubeh}(h]h ]h"]h$]h&]uh1j$hj!ubj%)}(hhh](j*)}(hpitch:h](hpitch:}(hjlhhhNhNubj4)}(hhh]h}(h]h ]h"]h$]h&]j>](j@pitch: term-pitchjCNtauh1j3hhhKVhjlubeh}(h]jah ]h"]h$]h&]uh1j)hhhKVhjiubjL)}(hhh]h)}(hSynonym for stride.h]hSynonym for stride.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKXhjubah}(h]h ]h"]h$]h&]uh1jKhjiubeh}(h]h ]h"]h$]h&]uh1j$hj!ubeh}(h]h ]jah"]h$]h&]uh1jhjhhhhhNubah}(h]h ]h"]h$]h&]sorteduh1jhhhj hhhNubeh}(h]glossary-of-termsah ]h"]glossary of termsah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hFormats and modifiersh]hFormats and modifiers}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhK\ubh)}(hXEach buffer must have an underlying format. This format describes the color values provided for each pixel. Although each subsystem has its own format descriptions (e.g. V4L2 and fbdev), the ``DRM_FORMAT_*`` tokens should be reused wherever possible, as they are the standard descriptions used for interchange. These tokens are described in the ``drm_fourcc.h`` file, which is a part of DRM's uAPI.h](hEach buffer must have an underlying format. This format describes the color values provided for each pixel. Although each subsystem has its own format descriptions (e.g. V4L2 and fbdev), the }(hjhhhNhNubhliteral)}(h``DRM_FORMAT_*``h]h DRM_FORMAT_*}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh tokens should be reused wherever possible, as they are the standard descriptions used for interchange. These tokens are described in the }(hjhhhNhNubj)}(h``drm_fourcc.h``h]h drm_fourcc.h}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh' file, which is a part of DRM’s uAPI.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK^hjhhubh)}(hXEach ``DRM_FORMAT_*`` token describes the translation between a pixel co-ordinate in an image, and the color values for that pixel contained within its memory buffers. The number and type of color channels are described: whether they are RGB or YUV, integer or floating-point, the size of each channel and their locations within the pixel memory, and the relationship between color planes.h](hEach }(hjhhhNhNubj)}(h``DRM_FORMAT_*``h]h DRM_FORMAT_*}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhXp token describes the translation between a pixel co-ordinate in an image, and the color values for that pixel contained within its memory buffers. The number and type of color channels are described: whether they are RGB or YUV, integer or floating-point, the size of each channel and their locations within the pixel memory, and the relationship between color planes.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKehjhhubh)}(hXFor example, ``DRM_FORMAT_ARGB8888`` describes a format in which each pixel has a single 32-bit value in memory. Alpha, red, green, and blue, color channels are available at 8-bit precision per channel, ordered respectively from most to least significant bits in little-endian storage. ``DRM_FORMAT_*`` is not affected by either CPU or device endianness; the byte pattern in memory is always as described in the format definition, which is usually little-endian.h](h For example, }(hjhhhNhNubj)}(h``DRM_FORMAT_ARGB8888``h]hDRM_FORMAT_ARGB8888}(hj&hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh describes a format in which each pixel has a single 32-bit value in memory. Alpha, red, green, and blue, color channels are available at 8-bit precision per channel, ordered respectively from most to least significant bits in little-endian storage. }(hjhhhNhNubj)}(h``DRM_FORMAT_*``h]h DRM_FORMAT_*}(hj8hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh is not affected by either CPU or device endianness; the byte pattern in memory is always as described in the format definition, which is usually little-endian.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKlhjhhubh)}(hXAs a more complex example, ``DRM_FORMAT_NV12`` describes a format in which luma and chroma YUV samples are stored in separate planes, where the chroma plane is stored at half the resolution in both dimensions (i.e. one U/V chroma sample is stored for each 2x2 pixel grouping).h](hAs a more complex example, }(hjPhhhNhNubj)}(h``DRM_FORMAT_NV12``h]hDRM_FORMAT_NV12}(hjXhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjPubh describes a format in which luma and chroma YUV samples are stored in separate planes, where the chroma plane is stored at half the resolution in both dimensions (i.e. one U/V chroma sample is stored for each 2x2 pixel grouping).}(hjPhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKshjhhubh)}(hXFormat modifiers describe a translation mechanism between these per-pixel memory samples, and the actual memory storage for the buffer. The most straightforward modifier is ``DRM_FORMAT_MOD_LINEAR``, describing a scheme in which each plane is laid out row-sequentially, from the top-left to the bottom-right corner. This is considered the baseline interchange format, and most convenient for CPU access.h](hFormat modifiers describe a translation mechanism between these per-pixel memory samples, and the actual memory storage for the buffer. The most straightforward modifier is }(hjphhhNhNubj)}(h``DRM_FORMAT_MOD_LINEAR``h]hDRM_FORMAT_MOD_LINEAR}(hjxhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjpubh, describing a scheme in which each plane is laid out row-sequentially, from the top-left to the bottom-right corner. This is considered the baseline interchange format, and most convenient for CPU access.}(hjphhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKxhjhhubh)}(hXModern hardware employs much more sophisticated access mechanisms, typically making use of tiled access and possibly also compression. For example, the ``DRM_FORMAT_MOD_VIVANTE_TILED`` modifier describes memory storage where pixels are stored in 4x4 blocks arranged in row-major ordering, i.e. the first tile in a plane stores pixels (0,0) to (3,3) inclusive, and the second tile in a plane stores pixels (4,0) to (7,3) inclusive.h](hModern hardware employs much more sophisticated access mechanisms, typically making use of tiled access and possibly also compression. For example, the }(hjhhhNhNubj)}(h ``DRM_FORMAT_MOD_VIVANTE_TILED``h]hDRM_FORMAT_MOD_VIVANTE_TILED}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh modifier describes memory storage where pixels are stored in 4x4 blocks arranged in row-major ordering, i.e. the first tile in a plane stores pixels (0,0) to (3,3) inclusive, and the second tile in a plane stores pixels (4,0) to (7,3) inclusive.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXOSome modifiers may modify the number of planes required for an image; for example, the ``I915_FORMAT_MOD_Y_TILED_CCS`` modifier adds a second plane to RGB formats in which it stores data about the status of every tile, notably including whether the tile is fully populated with pixel data, or can be expanded from a single solid color.h](hWSome modifiers may modify the number of planes required for an image; for example, the }(hjhhhNhNubj)}(h``I915_FORMAT_MOD_Y_TILED_CCS``h]hI915_FORMAT_MOD_Y_TILED_CCS}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh modifier adds a second plane to RGB formats in which it stores data about the status of every tile, notably including whether the tile is fully populated with pixel data, or can be expanded from a single solid color.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hX1These extended layouts are highly vendor-specific, and even specific to particular generations or configurations of devices per-vendor. For this reason, support of modifiers must be explicitly enumerated and negotiated by all users in order to ensure a compatible and optimal pipeline, as discussed below.h]hX1These extended layouts are highly vendor-specific, and even specific to particular generations or configurations of devices per-vendor. For this reason, support of modifiers must be explicitly enumerated and negotiated by all users in order to ensure a compatible and optimal pipeline, as discussed below.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]formats-and-modifiersah ]h"]formats and modifiersah$]h&]uh1hhhhhhhhK\ubh)}(hhh](h)}(hDimensions and sizeh]hDimensions and size}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hXEach pixel buffer must be accompanied by logical pixel dimensions. This refers to the number of unique samples which can be extracted from, or stored to, the underlying memory storage. For example, even though a 1920x1080 ``DRM_FORMAT_NV12`` buffer has a luma plane containing 1920x1080 samples for the Y component, and 960x540 samples for the U and V components, the overall buffer is still described as having dimensions of 1920x1080.h](hEach pixel buffer must be accompanied by logical pixel dimensions. This refers to the number of unique samples which can be extracted from, or stored to, the underlying memory storage. For example, even though a 1920x1080 }(hjhhhNhNubj)}(h``DRM_FORMAT_NV12``h]hDRM_FORMAT_NV12}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh buffer has a luma plane containing 1920x1080 samples for the Y component, and 960x540 samples for the U and V components, the overall buffer is still described as having dimensions of 1920x1080.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hThe in-memory storage of a buffer is not guaranteed to begin immediately at the base address of the underlying memory, nor is it guaranteed that the memory storage is tightly clipped to either dimension.h]hThe in-memory storage of a buffer is not guaranteed to begin immediately at the base address of the underlying memory, nor is it guaranteed that the memory storage is tightly clipped to either dimension.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXEach plane must therefore be described with an ``offset`` in bytes, which will be added to the base address of the memory storage before performing any per-pixel calculations. This may be used to combine multiple planes into a single memory buffer; for example, ``DRM_FORMAT_NV12`` may be stored in a single memory buffer where the luma plane's storage begins immediately at the start of the buffer with an offset of 0, and the chroma plane's storage follows within the same buffer beginning from the byte offset for that plane.h](h/Each plane must therefore be described with an }(hj%hhhNhNubj)}(h ``offset``h]hoffset}(hj-hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj%ubh in bytes, which will be added to the base address of the memory storage before performing any per-pixel calculations. This may be used to combine multiple planes into a single memory buffer; for example, }(hj%hhhNhNubj)}(h``DRM_FORMAT_NV12``h]hDRM_FORMAT_NV12}(hj?hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj%ubh may be stored in a single memory buffer where the luma plane’s storage begins immediately at the start of the buffer with an offset of 0, and the chroma plane’s storage follows within the same buffer beginning from the byte offset for that plane.}(hj%hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXEach plane must also have a ``stride`` in bytes, expressing the offset in memory between two contiguous row. For example, a ``DRM_FORMAT_MOD_LINEAR`` buffer with dimensions of 1000x1000 may have been allocated as if it were 1024x1000, in order to allow for aligned access patterns. In this case, the buffer will still be described with a width of 1000, however the stride will be ``1024 * bpp``, indicating that there are 24 pixels at the positive extreme of the x axis whose values are not significant.h](hEach plane must also have a }(hjWhhhNhNubj)}(h ``stride``h]hstride}(hj_hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjWubhV in bytes, expressing the offset in memory between two contiguous row. For example, a }(hjWhhhNhNubj)}(h``DRM_FORMAT_MOD_LINEAR``h]hDRM_FORMAT_MOD_LINEAR}(hjqhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjWubh buffer with dimensions of 1000x1000 may have been allocated as if it were 1024x1000, in order to allow for aligned access patterns. In this case, the buffer will still be described with a width of 1000, however the stride will be }(hjWhhhNhNubj)}(h``1024 * bpp``h]h 1024 * bpp}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjWubhm, indicating that there are 24 pixels at the positive extreme of the x axis whose values are not significant.}(hjWhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXBuffers may also be padded further in the y dimension, simply by allocating a larger area than would ordinarily be required. For example, many media decoders are not able to natively output buffers of height 1080, but instead require an effective height of 1088 pixels. In this case, the buffer continues to be described as having a height of 1080, with the memory allocation for each buffer being increased to account for the extra padding.h]hXBuffers may also be padded further in the y dimension, simply by allocating a larger area than would ordinarily be required. For example, many media decoders are not able to natively output buffers of height 1080, but instead require an effective height of 1088 pixels. In this case, the buffer continues to be described as having a height of 1080, with the memory allocation for each buffer being increased to account for the extra padding.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]dimensions-and-sizeah ]h"]dimensions and sizeah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h Enumerationh]h Enumeration}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hXEvery user of pixel buffers must be able to enumerate a set of supported formats and modifiers, described together. Within KMS, this is achieved with the ``IN_FORMATS`` property on each DRM plane, listing the supported DRM formats, and the modifiers supported for each format. In userspace, this is supported through the `EGL_EXT_image_dma_buf_import_modifiers`_ extension entrypoints for EGL, the `VK_EXT_image_drm_format_modifier`_ extension for Vulkan, and the `zwp_linux_dmabuf_v1`_ extension for Wayland.h](hEvery user of pixel buffers must be able to enumerate a set of supported formats and modifiers, described together. Within KMS, this is achieved with the }(hjhhhNhNubj)}(h``IN_FORMATS``h]h IN_FORMATS}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh property on each DRM plane, listing the supported DRM formats, and the modifiers supported for each format. In userspace, this is supported through the }(hjhhhNhNubh reference)}(h)`EGL_EXT_image_dma_buf_import_modifiers`_h]h&EGL_EXT_image_dma_buf_import_modifiers}(hjhhhNhNubah}(h]h ]h"]h$]h&]name&EGL_EXT_image_dma_buf_import_modifiersrefuriZhttps://registry.khronos.org/EGL/extensions/EXT/EGL_EXT_image_dma_buf_import_modifiers.txtuh1jhjresolvedKubh$ extension entrypoints for EGL, the }(hjhhhNhNubj)}(h#`VK_EXT_image_drm_format_modifier`_h]h VK_EXT_image_drm_format_modifier}(hjhhhNhNubah}(h]h ]h"]h$]h&]name VK_EXT_image_drm_format_modifierjghttps://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_EXT_image_drm_format_modifier.htmluh1jhjjKubh extension for Vulkan, and the }(hjhhhNhNubj)}(h`zwp_linux_dmabuf_v1`_h]hzwp_linux_dmabuf_v1}(hj hhhNhNubah}(h]h ]h"]h$]h&]namezwp_linux_dmabuf_v1jwhttps://gitlab.freedesktop.org/wayland/wayland-protocols/-/blob/main/unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xmluh1jhjjKubh extension for Wayland.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(h_Each of these interfaces allows users to query a set of supported format+modifier combinations.h]h_Each of these interfaces allows users to query a set of supported format+modifier combinations.}(hj%hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h] enumerationah ]h"] enumerationah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h Negotiationh]h Negotiation}(hj>hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj;hhhhhKubh)}(hX It is the responsibility of userspace to negotiate an acceptable format+modifier combination for its usage. This is performed through a simple intersection of lists. For example, if a user wants to use Vulkan to render an image to be displayed on a KMS plane, it must:h]hX It is the responsibility of userspace to negotiate an acceptable format+modifier combination for its usage. This is performed through a simple intersection of lists. For example, if a user wants to use Vulkan to render an image to be displayed on a KMS plane, it must:}(hjLhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj;hhubh block_quote)}(hX- query KMS for the ``IN_FORMATS`` property for the given plane - query Vulkan for the supported formats for its physical device, making sure to pass the ``VkImageUsageFlagBits`` and ``VkImageCreateFlagBits`` corresponding to the intended rendering use - intersect these formats to determine the most appropriate one - for this format, intersect the lists of supported modifiers for both KMS and Vulkan, to obtain a final list of acceptable modifiers for that format h]h bullet_list)}(hhh](h list_item)}(h=query KMS for the ``IN_FORMATS`` property for the given planeh]h)}(hjih](hquery KMS for the }(hjkhhhNhNubj)}(h``IN_FORMATS``h]h IN_FORMATS}(hjrhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjkubh property for the given plane}(hjkhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjgubah}(h]h ]h"]h$]h&]uh1jehjbubjf)}(hquery Vulkan for the supported formats for its physical device, making sure to pass the ``VkImageUsageFlagBits`` and ``VkImageCreateFlagBits`` corresponding to the intended rendering useh]h)}(hquery Vulkan for the supported formats for its physical device, making sure to pass the ``VkImageUsageFlagBits`` and ``VkImageCreateFlagBits`` corresponding to the intended rendering useh](hXquery Vulkan for the supported formats for its physical device, making sure to pass the }(hjhhhNhNubj)}(h``VkImageUsageFlagBits``h]hVkImageUsageFlagBits}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh and }(hjhhhNhNubj)}(h``VkImageCreateFlagBits``h]hVkImageCreateFlagBits}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh, corresponding to the intended rendering use}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jehjbubjf)}(h=intersect these formats to determine the most appropriate oneh]h)}(hjh]h=intersect these formats to determine the most appropriate one}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jehjbubjf)}(hfor this format, intersect the lists of supported modifiers for both KMS and Vulkan, to obtain a final list of acceptable modifiers for that format h]h)}(hfor this format, intersect the lists of supported modifiers for both KMS and Vulkan, to obtain a final list of acceptable modifiers for that formath]hfor this format, intersect the lists of supported modifiers for both KMS and Vulkan, to obtain a final list of acceptable modifiers for that format}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jehjbubeh}(h]h ]h"]h$]h&]bullet-uh1j`hhhKhj\ubah}(h]h ]h"]h$]h&]uh1jZhhhKhj;hhubh)}(hXThis intersection must be performed for all usages. For example, if the user also wishes to encode the image to a video stream, it must query the media API it intends to use for encoding for the set of modifiers it supports, and additionally intersect against this list.h]hXThis intersection must be performed for all usages. For example, if the user also wishes to encode the image to a video stream, it must query the media API it intends to use for encoding for the set of modifiers it supports, and additionally intersect against this list.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj;hhubh)}(hXIf the intersection of all lists is an empty list, it is not possible to share buffers in this way, and an alternate strategy must be considered (e.g. using CPU access routines to copy data between the different uses, with the corresponding performance cost).h]hXIf the intersection of all lists is an empty list, it is not possible to share buffers in this way, and an alternate strategy must be considered (e.g. using CPU access routines to copy data between the different uses, with the corresponding performance cost).}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj;hhubh)}(hFThe resulting modifier list is unsorted; the order is not significant.h]hFThe resulting modifier list is unsorted; the order is not significant.}(hj%hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj;hhubeh}(h] negotiationah ]h"] negotiationah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h Allocationh]h Allocation}(hj>hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj;hhhhhKubh)}(hXGOnce userspace has determined an appropriate format, and corresponding list of acceptable modifiers, it must allocate the buffer. As there is no universal buffer-allocation interface available at either kernel or userspace level, the client makes an arbitrary choice of allocation interface such as Vulkan, GBM, or a media API.h]hXGOnce userspace has determined an appropriate format, and corresponding list of acceptable modifiers, it must allocate the buffer. As there is no universal buffer-allocation interface available at either kernel or userspace level, the client makes an arbitrary choice of allocation interface such as Vulkan, GBM, or a media API.}(hjLhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj;hhubh)}(hXEach allocation request must take, at a minimum: the pixel format, a list of acceptable modifiers, and the buffer's width and height. Each API may extend this set of properties in different ways, such as allowing allocation in more than two dimensions, intended usage patterns, etc.h]hXEach allocation request must take, at a minimum: the pixel format, a list of acceptable modifiers, and the buffer’s width and height. Each API may extend this set of properties in different ways, such as allowing allocation in more than two dimensions, intended usage patterns, etc.}(hjZhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj;hhubh)}(hXThe component which allocates the buffer will make an arbitrary choice of what it considers the 'best' modifier within the acceptable list for the requested allocation, any padding required, and further properties of the underlying memory buffers such as whether they are stored in system or device-specific memory, whether or not they are physically contiguous, and their cache mode. These properties of the memory buffer are not visible to userspace, however the ``dma-heaps`` API is an effort to address this.h](hXThe component which allocates the buffer will make an arbitrary choice of what it considers the ‘best’ modifier within the acceptable list for the requested allocation, any padding required, and further properties of the underlying memory buffers such as whether they are stored in system or device-specific memory, whether or not they are physically contiguous, and their cache mode. These properties of the memory buffer are not visible to userspace, however the }(hjhhhhNhNubj)}(h ``dma-heaps``h]h dma-heaps}(hjphhhNhNubah}(h]h ]h"]h$]h&]uh1jhjhubh" API is an effort to address this.}(hjhhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj;hhubh)}(hXuAfter allocation, the client must query the allocator to determine the actual modifier selected for the buffer, as well as the per-plane offset and stride. Allocators are not permitted to vary the format in use, to select a modifier not provided within the acceptable list, nor to vary the pixel dimensions other than the padding expressed through offset, stride, and size.h]hXuAfter allocation, the client must query the allocator to determine the actual modifier selected for the buffer, as well as the per-plane offset and stride. Allocators are not permitted to vary the format in use, to select a modifier not provided within the acceptable list, nor to vary the pixel dimensions other than the padding expressed through offset, stride, and size.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj;hhubh)}(hCommunicating additional constraints, such as alignment of stride or offset, placement within a particular memory area, etc, is out of scope of dma-buf, and is not solved by format and modifier tokens.h]hCommunicating additional constraints, such as alignment of stride or offset, placement within a particular memory area, etc, is out of scope of dma-buf, and is not solved by format and modifier tokens.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj;hhubeh}(h] allocationah ]h"] allocationah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hImporth]hImport}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hTo use a buffer within a different context, device, or subsystem, the user passes these parameters (format, modifier, width, height, and per-plane offset and stride) to an importing API.h]hTo use a buffer within a different context, device, or subsystem, the user passes these parameters (format, modifier, width, height, and per-plane offset and stride) to an importing API.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hXEach memory buffer is referred to by a buffer handle, which may be unique or duplicated within an image. For example, a ``DRM_FORMAT_NV12`` buffer may have the luma and chroma buffers combined into a single memory buffer by use of the per-plane offset parameters, or they may be completely separate allocations in memory. For this reason, each import and allocation API must provide a separate handle for each plane.h](hxEach memory buffer is referred to by a buffer handle, which may be unique or duplicated within an image. For example, a }(hjhhhNhNubj)}(h``DRM_FORMAT_NV12``h]hDRM_FORMAT_NV12}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhX buffer may have the luma and chroma buffers combined into a single memory buffer by use of the per-plane offset parameters, or they may be completely separate allocations in memory. For this reason, each import and allocation API must provide a separate handle for each plane.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM hjhhubh)}(hEach kernel subsystem has its own types and interfaces for buffer management. DRM uses GEM buffer objects (BOs), V4L2 has its own references, etc. These types are not portable between contexts, processes, devices, or subsystems.h]hEach kernel subsystem has its own types and interfaces for buffer management. DRM uses GEM buffer objects (BOs), V4L2 has its own references, etc. These types are not portable between contexts, processes, devices, or subsystems.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hXdTo address this, ``dma-buf`` handles are used as the universal interchange for buffers. Subsystem-specific operations are used to export native buffer handles to a ``dma-buf`` file descriptor, and to import those file descriptors into a native buffer handle. dma-buf file descriptors can be transferred between contexts, processes, devices, and subsystems.h](hTo address this, }(hjhhhNhNubj)}(h ``dma-buf``h]hdma-buf}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh handles are used as the universal interchange for buffers. Subsystem-specific operations are used to export native buffer handles to a }(hjhhhNhNubj)}(h ``dma-buf``h]hdma-buf}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh file descriptor, and to import those file descriptors into a native buffer handle. dma-buf file descriptors can be transferred between contexts, processes, devices, and subsystems.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hXFor example, a Wayland media player may use V4L2 to decode a video frame into a ``DRM_FORMAT_NV12`` buffer. This will result in two memory planes (luma and chroma) being dequeued by the user from V4L2. These planes are then exported to one dma-buf file descriptor per plane, these descriptors are then sent along with the metadata (format, modifier, width, height, per-plane offset and stride) to the Wayland server. The Wayland server will then import these file descriptors as an EGLImage for use through EGL/OpenGL (ES), a VkImage for use through Vulkan, or a KMS framebuffer object; each of these import operations will take the same metadata and convert the dma-buf file descriptors into their native buffer handles.h](hPFor example, a Wayland media player may use V4L2 to decode a video frame into a }(hj+ hhhNhNubj)}(h``DRM_FORMAT_NV12``h]hDRM_FORMAT_NV12}(hj3 hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj+ ubhXn buffer. This will result in two memory planes (luma and chroma) being dequeued by the user from V4L2. These planes are then exported to one dma-buf file descriptor per plane, these descriptors are then sent along with the metadata (format, modifier, width, height, per-plane offset and stride) to the Wayland server. The Wayland server will then import these file descriptors as an EGLImage for use through EGL/OpenGL (ES), a VkImage for use through Vulkan, or a KMS framebuffer object; each of these import operations will take the same metadata and convert the dma-buf file descriptors into their native buffer handles.}(hj+ hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hHaving a non-empty intersection of supported modifiers does not guarantee that import will succeed into all consumers; they may have constraints beyond those implied by modifiers which must be satisfied.h]hHaving a non-empty intersection of supported modifiers does not guarantee that import will succeed into all consumers; they may have constraints beyond those implied by modifiers which must be satisfied.}(hjK hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM(hjhhubeh}(h]importah ]h"]importah$]h&]uh1hhhhhhhhMubh)}(hhh](h)}(hImplicit modifiersh]hImplicit modifiers}(hjd hhhNhNubah}(h]h ]h"]h$]h&]uh1hhja hhhhhM.ubh)}(hXThe concept of modifiers post-dates all of the subsystems mentioned above. As such, it has been retrofitted into all of these APIs, and in order to ensure backwards compatibility, support is needed for drivers and userspace which do not (yet) support modifiers.h]hXThe concept of modifiers post-dates all of the subsystems mentioned above. As such, it has been retrofitted into all of these APIs, and in order to ensure backwards compatibility, support is needed for drivers and userspace which do not (yet) support modifiers.}(hjr hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM0hja hhubh)}(hX<As an example, GBM is used to allocate buffers to be shared between EGL for rendering and KMS for display. It has two entrypoints for allocating buffers: ``gbm_bo_create`` which only takes the format, width, height, and a usage token, and ``gbm_bo_create_with_modifiers`` which extends this with a list of modifiers.h](hAs an example, GBM is used to allocate buffers to be shared between EGL for rendering and KMS for display. It has two entrypoints for allocating buffers: }(hj hhhNhNubj)}(h``gbm_bo_create``h]h gbm_bo_create}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubhD which only takes the format, width, height, and a usage token, and }(hj hhhNhNubj)}(h ``gbm_bo_create_with_modifiers``h]hgbm_bo_create_with_modifiers}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh- which extends this with a list of modifiers.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM5hja hhubh)}(hXIn the latter case, the allocation is as discussed above, being provided with a list of acceptable modifiers that the implementation can choose from (or fail if it is not possible to allocate within those constraints). In the former case where modifiers are not provided, the GBM implementation must make its own choice as to what is likely to be the 'best' layout. Such a choice is entirely implementation-specific: some will internally use tiled layouts which are not CPU-accessible if the implementation decides that is a good idea through whatever heuristic. It is the implementation's responsibility to ensure that this choice is appropriate.h]hXIn the latter case, the allocation is as discussed above, being provided with a list of acceptable modifiers that the implementation can choose from (or fail if it is not possible to allocate within those constraints). In the former case where modifiers are not provided, the GBM implementation must make its own choice as to what is likely to be the ‘best’ layout. Such a choice is entirely implementation-specific: some will internally use tiled layouts which are not CPU-accessible if the implementation decides that is a good idea through whatever heuristic. It is the implementation’s responsibility to ensure that this choice is appropriate.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM:hja hhubh)}(hX4To support this case where the layout is not known because there is no awareness of modifiers, a special ``DRM_FORMAT_MOD_INVALID`` token has been defined. This pseudo-modifier declares that the layout is not known, and that the driver should use its own logic to determine what the underlying layout may be.h](hiTo support this case where the layout is not known because there is no awareness of modifiers, a special }(hj hhhNhNubj)}(h``DRM_FORMAT_MOD_INVALID``h]hDRM_FORMAT_MOD_INVALID}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh token has been defined. This pseudo-modifier declares that the layout is not known, and that the driver should use its own logic to determine what the underlying layout may be.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMDhja hhubhnote)}(hX``DRM_FORMAT_MOD_INVALID`` is a non-zero value. The modifier value zero is ``DRM_FORMAT_MOD_LINEAR``, which is an explicit guarantee that the image has the linear layout. Care and attention should be taken to ensure that zero as a default value is not mixed up with either no modifier or the linear modifier. Also note that in some APIs the invalid modifier value is specified with an out-of-band flag, like in ``DRM_IOCTL_MODE_ADDFB2``.h]h)}(hX``DRM_FORMAT_MOD_INVALID`` is a non-zero value. The modifier value zero is ``DRM_FORMAT_MOD_LINEAR``, which is an explicit guarantee that the image has the linear layout. Care and attention should be taken to ensure that zero as a default value is not mixed up with either no modifier or the linear modifier. Also note that in some APIs the invalid modifier value is specified with an out-of-band flag, like in ``DRM_IOCTL_MODE_ADDFB2``.h](j)}(h``DRM_FORMAT_MOD_INVALID``h]hDRM_FORMAT_MOD_INVALID}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh1 is a non-zero value. The modifier value zero is }(hj hhhNhNubj)}(h``DRM_FORMAT_MOD_LINEAR``h]hDRM_FORMAT_MOD_LINEAR}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubhX7, which is an explicit guarantee that the image has the linear layout. Care and attention should be taken to ensure that zero as a default value is not mixed up with either no modifier or the linear modifier. Also note that in some APIs the invalid modifier value is specified with an out-of-band flag, like in }(hj hhhNhNubj)}(h``DRM_IOCTL_MODE_ADDFB2``h]hDRM_IOCTL_MODE_ADDFB2}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMKhj ubah}(h]h ]h"]h$]h&]uh1j hja hhhhhNubj )}(hhh]j%)}(hXPThere are four cases where this token may be used: - during enumeration, an interface may return ``DRM_FORMAT_MOD_INVALID``, either as the sole member of a modifier list to declare that explicit modifiers are not supported, or as part of a larger list to declare that implicit modifiers may be used - during allocation, a user may supply ``DRM_FORMAT_MOD_INVALID``, either as the sole member of a modifier list (equivalent to not supplying a modifier list at all) to declare that explicit modifiers are not supported and must not be used, or as part of a larger list to declare that an allocation using implicit modifiers is acceptable - in a post-allocation query, an implementation may return ``DRM_FORMAT_MOD_INVALID`` as the modifier of the allocated buffer to declare that the underlying layout is implementation-defined and that an explicit modifier description is not available; per the above rules, this may only be returned when the user has included ``DRM_FORMAT_MOD_INVALID`` as part of the list of acceptable modifiers, or not provided a list - when importing a buffer, the user may supply ``DRM_FORMAT_MOD_INVALID`` as the buffer modifier (or not supply a modifier) to indicate that the modifier is unknown for whatever reason; this is only acceptable when the buffer has not been allocated with an explicit modifier h](j*)}(h2There are four cases where this token may be used:h]h2There are four cases where this token may be used:}(hj3 hhhNhNubah}(h]h ]h"]h$]h&]uh1j)hhhMehj/ ubjL)}(hhh]ja)}(hhh](jf)}(hduring enumeration, an interface may return ``DRM_FORMAT_MOD_INVALID``, either as the sole member of a modifier list to declare that explicit modifiers are not supported, or as part of a larger list to declare that implicit modifiers may be usedh]h)}(hduring enumeration, an interface may return ``DRM_FORMAT_MOD_INVALID``, either as the sole member of a modifier list to declare that explicit modifiers are not supported, or as part of a larger list to declare that implicit modifiers may be usedh](h,during enumeration, an interface may return }(hjK hhhNhNubj)}(h``DRM_FORMAT_MOD_INVALID``h]hDRM_FORMAT_MOD_INVALID}(hjS hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjK ubh, either as the sole member of a modifier list to declare that explicit modifiers are not supported, or as part of a larger list to declare that implicit modifiers may be used}(hjK hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMShjG ubah}(h]h ]h"]h$]h&]uh1jehjD ubjf)}(hXNduring allocation, a user may supply ``DRM_FORMAT_MOD_INVALID``, either as the sole member of a modifier list (equivalent to not supplying a modifier list at all) to declare that explicit modifiers are not supported and must not be used, or as part of a larger list to declare that an allocation using implicit modifiers is acceptableh]h)}(hXNduring allocation, a user may supply ``DRM_FORMAT_MOD_INVALID``, either as the sole member of a modifier list (equivalent to not supplying a modifier list at all) to declare that explicit modifiers are not supported and must not be used, or as part of a larger list to declare that an allocation using implicit modifiers is acceptableh](h%during allocation, a user may supply }(hju hhhNhNubj)}(h``DRM_FORMAT_MOD_INVALID``h]hDRM_FORMAT_MOD_INVALID}(hj} hhhNhNubah}(h]h ]h"]h$]h&]uh1jhju ubhX, either as the sole member of a modifier list (equivalent to not supplying a modifier list at all) to declare that explicit modifiers are not supported and must not be used, or as part of a larger list to declare that an allocation using implicit modifiers is acceptable}(hju hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMWhjq ubah}(h]h ]h"]h$]h&]uh1jehjD ubjf)}(hXin a post-allocation query, an implementation may return ``DRM_FORMAT_MOD_INVALID`` as the modifier of the allocated buffer to declare that the underlying layout is implementation-defined and that an explicit modifier description is not available; per the above rules, this may only be returned when the user has included ``DRM_FORMAT_MOD_INVALID`` as part of the list of acceptable modifiers, or not provided a listh]h)}(hXin a post-allocation query, an implementation may return ``DRM_FORMAT_MOD_INVALID`` as the modifier of the allocated buffer to declare that the underlying layout is implementation-defined and that an explicit modifier description is not available; per the above rules, this may only be returned when the user has included ``DRM_FORMAT_MOD_INVALID`` as part of the list of acceptable modifiers, or not provided a listh](h9in a post-allocation query, an implementation may return }(hj hhhNhNubj)}(h``DRM_FORMAT_MOD_INVALID``h]hDRM_FORMAT_MOD_INVALID}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh as the modifier of the allocated buffer to declare that the underlying layout is implementation-defined and that an explicit modifier description is not available; per the above rules, this may only be returned when the user has included }(hj hhhNhNubj)}(h``DRM_FORMAT_MOD_INVALID``h]hDRM_FORMAT_MOD_INVALID}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubhD as part of the list of acceptable modifiers, or not provided a list}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM\hj ubah}(h]h ]h"]h$]h&]uh1jehjD ubjf)}(hXwhen importing a buffer, the user may supply ``DRM_FORMAT_MOD_INVALID`` as the buffer modifier (or not supply a modifier) to indicate that the modifier is unknown for whatever reason; this is only acceptable when the buffer has not been allocated with an explicit modifier h]h)}(hXwhen importing a buffer, the user may supply ``DRM_FORMAT_MOD_INVALID`` as the buffer modifier (or not supply a modifier) to indicate that the modifier is unknown for whatever reason; this is only acceptable when the buffer has not been allocated with an explicit modifierh](h-when importing a buffer, the user may supply }(hj hhhNhNubj)}(h``DRM_FORMAT_MOD_INVALID``h]hDRM_FORMAT_MOD_INVALID}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh as the buffer modifier (or not supply a modifier) to indicate that the modifier is unknown for whatever reason; this is only acceptable when the buffer has not been allocated with an explicit modifier}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMbhj ubah}(h]h ]h"]h$]h&]uh1jehjD ubeh}(h]h ]h"]h$]h&]jjuh1j`hhhMShjA ubah}(h]h ]h"]h$]h&]uh1jKhj/ ubeh}(h]h ]h"]h$]h&]uh1j$hhhMehj, ubah}(h]h ]h"]h$]h&]uh1jhja hhhNhNubh)}(hXTIt follows from this that for any single buffer, the complete chain of operations formed by the producer and all the consumers must be either fully implicit or fully explicit. For example, if a user wishes to allocate a buffer for use between GPU, display, and media, but the media API does not support modifiers, then the user **must not** allocate the buffer with explicit modifiers and attempt to import the buffer into the media API with no modifier, but either perform the allocation using implicit modifiers, or allocate the buffer for media use separately and copy between the two buffers.h](hXHIt follows from this that for any single buffer, the complete chain of operations formed by the producer and all the consumers must be either fully implicit or fully explicit. For example, if a user wishes to allocate a buffer for use between GPU, display, and media, but the media API does not support modifiers, then the user }(hj hhhNhNubhstrong)}(h **must not**h]hmust not}(hj# hhhNhNubah}(h]h ]h"]h$]h&]uh1j! hj ubhX allocate the buffer with explicit modifiers and attempt to import the buffer into the media API with no modifier, but either perform the allocation using implicit modifiers, or allocate the buffer for media use separately and copy between the two buffers.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMghja hhubh)}(hXSAs one exception to the above, allocations may be 'upgraded' from implicit to explicit modifiers. For example, if the buffer is allocated with ``gbm_bo_create`` (taking no modifiers), the user may then query the modifier with ``gbm_bo_get_modifier`` and then use this modifier as an explicit modifier token if a valid modifier is returned.h](hAs one exception to the above, allocations may be ‘upgraded’ from implicit to explicit modifiers. For example, if the buffer is allocated with }(hj; hhhNhNubj)}(h``gbm_bo_create``h]h gbm_bo_create}(hjC hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj; ubhB (taking no modifiers), the user may then query the modifier with }(hj; hhhNhNubj)}(h``gbm_bo_get_modifier``h]hgbm_bo_get_modifier}(hjU hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj; ubhZ and then use this modifier as an explicit modifier token if a valid modifier is returned.}(hj; hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMphja hhubh)}(hXWhen allocating buffers for exchange between different users and modifiers are not available, implementations are strongly encouraged to use ``DRM_FORMAT_MOD_LINEAR`` for their allocation, as this is the universal baseline for exchange. However, it is not guaranteed that this will result in the correct interpretation of buffer content, as implicit modifier operation may still be subject to driver-specific heuristics.h](hWhen allocating buffers for exchange between different users and modifiers are not available, implementations are strongly encouraged to use }(hjm hhhNhNubj)}(h``DRM_FORMAT_MOD_LINEAR``h]hDRM_FORMAT_MOD_LINEAR}(hju hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjm ubh for their allocation, as this is the universal baseline for exchange. However, it is not guaranteed that this will result in the correct interpretation of buffer content, as implicit modifier operation may still be subject to driver-specific heuristics.}(hjm hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMvhja hhubh)}(hXwAny new users - userspace programs and protocols, kernel subsystems, etc - wishing to exchange buffers must offer interoperability through dma-buf file descriptors for memory planes, DRM format tokens to describe the format, DRM format modifiers to describe the layout in memory, at least width and height for dimensions, and at least offset and stride for each memory plane.h]hXwAny new users - userspace programs and protocols, kernel subsystems, etc - wishing to exchange buffers must offer interoperability through dma-buf file descriptors for memory planes, DRM format tokens to describe the format, DRM format modifiers to describe the layout in memory, at least width and height for dimensions, and at least offset and stride for each memory plane.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM}hja hhubhtarget)}(h.. _zwp_linux_dmabuf_v1: https://gitlab.freedesktop.org/wayland/wayland-protocols/-/blob/main/unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xmlh]h}(h]zwp-linux-dmabuf-v1ah ]h"]zwp_linux_dmabuf_v1ah$]h&]jjuh1j hMhja hhhhnj referencedKubj )}(h.. _VK_EXT_image_drm_format_modifier: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_EXT_image_drm_format_modifier.htmlh]h}(h] vk-ext-image-drm-format-modifierah ]h"] vk_ext_image_drm_format_modifierah$]h&]jjuh1j hMhja hhhhj Kubj )}(h.. _EGL_EXT_image_dma_buf_import_modifiers: https://registry.khronos.org/EGL/extensions/EXT/EGL_EXT_image_dma_buf_import_modifiers.txth]h}(h]&egl-ext-image-dma-buf-import-modifiersa h ]h"]&egl_ext_image_dma_buf_import_modifiersah$]h&]jjuh1j hMhja hhhhj Kubeh}(h]implicit-modifiersah ]h"]implicit modifiersah$]h&]uh1hhhhhhhhM.ubeh}(h]exchanging-pixel-buffersah ]h"]exchanging pixel buffersah$]h&]uh1hhhhhhhhKubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerj error_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourcehnj _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}(&egl_ext_image_dma_buf_import_modifiers]ja vk_ext_image_drm_format_modifier]jazwp_linux_dmabuf_v1]j aurefids}nameids}(j j jjjjjjj8j5j8j5jjj^ j[ j j j j j j j j u nametypes}(j jjjj8j8jj^ j j j j uh}(j hjj jBj+jjmjjjjj1jjljYjjjjjj jXjEjjjjj jjDj1jjljjjjj5jj5j;jj;j[ jj ja j j j j j j u footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}Rparse_messages]transform_messages] transformerN include_log] decorationNhhub.