2 * This copyright notice applies to this header file only:
4 * Copyright (c) 2010-2017 NVIDIA Corporation
6 * Permission is hereby granted, free of charge, to any person
7 * obtaining a copy of this software and associated documentation
8 * files (the "Software"), to deal in the Software without
9 * restriction, including without limitation the rights to use,
10 * copy, modify, merge, publish, distribute, sublicense, and/or sell
11 * copies of the software, and to permit persons to whom the
12 * software is furnished to do so, subject to the following
15 * The above copyright notice and this permission notice shall be
16 * included in all copies or substantial portions of the Software.
18 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
19 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
20 * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
21 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
22 * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
23 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
24 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
25 * OTHER DEALINGS IN THE SOFTWARE.
28 /********************************************************************************************************************/
30 //! NVDECODE API provides video decoding interface to NVIDIA GPU devices.
32 //! This file contains the interface constants, structure definitions and function prototypes.
33 /********************************************************************************************************************/
35 #if !defined(__NVCUVID_H__)
38 #include "compat/cuda/dynlink_cuviddec.h"
40 #if defined(__cplusplus)
42 #endif /* __cplusplus */
44 /*********************************
46 *********************************/
47 CUresult CUDAAPI cuvidInit(unsigned int Flags);
49 /***********************************************/
51 //! High-level helper APIs for video sources
53 /***********************************************/
55 typedef void *CUvideosource;
56 typedef void *CUvideoparser;
57 typedef long long CUvideotimestamp;
60 /************************************************************************/
61 //! \enum cudaVideoState
62 //! Video source state enums
63 //! Used in cuvidSetVideoSourceState and cuvidGetVideoSourceState APIs
64 /************************************************************************/
66 cudaVideoState_Error = -1, /**< Error state (invalid source) */
67 cudaVideoState_Stopped = 0, /**< Source is stopped (or reached end-of-stream) */
68 cudaVideoState_Started = 1 /**< Source is running and delivering data */
71 /************************************************************************/
72 //! \enum cudaAudioCodec
73 //! Audio compression enums
74 //! Used in CUAUDIOFORMAT structure
75 /************************************************************************/
77 cudaAudioCodec_MPEG1=0, /**< MPEG-1 Audio */
78 cudaAudioCodec_MPEG2, /**< MPEG-2 Audio */
79 cudaAudioCodec_MP3, /**< MPEG-1 Layer III Audio */
80 cudaAudioCodec_AC3, /**< Dolby Digital (AC3) Audio */
81 cudaAudioCodec_LPCM, /**< PCM Audio */
82 cudaAudioCodec_AAC, /**< AAC Audio */
85 /************************************************************************************************/
87 //! \struct CUVIDEOFORMAT
89 //! Used in cuvidGetSourceVideoFormat API
90 /************************************************************************************************/
93 cudaVideoCodec codec; /**< OUT: Compression format */
95 * OUT: frame rate = numerator / denominator (for example: 30000/1001)
98 /**< OUT: frame rate numerator (0 = unspecified or variable frame rate) */
99 unsigned int numerator;
100 /**< OUT: frame rate denominator (0 = unspecified or variable frame rate) */
101 unsigned int denominator;
103 unsigned char progressive_sequence; /**< OUT: 0=interlaced, 1=progressive */
104 unsigned char bit_depth_luma_minus8; /**< OUT: high bit depth luma. E.g, 2 for 10-bitdepth, 4 for 12-bitdepth */
105 unsigned char bit_depth_chroma_minus8; /**< OUT: high bit depth chroma. E.g, 2 for 10-bitdepth, 4 for 12-bitdepth */
106 unsigned char reserved1; /**< Reserved for future use */
107 unsigned int coded_width; /**< OUT: coded frame width in pixels */
108 unsigned int coded_height; /**< OUT: coded frame height in pixels */
110 * area of the frame that should be displayed
112 * coded_width = 1920, coded_height = 1088
113 * display_area = { 0,0,1920,1080 }
116 int left; /**< OUT: left position of display rect */
117 int top; /**< OUT: top position of display rect */
118 int right; /**< OUT: right position of display rect */
119 int bottom; /**< OUT: bottom position of display rect */
121 cudaVideoChromaFormat chroma_format; /**< OUT: Chroma format */
122 unsigned int bitrate; /**< OUT: video bitrate (bps, 0=unknown) */
124 * OUT: Display Aspect Ratio = x:y (4:3, 16:9, etc)
129 } display_aspect_ratio;
131 * Video Signal Description
132 * Refer section E.2.1 (VUI parameters semantics) of H264 spec file
135 unsigned char video_format : 3; /**< OUT: 0-Component, 1-PAL, 2-NTSC, 3-SECAM, 4-MAC, 5-Unspecified */
136 unsigned char video_full_range_flag : 1; /**< OUT: indicates the black level and luma and chroma range */
137 unsigned char reserved_zero_bits : 4; /**< Reserved bits */
138 unsigned char color_primaries; /**< OUT: chromaticity coordinates of source primaries */
139 unsigned char transfer_characteristics; /**< OUT: opto-electronic transfer characteristic of the source picture */
140 unsigned char matrix_coefficients; /**< OUT: used in deriving luma and chroma signals from RGB primaries */
141 } video_signal_description;
142 unsigned int seqhdr_data_length; /**< OUT: Additional bytes following (CUVIDEOFORMATEX) */
145 /****************************************************************/
147 //! \struct CUVIDEOFORMATEX
148 //! Video format including raw sequence header information
149 //! Used in cuvidGetSourceVideoFormat API
150 /****************************************************************/
153 CUVIDEOFORMAT format; /**< OUT: CUVIDEOFORMAT structure */
154 unsigned char raw_seqhdr_data[1024]; /**< OUT: Sequence header data */
157 /****************************************************************/
159 //! \struct CUAUDIOFORMAT
161 //! Used in cuvidGetSourceAudioFormat API
162 /****************************************************************/
165 cudaAudioCodec codec; /**< OUT: Compression format */
166 unsigned int channels; /**< OUT: number of audio channels */
167 unsigned int samplespersec; /**< OUT: sampling frequency */
168 unsigned int bitrate; /**< OUT: For uncompressed, can also be used to determine bits per sample */
169 unsigned int reserved1; /**< Reserved for future use */
170 unsigned int reserved2; /**< Reserved for future use */
174 /***************************************************************/
175 //! \enum CUvideopacketflags
176 //! Data packet flags
177 //! Used in CUVIDSOURCEDATAPACKET structure
178 /***************************************************************/
180 CUVID_PKT_ENDOFSTREAM = 0x01, /**< Set when this is the last packet for this stream */
181 CUVID_PKT_TIMESTAMP = 0x02, /**< Timestamp is valid */
182 CUVID_PKT_DISCONTINUITY = 0x04, /**< Set when a discontinuity has to be signalled */
183 CUVID_PKT_ENDOFPICTURE = 0x08, /**< Set when the packet contains exactly one frame */
184 } CUvideopacketflags;
186 /*****************************************************************************/
188 //! \struct CUVIDSOURCEDATAPACKET
190 //! Used in cuvidParseVideoData API
191 //! IN for cuvidParseVideoData
192 /*****************************************************************************/
193 typedef struct _CUVIDSOURCEDATAPACKET
195 tcu_ulong flags; /**< IN: Combination of CUVID_PKT_XXX flags */
196 tcu_ulong payload_size; /**< IN: number of bytes in the payload (may be zero if EOS flag is set) */
197 const unsigned char *payload; /**< IN: Pointer to packet payload data (may be NULL if EOS flag is set) */
198 CUvideotimestamp timestamp; /**< IN: Presentation time stamp (10MHz clock), only valid if
199 CUVID_PKT_TIMESTAMP flag is set */
200 } CUVIDSOURCEDATAPACKET;
202 // Callback for packet delivery
203 typedef int (CUDAAPI *PFNVIDSOURCECALLBACK)(void *, CUVIDSOURCEDATAPACKET *);
205 /**************************************************************************************************************************/
207 //! \struct CUVIDSOURCEPARAMS
208 //! Describes parameters needed in cuvidCreateVideoSource API
209 //! NVDECODE API is intended for HW accelerated video decoding so CUvideosource doesn't have audio demuxer for all supported
210 //! containers. It's recommended to clients to use their own or third party demuxer if audio support is needed.
211 /**************************************************************************************************************************/
212 typedef struct _CUVIDSOURCEPARAMS
214 unsigned int ulClockRate; /**< IN: Time stamp units in Hz (0=default=10000000Hz) */
215 unsigned int uReserved1[7]; /**< Reserved for future use - set to zero */
216 void *pUserData; /**< IN: User private data passed in to the data handlers */
217 PFNVIDSOURCECALLBACK pfnVideoDataHandler; /**< IN: Called to deliver video packets */
218 PFNVIDSOURCECALLBACK pfnAudioDataHandler; /**< IN: Called to deliver audio packets. */
219 void *pvReserved2[8]; /**< Reserved for future use - set to NULL */
223 /**********************************************/
225 //! \enum CUvideosourceformat_flags
226 //! CUvideosourceformat_flags
227 //! Used in cuvidGetSourceVideoFormat API
228 /**********************************************/
230 CUVID_FMT_EXTFORMATINFO = 0x100 /**< Return extended format structure (CUVIDEOFORMATEX) */
231 } CUvideosourceformat_flags;
233 #if !defined(__APPLE__)
234 /**************************************************************************************************************************/
235 //! \fn CUresult CUDAAPI cuvidCreateVideoSource(CUvideosource *pObj, const char *pszFileName, CUVIDSOURCEPARAMS *pParams)
236 //! Create CUvideosource object. CUvideosource spawns demultiplexer thread that provides two callbacks:
237 //! pfnVideoDataHandler() and pfnAudioDataHandler()
238 //! NVDECODE API is intended for HW accelerated video decoding so CUvideosource doesn't have audio demuxer for all supported
239 //! containers. It's recommended to clients to use their own or third party demuxer if audio support is needed.
240 /**************************************************************************************************************************/
241 typedef CUresult CUDAAPI tcuvidCreateVideoSource(CUvideosource *pObj, const char *pszFileName, CUVIDSOURCEPARAMS *pParams);
243 /****************************************************************************************************************************/
244 //! \fn CUresult CUDAAPI cuvidCreateVideoSourceW(CUvideosource *pObj, const wchar_t *pwszFileName, CUVIDSOURCEPARAMS *pParams)
245 //! Create video source object and initialize
246 /****************************************************************************************************************************/
247 typedef CUresult CUDAAPI tcuvidCreateVideoSourceW(CUvideosource *pObj, const wchar_t *pwszFileName, CUVIDSOURCEPARAMS *pParams);
249 /*********************************************************************/
250 //! \fn CUresult CUDAAPI cuvidDestroyVideoSource(CUvideosource obj)
251 //! Destroy video source
252 /*********************************************************************/
253 typedef CUresult CUDAAPI tcuvidDestroyVideoSource(CUvideosource obj);
255 /******************************************************************************************/
256 //! \fn CUresult CUDAAPI cuvidSetVideoSourceState(CUvideosource obj, cudaVideoState state)
257 //! Set video source state
258 /******************************************************************************************/
259 typedef CUresult CUDAAPI tcuvidSetVideoSourceState(CUvideosource obj, cudaVideoState state);
261 /******************************************************************************************/
262 //! \fn cudaVideoState CUDAAPI cuvidGetVideoSourceState(CUvideosource obj)
263 //! Get video source state
264 /******************************************************************************************/
265 typedef cudaVideoState CUDAAPI tcuvidGetVideoSourceState(CUvideosource obj);
267 /****************************************************************************************************************/
268 //! \fn CUresult CUDAAPI cuvidGetSourceVideoFormat(CUvideosource obj, CUVIDEOFORMAT *pvidfmt, unsigned int flags)
269 //! Gets details of video stream in pvidfmt
270 /****************************************************************************************************************/
271 typedef CUresult CUDAAPI tcuvidGetSourceVideoFormat(CUvideosource obj, CUVIDEOFORMAT *pvidfmt, unsigned int flags);
273 /****************************************************************************************************************/
274 //! \fn CUresult CUDAAPI cuvidGetSourceAudioFormat(CUvideosource obj, CUAUDIOFORMAT *paudfmt, unsigned int flags)
275 //! Get audio source format
276 //! NVDECODE API is intended for HW accelarated video decoding so CUvideosource doesn't have audio demuxer for all suppported
277 //! containers. It's recommended to clients to use their own or third party demuxer if audio support is needed.
278 /****************************************************************************************************************/
279 typedef CUresult CUDAAPI tcuvidGetSourceAudioFormat(CUvideosource obj, CUAUDIOFORMAT *paudfmt, unsigned int flags);
282 /**********************************************************************************/
284 //! \struct CUVIDPARSERDISPINFO
285 //! Used in cuvidParseVideoData API with PFNVIDDISPLAYCALLBACK pfnDisplayPicture
286 /**********************************************************************************/
287 typedef struct _CUVIDPARSERDISPINFO
289 int picture_index; /**< OUT: Index of the current picture */
290 int progressive_frame; /**< OUT: 1 if progressive frame; 0 otherwise */
291 int top_field_first; /**< OUT: 1 if top field is displayed first; 0 otherwise */
292 int repeat_first_field; /**< OUT: Number of additional fields (1=ivtc, 2=frame doubling, 4=frame tripling,
293 -1=unpaired field) */
294 CUvideotimestamp timestamp; /**< OUT: Presentation time stamp */
295 } CUVIDPARSERDISPINFO;
297 /***********************************************************************************************************************/
299 //! The parser will call these synchronously from within cuvidParseVideoData(), whenever a picture is ready to
300 //! be decoded and/or displayed. First argument in functions is "void *pUserData" member of structure CUVIDSOURCEPARAMS
301 /***********************************************************************************************************************/
302 typedef int (CUDAAPI *PFNVIDSEQUENCECALLBACK)(void *, CUVIDEOFORMAT *);
303 typedef int (CUDAAPI *PFNVIDDECODECALLBACK)(void *, CUVIDPICPARAMS *);
304 typedef int (CUDAAPI *PFNVIDDISPLAYCALLBACK)(void *, CUVIDPARSERDISPINFO *);
306 /**************************************/
308 //! \struct CUVIDPARSERPARAMS
309 //! Used in cuvidCreateVideoParser API
310 /**************************************/
311 typedef struct _CUVIDPARSERPARAMS
313 cudaVideoCodec CodecType; /**< IN: cudaVideoCodec_XXX */
314 unsigned int ulMaxNumDecodeSurfaces; /**< IN: Max # of decode surfaces (parser will cycle through these) */
315 unsigned int ulClockRate; /**< IN: Timestamp units in Hz (0=default=10000000Hz) */
316 unsigned int ulErrorThreshold; /**< IN: % Error threshold (0-100) for calling pfnDecodePicture (100=always
317 IN: call pfnDecodePicture even if picture bitstream is fully corrupted) */
318 unsigned int ulMaxDisplayDelay; /**< IN: Max display queue delay (improves pipelining of decode with display)
319 0=no delay (recommended values: 2..4) */
320 unsigned int uReserved1[5]; /**< IN: Reserved for future use - set to 0 */
321 void *pUserData; /**< IN: User data for callbacks */
322 PFNVIDSEQUENCECALLBACK pfnSequenceCallback; /**< IN: Called before decoding frames and/or whenever there is a fmt change */
323 PFNVIDDECODECALLBACK pfnDecodePicture; /**< IN: Called when a picture is ready to be decoded (decode order) */
324 PFNVIDDISPLAYCALLBACK pfnDisplayPicture; /**< IN: Called whenever a picture is ready to be displayed (display order) */
325 void *pvReserved2[7]; /**< Reserved for future use - set to NULL */
326 CUVIDEOFORMATEX *pExtVideoInfo; /**< IN: [Optional] sequence header data from system layer */
329 /************************************************************************************************/
330 //! \fn CUresult CUDAAPI cuvidCreateVideoParser(CUvideoparser *pObj, CUVIDPARSERPARAMS *pParams)
331 //! Create video parser object and initialize
332 /************************************************************************************************/
333 typedef CUresult CUDAAPI tcuvidCreateVideoParser(CUvideoparser *pObj, CUVIDPARSERPARAMS *pParams);
335 /************************************************************************************************/
336 //! \fn CUresult CUDAAPI cuvidParseVideoData(CUvideoparser obj, CUVIDSOURCEDATAPACKET *pPacket)
337 //! Parse the video data from source data packet in pPacket
338 //! Extracts parameter sets like SPS, PPS, bitstream etc. from pPacket and
339 //! calls back pfnDecodePicture with CUVIDPICPARAMS data for kicking of HW decoding
340 /************************************************************************************************/
341 typedef CUresult CUDAAPI tcuvidParseVideoData(CUvideoparser obj, CUVIDSOURCEDATAPACKET *pPacket);
343 /*******************************************************************/
344 //! \fn CUresult CUDAAPI cuvidDestroyVideoParser(CUvideoparser obj)
345 /*******************************************************************/
346 typedef CUresult CUDAAPI tcuvidDestroyVideoParser(CUvideoparser obj);
348 /**********************************************************************************************/
350 #if defined(__cplusplus)
352 #endif /* __cplusplus */
354 #endif // __NVCUVID_H__