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}