maplibre_native_ffi/generated/
acquired_frame.rs

1// Generated from C headers by tools/bindgen. Do not edit.
2use super::*;
3
4native_owner! {
5    /// Owns one native handle.
6    ///
7    /// A rendered frame that the caller holds to read or show.
8    ///
9    /// See `mln_acquired_frame` in the
10    /// [C API reference](https://maplibre.org/maplibre-native-ffi/reference/c/base_8h.html).
11    #[must_use = "`AcquiredFrameHandle` must be released with `AcquiredFrameHandle::release`"]
12    pub struct AcquiredFrameHandle(mln_acquired_frame) dispose |raw| crate::error::check(|out_diagnostic| unsafe { sys::mln_acquired_frame_discard(raw, out_diagnostic) });
13    /// Returns the native handle value.
14    fn id;
15}
16
17impl AcquiredFrameHandle {
18    /// Gives up an acquired frame without saying when your GPU stops reading
19    /// it.
20    ///
21    /// Because your GPU may still read the frame's texture, the session never
22    /// renders into that texture again.
23    ///
24    /// See `mln_acquired_frame_discard` in the
25    /// [C API reference](https://maplibre.org/maplibre-native-ffi/reference/c/render__session_8h.html).
26    pub fn discard(self) -> std::result::Result<(), ReleaseError<Self>> {
27        self.consume(|frame| {
28            let mut call = Call::new(frame);
29            call.status(|frame, out_diagnostic| unsafe {
30                sys::mln_acquired_frame_discard(frame, out_diagnostic)
31            })
32        })
33    }
34
35    /// Reads the frame result of an acquired frame.
36    ///
37    /// It succeeds until you release or discard the frame, whatever the
38    /// session's state.
39    ///
40    /// See `mln_acquired_frame_get_result` in the
41    /// [C API reference](https://maplibre.org/maplibre-native-ffi/reference/c/render__session_8h.html).
42    pub fn get_result(&self) -> Result<RenderFrameResult> {
43        let mut call = self.inner.call();
44        let mut out_result: sys::mln_render_frame_result = unsafe { std::mem::zeroed() };
45        out_result.size = std::mem::size_of::<sys::mln_render_frame_result>() as _;
46        call.status(|frame, out_diagnostic| unsafe {
47            sys::mln_acquired_frame_get_result(frame, &mut out_result, out_diagnostic)
48        })?;
49        Ok(unsafe { from_native(out_result) }?)
50    }
51
52    /// Gives an acquired frame back to the session once you're done reading it.
53    ///
54    /// `consumer_completion` says when your GPU work that reads the texture
55    /// finishes. Pass `GpuSyncKind::CpuComplete` when that work has already
56    /// finished. The session waits for that point before it renders into the
57    /// texture again. If that wait fails, such as for an OpenGL fence outside
58    /// the session's share group, the session fails.
59    ///
60    /// See `mln_acquired_frame_release` in the
61    /// [C API reference](https://maplibre.org/maplibre-native-ffi/reference/c/render__session_8h.html).
62    ///
63    /// # Errors
64    ///
65    /// - `Status::Unsupported` when
66    ///   `RenderSessionCapabilities::consumer_sync_kinds` lacks the kind of
67    ///   `consumer_completion`.
68    ///
69    /// # Safety
70    /// Native graphics objects must have the types, lifetimes, and synchronization required by the C operation.
71    pub unsafe fn release(
72        self,
73        consumer_completion: &GpuSync,
74    ) -> std::result::Result<(), ReleaseError<Self>> {
75        self.consume(|frame| {
76            let mut call = Call::new(frame);
77            let consumer_completion = call.reference(&consumer_completion)?;
78            call.status(|frame, out_diagnostic| unsafe {
79                sys::mln_acquired_frame_release(frame, consumer_completion, out_diagnostic)
80            })
81        })
82    }
83}
84
85/// A view scope of [`AcquiredFrameHandle`], which ends when it drops. Its
86/// getters lend values that stay valid until then, and its owner can't
87/// be consumed while it lives.
88///
89/// Keeps an acquired frame's texture and sync objects in place while you use
90/// them.
91///
92/// See `mln_acquired_frame_view_begin` in the
93/// [C API reference](https://maplibre.org/maplibre-native-ffi/reference/c/render__session_8h.html).
94///
95/// # Errors
96///
97/// - `Status::TargetLost` when the session failed, or you detached, abandoned,
98///   or disposed it.
99pub struct AcquiredFrameView<'a> {
100    owner: &'a AcquiredFrameHandle,
101    _scope: crate::call::ViewScope,
102}
103impl std::fmt::Debug for AcquiredFrameView<'_> {
104    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
105        write!(f, "AcquiredFrameView(id={:#x})", self.owner.id())
106    }
107}
108impl AcquiredFrameHandle {
109    /// Keeps an acquired frame's texture and sync objects in place while you
110    /// use them.
111    ///
112    /// See `mln_acquired_frame_view_begin` in the
113    /// [C API reference](https://maplibre.org/maplibre-native-ffi/reference/c/render__session_8h.html).
114    ///
115    /// # Errors
116    ///
117    /// - `Status::TargetLost` when the session failed, or you detached,
118    ///   abandoned, or disposed it.
119    pub fn view(&self) -> Result<AcquiredFrameView<'_>> {
120        // SAFETY: these are this handle type's view scope functions.
121        let scope = unsafe {
122            crate::call::ViewScope::begin(
123                self.inner.native(),
124                sys::mln_acquired_frame_view_begin,
125                sys::mln_acquired_frame_view_end,
126            )
127        }?;
128        Ok(AcquiredFrameView {
129            owner: self,
130            _scope: scope,
131        })
132    }
133}
134impl AcquiredFrameView<'_> {
135    /// Gets the Android hardware buffer of an acquired frame.
136    ///
137    /// Wait for `AcquiredFrameView::get_producer_sync()` before you read the
138    /// buffer. Once you release or discard the frame, the session may render
139    /// into the buffer again. A reference that you take with
140    /// `AHardwareBuffer_acquire` keeps the buffer's memory, but not its
141    /// contents.
142    ///
143    /// See `mln_acquired_frame_get_android_hardware_buffer` in the
144    /// [C API reference](https://maplibre.org/maplibre-native-ffi/reference/c/android_8h.html).
145    ///
146    /// # Errors
147    ///
148    /// - `Status::TargetLost` when the session failed, or you detached,
149    ///   abandoned, or disposed it.
150    #[cfg(target_os = "android")]
151    pub fn get_android_hardware_buffer(&self) -> Result<Lent<'_, AndroidHardwareBufferFrame>> {
152        let mut call = self.owner.inner.call();
153        let mut out_frame: sys::mln_android_hardware_buffer_frame = unsafe { std::mem::zeroed() };
154        out_frame.size = std::mem::size_of::<sys::mln_android_hardware_buffer_frame>() as _;
155        call.status(|frame, out_diagnostic| unsafe {
156            sys::mln_acquired_frame_get_android_hardware_buffer(
157                frame,
158                &mut out_frame,
159                out_diagnostic,
160            )
161        })?;
162        Ok(Lent::new(unsafe { from_native(out_frame) }?))
163    }
164
165    /// Gets the dmabuf of an acquired frame.
166    ///
167    /// Wait for `AcquiredFrameView::get_producer_sync()` before you read the
168    /// buffer. Once you release or discard the frame, the session may render
169    /// into the buffer again. You can map a buffer with DRM_FORMAT_MOD_LINEAR,
170    /// which has one plane, with `mmap`, and bracket your reads with
171    /// DMA_BUF_IOCTL_SYNC.
172    ///
173    /// The session owns the planes' file descriptors, so don't close them. To
174    /// keep the buffer after you release the frame, duplicate each file
175    /// descriptor with `dup`. A duplicate keeps the buffer's memory, but not
176    /// its contents.
177    ///
178    /// See `mln_acquired_frame_get_dma_buf` in the
179    /// [C API reference](https://maplibre.org/maplibre-native-ffi/reference/c/linux_8h.html).
180    ///
181    /// # Errors
182    ///
183    /// - `Status::TargetLost` when the session failed, or you detached,
184    ///   abandoned, or disposed it.
185    #[cfg(any(
186        target_os = "freebsd",
187        all(target_os = "linux", not(target_env = "ohos"))
188    ))]
189    pub fn get_dma_buf(&self) -> Result<Lent<'_, DmaBufFrame>> {
190        let mut call = self.owner.inner.call();
191        let mut out_frame: sys::mln_dma_buf_frame = unsafe { std::mem::zeroed() };
192        out_frame.size = std::mem::size_of::<sys::mln_dma_buf_frame>() as _;
193        call.status(|frame, out_diagnostic| unsafe {
194            sys::mln_acquired_frame_get_dma_buf(frame, &mut out_frame, out_diagnostic)
195        })?;
196        Ok(Lent::new(unsafe { from_native(out_frame) }?))
197    }
198
199    /// Gets the DXGI shared texture of an acquired frame.
200    ///
201    /// Wait for `AcquiredFrameView::get_producer_sync()` before you read the
202    /// texture. Once you release or discard the frame, the session may render
203    /// into the texture again. Open the handle with
204    /// `ID3D11Device1::OpenSharedResource1` or
205    /// `ID3D12Device::OpenSharedHandle`. A texture that you open keeps its
206    /// memory, but not its contents.
207    ///
208    /// The session owns the handle, so don't close it. To keep the handle after
209    /// you release the frame, duplicate it with `DuplicateHandle`.
210    ///
211    /// See `mln_acquired_frame_get_dxgi_shared_texture` in the
212    /// [C API reference](https://maplibre.org/maplibre-native-ffi/reference/c/win32_8h.html).
213    ///
214    /// # Errors
215    ///
216    /// - `Status::TargetLost` when the session failed, or you detached,
217    ///   abandoned, or disposed it.
218    #[cfg(target_os = "windows")]
219    pub fn get_dxgi_shared_texture(&self) -> Result<Lent<'_, DxgiSharedTextureFrame>> {
220        let mut call = self.owner.inner.call();
221        let mut out_frame: sys::mln_dxgi_shared_texture_frame = unsafe { std::mem::zeroed() };
222        out_frame.size = std::mem::size_of::<sys::mln_dxgi_shared_texture_frame>() as _;
223        call.status(|frame, out_diagnostic| unsafe {
224            sys::mln_acquired_frame_get_dxgi_shared_texture(frame, &mut out_frame, out_diagnostic)
225        })?;
226        Ok(Lent::new(unsafe { from_native(out_frame) }?))
227    }
228
229    /// Gets the IOSurface of an acquired frame.
230    ///
231    /// Wait for `AcquiredFrameView::get_producer_sync()` before you read the
232    /// surface. Once you release or discard the frame, the session may render
233    /// into the surface again. For an API that takes a `CVPixelBuffer`, wrap
234    /// the surface with `CVPixelBufferCreateWithIOSurface`. A reference that
235    /// you take with `CFRetain`, or a pixel buffer that wraps the surface,
236    /// keeps the surface's memory, but not its contents.
237    ///
238    /// See `mln_acquired_frame_get_io_surface` in the
239    /// [C API reference](https://maplibre.org/maplibre-native-ffi/reference/c/apple_8h.html).
240    ///
241    /// # Errors
242    ///
243    /// - `Status::TargetLost` when the session failed, or you detached,
244    ///   abandoned, or disposed it.
245    #[cfg(any(
246        target_os = "ios",
247        target_os = "macos",
248        target_os = "tvos",
249        target_os = "visionos"
250    ))]
251    pub fn get_io_surface(&self) -> Result<Lent<'_, IoSurfaceFrame>> {
252        let mut call = self.owner.inner.call();
253        let mut out_frame: sys::mln_io_surface_frame = unsafe { std::mem::zeroed() };
254        out_frame.size = std::mem::size_of::<sys::mln_io_surface_frame>() as _;
255        call.status(|frame, out_diagnostic| unsafe {
256            sys::mln_acquired_frame_get_io_surface(frame, &mut out_frame, out_diagnostic)
257        })?;
258        Ok(Lent::new(unsafe { from_native(out_frame) }?))
259    }
260
261    /// Gets the Metal texture of an acquired frame.
262    ///
263    /// See `mln_acquired_frame_get_metal_texture` in the
264    /// [C API reference](https://maplibre.org/maplibre-native-ffi/reference/c/texture_8h.html).
265    ///
266    /// # Errors
267    ///
268    /// - `Status::TargetLost` when the session failed, or you detached,
269    ///   abandoned, or disposed it.
270    #[cfg(any(
271        target_os = "ios",
272        target_os = "macos",
273        target_os = "tvos",
274        target_os = "visionos"
275    ))]
276    pub fn get_metal_texture(&self) -> Result<Lent<'_, MetalTextureFrame>> {
277        let mut call = self.owner.inner.call();
278        let mut out_frame: sys::mln_metal_texture_frame = unsafe { std::mem::zeroed() };
279        out_frame.size = std::mem::size_of::<sys::mln_metal_texture_frame>() as _;
280        call.status(|frame, out_diagnostic| unsafe {
281            sys::mln_acquired_frame_get_metal_texture(frame, &mut out_frame, out_diagnostic)
282        })?;
283        Ok(Lent::new(unsafe { from_native(out_frame) }?))
284    }
285
286    /// Gets the OpenGL texture of an acquired frame.
287    ///
288    /// See `mln_acquired_frame_get_open_gl_texture` in the
289    /// [C API reference](https://maplibre.org/maplibre-native-ffi/reference/c/texture_8h.html).
290    ///
291    /// # Errors
292    ///
293    /// - `Status::TargetLost` when the session failed, or you detached,
294    ///   abandoned, or disposed it.
295    pub fn get_open_gl_texture(&self) -> Result<Lent<'_, OpenGlTextureFrame>> {
296        let mut call = self.owner.inner.call();
297        let mut out_frame: sys::mln_open_gl_texture_frame = unsafe { std::mem::zeroed() };
298        out_frame.size = std::mem::size_of::<sys::mln_open_gl_texture_frame>() as _;
299        call.status(|frame, out_diagnostic| unsafe {
300            sys::mln_acquired_frame_get_open_gl_texture(frame, &mut out_frame, out_diagnostic)
301        })?;
302        Ok(Lent::new(unsafe { from_native(out_frame) }?))
303    }
304
305    /// Reads what to wait for before you read an acquired frame's texture.
306    ///
307    /// See `mln_acquired_frame_get_producer_sync` in the
308    /// [C API reference](https://maplibre.org/maplibre-native-ffi/reference/c/render__session_8h.html).
309    ///
310    /// # Errors
311    ///
312    /// - `Status::TargetLost` when the session failed, or you detached,
313    ///   abandoned, or disposed it.
314    pub fn get_producer_sync(&self) -> Result<Lent<'_, GpuSync>> {
315        let mut call = self.owner.inner.call();
316        let mut out_sync: sys::mln_gpu_sync = unsafe { std::mem::zeroed() };
317        out_sync.size = std::mem::size_of::<sys::mln_gpu_sync>() as _;
318        call.status(|frame, out_diagnostic| unsafe {
319            sys::mln_acquired_frame_get_producer_sync(frame, &mut out_sync, out_diagnostic)
320        })?;
321        Ok(Lent::new(unsafe { from_native(out_sync) }?))
322    }
323
324    /// Gets the Vulkan image of an acquired frame.
325    ///
326    /// See `mln_acquired_frame_get_vulkan_texture` in the
327    /// [C API reference](https://maplibre.org/maplibre-native-ffi/reference/c/texture_8h.html).
328    ///
329    /// # Errors
330    ///
331    /// - `Status::TargetLost` when the session failed, or you detached,
332    ///   abandoned, or disposed it.
333    #[cfg(any(
334        target_os = "android",
335        target_os = "freebsd",
336        target_os = "linux",
337        target_os = "macos",
338        target_os = "windows"
339    ))]
340    pub fn get_vulkan_texture(&self) -> Result<Lent<'_, VulkanTextureFrame>> {
341        let mut call = self.owner.inner.call();
342        let mut out_frame: sys::mln_vulkan_texture_frame = unsafe { std::mem::zeroed() };
343        out_frame.size = std::mem::size_of::<sys::mln_vulkan_texture_frame>() as _;
344        call.status(|frame, out_diagnostic| unsafe {
345            sys::mln_acquired_frame_get_vulkan_texture(frame, &mut out_frame, out_diagnostic)
346        })?;
347        Ok(Lent::new(unsafe { from_native(out_frame) }?))
348    }
349
350    /// Gets the WebGPU texture of an acquired frame.
351    ///
352    /// See `mln_acquired_frame_get_web_gpu_texture` in the
353    /// [C API reference](https://maplibre.org/maplibre-native-ffi/reference/c/texture_8h.html).
354    ///
355    /// # Errors
356    ///
357    /// - `Status::TargetLost` when the session failed, or you detached,
358    ///   abandoned, or disposed it.
359    #[cfg(target_os = "emscripten")]
360    pub fn get_web_gpu_texture(&self) -> Result<Lent<'_, WebGpuTextureFrame>> {
361        let mut call = self.owner.inner.call();
362        let mut out_frame: sys::mln_web_gpu_texture_frame = unsafe { std::mem::zeroed() };
363        out_frame.size = std::mem::size_of::<sys::mln_web_gpu_texture_frame>() as _;
364        call.status(|frame, out_diagnostic| unsafe {
365            sys::mln_acquired_frame_get_web_gpu_texture(frame, &mut out_frame, out_diagnostic)
366        })?;
367        Ok(Lent::new(unsafe { from_native(out_frame) }?))
368    }
369}
maplibre_native_ffi/generated/acquired_frame.rs

maplibre_native_ffi/generated/
acquired_frame.rs
