gdk4/auto/
dmabuf_texture_builder.rs

1// This file was generated by gir (https://github.com/gtk-rs/gir)
2// from gir-files (https://github.com/gtk-rs/gir-files)
3// DO NOT EDIT
4
5#[cfg(feature = "v4_16")]
6#[cfg_attr(docsrs, doc(cfg(feature = "v4_16")))]
7use crate::ColorState;
8use crate::{ffi, Display, Texture};
9use glib::translate::*;
10
11glib::wrapper! {
12    /// Constructs [`Texture`][crate::Texture] objects from DMA buffers.
13    ///
14    /// DMA buffers are commonly called **_dma-bufs_**.
15    ///
16    /// DMA buffers are a feature of the Linux kernel to enable efficient buffer and
17    /// memory sharing between hardware such as codecs, GPUs, displays, cameras and the
18    /// kernel drivers controlling them. For example, a decoder may want its output to
19    /// be directly shared with the display server for rendering without a copy.
20    ///
21    /// Any device driver which participates in DMA buffer sharing, can do so as either
22    /// the exporter or importer of buffers (or both).
23    ///
24    /// The memory that is shared via DMA buffers is usually stored in non-system memory
25    /// (maybe in device's local memory or something else not directly accessible by the
26    /// CPU), and accessing this memory from the CPU may have higher-than-usual overhead.
27    ///
28    /// In particular for graphics data, it is not uncommon that data consists of multiple
29    /// separate blocks of memory, for example one block for each of the red, green and
30    /// blue channels. These blocks are called **_planes_**. DMA buffers can have up to
31    /// four planes. Even if the memory is a single block, the data can be organized in
32    /// multiple planes, by specifying offsets from the beginning of the data.
33    ///
34    /// DMA buffers are exposed to user-space as file descriptors allowing to pass them
35    /// between processes. If a DMA buffer has multiple planes, there is one file
36    /// descriptor per plane.
37    ///
38    /// The format of the data (for graphics data, essentially its colorspace) is described
39    /// by a 32-bit integer. These format identifiers are defined in the header file `drm_fourcc.h`
40    /// and commonly referred to as **_fourcc_** values, since they are identified by 4 ASCII
41    /// characters. Additionally, each DMA buffer has a **_modifier_**, which is a 64-bit integer
42    /// that describes driver-specific details of the memory layout, such as tiling or compression.
43    ///
44    /// For historical reasons, some producers of dma-bufs don't provide an explicit modifier, but
45    /// instead return `DMA_FORMAT_MOD_INVALID` to indicate that their modifier is **_implicit_**.
46    /// GTK tries to accommodate this situation by accepting `DMA_FORMAT_MOD_INVALID` as modifier.
47    ///
48    /// The operation of [`DmabufTextureBuilder`][crate::DmabufTextureBuilder] is quite simple: Create a texture builder,
49    /// set all the necessary properties, and then call [`build()`][Self::build()]
50    /// to create the new texture.
51    ///
52    /// The required properties for a dma-buf texture are
53    ///
54    ///  * The width and height in pixels
55    ///
56    ///  * The `fourcc` code and `modifier` which identify the format and memory layout of the dma-buf
57    ///
58    ///  * The file descriptor, offset and stride for each of the planes
59    ///
60    /// [`DmabufTextureBuilder`][crate::DmabufTextureBuilder] can be used for quick one-shot construction of
61    /// textures as well as kept around and reused to construct multiple textures.
62    ///
63    /// For further information, see
64    ///
65    /// * The Linux kernel [documentation](https://docs.kernel.org/driver-api/dma-buf.html)
66    ///
67    /// * The header file [drm_fourcc.h](https://gitlab.freedesktop.org/mesa/drm/-/blob/main/include/drm/drm_fourcc.h)
68    ///
69    /// ## Properties
70    ///
71    ///
72    /// #### `color-state`
73    ///  The color state of the texture.
74    ///
75    /// Readable | Writeable
76    ///
77    ///
78    /// #### `display`
79    ///  The display that this texture will be used on.
80    ///
81    /// Readable | Writeable
82    ///
83    ///
84    /// #### `fourcc`
85    ///  The format of the texture, as a fourcc value.
86    ///
87    /// Readable | Writeable
88    ///
89    ///
90    /// #### `height`
91    ///  The height of the texture.
92    ///
93    /// Readable | Writeable
94    ///
95    ///
96    /// #### `modifier`
97    ///  The modifier.
98    ///
99    /// Readable | Writeable
100    ///
101    ///
102    /// #### `n-planes`
103    ///  The number of planes of the texture.
104    ///
105    /// Note that you can set properties for other planes,
106    /// but they will be ignored when constructing the texture.
107    ///
108    /// Readable | Writeable
109    ///
110    ///
111    /// #### `premultiplied`
112    ///  Whether the alpha channel is premultiplied into the others.
113    ///
114    /// Only relevant if the format has alpha.
115    ///
116    /// Readable | Writeable
117    ///
118    ///
119    /// #### `update-region`
120    ///  The update region for [`update-texture`][struct@crate::DmabufTextureBuilder#update-texture].
121    ///
122    /// Readable | Writeable
123    ///
124    ///
125    /// #### `update-texture`
126    ///  The texture [`update-region`][struct@crate::DmabufTextureBuilder#update-region] is an update for.
127    ///
128    /// Readable | Writeable
129    ///
130    ///
131    /// #### `width`
132    ///  The width of the texture.
133    ///
134    /// Readable | Writeable
135    #[doc(alias = "GdkDmabufTextureBuilder")]
136    pub struct DmabufTextureBuilder(Object<ffi::GdkDmabufTextureBuilder, ffi::GdkDmabufTextureBuilderClass>);
137
138    match fn {
139        type_ => || ffi::gdk_dmabuf_texture_builder_get_type(),
140    }
141}
142
143impl DmabufTextureBuilder {
144    /// Creates a new texture builder.
145    ///
146    /// # Returns
147    ///
148    /// the new `GdkTextureBuilder`
149    #[doc(alias = "gdk_dmabuf_texture_builder_new")]
150    pub fn new() -> DmabufTextureBuilder {
151        assert_initialized_main_thread!();
152        unsafe { from_glib_full(ffi::gdk_dmabuf_texture_builder_new()) }
153    }
154
155    /// Gets the color state previously set via gdk_dmabuf_texture_builder_set_color_state().
156    ///
157    /// # Returns
158    ///
159    /// the color state
160    #[cfg(feature = "v4_16")]
161    #[cfg_attr(docsrs, doc(cfg(feature = "v4_16")))]
162    #[doc(alias = "gdk_dmabuf_texture_builder_get_color_state")]
163    #[doc(alias = "get_color_state")]
164    #[doc(alias = "color-state")]
165    pub fn color_state(&self) -> Option<ColorState> {
166        unsafe {
167            from_glib_none(ffi::gdk_dmabuf_texture_builder_get_color_state(
168                self.to_glib_none().0,
169            ))
170        }
171    }
172
173    /// Returns the display that this texture builder is
174    /// associated with.
175    ///
176    /// # Returns
177    ///
178    /// the display
179    #[doc(alias = "gdk_dmabuf_texture_builder_get_display")]
180    #[doc(alias = "get_display")]
181    pub fn display(&self) -> Display {
182        unsafe {
183            from_glib_none(ffi::gdk_dmabuf_texture_builder_get_display(
184                self.to_glib_none().0,
185            ))
186        }
187    }
188
189    /// Gets the format previously set via gdk_dmabuf_texture_builder_set_fourcc()
190    /// or 0 if the format wasn't set.
191    ///
192    /// The format is specified as a fourcc code.
193    ///
194    /// # Returns
195    ///
196    /// The format
197    #[doc(alias = "gdk_dmabuf_texture_builder_get_fourcc")]
198    #[doc(alias = "get_fourcc")]
199    pub fn fourcc(&self) -> u32 {
200        unsafe { ffi::gdk_dmabuf_texture_builder_get_fourcc(self.to_glib_none().0) }
201    }
202
203    /// Gets the height previously set via gdk_dmabuf_texture_builder_set_height() or
204    /// 0 if the height wasn't set.
205    ///
206    /// # Returns
207    ///
208    /// The height
209    #[doc(alias = "gdk_dmabuf_texture_builder_get_height")]
210    #[doc(alias = "get_height")]
211    pub fn height(&self) -> u32 {
212        unsafe { ffi::gdk_dmabuf_texture_builder_get_height(self.to_glib_none().0) }
213    }
214
215    /// Gets the modifier value.
216    ///
217    /// # Returns
218    ///
219    /// the modifier
220    #[doc(alias = "gdk_dmabuf_texture_builder_get_modifier")]
221    #[doc(alias = "get_modifier")]
222    pub fn modifier(&self) -> u64 {
223        unsafe { ffi::gdk_dmabuf_texture_builder_get_modifier(self.to_glib_none().0) }
224    }
225
226    /// Gets the number of planes.
227    ///
228    /// # Returns
229    ///
230    /// The number of planes
231    #[doc(alias = "gdk_dmabuf_texture_builder_get_n_planes")]
232    #[doc(alias = "get_n_planes")]
233    #[doc(alias = "n-planes")]
234    pub fn n_planes(&self) -> u32 {
235        unsafe { ffi::gdk_dmabuf_texture_builder_get_n_planes(self.to_glib_none().0) }
236    }
237
238    /// Gets the offset value for a plane.
239    /// ## `plane`
240    /// the plane to get the offset for
241    ///
242    /// # Returns
243    ///
244    /// the offset
245    #[doc(alias = "gdk_dmabuf_texture_builder_get_offset")]
246    #[doc(alias = "get_offset")]
247    pub fn offset(&self, plane: u32) -> u32 {
248        unsafe { ffi::gdk_dmabuf_texture_builder_get_offset(self.to_glib_none().0, plane) }
249    }
250
251    /// Whether the data is premultiplied.
252    ///
253    /// # Returns
254    ///
255    /// whether the data is premultiplied
256    #[doc(alias = "gdk_dmabuf_texture_builder_get_premultiplied")]
257    #[doc(alias = "get_premultiplied")]
258    #[doc(alias = "premultiplied")]
259    pub fn is_premultiplied(&self) -> bool {
260        unsafe {
261            from_glib(ffi::gdk_dmabuf_texture_builder_get_premultiplied(
262                self.to_glib_none().0,
263            ))
264        }
265    }
266
267    /// Gets the stride value for a plane.
268    /// ## `plane`
269    /// the plane to get the stride for
270    ///
271    /// # Returns
272    ///
273    /// the stride
274    #[doc(alias = "gdk_dmabuf_texture_builder_get_stride")]
275    #[doc(alias = "get_stride")]
276    pub fn stride(&self, plane: u32) -> u32 {
277        unsafe { ffi::gdk_dmabuf_texture_builder_get_stride(self.to_glib_none().0, plane) }
278    }
279
280    /// Gets the region previously set via gdk_dmabuf_texture_builder_set_update_region() or
281    /// [`None`] if none was set.
282    ///
283    /// # Returns
284    ///
285    /// The region
286    #[doc(alias = "gdk_dmabuf_texture_builder_get_update_region")]
287    #[doc(alias = "get_update_region")]
288    #[doc(alias = "update-region")]
289    pub fn update_region(&self) -> Option<cairo::Region> {
290        unsafe {
291            from_glib_none(ffi::gdk_dmabuf_texture_builder_get_update_region(
292                self.to_glib_none().0,
293            ))
294        }
295    }
296
297    /// Gets the texture previously set via gdk_dmabuf_texture_builder_set_update_texture() or
298    /// [`None`] if none was set.
299    ///
300    /// # Returns
301    ///
302    /// The texture
303    #[doc(alias = "gdk_dmabuf_texture_builder_get_update_texture")]
304    #[doc(alias = "get_update_texture")]
305    #[doc(alias = "update-texture")]
306    pub fn update_texture(&self) -> Option<Texture> {
307        unsafe {
308            from_glib_none(ffi::gdk_dmabuf_texture_builder_get_update_texture(
309                self.to_glib_none().0,
310            ))
311        }
312    }
313
314    /// Gets the width previously set via gdk_dmabuf_texture_builder_set_width() or
315    /// 0 if the width wasn't set.
316    ///
317    /// # Returns
318    ///
319    /// The width
320    #[doc(alias = "gdk_dmabuf_texture_builder_get_width")]
321    #[doc(alias = "get_width")]
322    pub fn width(&self) -> u32 {
323        unsafe { ffi::gdk_dmabuf_texture_builder_get_width(self.to_glib_none().0) }
324    }
325}
326
327#[cfg(feature = "v4_14")]
328#[cfg_attr(docsrs, doc(cfg(feature = "v4_14")))]
329impl Default for DmabufTextureBuilder {
330    fn default() -> Self {
331        Self::new()
332    }
333}