Documentation/userspace-api/dma-buf-alloc-exchange.rst

Source file repositories/reference/linux-study-clean/Documentation/userspace-api/dma-buf-alloc-exchange.rst

File Facts

System
Linux kernel
Corpus path
Documentation/userspace-api/dma-buf-alloc-exchange.rst
Extension
.rst
Size
19844 bytes
Lines
390
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. SPDX-License-Identifier: GPL-2.0
.. Copyright 2021-2023 Collabora Ltd.

========================
Exchanging pixel buffers
========================

As 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.

It 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.


Glossary of terms
=================

.. glossary::

    image:
      Conceptually 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).

    row:
      A span along a single y-axis value, e.g. from co-ordinates (0,100) to
      (200,100).

    scanline:
      Synonym for row.

    column:
      A span along a single x-axis value, e.g. from co-ordinates (100,0) to
      (100,100).

    memory buffer:
      A 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.

    plane:
      A two-dimensional array of some or all of an image's color and alpha
      channel values.

    pixel:
      A 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.

    pixel data:
      Bytes 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.

    color value:
      A tuple of numbers, representing a color. Each element in the tuple is a
      color channel value.

    color channel:
      One 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.

    pixel format:
      A description of how pixel data represents the pixel's color and alpha
      values.

Annotation

Implementation Notes