FFmpeg
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
dynlink_nvcuvid.h
Go to the documentation of this file.
1 /*
2  * This copyright notice applies to this header file only:
3  *
4  * Copyright (c) 2010-2017 NVIDIA Corporation
5  *
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
13  * conditions:
14  *
15  * The above copyright notice and this permission notice shall be
16  * included in all copies or substantial portions of the Software.
17  *
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.
26  */
27 
28 /********************************************************************************************************************/
29 //! \file nvcuvid.h
30 //! NVDECODE API provides video decoding interface to NVIDIA GPU devices.
31 //! \date 2015-2017
32 //! This file contains the interface constants, structure definitions and function prototypes.
33 /********************************************************************************************************************/
34 
35 #if !defined(__NVCUVID_H__)
36 #define __NVCUVID_H__
37 
39 
40 #if defined(__cplusplus)
41 extern "C" {
42 #endif /* __cplusplus */
43 
44 /*********************************
45 ** Initialization
46 *********************************/
47 CUresult CUDAAPI cuvidInit(unsigned int Flags);
48 
49 /***********************************************/
50 //!
51 //! High-level helper APIs for video sources
52 //!
53 /***********************************************/
54 
55 typedef void *CUvideosource;
56 typedef void *CUvideoparser;
57 typedef long long CUvideotimestamp;
58 
59 
60 /************************************************************************/
61 //! \enum cudaVideoState
62 //! Video source state enums
63 //! Used in cuvidSetVideoSourceState and cuvidGetVideoSourceState APIs
64 /************************************************************************/
65 typedef enum {
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 */
70 
71 /************************************************************************/
72 //! \enum cudaAudioCodec
73 //! Audio compression enums
74 //! Used in CUAUDIOFORMAT structure
75 /************************************************************************/
76 typedef enum {
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 */
84 
85 /************************************************************************************************/
86 //! \ingroup STRUCTS
87 //! \struct CUVIDEOFORMAT
88 //! Video format
89 //! Used in cuvidGetSourceVideoFormat API
90 /************************************************************************************************/
91 typedef struct
92 {
93  cudaVideoCodec codec; /**< OUT: Compression format */
94  /**
95  * OUT: frame rate = numerator / denominator (for example: 30000/1001)
96  */
97  struct {
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;
102  } frame_rate;
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 */
109  /**
110  * area of the frame that should be displayed
111  * typical example:
112  * coded_width = 1920, coded_height = 1088
113  * display_area = { 0,0,1920,1080 }
114  */
115  struct {
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 */
120  } display_area;
121  cudaVideoChromaFormat chroma_format; /**< OUT: Chroma format */
122  unsigned int bitrate; /**< OUT: video bitrate (bps, 0=unknown) */
123  /**
124  * OUT: Display Aspect Ratio = x:y (4:3, 16:9, etc)
125  */
126  struct {
127  int x;
128  int y;
129  } display_aspect_ratio;
130  /**
131  * Video Signal Description
132  * Refer section E.2.1 (VUI parameters semantics) of H264 spec file
133  */
134  struct {
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) */
143 } CUVIDEOFORMAT;
144 
145 /****************************************************************/
146 //! \ingroup STRUCTS
147 //! \struct CUVIDEOFORMATEX
148 //! Video format including raw sequence header information
149 //! Used in cuvidGetSourceVideoFormat API
150 /****************************************************************/
151 typedef struct
152 {
153  CUVIDEOFORMAT format; /**< OUT: CUVIDEOFORMAT structure */
154  unsigned char raw_seqhdr_data[1024]; /**< OUT: Sequence header data */
156 
157 /****************************************************************/
158 //! \ingroup STRUCTS
159 //! \struct CUAUDIOFORMAT
160 //! Audio formats
161 //! Used in cuvidGetSourceAudioFormat API
162 /****************************************************************/
163 typedef struct
164 {
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 */
171 } CUAUDIOFORMAT;
172 
173 
174 /***************************************************************/
175 //! \enum CUvideopacketflags
176 //! Data packet flags
177 //! Used in CUVIDSOURCEDATAPACKET structure
178 /***************************************************************/
179 typedef enum {
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 */
185 
186 /*****************************************************************************/
187 //! \ingroup STRUCTS
188 //! \struct CUVIDSOURCEDATAPACKET
189 //! Data Packet
190 //! Used in cuvidParseVideoData API
191 //! IN for cuvidParseVideoData
192 /*****************************************************************************/
193 typedef struct _CUVIDSOURCEDATAPACKET
194 {
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 */
201 
202 // Callback for packet delivery
204 
205 /**************************************************************************************************************************/
206 //! \ingroup STRUCTS
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
213 {
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 */
221 
222 
223 /**********************************************/
224 //! \ingroup ENUMS
225 //! \enum CUvideosourceformat_flags
226 //! CUvideosourceformat_flags
227 //! Used in cuvidGetSourceVideoFormat API
228 /**********************************************/
229 typedef enum {
230  CUVID_FMT_EXTFORMATINFO = 0x100 /**< Return extended format structure (CUVIDEOFORMATEX) */
232 
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);
242 
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);
248 
249 /*********************************************************************/
250 //! \fn CUresult CUDAAPI cuvidDestroyVideoSource(CUvideosource obj)
251 //! Destroy video source
252 /*********************************************************************/
253 typedef CUresult CUDAAPI tcuvidDestroyVideoSource(CUvideosource obj);
254 
255 /******************************************************************************************/
256 //! \fn CUresult CUDAAPI cuvidSetVideoSourceState(CUvideosource obj, cudaVideoState state)
257 //! Set video source state
258 /******************************************************************************************/
260 
261 /******************************************************************************************/
262 //! \fn cudaVideoState CUDAAPI cuvidGetVideoSourceState(CUvideosource obj)
263 //! Get video source state
264 /******************************************************************************************/
266 
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);
272 
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);
280 
281 #endif
282 /**********************************************************************************/
283 //! \ingroup STRUCTS
284 //! \struct CUVIDPARSERDISPINFO
285 //! Used in cuvidParseVideoData API with PFNVIDDISPLAYCALLBACK pfnDisplayPicture
286 /**********************************************************************************/
287 typedef struct _CUVIDPARSERDISPINFO
288 {
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 */
296 
297 /***********************************************************************************************************************/
298 //! Parser callbacks
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 /***********************************************************************************************************************/
305 
306 /**************************************/
307 //! \ingroup STRUCTS
308 //! \struct CUVIDPARSERPARAMS
309 //! Used in cuvidCreateVideoParser API
310 /**************************************/
311 typedef struct _CUVIDPARSERPARAMS
312 {
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 */
328 
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);
334 
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);
342 
343 /*******************************************************************/
344 //! \fn CUresult CUDAAPI cuvidDestroyVideoParser(CUvideoparser obj)
345 /*******************************************************************/
346 typedef CUresult CUDAAPI tcuvidDestroyVideoParser(CUvideoparser obj);
347 
348 /**********************************************************************************************/
349 
350 #if defined(__cplusplus)
351 }
352 #endif /* __cplusplus */
353 
354 #endif // __NVCUVID_H__
355 
356 
int top
OUT: top position of display rect.
tcu_ulong payload_size
IN: number of bytes in the payload (may be zero if EOS flag is set)
unsigned char reserved1
Reserved for future use.
int right
OUT: right position of display rect.
unsigned char bit_depth_chroma_minus8
OUT: high bit depth chroma.
Video format Used in cuvidGetSourceVideoFormat API.
unsigned int reserved2
Reserved for future use.
tcu_ulong flags
IN: Combination of CUVID_PKT_XXX flags.
unsigned int seqhdr_data_length
OUT: Additional bytes following (CUVIDEOFORMATEX)
void * pUserData
IN: User private data passed in to the data handlers.
PFNVIDSOURCECALLBACK pfnAudioDataHandler
IN: Called to deliver audio packets.
unsigned int samplespersec
OUT: sampling frequency.
unsigned int numerator
< OUT: frame rate numerator (0 = unspecified or variable frame rate)
unsigned char color_primaries
OUT: chromaticity coordinates of source primaries.
static struct @281 state
unsigned int bitrate
OUT: For uncompressed, can also be used to determine bits per sample.
CUVIDEOFORMATEX * pExtVideoInfo
IN: [Optional] sequence header data from system layer.
static int flags
Definition: log.c:55
int left
OUT: left position of display rect.
unsigned char transfer_characteristics
OUT: opto-electronic transfer characteristic of the source picture.
Video format including raw sequence header information Used in cuvidGetSourceVideoFormat API...
unsigned char bit_depth_luma_minus8
OUT: high bit depth luma.
Picture parameters for decoding This structure is used in cuvidDecodePicture API IN for cuvidDecodePi...
unsigned int reserved1
Reserved for future use.
Audio formats Used in cuvidGetSourceAudioFormat API.
int bottom
OUT: bottom position of display rect.
unsigned int ulClockRate
IN: Timestamp units in Hz (0=default=10000000Hz)
cudaVideoCodec codec
OUT: Compression format.
unsigned int coded_width
OUT: coded frame width in pixels.
unsigned int denominator
unsigned int ulClockRate
IN: Time stamp units in Hz (0=default=10000000Hz)
unsigned char progressive_sequence
OUT: 0=interlaced, 1=progressive.
unsigned char matrix_coefficients
OUT: used in deriving luma and chroma signals from RGB primaries.
PFNVIDSEQUENCECALLBACK pfnSequenceCallback
IN: Called before decoding frames and/or whenever there is a fmt change.
Used in cuvidParseVideoData API with PFNVIDDISPLAYCALLBACK pfnDisplayPicture.
int picture_index
OUT: Index of the current picture.
PFNVIDSOURCECALLBACK pfnVideoDataHandler
IN: Called to deliver video packets.
const unsigned char * payload
IN: Pointer to packet payload data (may be NULL if EOS flag is set)
CUvideotimestamp timestamp
OUT: Presentation time stamp.
int top_field_first
OUT: 1 if top field is displayed first; 0 otherwise.
unsigned int coded_height
OUT: coded frame height in pixels.
cudaVideoCodec CodecType
IN: cudaVideoCodec_XXX.
CUvideotimestamp timestamp
IN: Presentation time stamp (10MHz clock), only valid if CUVID_PKT_TIMESTAMP flag is set...
unsigned int channels
OUT: number of audio channels.
cudaAudioCodec codec
OUT: Compression format.
int
PFNVIDDECODECALLBACK pfnDecodePicture
IN: Called when a picture is ready to be decoded (decode order)
void * pUserData
IN: User data for callbacks.
CUVIDEOFORMAT format
OUT: CUVIDEOFORMAT structure.
unsigned int ulMaxNumDecodeSurfaces
IN: Max # of decode surfaces (parser will cycle through these)
int progressive_frame
OUT: 1 if progressive frame; 0 otherwise.
unsigned int bitrate
OUT: video bitrate (bps, 0=unknown)
int repeat_first_field
OUT: Number of additional fields (1=ivtc, 2=frame doubling, 4=frame tripling, -1=unpaired field) ...
PFNVIDDISPLAYCALLBACK pfnDisplayPicture
IN: Called whenever a picture is ready to be displayed (display order)
unsigned int ulErrorThreshold
IN: % Error threshold (0-100) for calling pfnDecodePicture (100=always IN: call pfnDecodePicture even...
Data Packet Used in cuvidParseVideoData API IN for cuvidParseVideoData.
unsigned int ulMaxDisplayDelay
IN: Max display queue delay (improves pipelining of decode with display) 0=no delay (recommended valu...
cudaVideoChromaFormat chroma_format
OUT: Chroma format.
Describes parameters needed in cuvidCreateVideoSource API NVDECODE API is intended for HW accelerated...
Used in cuvidCreateVideoParser API.