1use 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 #[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
61pub type VideoFrame<S = Shared> = MediaFrame<Video, S>;
63pub type AudioFrame<S = Shared> = MediaFrame<Audio, S>;
64
65pub type VideoFrameMut = VideoFrame<Writable>;
67pub type AudioFrameMut = AudioFrame<Writable>;
69
70#[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 pub(crate) unsafe fn from_unique_ptr(ptr: *mut ffi::VSFrame, api: Api) -> Self {
149 Self::new(ptr, api)
150 }
151
152 #[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}