Skip to main content

vapoursynth4_rs/
frame.rs

1/*
2 This Source Code Form is subject to the terms of the Mozilla Public
3 License, v. 2.0. If a copy of the MPL was not distributed with this
4 file, You can obtain one at http://mozilla.org/MPL/2.0/.
5*/
6
7use std::{marker::PhantomData, mem::ManuallyDrop};
8
9use crate::{
10    api::Api,
11    ffi,
12    map::{MapMut, MapRef},
13};
14
15mod context;
16mod format;
17
18pub use context::*;
19pub use format::*;
20
21pub trait Frame: Sized + Send + internal::FrameFromPtr {
22    fn api(&self) -> Api;
23
24    #[must_use]
25    fn as_ptr(&self) -> *mut ffi::VSFrame;
26
27    /// Returns whether the data resides in host or GPU memory.
28    #[cfg(feature = "vs-43")]
29    #[must_use]
30    fn residency(&self) -> ffi::VSNodeResidency;
31
32    #[must_use]
33    fn properties(&self) -> Option<MapRef<'_>>;
34}
35
36pub(crate) mod internal {
37    use super::{Api, ffi};
38
39    pub trait FrameFromPtr {
40        type Writable;
41
42        unsafe fn from_ptr(ptr: *const ffi::VSFrame, api: Api) -> Self;
43
44        unsafe fn writable_from_ptr(ptr: *mut ffi::VSFrame, api: Api) -> Self::Writable;
45    }
46}
47use internal::FrameFromPtr;
48
49#[derive(Debug, PartialEq, Eq, Hash)]
50pub enum Video {}
51
52#[derive(Debug, PartialEq, Eq, Hash)]
53pub enum Audio {}
54
55#[derive(Debug, PartialEq, Eq, Hash)]
56pub enum Shared {}
57
58#[derive(Debug, PartialEq, Eq, Hash)]
59pub enum Writable {}
60
61/// A video frame. The default shared state allows reads and reference-counted cloning.
62pub type VideoFrame<S = Shared> = MediaFrame<Video, S>;
63pub type AudioFrame<S = Shared> = MediaFrame<Audio, S>;
64
65/// A uniquely owned video frame. Call `freeze` before publishing it.
66pub type VideoFrameMut = VideoFrame<Writable>;
67/// A uniquely owned audio frame. Call `freeze` before publishing it.
68pub type AudioFrameMut = AudioFrame<Writable>;
69
70/// An owned native frame reference. Only the writable state permits mutation.
71#[derive(Debug, PartialEq, Eq, Hash)]
72pub struct MediaFrame<M, S = Shared> {
73    handle: *const ffi::VSFrame,
74    api: Api,
75    marker: PhantomData<fn() -> (M, S)>,
76}
77
78unsafe impl<M, S> Send for MediaFrame<M, S> {}
79
80impl<M, S> MediaFrame<M, S> {
81    fn new(handle: *const ffi::VSFrame, api: Api) -> Self {
82        assert!(!handle.is_null(), "VapourSynth returned a null frame");
83        Self {
84            handle,
85            api,
86            marker: PhantomData,
87        }
88    }
89
90    #[must_use]
91    #[inline]
92    pub fn as_ptr(&self) -> *mut ffi::VSFrame {
93        self.handle.cast_mut()
94    }
95
96    #[cfg(feature = "vs-43")]
97    #[must_use]
98    #[inline]
99    pub fn residency(&self) -> ffi::VSNodeResidency {
100        unsafe { (self.api.getFrameResidency)(self.handle) }
101    }
102
103    #[must_use]
104    #[inline]
105    pub fn properties(&self) -> Option<MapRef<'_>> {
106        unsafe {
107            let ptr = (self.api.getFramePropertiesRO)(self.handle);
108            (!ptr.is_null()).then(|| MapRef::from_ptr(ptr, self.api))
109        }
110    }
111}
112
113impl<M> FrameFromPtr for MediaFrame<M> {
114    type Writable = MediaFrame<M, Writable>;
115
116    unsafe fn from_ptr(ptr: *const ffi::VSFrame, api: Api) -> Self {
117        Self::new(ptr, api)
118    }
119
120    unsafe fn writable_from_ptr(ptr: *mut ffi::VSFrame, api: Api) -> Self::Writable {
121        unsafe { MediaFrame::from_unique_ptr(ptr, api) }
122    }
123}
124
125impl<M> Frame for MediaFrame<M> {
126    #[inline]
127    fn api(&self) -> Api {
128        self.api
129    }
130
131    #[inline]
132    fn as_ptr(&self) -> *mut ffi::VSFrame {
133        self.as_ptr()
134    }
135
136    #[cfg(feature = "vs-43")]
137    fn residency(&self) -> ffi::VSNodeResidency {
138        self.residency()
139    }
140
141    fn properties(&self) -> Option<MapRef<'_>> {
142        self.properties()
143    }
144}
145
146impl<M> MediaFrame<M, Writable> {
147    // The caller transfers the only reference to a newly allocated or copied frame.
148    pub(crate) unsafe fn from_unique_ptr(ptr: *mut ffi::VSFrame, api: Api) -> Self {
149        Self::new(ptr, api)
150    }
151
152    /// Publishes the frame without copying it or changing its reference count.
153    #[must_use]
154    #[inline]
155    pub fn freeze(self) -> MediaFrame<M> {
156        let frame = ManuallyDrop::new(self);
157        MediaFrame {
158            handle: frame.handle,
159            api: frame.api,
160            marker: PhantomData,
161        }
162    }
163
164    #[must_use]
165    #[inline]
166    pub fn properties_mut(&mut self) -> Option<MapMut<'_>> {
167        unsafe {
168            let ptr = (self.api.getFramePropertiesRW)(self.as_ptr());
169            (!ptr.is_null()).then(|| MapMut::from_ptr(ptr, self.api))
170        }
171    }
172}
173
174impl<S> VideoFrame<S> {
175    #[must_use]
176    pub fn stride(&self, plane: i32) -> isize {
177        unsafe { (self.api.getStride)(self.handle, plane) }
178    }
179
180    #[must_use]
181    pub fn plane(&self, plane: i32) -> *const u8 {
182        unsafe { (self.api.getReadPtr)(self.handle, plane) }
183    }
184
185    #[must_use]
186    pub fn get_video_format(&self) -> &VideoFormat {
187        unsafe { &*(self.api.getVideoFrameFormat)(self.handle) }
188    }
189
190    #[must_use]
191    pub fn get_type(&self) -> MediaType {
192        unsafe { (self.api.getFrameType)(self.handle) }
193    }
194
195    #[must_use]
196    pub fn frame_width(&self, plane: i32) -> i32 {
197        unsafe { (self.api.getFrameWidth)(self.handle, plane) }
198    }
199
200    #[must_use]
201    pub fn frame_height(&self, plane: i32) -> i32 {
202        unsafe { (self.api.getFrameHeight)(self.handle, plane) }
203    }
204}
205
206impl VideoFrameMut {
207    #[must_use]
208    pub fn plane_mut(&mut self, plane: i32) -> *mut u8 {
209        unsafe { (self.api.getWritePtr)(self.as_ptr(), plane) }
210    }
211}
212
213impl<S> AudioFrame<S> {
214    #[must_use]
215    pub fn channel(&self, channel: i32) -> *const u8 {
216        unsafe { (self.api.getReadPtr)(self.handle, channel) }
217    }
218
219    #[must_use]
220    pub fn get_audio_format(&self) -> &AudioFormat {
221        unsafe { &*(self.api.getAudioFrameFormat)(self.handle) }
222    }
223
224    #[must_use]
225    pub fn frame_length(&self) -> i32 {
226        unsafe { (self.api.getFrameLength)(self.handle) }
227    }
228}
229
230impl AudioFrameMut {
231    #[must_use]
232    pub fn channel_mut(&mut self, channel: i32) -> *mut u8 {
233        unsafe { (self.api.getWritePtr)(self.as_ptr(), channel) }
234    }
235}
236
237impl<M> Clone for MediaFrame<M> {
238    fn clone(&self) -> Self {
239        unsafe { Self::from_ptr((self.api.addFrameRef)(self.handle), self.api) }
240    }
241}
242
243impl<M, S> Drop for MediaFrame<M, S> {
244    fn drop(&mut self) {
245        unsafe { (self.api.freeFrame)(self.handle) }
246    }
247}
248
249pub type MediaType = ffi::VSMediaType;
250
251#[cfg(all(test, feature = "link-vs"))]
252mod tests {
253    use crate::{
254        ColorFamily, SampleType,
255        core::Core,
256        key,
257        map::{AppendMode, Value},
258    };
259
260    #[test]
261    fn assembling_frames_retains_source_samples() {
262        let core = crate::core::Core::builder().disable_auto_loading().build();
263        let gray = core
264            .query_video_format(
265                crate::ffi::VSColorFamily::Gray,
266                crate::ffi::VSSampleType::Integer,
267                8,
268                0,
269                0,
270            )
271            .unwrap();
272        let mut source = core.new_video_frame(&gray, 16, 16, None);
273        unsafe { source.plane_mut(0).write(42) };
274        let source = source.freeze();
275        let video = unsafe {
276            core.new_video_frame2(&gray, 16, 16, &[source.as_ptr()], &[0], Some(&source))
277        };
278        drop(source);
279        let video = video.freeze();
280        assert_eq!(video.get_video_format().bits_per_sample, 8);
281        assert!(video.stride(0) >= 16);
282        assert_eq!(unsafe { video.plane(0).read() }, 42);
283
284        let stereo = core
285            .query_audio_format(crate::ffi::VSSampleType::Integer, 16, 3)
286            .unwrap();
287        let mut source = core.new_audio_frame(&stereo, 32, None);
288        unsafe {
289            source
290                .channel_mut(0)
291                .copy_from_nonoverlapping(17_i16.to_ne_bytes().as_ptr(), 2);
292            source
293                .channel_mut(1)
294                .copy_from_nonoverlapping(29_i16.to_ne_bytes().as_ptr(), 2);
295        }
296        let source = source.freeze();
297        let audio = unsafe {
298            core.new_audio_frame2(
299                &stereo,
300                32,
301                &[source.as_ptr(), source.as_ptr()],
302                &[1, 0],
303                Some(&source),
304            )
305        };
306        drop(source);
307        let audio = audio.freeze();
308        assert_eq!(audio.get_audio_format().num_channels, 2);
309        assert_eq!(audio.frame_length(), 32);
310        assert_eq!(unsafe { audio.channel(0).read() }, 29_i16.to_ne_bytes()[0]);
311        assert_eq!(unsafe { audio.channel(1).read() }, 17_i16.to_ne_bytes()[0]);
312    }
313
314    #[test]
315    fn freezing_preserves_handle_and_copying_isolates_properties() {
316        let core = Core::builder().build();
317        let format = core
318            .query_video_format(ColorFamily::Gray, SampleType::Integer, 8, 0, 0)
319            .unwrap();
320        let mut original = core.new_video_frame(&format, 16, 16, None);
321        let key = key!(c"test");
322        original
323            .properties_mut()
324            .unwrap()
325            .set(key, Value::Int(1), AppendMode::Replace)
326            .unwrap();
327
328        let ptr = original.as_ptr();
329        let original = original.freeze();
330        assert_eq!(original.as_ptr(), ptr);
331        let alias = original.clone();
332        let mut copy = core.copy_frame(&original);
333        copy.properties_mut()
334            .unwrap()
335            .set(key, Value::Int(2), AppendMode::Replace)
336            .unwrap();
337
338        assert_eq!(alias.properties().unwrap().get_int(key, 0), Ok(1));
339        assert_eq!(copy.freeze().properties().unwrap().get_int(key, 0), Ok(2));
340    }
341}