Skip to main content

vapoursynth4_rs/
api.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::ops::Deref;
8
9#[cfg(any(feature = "link-vs", feature = "link-vsscript"))]
10use vapoursynth4_sys::vs_make_version;
11
12use crate::ffi;
13
14#[cfg(any(feature = "link-vs", feature = "link-vsscript"))]
15use self::error::ApiNotFound;
16
17#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
18#[repr(transparent)]
19pub struct Api(*const ffi::VSAPI);
20
21impl Api {
22    /// Creates a new `Api` instance with the specified major and minor version.
23    ///
24    /// # Errors
25    ///
26    /// Returns `ApiNotFound` if the requested API version is not supported by the linked `VapourSynth` library.
27    #[cfg(feature = "link-vs")]
28    pub fn new(major: u16, minor: u16) -> Result<Self, ApiNotFound> {
29        let ptr = unsafe { ffi::getVapourSynthAPI(vs_make_version(major, minor)) };
30        if ptr.is_null() {
31            Err(ApiNotFound { major, minor })
32        } else {
33            Ok(Self(ptr))
34        }
35    }
36
37    /// Returns the Vulkan GPU filtering API associated with this core API version.
38    #[cfg(feature = "vulkan")]
39    #[must_use]
40    pub fn vulkan(&self) -> &ffi::VSVULKANAPI {
41        unsafe { &*(self.getVulkanAPI)() }
42    }
43
44    pub(crate) unsafe fn from_ptr(ptr: *const ffi::VSAPI) -> Self {
45        Self(ptr)
46    }
47}
48
49impl Deref for Api {
50    type Target = ffi::VSAPI;
51
52    fn deref(&self) -> &Self::Target {
53        unsafe { &*self.0 }
54    }
55}
56
57#[cfg(feature = "link-vs")]
58impl Default for Api {
59    /// Creates a new `Api` instance with the default version.
60    ///
61    /// # Panics
62    ///
63    /// Internal error indicates that something went wrong with the linked `VapourSynth` library.
64    fn default() -> Self {
65        Self::new(ffi::VAPOURSYNTH_API_MAJOR, ffi::VAPOURSYNTH_API_MINOR).unwrap()
66    }
67}
68
69#[cfg(feature = "vsscript")]
70#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
71#[repr(transparent)]
72pub struct VssApi(*const ffi::VSSCRIPTAPI);
73
74#[cfg(feature = "vsscript")]
75impl VssApi {
76    /// Creates a new `VssApi` instance with the specified major and minor version.
77    ///
78    /// # Errors
79    ///
80    /// Returns `ApiNotFound` if the requested API version is not supported by the linked `VapourSynth` library.
81    #[cfg(feature = "link-vsscript")]
82    pub fn new(major: u16, minor: u16) -> Result<Self, ApiNotFound> {
83        let ptr = unsafe { ffi::getVSScriptAPI(vs_make_version(major, minor)) };
84        (!ptr.is_null())
85            .then_some(Self(ptr))
86            .ok_or(ApiNotFound { major, minor })
87    }
88
89    #[allow(unused)]
90    pub(crate) unsafe fn from_ptr(ptr: *const ffi::VSSCRIPTAPI) -> Self {
91        Self(ptr.cast_mut())
92    }
93
94    /// Detailed message explaining why the most recent [`VssApi::new()`] failed,
95    /// or [`None`] if it succeeded.
96    ///
97    /// [`ApiNotFound`] only reports the version that was asked for; this reports
98    /// what actually went wrong, typically a failure to locate or load Python.
99    ///
100    /// The message is copied out because the library keeps it in a static buffer
101    /// that the next `VssApi::new()` call overwrites.
102    #[cfg(all(feature = "link-vsscript", feature = "vsscript-43"))]
103    #[must_use]
104    pub fn last_error() -> Option<std::ffi::CString> {
105        let ptr = unsafe { ffi::getVSScriptAPILastError() };
106        (!ptr.is_null()).then(|| unsafe { std::ffi::CStr::from_ptr(ptr) }.to_owned())
107    }
108}
109
110#[cfg(feature = "vsscript")]
111impl Deref for VssApi {
112    type Target = ffi::VSSCRIPTAPI;
113
114    fn deref(&self) -> &Self::Target {
115        unsafe { &*self.0 }
116    }
117}
118
119#[cfg(feature = "link-vsscript")]
120impl Default for VssApi {
121    /// Creates a new `Api` instance with the default version.
122    ///
123    /// # Panics
124    ///
125    /// Internal error indicates that something went wrong with the linked `VapourSynth` library.
126    fn default() -> Self {
127        Self::new(ffi::VSSCRIPT_API_MAJOR, ffi::VSSCRIPT_API_MINOR).unwrap()
128    }
129}
130
131pub mod error {
132    use thiserror::Error;
133
134    #[derive(Error, Debug, Clone, Copy, PartialEq, Eq, Hash)]
135    #[error(
136        "Request API with version {major}.{minor} failed. \
137        Please check if the version is supported by the linked VapourSynth library."
138    )]
139    pub struct ApiNotFound {
140        pub major: u16,
141        pub minor: u16,
142    }
143}
144
145#[cfg(all(test, feature = "link-vs"))]
146mod tests {
147    use super::*;
148
149    #[test]
150    fn rejects_unsupported_core_api_versions() {
151        let error = Api::new(99, 0).unwrap_err();
152        assert_eq!(
153            error,
154            ApiNotFound {
155                major: 99,
156                minor: 0
157            }
158        );
159        assert_eq!(
160            Api::new(ffi::VAPOURSYNTH_API_MAJOR, ffi::VAPOURSYNTH_API_MINOR).unwrap(),
161            Api::default()
162        );
163    }
164}