nvidia_video_codec_sdk/safe/
api.rs

1//! Defines `ENCODE_API`, which is a lazy static of [`EncodeAPI`].
2
3use core::ffi::{c_int, c_void};
4
5use crate::sys::nvEncodeAPI::{
6    NvEncodeAPICreateInstance,
7    NvEncodeAPIGetMaxSupportedVersion,
8    GUID,
9    NVENCAPI_MAJOR_VERSION,
10    NVENCAPI_MINOR_VERSION,
11    NVENCSTATUS,
12    NV_ENCODE_API_FUNCTION_LIST,
13    NV_ENCODE_API_FUNCTION_LIST_VER,
14    NV_ENC_BUFFER_FORMAT,
15    NV_ENC_CAPS_PARAM,
16    NV_ENC_CREATE_BITSTREAM_BUFFER,
17    NV_ENC_CREATE_INPUT_BUFFER,
18    NV_ENC_CREATE_MV_BUFFER,
19    NV_ENC_CUSTREAM_PTR,
20    NV_ENC_EVENT_PARAMS,
21    NV_ENC_INITIALIZE_PARAMS,
22    NV_ENC_INPUT_PTR,
23    NV_ENC_LOCK_BITSTREAM,
24    NV_ENC_LOCK_INPUT_BUFFER,
25    NV_ENC_LOOKAHEAD_PIC_PARAMS,
26    NV_ENC_MAP_INPUT_RESOURCE,
27    NV_ENC_MEONLY_PARAMS,
28    NV_ENC_OPEN_ENCODE_SESSION_EX_PARAMS,
29    NV_ENC_OUTPUT_PTR,
30    NV_ENC_PIC_PARAMS,
31    NV_ENC_PRESET_CONFIG,
32    NV_ENC_RECONFIGURE_PARAMS,
33    NV_ENC_REGISTERED_PTR,
34    NV_ENC_REGISTER_RESOURCE,
35    NV_ENC_RESTORE_ENCODER_STATE_PARAMS,
36    NV_ENC_SEQUENCE_PARAM_PAYLOAD,
37    NV_ENC_STAT,
38    NV_ENC_TUNING_INFO,
39};
40
41lazy_static! {
42    /// A lazy static for the Encoder API.
43    ///
44    /// You should not interact with this directly.
45    /// [`Encoder`](crate::Encoder) exposes much of the functionality and provides a nicer API.
46    pub static ref ENCODE_API: EncodeAPI =
47        EncodeAPI::new();
48}
49
50// Function type aliases to shorten later definitions.
51type OpenEncodeSession = unsafe extern "C" fn(*mut c_void, u32, *mut *mut c_void) -> NVENCSTATUS;
52type GetEncodeGUIDCount = unsafe extern "C" fn(*mut c_void, *mut u32) -> NVENCSTATUS;
53type GetEncodeGUIDs = unsafe extern "C" fn(*mut c_void, *mut GUID, u32, *mut u32) -> NVENCSTATUS;
54type GetInputFormatCount = unsafe extern "C" fn(*mut c_void, GUID, *mut u32) -> NVENCSTATUS;
55type GetInputFormats = unsafe extern "C" fn(
56    *mut c_void,
57    GUID,
58    *mut NV_ENC_BUFFER_FORMAT,
59    u32,
60    *mut u32,
61) -> NVENCSTATUS;
62type GetEncodeCaps =
63    unsafe extern "C" fn(*mut c_void, GUID, *mut NV_ENC_CAPS_PARAM, *mut c_int) -> NVENCSTATUS;
64type GetEncodePresetCount = unsafe extern "C" fn(*mut c_void, GUID, *mut u32) -> NVENCSTATUS;
65type GetEncodePresetGUIDs =
66    unsafe extern "C" fn(*mut c_void, GUID, *mut GUID, u32, *mut u32) -> NVENCSTATUS;
67type GetEncodeProfileGUIDCount = GetEncodePresetCount;
68type GetEncodeProfileGUIDs = GetEncodePresetGUIDs;
69type GetEncodePresetConfig =
70    unsafe extern "C" fn(*mut c_void, GUID, GUID, *mut NV_ENC_PRESET_CONFIG) -> NVENCSTATUS;
71type GetEncodePresetConfigEx = unsafe extern "C" fn(
72    *mut c_void,
73    GUID,
74    GUID,
75    NV_ENC_TUNING_INFO,
76    *mut NV_ENC_PRESET_CONFIG,
77) -> NVENCSTATUS;
78type InitializeEncoder =
79    unsafe extern "C" fn(*mut c_void, *mut NV_ENC_INITIALIZE_PARAMS) -> NVENCSTATUS;
80type CreateInputBuffer =
81    unsafe extern "C" fn(*mut c_void, *mut NV_ENC_CREATE_INPUT_BUFFER) -> NVENCSTATUS;
82type DestroyInputBuffer = unsafe extern "C" fn(*mut c_void, NV_ENC_INPUT_PTR) -> NVENCSTATUS;
83type CreateBitstreamBuffer =
84    unsafe extern "C" fn(*mut c_void, *mut NV_ENC_CREATE_BITSTREAM_BUFFER) -> NVENCSTATUS;
85type DestroyBitstreamBuffer = unsafe extern "C" fn(*mut c_void, NV_ENC_OUTPUT_PTR) -> NVENCSTATUS;
86type EncodePicture = unsafe extern "C" fn(*mut c_void, *mut NV_ENC_PIC_PARAMS) -> NVENCSTATUS;
87type LockBitstream = unsafe extern "C" fn(*mut c_void, *mut NV_ENC_LOCK_BITSTREAM) -> NVENCSTATUS;
88type UnlockBitstream = unsafe extern "C" fn(*mut c_void, NV_ENC_OUTPUT_PTR) -> NVENCSTATUS;
89type LockInputBuffer =
90    unsafe extern "C" fn(*mut c_void, *mut NV_ENC_LOCK_INPUT_BUFFER) -> NVENCSTATUS;
91type UnlockInputBuffer = unsafe extern "C" fn(*mut c_void, NV_ENC_INPUT_PTR) -> NVENCSTATUS;
92type GetEncodeStats = unsafe extern "C" fn(*mut c_void, *mut NV_ENC_STAT) -> NVENCSTATUS;
93type GetSequenceParams =
94    unsafe extern "C" fn(*mut c_void, *mut NV_ENC_SEQUENCE_PARAM_PAYLOAD) -> NVENCSTATUS;
95type RegisterAsyncEvent =
96    unsafe extern "C" fn(*mut c_void, *mut NV_ENC_EVENT_PARAMS) -> NVENCSTATUS;
97type UnregisterAsyncEvent =
98    unsafe extern "C" fn(*mut c_void, *mut NV_ENC_EVENT_PARAMS) -> NVENCSTATUS;
99type MapInputResource =
100    unsafe extern "C" fn(*mut c_void, *mut NV_ENC_MAP_INPUT_RESOURCE) -> NVENCSTATUS;
101type UnmapInputResource = unsafe extern "C" fn(*mut c_void, NV_ENC_INPUT_PTR) -> NVENCSTATUS;
102type DestroyEncoder = unsafe extern "C" fn(encoder: *mut c_void) -> NVENCSTATUS;
103type InvalidateRefFrames = unsafe extern "C" fn(*mut c_void, u64) -> NVENCSTATUS;
104type OpenEncodeSessionEx = unsafe extern "C" fn(
105    *mut NV_ENC_OPEN_ENCODE_SESSION_EX_PARAMS,
106    *mut *mut c_void,
107) -> NVENCSTATUS;
108type RegisterResource =
109    unsafe extern "C" fn(*mut c_void, *mut NV_ENC_REGISTER_RESOURCE) -> NVENCSTATUS;
110type UnregisterResource = unsafe extern "C" fn(*mut c_void, NV_ENC_REGISTERED_PTR) -> NVENCSTATUS;
111type ReconfigureEncoder =
112    unsafe extern "C" fn(*mut c_void, *mut NV_ENC_RECONFIGURE_PARAMS) -> NVENCSTATUS;
113type CreateMVBuffer =
114    unsafe extern "C" fn(*mut c_void, *mut NV_ENC_CREATE_MV_BUFFER) -> NVENCSTATUS;
115type DestroyMVBuffer = unsafe extern "C" fn(*mut c_void, NV_ENC_OUTPUT_PTR) -> NVENCSTATUS;
116type RunMotionEstimationOnly =
117    unsafe extern "C" fn(*mut c_void, *mut NV_ENC_MEONLY_PARAMS) -> NVENCSTATUS;
118type GetLastErrorString = unsafe extern "C" fn(encoder: *mut c_void) -> *const ::core::ffi::c_char;
119type SetIOCudaStreams =
120    unsafe extern "C" fn(*mut c_void, NV_ENC_CUSTREAM_PTR, NV_ENC_CUSTREAM_PTR) -> NVENCSTATUS;
121type GetSequenceParamEx = unsafe extern "C" fn(
122    *mut c_void,
123    *mut NV_ENC_INITIALIZE_PARAMS,
124    *mut NV_ENC_SEQUENCE_PARAM_PAYLOAD,
125) -> NVENCSTATUS;
126type RestoreEncoderState =
127    unsafe extern "C" fn(*mut c_void, *mut NV_ENC_RESTORE_ENCODER_STATE_PARAMS) -> NVENCSTATUS;
128type LookaheadPicture =
129    unsafe extern "C" fn(*mut c_void, *mut NV_ENC_LOOKAHEAD_PIC_PARAMS) -> NVENCSTATUS;
130
131/// An instance of the `NvEncodeAPI` interface, containing function pointers
132/// which should be used to interface with the rest of the Encoder API.
133#[allow(dead_code, missing_docs)]
134#[derive(Debug, Clone)]
135pub struct EncodeAPI {
136    #[doc(alias = "NvEncOpenEncodeSession")]
137    pub open_encode_session: OpenEncodeSession,
138    #[doc(alias = "NvEncOpenEncodeSessionEx")]
139    pub open_encode_session_ex: OpenEncodeSessionEx,
140    #[doc(alias = "NvEncInitializeEncoder")]
141    pub initialize_encoder: InitializeEncoder,
142    #[doc(alias = "NvEncReconfigureEncoder")]
143    pub reconfigure_encoder: ReconfigureEncoder,
144    #[doc(alias = "NvEncDestroyEncoder")]
145    pub destroy_encoder: DestroyEncoder,
146    #[doc(alias = "NvEncGetEncodeGuidCount")]
147    pub get_encode_guid_count: GetEncodeGUIDCount,
148    #[doc(alias = "NvEncGetEncodeGUIDs")]
149    pub get_encode_guids: GetEncodeGUIDs,
150    #[doc(alias = "NvEncGetEncodeProfileGuidCount")]
151    pub get_encode_profile_guid_count: GetEncodeProfileGUIDCount,
152    #[doc(alias = "NvEncGetEncodeProfileGUIDs")]
153    pub get_encode_profile_guids: GetEncodeProfileGUIDs,
154    #[doc(alias = "NvEncGetInputFormatCount")]
155    pub get_input_format_count: GetInputFormatCount,
156    #[doc(alias = "NvEncGetInputFormats")]
157    pub get_input_formats: GetInputFormats,
158    #[doc(alias = "NvEncGetEncodePresetCount")]
159    pub get_encode_preset_count: GetEncodePresetCount,
160    #[doc(alias = "NvEncGetEncodePresetGUIDs")]
161    pub get_encode_preset_guids: GetEncodePresetGUIDs,
162    #[doc(alias = "NvEncGetEncodePresetConfig")]
163    pub get_encode_preset_config: GetEncodePresetConfig,
164    #[doc(alias = "NvEncGetEncodePresetConfigEx")]
165    pub get_encode_preset_config_ex: GetEncodePresetConfigEx,
166    #[doc(alias = "NvEncGetEncodeCaps")]
167    pub get_encode_caps: GetEncodeCaps,
168    #[doc(alias = "NvEncCreateInputBuffer")]
169    pub create_input_buffer: CreateInputBuffer,
170    #[doc(alias = "NvEncDestroyInputBuffer")]
171    pub destroy_input_buffer: DestroyInputBuffer,
172    #[doc(alias = "NvLockInputBuffer")]
173    pub lock_input_buffer: LockInputBuffer,
174    #[doc(alias = "NvUnlockInputBuffer")]
175    pub unlock_input_buffer: UnlockInputBuffer,
176    #[doc(alias = "NvEncCreateBitstreamBuffer")]
177    pub create_bitstream_buffer: CreateBitstreamBuffer,
178    #[doc(alias = "NvEncDestroyBitstreamBuffer")]
179    pub destroy_bitstream_buffer: DestroyBitstreamBuffer,
180    #[doc(alias = "NvEncLockBitstream")]
181    pub lock_bitstream: LockBitstream,
182    #[doc(alias = "NvEncUnlockBitstream")]
183    pub unlock_bitstream: UnlockBitstream,
184    #[doc(alias = "NvEncMapInputResource")]
185    pub map_input_resource: MapInputResource,
186    #[doc(alias = "NvEncUnmapInputResource")]
187    pub unmap_input_resource: UnmapInputResource,
188    #[doc(alias = "NvEncRegisterResource")]
189    pub register_resource: RegisterResource,
190    #[doc(alias = "NvEncUnregisterResource")]
191    pub unregister_resource: UnregisterResource,
192    #[doc(alias = "NvEncCreateMVBuffer")]
193    pub create_mv_buffer: CreateMVBuffer,
194    #[doc(alias = "NvEncDestroyMVBuffer")]
195    pub destroy_mv_buffer: DestroyMVBuffer,
196    #[doc(alias = "NvEncEncodePicture")]
197    pub encode_picture: EncodePicture,
198    #[doc(alias = "NvEncGetEncodeStats")]
199    pub get_encode_stats: GetEncodeStats,
200    #[doc(alias = "NvEncGetSequenceParams")]
201    pub get_sequence_params: GetSequenceParams,
202    #[doc(alias = "NvEncGetSequenceParamEx")]
203    pub get_sequence_param_ex: GetSequenceParamEx,
204    #[doc(alias = "NvEncRegisterAsyncEvent")]
205    pub register_async_event: RegisterAsyncEvent,
206    #[doc(alias = "NvEncUnregisterAsyncEvent")]
207    pub unregister_async_event: UnregisterAsyncEvent,
208    #[doc(alias = "NvEncInvalidateRefFrames")]
209    pub invalidate_ref_frames: InvalidateRefFrames,
210    #[doc(alias = "NvEncRunMotionEstimationOnly")]
211    pub run_motion_estimation_only: RunMotionEstimationOnly,
212    #[doc(alias = "NvEncGetLastErrorString")]
213    pub get_last_error_string: GetLastErrorString,
214    #[doc(alias = "NvEncSetIOCudaStreams")]
215    pub set_io_cuda_streams: SetIOCudaStreams,
216    #[doc(alias = "NvEncRestoreEncoderState")]
217    pub restore_encoder_state: RestoreEncoderState,
218    #[doc(alias = "NvEncLookaheadPicture")]
219    pub lookahead_picture: LookaheadPicture,
220}
221
222fn assert_versions_match(max_supported_version: u32) {
223    let major_version = max_supported_version >> 4;
224    let minor_version = max_supported_version & 0b1111;
225    assert!(
226        (major_version, minor_version) >= (NVENCAPI_MAJOR_VERSION, NVENCAPI_MINOR_VERSION),
227        "The maximum supported version should be greater or equal than the header version."
228    );
229}
230
231impl EncodeAPI {
232    fn new() -> Self {
233        const MSG: &str = "The API instance should populate the whole function list.";
234
235        // Check that the driver max supported version matches the version
236        // from the header files. If they do not match, the bindings should be updated.
237        let mut version = 0;
238        unsafe { NvEncodeAPIGetMaxSupportedVersion(&mut version) }
239            .result_without_string()
240            .expect("The pointer to the version should be valid.");
241        assert_versions_match(version);
242
243        // Create empty function buffer.
244        let mut function_list = NV_ENCODE_API_FUNCTION_LIST {
245            version: NV_ENCODE_API_FUNCTION_LIST_VER,
246            ..Default::default()
247        };
248        // Create Encode API Instance (populate function buffer).
249        unsafe { NvEncodeAPICreateInstance(&mut function_list) }
250            .result_without_string()
251            .expect("The pointer to the function list should be valid.");
252
253        Self {
254            open_encode_session: function_list.nvEncOpenEncodeSession.expect(MSG),
255            open_encode_session_ex: function_list.nvEncOpenEncodeSessionEx.expect(MSG),
256            initialize_encoder: function_list.nvEncInitializeEncoder.expect(MSG),
257            reconfigure_encoder: function_list.nvEncReconfigureEncoder.expect(MSG),
258            destroy_encoder: function_list.nvEncDestroyEncoder.expect(MSG),
259            get_encode_guid_count: function_list.nvEncGetEncodeGUIDCount.expect(MSG),
260            get_encode_guids: function_list.nvEncGetEncodeGUIDs.expect(MSG),
261            get_encode_profile_guid_count: function_list.nvEncGetEncodeProfileGUIDCount.expect(MSG),
262            get_encode_profile_guids: function_list.nvEncGetEncodeProfileGUIDs.expect(MSG),
263            get_input_format_count: function_list.nvEncGetInputFormatCount.expect(MSG),
264            get_input_formats: function_list.nvEncGetInputFormats.expect(MSG),
265            get_encode_preset_count: function_list.nvEncGetEncodePresetCount.expect(MSG),
266            get_encode_preset_guids: function_list.nvEncGetEncodePresetGUIDs.expect(MSG),
267            get_encode_preset_config: function_list.nvEncGetEncodePresetConfig.expect(MSG),
268            get_encode_preset_config_ex: function_list.nvEncGetEncodePresetConfigEx.expect(MSG),
269            get_encode_caps: function_list.nvEncGetEncodeCaps.expect(MSG),
270            create_input_buffer: function_list.nvEncCreateInputBuffer.expect(MSG),
271            destroy_input_buffer: function_list.nvEncDestroyInputBuffer.expect(MSG),
272            lock_input_buffer: function_list.nvEncLockInputBuffer.expect(MSG),
273            unlock_input_buffer: function_list.nvEncUnlockInputBuffer.expect(MSG),
274            create_bitstream_buffer: function_list.nvEncCreateBitstreamBuffer.expect(MSG),
275            destroy_bitstream_buffer: function_list.nvEncDestroyBitstreamBuffer.expect(MSG),
276            lock_bitstream: function_list.nvEncLockBitstream.expect(MSG),
277            unlock_bitstream: function_list.nvEncUnlockBitstream.expect(MSG),
278            map_input_resource: function_list.nvEncMapInputResource.expect(MSG),
279            unmap_input_resource: function_list.nvEncUnmapInputResource.expect(MSG),
280            register_resource: function_list.nvEncRegisterResource.expect(MSG),
281            unregister_resource: function_list.nvEncUnregisterResource.expect(MSG),
282            create_mv_buffer: function_list.nvEncCreateMVBuffer.expect(MSG),
283            destroy_mv_buffer: function_list.nvEncDestroyMVBuffer.expect(MSG),
284            encode_picture: function_list.nvEncEncodePicture.expect(MSG),
285            get_encode_stats: function_list.nvEncGetEncodeStats.expect(MSG),
286            get_sequence_params: function_list.nvEncGetSequenceParams.expect(MSG),
287            get_sequence_param_ex: function_list.nvEncGetSequenceParamEx.expect(MSG),
288            register_async_event: function_list.nvEncRegisterAsyncEvent.expect(MSG),
289            unregister_async_event: function_list.nvEncUnregisterAsyncEvent.expect(MSG),
290            invalidate_ref_frames: function_list.nvEncInvalidateRefFrames.expect(MSG),
291            run_motion_estimation_only: function_list.nvEncRunMotionEstimationOnly.expect(MSG),
292            get_last_error_string: function_list.nvEncGetLastErrorString.expect(MSG),
293            set_io_cuda_streams: function_list.nvEncSetIOCudaStreams.expect(MSG),
294            restore_encoder_state: function_list.nvEncRestoreEncoderState.expect(MSG),
295            lookahead_picture: function_list.nvEncLookaheadPicture.expect(MSG),
296        }
297    }
298}