gdk4/auto/

dmabuf_texture_builder.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// DO NOT EDIT

#[cfg(feature = "v4_16")]
#[cfg_attr(docsrs, doc(cfg(feature = "v4_16")))]
use crate::ColorState;
use crate::{Display, Texture, ffi};
use glib::translate::*;

glib::wrapper! {
    /// Constructs [`Texture`][crate::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, more than one file
    /// descriptor may be present, up to the number of planes. If the number of file
    /// descriptors is less than the number of planes, the remaining ones should be set to
    /// -1.
    ///
    /// 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 [`DmabufTextureBuilder`][crate::DmabufTextureBuilder] is quite simple: Create a texture builder,
    /// set all the necessary properties, and then call [`build()`][Self::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
    ///
    /// [`DmabufTextureBuilder`][crate::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](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)
    ///
    /// ## Properties
    ///
    ///
    /// #### `color-state`
    ///  The color state of the texture.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `display`
    ///  The display that this texture will be used on.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `fourcc`
    ///  The format of the texture, as a fourcc value.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `height`
    ///  The height of the texture.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `modifier`
    ///  The modifier.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `n-planes`
    ///  The number of planes of the texture.
    ///
    /// Note that you can set properties for other planes,
    /// but they will be ignored when constructing the texture.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `premultiplied`
    ///  Whether the alpha channel is premultiplied into the others.
    ///
    /// Only relevant if the format has alpha.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `update-region`
    ///  The update region for [`update-texture`][struct@crate::DmabufTextureBuilder#update-texture].
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `update-texture`
    ///  The texture [`update-region`][struct@crate::DmabufTextureBuilder#update-region] is an update for.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `width`
    ///  The width of the texture.
    ///
    /// Readable | Writeable
    #[doc(alias = "GdkDmabufTextureBuilder")]
    pub struct DmabufTextureBuilder(Object<ffi::GdkDmabufTextureBuilder, ffi::GdkDmabufTextureBuilderClass>);

    match fn {
        type_ => || ffi::gdk_dmabuf_texture_builder_get_type(),
    }
}

impl DmabufTextureBuilder {
    /// Creates a new texture builder.
    ///
    /// # Returns
    ///
    /// the new `GdkTextureBuilder`
    #[doc(alias = "gdk_dmabuf_texture_builder_new")]
    pub fn new() -> DmabufTextureBuilder {
        assert_initialized_main_thread!();
        unsafe { from_glib_full(ffi::gdk_dmabuf_texture_builder_new()) }
    }

    /// Gets the color state previously set via gdk_dmabuf_texture_builder_set_color_state().
    ///
    /// # Returns
    ///
    /// the color state
    #[cfg(feature = "v4_16")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_16")))]
    #[doc(alias = "gdk_dmabuf_texture_builder_get_color_state")]
    #[doc(alias = "get_color_state")]
    #[doc(alias = "color-state")]
    pub fn color_state(&self) -> Option<ColorState> {
        unsafe {
            from_glib_none(ffi::gdk_dmabuf_texture_builder_get_color_state(
                self.to_glib_none().0,
            ))
        }
    }

    /// Returns the display that this texture builder is
    /// associated with.
    ///
    /// # Returns
    ///
    /// the display
    #[doc(alias = "gdk_dmabuf_texture_builder_get_display")]
    #[doc(alias = "get_display")]
    pub fn display(&self) -> Display {
        unsafe {
            from_glib_none(ffi::gdk_dmabuf_texture_builder_get_display(
                self.to_glib_none().0,
            ))
        }
    }

    /// 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.
    ///
    /// # Returns
    ///
    /// The format
    #[doc(alias = "gdk_dmabuf_texture_builder_get_fourcc")]
    #[doc(alias = "get_fourcc")]
    pub fn fourcc(&self) -> u32 {
        unsafe { ffi::gdk_dmabuf_texture_builder_get_fourcc(self.to_glib_none().0) }
    }

    /// Gets the height previously set via gdk_dmabuf_texture_builder_set_height() or
    /// 0 if the height wasn't set.
    ///
    /// # Returns
    ///
    /// The height
    #[doc(alias = "gdk_dmabuf_texture_builder_get_height")]
    #[doc(alias = "get_height")]
    pub fn height(&self) -> u32 {
        unsafe { ffi::gdk_dmabuf_texture_builder_get_height(self.to_glib_none().0) }
    }

