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) -> OptionsIter<'_> {
132        OptionsIter::new(self)
133    }
134
135    #[doc(alias = "gst_buffer_pool_config_set_params")]
136    pub fn set_params(
137        &mut self,
138        caps: Option<&crate::Caps>,
139        size: u32,
140        min_buffers: u32,
141        max_buffers: u32,
142    ) {
143        unsafe {
144            ffi::gst_buffer_pool_config_set_params(
145                self.0.as_mut_ptr(),
146                caps.to_glib_none().0,
147                size,
148                min_buffers,
149                max_buffers,
150            );
151        }
152    }
153
154    #[doc(alias = "get_params")]
155    #[doc(alias = "gst_buffer_pool_config_get_params")]
156    pub fn params(&self) -> Option<(Option<crate::Caps>, u32, u32, u32)> {
157        unsafe {
158            let mut caps = ptr::null_mut();
159            let mut size = mem::MaybeUninit::uninit();
160            let mut min_buffers = mem::MaybeUninit::uninit();
161            let mut max_buffers = mem::MaybeUninit::uninit();
162
163            let ret: bool = from_glib(ffi::gst_buffer_pool_config_get_params(
164                self.0.as_mut_ptr(),
165                &mut caps,
166                size.as_mut_ptr(),
167                min_buffers.as_mut_ptr(),
168                max_buffers.as_mut_ptr(),
169            ));
170            if !ret {
171                return None;
172            }
173
174            Some((
175                from_glib_none(caps),
176                size.assume_init(),
177                min_buffers.assume_init(),
178                max_buffers.assume_init(),
179            ))
180        }
181    }
182
183    #[doc(alias = "gst_buffer_pool_config_validate_params")]
184    pub fn validate_params(
185        &self,
186        caps: Option<&crate::Caps>,
187        size: u32,
188        min_buffers: u32,
189        max_buffers: u32,
190    ) -> Result<(), glib::BoolError> {
191        unsafe {
192            glib::result_from_gboolean!(
193                ffi::gst_buffer_pool_config_validate_params(
194                    self.0.as_mut_ptr(),
195                    caps.to_glib_none().0,
196                    size,
197                    min_buffers,
198                    max_buffers,
199                ),
200                "Parameters are not valid in this context"
201            )
202        }
203    }
204
205    #[doc(alias = "get_allocator")]
206    #[doc(alias = "gst_buffer_pool_config_get_allocator")]
207    pub fn allocator(&self) -> Option<(Option<Allocator>, AllocationParams)> {
208        unsafe {
209            let mut allocator = ptr::null_mut();
210            let mut params = mem::MaybeUninit::uninit();
211            let ret = from_glib(ffi::gst_buffer_pool_config_get_allocator(
212                self.0.as_mut_ptr(),
213                &mut allocator,
214                params.as_mut_ptr(),
215            ));
216            if ret {
217                Some((from_glib_none(allocator), params.assume_init().into()))
218            } else {
219                None
220            }
221        }
222    }
223
224    #[doc(alias = "gst_buffer_pool_config_set_allocator")]
225    pub fn set_allocator(
226        &self,
227        allocator: Option<&impl IsA<Allocator>>,
228        params: Option<&AllocationParams>,
229    ) {
230        assert!(allocator.is_some() || params.is_some());
231        unsafe {
232            ffi::gst_buffer_pool_config_set_allocator(
233                self.0.as_mut_ptr(),
234                allocator.to_glib_none().0 as *mut ffi::GstAllocator,
235                match params {
236                    Some(val) => val.as_ptr(),
237                    None => ptr::null(),
238                },
239            )
240        }
241    }
242}
243
244crate::utils::define_fixed_size_iter!(
245    OptionsIter,
246    &'a BufferPoolConfigRef,
247    &'a glib::GStr,
248    |collection: &BufferPoolConfigRef| unsafe {
249        ffi::gst_buffer_pool_config_n_options(collection.as_mut_ptr()) as usize
250    },
251    |collection: &BufferPoolConfigRef, idx: usize| unsafe {
252        glib::GStr::from_ptr(ffi::gst_buffer_pool_config_get_option(
253            collection.as_mut_ptr(),
254            idx as u32,
255        ))
256    }
257);
258
259#[derive(Debug, Copy, Clone)]
260#[doc(alias = "GstBufferPoolAcquireParams")]
261pub struct BufferPoolAcquireParams(ffi::GstBufferPoolAcquireParams);
262
263unsafe impl Send for BufferPoolAcquireParams {}
264unsafe impl Sync for BufferPoolAcquireParams {}
265
266impl BufferPoolAcquireParams {
267    pub fn with_flags(flags: crate::BufferPoolAcquireFlags) -> Self {
268        skip_assert_initialized!();
269        BufferPoolAcquireParams(ffi::GstBufferPoolAcquireParams {
270            format: ffi::GST_FORMAT_UNDEFINED,
271            start: -1,
272            stop: -1,
273            flags: flags.into_glib(),
274            _gst_reserved: [ptr::null_mut(); 4],
275        })
276    }
277
278    pub fn with_start_stop<T: crate::format::SpecificFormattedValue>(
279        start: T,
280        stop: T,
281        flags: crate::BufferPoolAcquireFlags,
282    ) -> Self {
283        skip_assert_initialized!();
284        unsafe {
285            BufferPoolAcquireParams(ffi::GstBufferPoolAcquireParams {
286                format: start.format().into_glib(),
287                start: start.into_raw_value(),
288                stop: stop.into_raw_value(),
289                flags: flags.into_glib(),
290                _gst_reserved: [ptr::null_mut(); 4],
291            })
292        }
293    }
294
295    pub fn flags(&self) -> crate::BufferPoolAcquireFlags {
296        unsafe { from_glib(self.0.flags) }
297    }
298
299    pub fn format(&self) -> crate::Format {
300        unsafe { from_glib(self.0.format) }
301    }
302
303    pub fn start(&self) -> crate::GenericFormattedValue {
304        unsafe { crate::GenericFormattedValue::new(from_glib(self.0.format), self.0.start) }
305    }
306
307    pub fn stop(&self) -> crate::GenericFormattedValue {
308        unsafe { crate::GenericFormattedValue::new(from_glib(self.0.format), self.0.stop) }
309    }
310
311    pub fn set_flags(&mut self, flags: crate::BufferPoolAcquireFlags) {
312        self.0.flags = flags.into_glib();
313    }
314
315    pub fn set_format(&mut self, format: crate::Format) {
316        self.0.format = format.into_glib();
317    }
318
319    pub fn set_start(&mut self, start: crate::GenericFormattedValue) {
320        assert_eq!(self.format(), start.format());
321        self.0.start = start.value();
322    }
323
324    pub fn set_stop(&mut self, stop: crate::GenericFormattedValue) {
325        assert_eq!(self.format(), stop.format());
326        self.0.stop = stop.value();
327    }
328}
329
330impl PartialEq for BufferPoolAcquireParams {
331    fn eq(&self, other: &Self) -> bool {
332        self.flags() == other.flags()
333            && self.format() == other.format()
334            && self.start() == other.start()
335            && self.stop() == other.stop()
336    }
337}
338
339impl Eq for BufferPoolAcquireParams {}
340
341impl Default for BufferPoolAcquireParams {
342    fn default() -> Self {
343        Self(ffi::GstBufferPoolAcquireParams {
344            format: ffi::GST_FORMAT_UNDEFINED,
345            start: -1,
346            stop: -1,
347            flags: ffi::GST_BUFFER_POOL_ACQUIRE_FLAG_NONE,
348            _gst_reserved: [ptr::null_mut(); 4],
349        })
350    }
351}
352
353#[doc(hidden)]
354impl<'a> ToGlibPtr<'a, *const ffi::GstBufferPoolAcquireParams> for BufferPoolAcquireParams {
355    type Storage = PhantomData<&'a Self>;
356
357    #[inline]
358    fn to_glib_none(
359        &'a self,
360    ) -> glib::translate::Stash<'a, *const ffi::GstBufferPoolAcquireParams, Self> {
361        glib::translate::Stash(&self.0, PhantomData)
362    }
363}
364
365#[doc(hidden)]
366impl<'a> ToGlibPtrMut<'a, *mut ffi::GstBufferPoolAcquireParams> for BufferPoolAcquireParams {
367    type Storage = PhantomData<&'a mut Self>;
368
369    #[inline]
370    fn to_glib_none_mut(
371        &'a mut self,
372    ) -> glib::translate::StashMut<'a, *mut ffi::GstBufferPoolAcquireParams, Self> {
373        glib::translate::StashMut(&mut self.0, PhantomData)
374    }
375}
376
377#[doc(hidden)]
378impl FromGlibPtrNone<*mut ffi::GstBufferPoolAcquireParams> for BufferPoolAcquireParams {
379    #[inline]
380    unsafe fn from_glib_none(ptr: *mut ffi::GstBufferPoolAcquireParams) -> Self {
381        Self(*ptr)
382    }
383}
384
385pub trait BufferPoolExtManual: IsA<BufferPool> + 'static {
386    /// Gets a copy of the current configuration of the pool. This configuration
387    /// can be modified and used for the [`set_config()`][Self::set_config()] call.
388    ///
389    /// # Returns
390    ///
391    /// a copy of the current configuration of `self`.
392    #[doc(alias = "get_config")]
393    #[doc(alias = "gst_buffer_pool_get_config")]
394    fn config(&self) -> BufferPoolConfig {
395        unsafe {
396            let ptr = ffi::gst_buffer_pool_get_config(self.as_ref().to_glib_none().0);
397            BufferPoolConfig(from_glib_full(ptr))
398        }
399    }
400
401    /// Sets the configuration of the pool. If the pool is already configured, and
402    /// the configuration hasn't changed, this function will return [`true`]. If the
403    /// pool is active, this method will return [`false`] and active configuration
404    /// will remain. Buffers allocated from this pool must be returned or else this
405    /// function will do nothing and return [`false`].
406    ///
407    /// `config` is a [`Structure`][crate::Structure] that contains the configuration parameters for
408    /// the pool. A default and mandatory set of parameters can be configured with
409    /// `gst_buffer_pool_config_set_params()`, `gst_buffer_pool_config_set_allocator()`
410    /// and `gst_buffer_pool_config_add_option()`.
411    ///
412    /// If the parameters in `config` can not be set exactly, this function returns
413    /// [`false`] and will try to update as much state as possible. The new state can
414    /// then be retrieved and refined with [`config()`][Self::config()].
415    ///
416    /// This function takes ownership of `config`.
417    /// ## `config`
418    /// a [`Structure`][crate::Structure]
419    ///
420    /// # Returns
421    ///
422    /// [`true`] when the configuration could be set.
423    #[doc(alias = "gst_buffer_pool_set_config")]
424    fn set_config(&self, config: BufferPoolConfig) -> Result<(), glib::error::BoolError> {
425        unsafe {
426            glib::result_from_gboolean!(
427                ffi::gst_buffer_pool_set_config(
428                    self.as_ref().to_glib_none().0,
429                    config.0.into_glib_ptr()
430                ),
431                "Failed to set config",
432            )
433        }
434    }
435
436    fn is_flushing(&self) -> bool {
437        unsafe {
438            let stash = self.as_ref().to_glib_none();
439            let ptr: *mut ffi::GstBufferPool = stash.0;
440
441            from_glib((*ptr).flushing)
442        }
443    }
444
445    /// Acquires a buffer from `self`. `buffer` should point to a memory location that
446    /// can hold a pointer to the new buffer. When the pool is empty, this function
447    /// will by default block until a buffer is released into the pool again or when
448    /// the pool is set to flushing or deactivated.
449    ///
450    /// `params` can contain optional parameters to influence the allocation.
451    /// ## `params`
452    /// parameters.
453    ///
454    /// # Returns
455    ///
456    /// a [`FlowReturn`][crate::FlowReturn] such as [`FlowReturn::Flushing`][crate::FlowReturn::Flushing] when the pool is
457    /// inactive.
458    ///
459    /// ## `buffer`
460    /// a location for a [`Buffer`][crate::Buffer]
461    #[doc(alias = "gst_buffer_pool_acquire_buffer")]
462    fn acquire_buffer(
463        &self,
464        params: Option<&BufferPoolAcquireParams>,
465    ) -> Result<crate::Buffer, crate::FlowError> {
466        let params_ptr = params.to_glib_none().0 as *mut _;
467
468        unsafe {
469            let mut buffer = ptr::null_mut();
470            crate::FlowSuccess::try_from_glib(ffi::gst_buffer_pool_acquire_buffer(
471                self.as_ref().to_glib_none().0,
472                &mut buffer,
473                params_ptr,
474            ))
475            .map(|_| from_glib_full(buffer))
476        }
477    }
478}
479
480impl<O: IsA<BufferPool>> BufferPoolExtManual for O {}
481
482#[cfg(test)]
483mod tests {
484    use super::*;
485    use crate::prelude::*;
486
487    #[test]
488    fn pool_with_params() {
489        crate::init().unwrap();
490
491        let pool = crate::BufferPool::new();
492        let mut config = pool.config();
493        config.set_params(Some(&crate::Caps::builder("foo/bar").build()), 1024, 0, 2);
494        pool.set_config(config).unwrap();
495
496        pool.set_active(true).unwrap();
497
498        let params =
499            crate::BufferPoolAcquireParams::with_flags(crate::BufferPoolAcquireFlags::DONTWAIT);
500
501        let _buf1 = pool.acquire_buffer(Some(&params)).unwrap();
502        let buf2 = pool.acquire_buffer(Some(&params)).unwrap();
503
504        assert!(pool.acquire_buffer(Some(&params)).is_err());
505
506        drop(buf2);
507        let _buf2 = pool.acquire_buffer(Some(&params)).unwrap();
508
509        pool.set_active(false).unwrap();
510    }
511
512    #[test]
513    fn pool_no_params() {
514        crate::init().unwrap();
515
516        let pool = crate::BufferPool::new();
517        let mut config = pool.config();
518        config.set_params(None, 1024, 0, 2);
519        pool.set_config(config).unwrap();
520
521        pool.set_active(true).unwrap();
522        let _buf1 = pool.acquire_buffer(None).unwrap();
523        pool.set_active(false).unwrap();
524    }
525}