class Gdk::DmabufTextureBuilder
- Gdk::DmabufTextureBuilder
- GObject::Object
- Reference
- Object
Overview
Constructs 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 Gdk::DmabufTextureBuilder
is quite simple: Create a texture builder,
set all the necessary properties, and then call 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
Gdk::DmabufTextureBuilder
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
-
The header file drm_fourcc.h
Defined in:
lib/gi-crystal/src/auto/gdk-4.0/dmabuf_texture_builder.crConstructors
-
.new : self
Creates a new texture builder.
- .new(*, color_state : Gdk::ColorState | Nil = nil, display : Gdk::Display | Nil = nil, fourcc : UInt32 | Nil = nil, height : UInt32 | Nil = nil, modifier : UInt64 | Nil = nil, n_planes : UInt32 | Nil = nil, premultiplied : Bool | Nil = nil, update_region : Cairo::Region | Nil = nil, update_texture : Gdk::Texture | Nil = nil, width : UInt32 | Nil = nil)
Class Method Summary
-
.g_type : UInt64
Returns the type id (GType) registered in GLib type system.
Instance Method Summary
-
#==(other : self)
Returns
true
if this reference is the same as other. -
#build(destroy : GLib::DestroyNotify | Nil, data : Pointer(Void) | Nil) : Gdk::Texture | Nil
Builds a new
Gdk::Texture
with the values set up in the builder. -
#color_state : Gdk::ColorState | Nil
Gets the color state previously set via gdk_dmabuf_texture_builder_set_color_state().
-
#color_state=(color_state : Gdk::ColorState | Nil) : Nil
Sets the color state for the texture.
-
#display : Gdk::Display
Returns the display that this texture builder is associated with.
-
#display=(display : Gdk::Display) : Nil
Sets the display that this texture builder is associated with.
- #display=(value : Gdk::Display | Nil) : Gdk::Display | Nil
-
#fd(plane : UInt32) : Int32
Gets the file descriptor for a plane.
-
#fourcc : UInt32
Gets the format previously set via gdk_dmabuf_texture_builder_set_fourcc() or 0 if the format wasn't set.
-
#fourcc=(fourcc : UInt32) : Nil
Sets the format of the texture.
-
#hash(hasher)
See
Object#hash(hasher)
-
#height : UInt32
Gets the height previously set via gdk_dmabuf_texture_builder_set_height() or 0 if the height wasn't set.
-
#height=(height : UInt32) : Nil
Sets the height of the texture.
-
#modifier : UInt64
Gets the modifier value.
-
#modifier=(modifier : UInt64) : Nil
Sets the modifier.
-
#n_planes : UInt32
Gets the number of planes.
-
#n_planes=(n_planes : UInt32) : Nil
Sets the number of planes of the texture.
-
#offset(plane : UInt32) : UInt32
Gets the offset value for a plane.
-
#premultiplied : Bool
Whether the data is premultiplied.
-
#premultiplied=(premultiplied : Bool) : Nil
Sets whether the data is premultiplied.
- #premultiplied? : Bool
-
#set_fd(plane : UInt32, fd : Int32) : Nil
Sets the file descriptor for a plane.
-
#set_offset(plane : UInt32, offset : UInt32) : Nil
Sets the offset for a plane.
-
#set_stride(plane : UInt32, stride : UInt32) : Nil
Sets the stride for a plane.
-
#stride(plane : UInt32) : UInt32
Gets the stride value for a plane.
-
#update_region : Cairo::Region | Nil
Gets the region previously set via gdk_dmabuf_texture_builder_set_update_region() or
nil
if none was set. -
#update_region=(region : Cairo::Region | Nil) : Nil
Sets the region to be updated by this texture.
-
#update_texture : Gdk::Texture | Nil
Gets the texture previously set via gdk_dmabuf_texture_builder_set_update_texture() or
nil
if none was set. -
#update_texture=(texture : Gdk::Texture | Nil) : Nil
Sets the texture to be updated by this texture.
-
#width : UInt32
Gets the width previously set via gdk_dmabuf_texture_builder_set_width() or 0 if the width wasn't set.
-
#width=(width : UInt32) : Nil
Sets the width of the texture.
Instance methods inherited from class GObject::Object
==(other : self)
==,
bind_property(source_property : String, target : GObject::Object, target_property : String, flags : GObject::BindingFlags) : GObject::Binding
bind_property,
bind_property_full(source_property : String, target : GObject::Object, target_property : String, flags : GObject::BindingFlags, transform_to : GObject::Closure, transform_from : GObject::Closure) : GObject::Binding
bind_property_full,
data(key : String) : Pointer(Void) | Nil
data,
finalize
finalize,
freeze_notify : Nil
freeze_notify,
getv(names : Enumerable(String), values : Enumerable(_)) : Nil
getv,
hash(hasher)
hash,
notify(property_name : String) : Nil
notify,
notify_by_pspec(pspec : GObject::ParamSpec) : Nil
notify_by_pspec,
notify_signal
notify_signal,
property(property_name : String, value : _) : Nil
property,
qdata(quark : UInt32) : Pointer(Void) | Nil
qdata,
ref_count : UInt32
ref_count,
run_dispose : Nil
run_dispose,
set_data(key : String, data : Pointer(Void) | Nil) : Nil
set_data,
set_property(property_name : String, value : _) : Nil
set_property,
steal_data(key : String) : Pointer(Void) | Nil
steal_data,
steal_qdata(quark : UInt32) : Pointer(Void) | Nil
steal_qdata,
thaw_notify : Nil
thaw_notify,
to_unsafe : Pointer(Void)
to_unsafe,
watch_closure(closure : GObject::Closure) : Nil
watch_closure
Constructor methods inherited from class GObject::Object
cast(obj : GObject::Object) : self
cast,
new(pointer : Pointer(Void), transfer : GICrystal::Transfer)new new, newv(object_type : UInt64, parameters : Enumerable(GObject::Parameter)) : self newv
Class methods inherited from class GObject::Object
cast?(obj : GObject::Object) : self | Nil
cast?,
compat_control(what : UInt64, data : Pointer(Void) | Nil) : UInt64
compat_control,
g_type : UInt64
g_type,
interface_find_property(g_iface : GObject::TypeInterface, property_name : String) : GObject::ParamSpec
interface_find_property,
interface_list_properties(g_iface : GObject::TypeInterface) : Enumerable(GObject::ParamSpec)
interface_list_properties
Macros inherited from class GObject::Object
previous_vfunc(*args)
previous_vfunc,
previous_vfunc!(*args)
previous_vfunc!,
signal(signature)
signal
Constructor Detail
Class Method Detail
Instance Method Detail
Returns true
if this reference is the same as other. Invokes same?
.
Builds a new Gdk::Texture
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
Gdk::Display#dmabuf_formats
to get a list of supported formats. If the
format is not supported by GTK, nil
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.
Gets the color state previously set via gdk_dmabuf_texture_builder_set_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.
Sets the display that this texture builder is associated with.
The display is used to determine the supported dma-buf formats.
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.
Sets the format of the texture.
The format is specified as a fourcc code.
The format must be set before calling Gdk::DmabufTextureBuilder#build
.
Gets the height previously set via gdk_dmabuf_texture_builder_set_height() or 0 if the height wasn't set.
Sets the height of the texture.
The height must be set before calling Gdk::DmabufTextureBuilder#build
.
Sets whether the data is premultiplied.
Unless otherwise specified, all formats including alpha channels are assumed to be premultiplied.
Sets the stride for a plane.
The stride must be set for all planes before calling Gdk::DmabufTextureBuilder#build
.
Gets the region previously set via gdk_dmabuf_texture_builder_set_update_region() or
nil
if none was set.
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.
Gets the texture previously set via gdk_dmabuf_texture_builder_set_update_texture() or
nil
if none was set.
Sets the texture to be updated by this texture. See
Gdk::DmabufTextureBuilder#update_region=
for an explanation.
Gets the width previously set via gdk_dmabuf_texture_builder_set_width() or 0 if the width wasn't set.
Sets the width of the texture.
The width must be set before calling Gdk::DmabufTextureBuilder#build
.