    /// Gets the modifier value.
    ///
    /// # Returns
    ///
    /// the modifier
    #[doc(alias = "gdk_dmabuf_texture_builder_get_modifier")]
    #[doc(alias = "get_modifier")]
    pub fn modifier(&self) -> u64 {
        unsafe { ffi::gdk_dmabuf_texture_builder_get_modifier(self.to_glib_none().0) }
    }

    /// Gets the number of planes.
    ///
    /// # Returns
    ///
    /// The number of planes
    #[doc(alias = "gdk_dmabuf_texture_builder_get_n_planes")]
    #[doc(alias = "get_n_planes")]
    #[doc(alias = "n-planes")]
    pub fn n_planes(&self) -> u32 {
        unsafe { ffi::gdk_dmabuf_texture_builder_get_n_planes(self.to_glib_none().0) }
    }

    /// Gets the offset value for a plane.
    /// ## `plane`
    /// the plane to get the offset for
    ///
    /// # Returns
    ///
    /// the offset
    #[doc(alias = "gdk_dmabuf_texture_builder_get_offset")]
    #[doc(alias = "get_offset")]
    pub fn offset(&self, plane: u32) -> u32 {
        unsafe { ffi::gdk_dmabuf_texture_builder_get_offset(self.to_glib_none().0, plane) }
    }

    /// Whether the data is premultiplied.
    ///
    /// # Returns
    ///
    /// whether the data is premultiplied
    #[doc(alias = "gdk_dmabuf_texture_builder_get_premultiplied")]
    #[doc(alias = "get_premultiplied")]
    #[doc(alias = "premultiplied")]
    pub fn is_premultiplied(&self) -> bool {
        unsafe {
            from_glib(ffi::gdk_dmabuf_texture_builder_get_premultiplied(
                self.to_glib_none().0,
            ))
        }
    }

    /// Gets the stride value for a plane.
    /// ## `plane`
    /// the plane to get the stride for
    ///
    /// # Returns
    ///
    /// the stride
    #[doc(alias = "gdk_dmabuf_texture_builder_get_stride")]
    #[doc(alias = "get_stride")]
    pub fn stride(&self, plane: u32) -> u32 {
        unsafe { ffi::gdk_dmabuf_texture_builder_get_stride(self.to_glib_none().0, plane) }
    }

    /// Gets the region previously set via gdk_dmabuf_texture_builder_set_update_region() or
    /// [`None`] if none was set.
    ///
    /// # Returns
    ///
    /// The region
    #[doc(alias = "gdk_dmabuf_texture_builder_get_update_region")]
    #[doc(alias = "get_update_region")]
    #[doc(alias = "update-region")]
    pub fn update_region(&self) -> Option<cairo::Region> {
        unsafe {
            from_glib_none(ffi::gdk_dmabuf_texture_builder_get_update_region(
                self.to_glib_none().0,
            ))
        }
    }

    /// Gets the texture previously set via gdk_dmabuf_texture_builder_set_update_texture() or
    /// [`None`] if none was set.
    ///
    /// # Returns
    ///
    /// The texture
    #[doc(alias = "gdk_dmabuf_texture_builder_get_update_texture")]
    #[doc(alias = "get_update_texture")]
    #[doc(alias = "update-texture")]
    pub fn update_texture(&self) -> Option<Texture> {
        unsafe {
            from_glib_none(ffi::gdk_dmabuf_texture_builder_get_update_texture(
                self.to_glib_none().0,
            ))
        }
    }

    /// Gets the width previously set via gdk_dmabuf_texture_builder_set_width() or
    /// 0 if the width wasn't set.
    ///
    /// # Returns
    ///
    /// The width
    #[doc(alias = "gdk_dmabuf_texture_builder_get_width")]
    #[doc(alias = "get_width")]
    pub fn width(&self) -> u32 {
        unsafe { ffi::gdk_dmabuf_texture_builder_get_width(self.to_glib_none().0) }
    }
}

#[cfg(feature = "v4_14")]
#[cfg_attr(docsrs, doc(cfg(feature = "v4_14")))]
impl Default for DmabufTextureBuilder {
    fn default() -> Self {
        Self::new()
    }
}