Package ch.bailu.gtk.gdk

Klasse DmabufTextureBuilder

java.lang.Object
ch.bailu.gtk.type.Type
ch.bailu.gtk.type.Pointer
ch.bailu.gtk.gobject.Object
ch.bailu.gtk.type.PropertyHolder
ch.bailu.gtk.gdk.DmabufTextureBuilder
Alle implementierten Schnittstellen:
PointerInterface
public class DmabufTextureBuilder extends PropertyHolder
Constructs [class@Gdk.Texture] objects from DMA buffers.

DMA buffers are commonly called **_dma-bufs_**.

DMA buffers are a feature of the Linux kernel to enable efficient buffer and
memory sharing between hardware such as codecs, GPUs, displays, cameras and the
kernel drivers controlling them. For example, a decoder may want its output to
be directly shared with the display server for rendering without a copy.

Any device driver which participates in DMA buffer sharing, can do so as either
the exporter or importer of buffers (or both).

The memory that is shared via DMA buffers is usually stored in non-system memory
(maybe in device's local memory or something else not directly accessible by the
CPU), and accessing this memory from the CPU may have higher-than-usual overhead.

In particular for graphics data, it is not uncommon that data consists of multiple
separate blocks of memory, for example one block for each of the red, green and
blue channels. These blocks are called **_planes_**. DMA buffers can have up to
four planes. Even if the memory is a single block, the data can be organized in
multiple planes, by specifying offsets from the beginning of the data.

DMA buffers are exposed to user-space as file descriptors allowing to pass them
between processes. If a DMA buffer has multiple planes, there is one file
descriptor per plane.

The format of the data (for graphics data, essentially its colorspace) is described
by a 32-bit integer. These format identifiers are defined in the header file `drm_fourcc.h`
and commonly referred to as **_fourcc_** values, since they are identified by 4 ASCII
characters. Additionally, each DMA buffer has a **_modifier_**, which is a 64-bit integer
that describes driver-specific details of the memory layout, such as tiling or compression.

For historical reasons, some producers of dma-bufs don't provide an explicit modifier, but
instead return `DMA_FORMAT_MOD_INVALID` to indicate that their modifier is **_implicit_**.
GTK tries to accommodate this situation by accepting `DMA_FORMAT_MOD_INVALID` as modifier.

The operation of `GdkDmabufTextureBuilder` is quite simple: Create a texture builder,
set all the necessary properties, and then call [method@Gdk.DmabufTextureBuilder.build]
to create the new texture.

The required properties for a dma-buf texture are

* The width and height in pixels

* The `fourcc` code and `modifier` which identify the format and memory layout of the dma-buf

* The file descriptor, offset and stride for each of the planes

`GdkDmabufTextureBuilder` can be used for quick one-shot construction of
textures as well as kept around and reused to construct multiple textures.

For further information, see

