gstreamer/
buffer_pool.rs

1// Take a look at the license at the top of the repository in the LICENSE file.
2
3use std::{
4    marker::PhantomData,
5    mem, ops,
6    ops::{Deref, DerefMut},
7    ptr,
8};
9
10use glib::{prelude::*, translate::*};
11
12use crate::{ffi, AllocationParams, Allocator, BufferPool, Structure, StructureRef};
13
14#[derive(Debug, Clone, PartialEq, Eq)]
15#[repr(transparent)]
16pub struct BufferPoolConfig(Structure);
17
18impl Deref for BufferPoolConfig {
19    type Target = BufferPoolConfigRef;
20
21    #[inline]
22    fn deref(&self) -> &BufferPoolConfigRef {
23        unsafe { &*(self.0.as_ptr() as *const StructureRef as *const BufferPoolConfigRef) }
24    }
25}
26
27impl DerefMut for BufferPoolConfig {
28    #[inline]
29    fn deref_mut(&mut self) -> &mut BufferPoolConfigRef {
30        unsafe { &mut *(self.0.as_ptr() as *mut StructureRef as *mut BufferPoolConfigRef) }
31    }
32}
33
34impl AsRef<BufferPoolConfigRef> for BufferPoolConfig {
35    #[inline]
36    fn as_ref(&self) -> &BufferPoolConfigRef {
37        self.deref()
38    }
39}
40
41impl AsMut<BufferPoolConfigRef> for BufferPoolConfig {
42    #[inline]
43    fn as_mut(&mut self) -> &mut BufferPoolConfigRef {
44        self.deref_mut()
45    }
46}
47
48#[derive(Debug)]
49#[repr(transparent)]
50pub struct BufferPoolConfigRef(StructureRef);
51
52impl BufferPoolConfigRef {
53    #[inline]
54    pub unsafe fn from_glib_borrow<'a>(ptr: *const ffi::GstStructure) -> &'a BufferPoolConfigRef {
55        debug_assert!(!ptr.is_null());
56
57        &*(ptr as *mut StructureRef as *mut BufferPoolConfigRef)
58    }
59
60    #[inline]
61    pub unsafe fn from_glib_borrow_mut<'a>(
62        ptr: *mut ffi::GstStructure,
63    ) -> &'a mut BufferPoolConfigRef {
64        debug_assert!(!ptr.is_null());
65
66        &mut *(ptr as *mut StructureRef as *mut BufferPoolConfigRef)
67    }
68
69    #[inline]
70    pub fn as_ptr(&self) -> *const ffi::GstStructure {
71        self as *const Self as *const ffi::GstStructure
72    }
73
74    #[inline]
75    pub fn as_mut_ptr(&self) -> *mut ffi::GstStructure {
76        self as *const Self as *mut ffi::GstStructure
77    }
78}
79
80impl ops::Deref for BufferPoolConfigRef {
81    type Target = crate::StructureRef;
82
83    #[inline]
84    fn deref(&self) -> &crate::StructureRef {
85        &self.0
86    }
87}
88
89impl ops::DerefMut for BufferPoolConfigRef {
90    #[inline]
91    fn deref_mut(&mut self) -> &mut crate::StructureRef {
92        &mut self.0
93    }
94}
95
96impl AsRef<crate::StructureRef> for BufferPoolConfigRef {
97    #[inline]
98    fn as_ref(&self) -> &crate::StructureRef {
99        &self.0
100    }
101}
102
103impl AsMut<crate::StructureRef> for BufferPoolConfigRef {
104    #[inline]
105    fn as_mut(&mut self) -> &mut crate::StructureRef {
106        &mut self.0
107    }
108}
109
110impl BufferPoolConfigRef {
111    #[doc(alias = "gst_buffer_pool_config_add_option")]
112    pub fn add_option(&mut self, option: &str) {
113        unsafe {
114            ffi::gst_buffer_pool_config_add_option(self.0.as_mut_ptr(), option.to_glib_none().0);
115        }
116    }
117
118    #[doc(alias = "gst_buffer_pool_config_has_option")]
119    pub fn has_option(&self, option: &str) -> bool {
120        unsafe {
121            from_glib(ffi::gst_buffer_pool_config_has_option(
122                self.0.as_mut_ptr(),
123                option.to_glib_none().0,
124            ))
125        }
126    }
127
128    #[doc(alias = "get_options")]
129    #[doc(alias = "gst_buffer_pool_config_n_options")]
130    #[doc(alias = "gst_buffer_pool_config_get_option")]
131    pub fn options(&self) -> Vec<String> {
132        unsafe {
133            let n = ffi::gst_buffer_pool_config_n_options(self.0.as_mut_ptr()) as usize;
134            let mut options = Vec::with_capacity(n);
135
136            for i in 0..n {
137                options.push(from_glib_none(ffi::gst_buffer_pool_config_get_option(
138                    self.0.as_mut_ptr(),
139                    i as u32,
140                )));
141            }
142
143            options
144        }
145    }
146
147    #[doc(alias = "gst_buffer_pool_config_set_params")]
148    pub fn set_params(
149        &mut self,
150        caps: Option<&crate::Caps>,
151        size: u32,
152        min_buffers: u32,
153        max_buffers: u32,
154    ) {
155        unsafe {
156            ffi::gst_buffer_pool_config_set_params(
157                self.0.as_mut_ptr(),
158                caps.to_glib_none().0,
159                size,
160                min_buffers,
161                max_buffers,
162            );
163        }
164    }
165
166    #[doc(alias = "get_params")]
167    #[doc(alias = "gst_buffer_pool_config_get_params")]
168    pub fn params(&self) -> Option<(Option<crate::Caps>, u32, u32, u32)> {
169        unsafe {
170            let mut caps = ptr::null_mut();
171            let mut size = mem::MaybeUninit::uninit();
172            let mut min_buffers = mem::MaybeUninit::uninit();
173            let mut max_buffers = mem::MaybeUninit::uninit();
174
175            let ret: bool = from_glib(ffi::gst_buffer_pool_config_get_params(
176                self.0.as_mut_ptr(),
177                &mut caps,
178                size.as_mut_ptr(),
179                min_buffers.as_mut_ptr(),
180                max_buffers.as_mut_ptr(),
181            ));
182            if !ret {
183                return None;
184            }
185
186            Some((
187                from_glib_none(caps),
188                size.assume_init(),
189                min_buffers.assume_init(),
190                max_buffers.assume_init(),
191            ))
192        }
193    }
194
195    #[doc(alias = "gst_buffer_pool_config_validate_params")]
196    pub fn validate_params(
197        &self,
198        caps: Option<&crate::Caps>,
199        size: u32,
200        min_buffers: u32,
201        max_buffers: u32,
202    ) -> Result<(), glib::BoolError> {
203        unsafe {
204            glib::result_from_gboolean!(
205                ffi::gst_buffer_pool_config_validate_params(
206                    self.0.as_mut_ptr(),
207                    caps.to_glib_none().0,
208                    size,
209                    min_buffers,
210                    max_buffers,
211                ),
212                "Parameters are not valid in this context"
213            )
214        }
215    }
216
217    #[doc(alias = "get_allocator")]
218    #[doc(alias = "gst_buffer_pool_config_get_allocator")]
219    pub fn allocator(&self) -> Option<(Option<Allocator>, AllocationParams)> {
220        unsafe {
221            let mut allocator = ptr::null_mut();
222            let mut params = mem::MaybeUninit::uninit();
223            let ret = from_glib(ffi::gst_buffer_pool_config_get_allocator(
224                self.0.as_mut_ptr(),
225                &mut allocator,
226                params.as_mut_ptr(),
227            ));
228            if ret {
229                Some((from_glib_none(allocator), params.assume_init().into()))
230            } else {
231                None
232            }
233        }
234    }
235
236    #[doc(alias = "gst_buffer_pool_config_set_allocator")]
237    pub fn set_allocator(&self, allocator: Option<&Allocator>, params: Option<&AllocationParams>) {
238        assert!(allocator.is_some() || params.is_some());
239        unsafe {
240            ffi::gst_buffer_pool_config_set_allocator(
241                self.0.as_mut_ptr(),
242                allocator.to_glib_none().0,
243                match params {
244                    Some(val) => val.as_ptr(),
245                    None => ptr::null(),
246                },
247            )
248        }
249    }
250    // TODO: options iterator
251}
252
253#[derive(Debug, Copy, Clone)]
254#[doc(alias = "GstBufferPoolAcquireParams")]
255pub struct BufferPoolAcquireParams(ffi::GstBufferPoolAcquireParams);
256
257unsafe impl Send for BufferPoolAcquireParams {}
258unsafe impl Sync for BufferPoolAcquireParams {}
259
260impl BufferPoolAcquireParams {
261    pub fn with_flags(flags: crate::BufferPoolAcquireFlags) -> Self {
262        skip_assert_initialized!();
263        BufferPoolAcquireParams(ffi::GstBufferPoolAcquireParams {
264            format: ffi::GST_FORMAT_UNDEFINED,
265            start: -1,
266            stop: -1,
267            flags: flags.into_glib(),
268            _gst_reserved: [ptr::null_mut(); 4],
269        })
270    }
271
272    pub fn with_start_stop<T: crate::format::SpecificFormattedValue>(
273        start: T,
274        stop: T,
275        flags: crate::BufferPoolAcquireFlags,
276    ) -> Self {
277        skip_assert_initialized!();
278        unsafe {
279            BufferPoolAcquireParams(ffi::GstBufferPoolAcquireParams {
280                format: start.format().into_glib(),
281                start: start.into_raw_value(),
282                stop: stop.into_raw_value(),
283                flags: flags.into_glib(),
284                _gst_reserved: [ptr::null_mut(); 4],
285            })
286        }
287    }
288
289    pub fn flags(&self) -> crate::BufferPoolAcquireFlags {
290        unsafe { from_glib(self.0.flags) }
291    }
292
293    pub fn format(&self) -> crate::Format {
294        unsafe { from_glib(self.0.format) }
295    }
296
297    pub fn start(&self) -> crate::GenericFormattedValue {
298        unsafe { crate::GenericFormattedValue::new(from_glib(self.0.format), self.0.start) }
299    }
300
301    pub fn stop(&self) -> crate::GenericFormattedValue {
302        unsafe { crate::GenericFormattedValue::new(from_glib(self.0.format), self.0.stop) }
303    }
304
305    pub fn set_flags(&mut self, flags: crate::BufferPoolAcquireFlags) {
306        self.0.flags = flags.into_glib();
307    }
308
309    pub fn set_format(&mut self, format: crate::Format) {
310        self.0.format = format.into_glib();
311    }
312
313    pub fn set_start(&mut self, start: crate::GenericFormattedValue) {
314        assert_eq!(self.format(), start.format());
315        self.0.start = start.value();
316    }
317
318    pub fn set_stop(&mut self, stop: crate::GenericFormattedValue) {
319        assert_eq!(self.format(), stop.format());
320        self.0.stop = stop.value();
321    }
322}
323
324impl PartialEq for BufferPoolAcquireParams {
325    fn eq(&self, other: &Self) -> bool {
326        self.flags() == other.flags()
327            && self.format() == other.format()
328            && self.start() == other.start()
329            && self.stop() == other.stop()
330    }
331}
332
333impl Eq for BufferPoolAcquireParams {}
334
335impl Default for BufferPoolAcquireParams {
336    fn default() -> Self {
337        Self(ffi::GstBufferPoolAcquireParams {
338            format: ffi::GST_FORMAT_UNDEFINED,
339            start: -1,
340            stop: -1,
341            flags: ffi::GST_BUFFER_POOL_ACQUIRE_FLAG_NONE,
342            _gst_reserved: [ptr::null_mut(); 4],
343        })
344    }
345}
346
347#[doc(hidden)]
348impl<'a> ToGlibPtr<'a, *const ffi::GstBufferPoolAcquireParams> for BufferPoolAcquireParams {
349    type Storage = PhantomData<&'a Self>;
350
351    #[inline]
352    fn to_glib_none(
353        &'a self,
354    ) -> glib::translate::Stash<'a, *const ffi::GstBufferPoolAcquireParams, Self> {
355        glib::translate::Stash(&self.0, PhantomData)
356    }
357}
358
359#[doc(hidden)]
360impl<'a> ToGlibPtrMut<'a, *mut ffi::GstBufferPoolAcquireParams> for BufferPoolAcquireParams {
361    type Storage = PhantomData<&'a mut Self>;
362
363    #[inline]
364    fn to_glib_none_mut(
365        &'a mut self,
366    ) -> glib::translate::StashMut<'a, *mut ffi::GstBufferPoolAcquireParams, Self> {
367        glib::translate::StashMut(&mut self.0, PhantomData)
368    }
369}
370
371#[doc(hidden)]
372impl FromGlibPtrNone<*mut ffi::GstBufferPoolAcquireParams> for BufferPoolAcquireParams {
373    #[inline]
374    unsafe fn from_glib_none(ptr: *mut ffi::GstBufferPoolAcquireParams) -> Self {
375        Self(*ptr)
376    }
377}
378
379mod sealed {
380    pub trait Sealed {}
381    impl<T: super::IsA<super::BufferPool>> Sealed for T {}
382}
383
384pub trait BufferPoolExtManual: sealed::Sealed + IsA<BufferPool> + 'static {
385    /// Gets a copy of the current configuration of the pool. This configuration
386    /// can be modified and used for the [`set_config()`][Self::set_config()] call.
387    ///
388    /// # Returns
389    ///
390    /// a copy of the current configuration of `self`.
391    #[doc(alias = "get_config")]
392    #[doc(alias = "gst_buffer_pool_get_config")]
393    fn config(&self) -> BufferPoolConfig {
394        unsafe {
395            let ptr = ffi::gst_buffer_pool_get_config(self.as_ref().to_glib_none().0);
396            BufferPoolConfig(from_glib_full(ptr))
397        }
398    }
399
400    /// Sets the configuration of the pool. If the pool is already configured, and
401    /// the configuration hasn't changed, this function will return [`true`]. If the
402    /// pool is active, this method will return [`false`] and active configuration
403    /// will remain. Buffers allocated from this pool must be returned or else this
404    /// function will do nothing and return [`false`].
405    ///
406    /// `config` is a [`Structure`][crate::Structure] that contains the configuration parameters for
407    /// the pool. A default and mandatory set of parameters can be configured with
408    /// `gst_buffer_pool_config_set_params()`, `gst_buffer_pool_config_set_allocator()`
409    /// and `gst_buffer_pool_config_add_option()`.
410    ///
411    /// If the parameters in `config` can not be set exactly, this function returns
412    /// [`false`] and will try to update as much state as possible. The new state can
413    /// then be retrieved and refined with [`config()`][Self::config()].
414    ///
415    /// This function takes ownership of `config`.
416    /// ## `config`
417    /// a [`Structure`][crate::Structure]
418    ///
419    /// # Returns
420    ///
421    /// [`true`] when the configuration could be set.
422    #[doc(alias = "gst_buffer_pool_set_config")]
423    fn set_config(&self, config: BufferPoolConfig) -> Result<(), glib::error::BoolError> {
424        unsafe {
425            glib::result_from_gboolean!(
426                ffi::gst_buffer_pool_set_config(
427                    self.as_ref().to_glib_none().0,
428                    config.0.into_glib_ptr()
429                ),
430                "Failed to set config",
431            )
432        }
433    }
434
435    fn is_flushing(&self) -> bool {
436        unsafe {
437            let stash = self.as_ref().to_glib_none();
438            let ptr: *mut ffi::GstBufferPool = stash.0;
439
440            from_glib((*ptr).flushing)
441        }
442    }
443
444    /// Acquires a buffer from `self`. `buffer` should point to a memory location that
445    /// can hold a pointer to the new buffer. When the pool is empty, this function
446    /// will by default block until a buffer is released into the pool again or when
447    /// the pool is set to flushing or deactivated.
448    ///
449    /// `params` can contain optional parameters to influence the allocation.
450    /// ## `params`
451    /// parameters.
452    ///
453    /// # Returns
454    ///
455    /// a [`FlowReturn`][crate::FlowReturn] such as [`FlowReturn::Flushing`][crate::FlowReturn::Flushing] when the pool is
456    /// inactive.
457    ///
458    /// ## `buffer`
459    /// a location for a [`Buffer`][crate::Buffer]
460    #[doc(alias = "gst_buffer_pool_acquire_buffer")]
461    fn acquire_buffer(
462        &self,
463        params: Option<&BufferPoolAcquireParams>,
464    ) -> Result<crate::Buffer, crate::FlowError> {
465        let params_ptr = params.to_glib_none().0 as *mut _;
466
467        unsafe {
468            let mut buffer = ptr::null_mut();
469            crate::FlowSuccess::try_from_glib(ffi::gst_buffer_pool_acquire_buffer(
470                self.as_ref().to_glib_none().0,
471                &mut buffer,
472                params_ptr,
473            ))
474            .map(|_| from_glib_full(buffer))
475        }
476    }
477}
478
479impl<O: IsA<BufferPool>> BufferPoolExtManual for O {}
480
481#[cfg(test)]
482mod tests {
483    use super::*;
484    use crate::prelude::*;
485
486    #[test]
487    fn pool_with_params() {
488        crate::init().unwrap();
489
490        let pool = crate::BufferPool::new();
491        let mut config = pool.config();
492        config.set_params(Some(&crate::Caps::builder("foo/bar").build()), 1024, 0, 2);
493        pool.set_config(config).unwrap();
494
495        pool.set_active(true).unwrap();
496
497        let params =
498            crate::BufferPoolAcquireParams::with_flags(crate::BufferPoolAcquireFlags::DONTWAIT);
499
500        let _buf1 = pool.acquire_buffer(Some(&params)).unwrap();
501        let buf2 = pool.acquire_buffer(Some(&params)).unwrap();
502
503        assert!(pool.acquire_buffer(Some(&params)).is_err());
504
505        drop(buf2);
506        let _buf2 = pool.acquire_buffer(Some(&params)).unwrap();
507
508        pool.set_active(false).unwrap();
509    }
510
511    #[test]
512    fn pool_no_params() {
513        crate::init().unwrap();
514
515        let pool = crate::BufferPool::new();
516        let mut config = pool.config();
517        config.set_params(None, 1024, 0, 2);
518        pool.set_config(config).unwrap();
519
520        pool.set_active(true).unwrap();
521        let _buf1 = pool.acquire_buffer(None).unwrap();
522        pool.set_active(false).unwrap();
523    }
524}