* The Linux kernel [documentation](https://docs.kernel.org/driver-api/dma-buf.html)

* The header file [drm_fourcc.h](https://gitlab.freedesktop.org/mesa/drm/-/blob/main/include/drm/drm_fourcc.h)

https://docs.gtk.org/gdk4/class.DmabufTextureBuilder.html

  • Konstruktordetails

    • DmabufTextureBuilder

      public DmabufTextureBuilder(PointerContainer pointer)

    • DmabufTextureBuilder

      public DmabufTextureBuilder()
      Creates a new texture builder.

  • Methodendetails

    • getClassHandler

      public static ClassHandler getClassHandler()

    • build

      public Texture build(DmabufTextureBuilder.OnDestroyNotify destroy, @Nullable Pointer data) throws AllocationError
      Builds a new `GdkTexture` with the values set up in the builder.

      It is a programming error to call this function if any mandatory property has not been set.

      Not all formats defined in the `drm_fourcc.h` header are supported. You can use
      [method@Gdk.Display.get_dmabuf_formats] to get a list of supported formats. If the
      format is not supported by GTK, %NULL will be returned and @error will be set.

      The `destroy` function gets called when the returned texture gets released.

      It is the responsibility of the caller to keep the file descriptors for the planes
      open until the created texture is no longer used, and close them afterwards (possibly
      using the @destroy notify).

      It is possible to call this function multiple times to create multiple textures,
      possibly with changing properties in between.
      Parameter:
      destroy - destroy function to be called when the texture is released
      data - user data to pass to the destroy function
      Gibt zurück:
      a newly built `GdkTexture` or `NULL` if the format is not supported
      Löst aus:
      AllocationError

    • getColorState

      public ColorState getColorState()
      Gets the color state previously set via gdk_dmabuf_texture_builder_set_color_state().
      Gibt zurück:
      the color state

    • getDisplay

      public Display getDisplay()
      Returns the display that this texture builder is
      associated with.
      Gibt zurück:
      the display

    • getFourcc

      public int getFourcc()
      Gets the format previously set via gdk_dmabuf_texture_builder_set_fourcc()
      or 0 if the format wasn't set.

      The format is specified as a fourcc code.
      Gibt zurück:
      The format

    • getModifier

      public long getModifier()
      Gets the modifier value.
      Gibt zurück:
      the modifier

    • getPremultiplied

      public boolean getPremultiplied()
      Whether the data is premultiplied.
      Gibt zurück:
      whether the data is premultiplied

    • getUpdateRegion

      public Region getUpdateRegion()
      Gets the region previously set via gdk_dmabuf_texture_builder_set_update_region() or
      %NULL if none was set.
      Gibt zurück:
      The region

    • getUpdateTexture

      public Texture getUpdateTexture()
      Gets the texture previously set via gdk_dmabuf_texture_builder_set_update_texture() or
      %NULL if none was set.
      Gibt zurück:
      The texture

    • setColorState

      public void setColorState(@Nullable ColorState color_state)
      Sets the color state for the texture.

      By default, the colorstate is `NULL`. In that case, GTK will choose the
      correct colorstate based on the format.
      If you don't know what colorstates are, this is probably the right thing.
      Parameter:
      color_state - a `GdkColorState` or `NULL` to unset the colorstate.

    • setDisplay

      public void setDisplay(@Nonnull Display display)
      Sets the display that this texture builder is
      associated with.

      The display is used to determine the supported
      dma-buf formats.
      Parameter:
      display - the display

    • setFourcc

      public void setFourcc(int fourcc)
      Sets the format of the texture.

      The format is specified as a fourcc code.

      The format must be set before calling [method@Gdk.DmabufTextureBuilder.build].
      Parameter:
      fourcc - the texture's format or 0 to unset

    • setModifier

      public void setModifier(long modifier)
      Sets the modifier.
      Parameter:
      modifier - the modifier value

    • setPremultiplied

      public void setPremultiplied(boolean premultiplied)
      Sets whether the data is premultiplied.

      Unless otherwise specified, all formats including alpha channels are assumed
      to be premultiplied.
      Parameter:
      premultiplied - whether the data is premultiplied

    • setUpdateRegion

      public void setUpdateRegion(@Nullable Region region)
      Sets the region to be updated by this texture. Together with
      [property@Gdk.DmabufTextureBuilder:update-texture] this describes an
      update of a previous texture.

      When rendering animations of large textures, it is possible that
      consecutive textures are only updating contents in parts of the texture.
      It is then possible to describe this update via these two properties,
      so that GTK can avoid rerendering parts that did not change.

      An example would be a screen recording where only the mouse pointer moves.
      Parameter:
      region - the region to update

    • setUpdateTexture

      public void setUpdateTexture(@Nullable Texture texture)
      Sets the texture to be updated by this texture. See
      [method@Gdk.DmabufTextureBuilder.set_update_region] for an explanation.
      Parameter:
      texture - the texture to update

    • getTypeID

      public static long getTypeID()

    • getParentTypeID

      public static long getParentTypeID()

    • getTypeSize

      public static TypeSystem.TypeSize getTypeSize()

    • getParentTypeSize

      public static TypeSystem.TypeSize getParentTypeSize()

    • getInstanceSize

      public static int getInstanceSize()