1 /* 2 * This copyright notice applies to this header file only: 3 * 4 * Copyright (c) 2010-2019 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-2019 32 //! This file contains the interface constants, structure definitions and function prototypes. 33 /********************************************************************************************************************/ 34 35 #if !defined(__NVCUVID_H__) 36 #define __NVCUVID_H__ 37 38 #include "cuviddec.h" 39 40 #if defined(__cplusplus) 41 extern "C" { 42 #endif /* __cplusplus */ 43 44 45 /***********************************************/ 46 //! 47 //! High-level helper APIs for video sources 48 //! 49 /***********************************************/ 50 51 typedef void *CUvideosource; 52 typedef void *CUvideoparser; 53 typedef long long CUvideotimestamp; 54 55 56 /************************************************************************/ 57 //! \enum cudaVideoState 58 //! Video source state enums 59 //! Used in cuvidSetVideoSourceState and cuvidGetVideoSourceState APIs 60 /************************************************************************/ 61 typedef enum { 62 cudaVideoState_Error = -1, /**< Error state (invalid source) */ 63 cudaVideoState_Stopped = 0, /**< Source is stopped (or reached end-of-stream) */ 64 cudaVideoState_Started = 1 /**< Source is running and delivering data */ 65 } cudaVideoState; 66 67 /************************************************************************/ 68 //! \enum cudaAudioCodec 69 //! Audio compression enums 70 //! Used in CUAUDIOFORMAT structure 71 /************************************************************************/ 72 typedef enum { 73 cudaAudioCodec_MPEG1=0, /**< MPEG-1 Audio */ 74 cudaAudioCodec_MPEG2, /**< MPEG-2 Audio */ 75 cudaAudioCodec_MP3, /**< MPEG-1 Layer III Audio */ 76 cudaAudioCodec_AC3, /**< Dolby Digital (AC3) Audio */ 77 cudaAudioCodec_LPCM, /**< PCM Audio */ 78 cudaAudioCodec_AAC, /**< AAC Audio */ 79 } cudaAudioCodec; 80 81 /************************************************************************************************/ 82 //! \ingroup STRUCTS 83 //! \struct CUVIDEOFORMAT 84 //! Video format 85 //! Used in cuvidGetSourceVideoFormat API 86 /************************************************************************************************/ 87 typedef struct 88 { 89 cudaVideoCodec codec; /**< OUT: Compression format */ 90 /** 91 * OUT: frame rate = numerator / denominator (for example: 30000/1001) 92 */ 93 struct { 94 /**< OUT: frame rate numerator (0 = unspecified or variable frame rate) */ 95 unsigned int numerator; 96 /**< OUT: frame rate denominator (0 = unspecified or variable frame rate) */ 97 unsigned int denominator; 98 } frame_rate; 99 unsigned char progressive_sequence; /**< OUT: 0=interlaced, 1=progressive */ 100 unsigned char bit_depth_luma_minus8; /**< OUT: high bit depth luma. E.g, 2 for 10-bitdepth, 4 for 12-bitdepth */ 101 unsigned char bit_depth_chroma_minus8; /**< OUT: high bit depth chroma. E.g, 2 for 10-bitdepth, 4 for 12-bitdepth */ 102 unsigned char min_num_decode_surfaces; /**< OUT: Minimum number of decode surfaces to be allocated for correct 103 decoding. The client can send this value in ulNumDecodeSurfaces 104 (in CUVIDDECODECREATEINFO structure). 105 This guarantees correct functionality and optimal video memory 106 usage but not necessarily the best performance, which depends on 107 the design of the overall application. The optimal number of 108 decode surfaces (in terms of performance and memory utilization) 109 should be decided by experimentation for each application, but it 110 cannot go below min_num_decode_surfaces. 111 If this value is used for ulNumDecodeSurfaces then it must be 112 returned to parser during sequence callback. */ 113 unsigned int coded_width; /**< OUT: coded frame width in pixels */ 114 unsigned int coded_height; /**< OUT: coded frame height in pixels */ 115 /** 116 * area of the frame that should be displayed 117 * typical example: 118 * coded_width = 1920, coded_height = 1088 119 * display_area = { 0,0,1920,1080 } 120 */ 121 struct { 122 int left; /**< OUT: left position of display rect */ 123 int top; /**< OUT: top position of display rect */ 124 int right; /**< OUT: right position of display rect */ 125 int bottom; /**< OUT: bottom position of display rect */ 126 } display_area; 127 cudaVideoChromaFormat chroma_format; /**< OUT: Chroma format */ 128 unsigned int bitrate; /**< OUT: video bitrate (bps, 0=unknown) */ 129 /** 130 * OUT: Display Aspect Ratio = x:y (4:3, 16:9, etc) 131 */ 132 struct { 133 int x; 134 int y; 135 } display_aspect_ratio; 136 /** 137 * Video Signal Description 138 * Refer section E.2.1 (VUI parameters semantics) of H264 spec file 139 */ 140 struct { 141 unsigned char video_format : 3; /**< OUT: 0-Component, 1-PAL, 2-NTSC, 3-SECAM, 4-MAC, 5-Unspecified */ 142 unsigned char video_full_range_flag : 1; /**< OUT: indicates the black level and luma and chroma range */ 143 unsigned char reserved_zero_bits : 4; /**< Reserved bits */ 144 unsigned char color_primaries; /**< OUT: chromaticity coordinates of source primaries */ 145 unsigned char transfer_characteristics; /**< OUT: opto-electronic transfer characteristic of the source picture */ 146 unsigned char matrix_coefficients; /**< OUT: used in deriving luma and chroma signals from RGB primaries */ 147 } video_signal_description; 148 unsigned int seqhdr_data_length; /**< OUT: Additional bytes following (CUVIDEOFORMATEX) */ 149 } CUVIDEOFORMAT; 150 151 /****************************************************************/ 152 //! \ingroup STRUCTS 153 //! \struct CUVIDEOFORMATEX 154 //! Video format including raw sequence header information 155 //! Used in cuvidGetSourceVideoFormat API 156 /****************************************************************/ 157 typedef struct 158 { 159 CUVIDEOFORMAT format; /**< OUT: CUVIDEOFORMAT structure */ 160 unsigned char raw_seqhdr_data[1024]; /**< OUT: Sequence header data */ 161 } CUVIDEOFORMATEX; 162 163 /****************************************************************/ 164 //! \ingroup STRUCTS 165 //! \struct CUAUDIOFORMAT 166 //! Audio formats 167 //! Used in cuvidGetSourceAudioFormat API 168 /****************************************************************/ 169 typedef struct 170 { 171 cudaAudioCodec codec; /**< OUT: Compression format */ 172 unsigned int channels; /**< OUT: number of audio channels */ 173 unsigned int samplespersec; /**< OUT: sampling frequency */ 174 unsigned int bitrate; /**< OUT: For uncompressed, can also be used to determine bits per sample */ 175 unsigned int reserved1; /**< Reserved for future use */ 176 unsigned int reserved2; /**< Reserved for future use */ 177 } CUAUDIOFORMAT; 178 179 180 /***************************************************************/ 181 //! \enum CUvideopacketflags 182 //! Data packet flags 183 //! Used in CUVIDSOURCEDATAPACKET structure 184 /***************************************************************/ 185 typedef enum { 186 CUVID_PKT_ENDOFSTREAM = 0x01, /**< Set when this is the last packet for this stream */ 187 CUVID_PKT_TIMESTAMP = 0x02, /**< Timestamp is valid */ 188 CUVID_PKT_DISCONTINUITY = 0x04, /**< Set when a discontinuity has to be signalled */ 189 CUVID_PKT_ENDOFPICTURE = 0x08, /**< Set when the packet contains exactly one frame or one field */ 190 CUVID_PKT_NOTIFY_EOS = 0x10, /**< If this flag is set along with CUVID_PKT_ENDOFSTREAM, an additional (dummy) 191 display callback will be invoked with null value of CUVIDPARSERDISPINFO which 192 should be interpreted as end of the stream. */ 193 } CUvideopacketflags; 194 195 /*****************************************************************************/ 196 //! \ingroup STRUCTS 197 //! \struct CUVIDSOURCEDATAPACKET 198 //! Data Packet 199 //! Used in cuvidParseVideoData API 200 //! IN for cuvidParseVideoData 201 /*****************************************************************************/ 202 typedef struct _CUVIDSOURCEDATAPACKET 203 { 204 unsigned long flags; /**< IN: Combination of CUVID_PKT_XXX flags */ 205 unsigned long payload_size; /**< IN: number of bytes in the payload (may be zero if EOS flag is set) */ 206 const unsigned char *payload; /**< IN: Pointer to packet payload data (may be NULL if EOS flag is set) */ 207 CUvideotimestamp timestamp; /**< IN: Presentation time stamp (10MHz clock), only valid if 208 CUVID_PKT_TIMESTAMP flag is set */ 209 } CUVIDSOURCEDATAPACKET; 210 211 // Callback for packet delivery 212 typedef int (CUDAAPI *PFNVIDSOURCECALLBACK)(void *, CUVIDSOURCEDATAPACKET *); 213 214 /**************************************************************************************************************************/ 215 //! \ingroup STRUCTS 216 //! \struct CUVIDSOURCEPARAMS 217 //! Describes parameters needed in cuvidCreateVideoSource API 218 //! NVDECODE API is intended for HW accelerated video decoding so CUvideosource doesn't have audio demuxer for all supported 219 //! containers. It's recommended to clients to use their own or third party demuxer if audio support is needed. 220 /**************************************************************************************************************************/ 221 typedef struct _CUVIDSOURCEPARAMS 222 { 223 unsigned int ulClockRate; /**< IN: Time stamp units in Hz (0=default=10000000Hz) */ 224 unsigned int uReserved1[7]; /**< Reserved for future use - set to zero */ 225 void *pUserData; /**< IN: User private data passed in to the data handlers */ 226 PFNVIDSOURCECALLBACK pfnVideoDataHandler; /**< IN: Called to deliver video packets */ 227 PFNVIDSOURCECALLBACK pfnAudioDataHandler; /**< IN: Called to deliver audio packets. */ 228 void *pvReserved2[8]; /**< Reserved for future use - set to NULL */ 229 } CUVIDSOURCEPARAMS; 230 231 232 /**********************************************/ 233 //! \ingroup ENUMS 234 //! \enum CUvideosourceformat_flags 235 //! CUvideosourceformat_flags 236 //! Used in cuvidGetSourceVideoFormat API 237 /**********************************************/ 238 typedef enum { 239 CUVID_FMT_EXTFORMATINFO = 0x100 /**< Return extended format structure (CUVIDEOFORMATEX) */ 240 } CUvideosourceformat_flags; 241 242 #if !defined(__APPLE__) 243 /***************************************************************************************************************************/ 244 //! \ingroup FUNCTS 245 //! \fn CUresult CUDAAPI cuvidCreateVideoSource(CUvideosource *pObj, const char *pszFileName, CUVIDSOURCEPARAMS *pParams) 246 //! Create CUvideosource object. CUvideosource spawns demultiplexer thread that provides two callbacks: 247 //! pfnVideoDataHandler() and pfnAudioDataHandler() 248 //! NVDECODE API is intended for HW accelerated video decoding so CUvideosource doesn't have audio demuxer for all supported 249 //! containers. It's recommended to clients to use their own or third party demuxer if audio support is needed. 250 /***************************************************************************************************************************/ 251 CUresult CUDAAPI cuvidCreateVideoSource(CUvideosource *pObj, const char *pszFileName, CUVIDSOURCEPARAMS *pParams); 252 253 /***************************************************************************************************************************/ 254 //! \ingroup FUNCTS 255 //! \fn CUresult CUDAAPI cuvidCreateVideoSourceW(CUvideosource *pObj, const wchar_t *pwszFileName, CUVIDSOURCEPARAMS *pParams) 256 //! Create video source 257 /***************************************************************************************************************************/ 258 CUresult CUDAAPI cuvidCreateVideoSourceW(CUvideosource *pObj, const wchar_t *pwszFileName, CUVIDSOURCEPARAMS *pParams); 259 260 /********************************************************************/ 261 //! \ingroup FUNCTS 262 //! \fn CUresult CUDAAPI cuvidDestroyVideoSource(CUvideosource obj) 263 //! Destroy video source 264 /********************************************************************/ 265 CUresult CUDAAPI cuvidDestroyVideoSource(CUvideosource obj); 266 267 /******************************************************************************************/ 268 //! \ingroup FUNCTS 269 //! \fn CUresult CUDAAPI cuvidSetVideoSourceState(CUvideosource obj, cudaVideoState state) 270 //! Set video source state to: 271 //! cudaVideoState_Started - to signal the source to run and deliver data 272 //! cudaVideoState_Stopped - to stop the source from delivering the data 273 //! cudaVideoState_Error - invalid source 274 /******************************************************************************************/ 275 CUresult CUDAAPI cuvidSetVideoSourceState(CUvideosource obj, cudaVideoState state); 276 277 /******************************************************************************************/ 278 //! \ingroup FUNCTS 279 //! \fn cudaVideoState CUDAAPI cuvidGetVideoSourceState(CUvideosource obj) 280 //! Get video source state 281 //! Returns: 282 //! cudaVideoState_Started - if Source is running and delivering data 283 //! cudaVideoState_Stopped - if Source is stopped or reached end-of-stream 284 //! cudaVideoState_Error - if Source is in error state 285 /******************************************************************************************/ 286 cudaVideoState CUDAAPI cuvidGetVideoSourceState(CUvideosource obj); 287 288 /******************************************************************************************************************/ 289 //! \ingroup FUNCTS 290 //! \fn CUresult CUDAAPI cuvidGetSourceVideoFormat(CUvideosource obj, CUVIDEOFORMAT *pvidfmt, unsigned int flags) 291 //! Gets video source format in pvidfmt, flags is set to combination of CUvideosourceformat_flags as per requirement 292 /******************************************************************************************************************/ 293 CUresult CUDAAPI cuvidGetSourceVideoFormat(CUvideosource obj, CUVIDEOFORMAT *pvidfmt, unsigned int flags); 294 295 /**************************************************************************************************************************/ 296 //! \ingroup FUNCTS 297 //! \fn CUresult CUDAAPI cuvidGetSourceAudioFormat(CUvideosource obj, CUAUDIOFORMAT *paudfmt, unsigned int flags) 298 //! Get audio source format 299 //! NVDECODE API is intended for HW accelerated video decoding so CUvideosource doesn't have audio demuxer for all supported 300 //! containers. It's recommended to clients to use their own or third party demuxer if audio support is needed. 301 /**************************************************************************************************************************/ 302 CUresult CUDAAPI cuvidGetSourceAudioFormat(CUvideosource obj, CUAUDIOFORMAT *paudfmt, unsigned int flags); 303 304 #endif 305 /**********************************************************************************/ 306 //! \ingroup STRUCTS 307 //! \struct CUVIDPARSERDISPINFO 308 //! Used in cuvidParseVideoData API with PFNVIDDISPLAYCALLBACK pfnDisplayPicture 309 /**********************************************************************************/ 310 typedef struct _CUVIDPARSERDISPINFO 311 { 312 int picture_index; /**< OUT: Index of the current picture */ 313 int progressive_frame; /**< OUT: 1 if progressive frame; 0 otherwise */ 314 int top_field_first; /**< OUT: 1 if top field is displayed first; 0 otherwise */ 315 int repeat_first_field; /**< OUT: Number of additional fields (1=ivtc, 2=frame doubling, 4=frame tripling, 316 -1=unpaired field) */ 317 CUvideotimestamp timestamp; /**< OUT: Presentation time stamp */ 318 } CUVIDPARSERDISPINFO; 319 320 /***********************************************************************************************************************/ 321 //! Parser callbacks 322 //! The parser will call these synchronously from within cuvidParseVideoData(), whenever there is sequence change or a picture 323 //! is ready to be decoded and/or displayed. First argument in functions is "void *pUserData" member of structure CUVIDSOURCEPARAMS 324 //! Return values from these callbacks are interpreted as below. If the callbacks return failure, it will be propagated by 325 //! cuvidParseVideoData() to the application. 326 //! PFNVIDSEQUENCECALLBACK : 0: fail, 1: succeeded, > 1: override dpb size of parser (set by CUVIDPARSERPARAMS::ulMaxNumDecodeSurfaces 327 //! while creating parser) 328 //! PFNVIDDECODECALLBACK : 0: fail, >=1: succeeded 329 //! PFNVIDDISPLAYCALLBACK : 0: fail, >=1: succeeded 330 /***********************************************************************************************************************/ 331 typedef int (CUDAAPI *PFNVIDSEQUENCECALLBACK)(void *, CUVIDEOFORMAT *); 332 typedef int (CUDAAPI *PFNVIDDECODECALLBACK)(void *, CUVIDPICPARAMS *); 333 typedef int (CUDAAPI *PFNVIDDISPLAYCALLBACK)(void *, CUVIDPARSERDISPINFO *); 334 335 /**************************************/ 336 //! \ingroup STRUCTS 337 //! \struct CUVIDPARSERPARAMS 338 //! Used in cuvidCreateVideoParser API 339 /**************************************/ 340 typedef struct _CUVIDPARSERPARAMS 341 { 342 cudaVideoCodec CodecType; /**< IN: cudaVideoCodec_XXX */ 343 unsigned int ulMaxNumDecodeSurfaces; /**< IN: Max # of decode surfaces (parser will cycle through these) */ 344 unsigned int ulClockRate; /**< IN: Timestamp units in Hz (0=default=10000000Hz) */ 345 unsigned int ulErrorThreshold; /**< IN: % Error threshold (0-100) for calling pfnDecodePicture (100=always 346 IN: call pfnDecodePicture even if picture bitstream is fully corrupted) */ 347 unsigned int ulMaxDisplayDelay; /**< IN: Max display queue delay (improves pipelining of decode with display) 348 0=no delay (recommended values: 2..4) */ 349 unsigned int uReserved1[5]; /**< IN: Reserved for future use - set to 0 */ 350 void *pUserData; /**< IN: User data for callbacks */ 351 PFNVIDSEQUENCECALLBACK pfnSequenceCallback; /**< IN: Called before decoding frames and/or whenever there is a fmt change */ 352 PFNVIDDECODECALLBACK pfnDecodePicture; /**< IN: Called when a picture is ready to be decoded (decode order) */ 353 PFNVIDDISPLAYCALLBACK pfnDisplayPicture; /**< IN: Called whenever a picture is ready to be displayed (display order) */ 354 void *pvReserved2[7]; /**< Reserved for future use - set to NULL */ 355 CUVIDEOFORMATEX *pExtVideoInfo; /**< IN: [Optional] sequence header data from system layer */ 356 } CUVIDPARSERPARAMS; 357 358 /************************************************************************************************/ 359 //! \ingroup FUNCTS 360 //! \fn CUresult CUDAAPI cuvidCreateVideoParser(CUvideoparser *pObj, CUVIDPARSERPARAMS *pParams) 361 //! Create video parser object and initialize 362 /************************************************************************************************/ 363 CUresult CUDAAPI cuvidCreateVideoParser(CUvideoparser *pObj, CUVIDPARSERPARAMS *pParams); 364 365 /************************************************************************************************/ 366 //! \ingroup FUNCTS 367 //! \fn CUresult CUDAAPI cuvidParseVideoData(CUvideoparser obj, CUVIDSOURCEDATAPACKET *pPacket) 368 //! Parse the video data from source data packet in pPacket 369 //! Extracts parameter sets like SPS, PPS, bitstream etc. from pPacket and 370 //! calls back pfnDecodePicture with CUVIDPICPARAMS data for kicking of HW decoding 371 //! calls back pfnSequenceCallback with CUVIDEOFORMAT data for initial sequence header or when 372 //! the decoder encounters a video format change 373 //! calls back pfnDisplayPicture with CUVIDPARSERDISPINFO data to display a video frame 374 /************************************************************************************************/ 375 CUresult CUDAAPI cuvidParseVideoData(CUvideoparser obj, CUVIDSOURCEDATAPACKET *pPacket); 376 377 /************************************************************************************************/ 378 //! \ingroup FUNCTS 379 //! \fn CUresult CUDAAPI cuvidDestroyVideoParser(CUvideoparser obj) 380 //! Destroy the video parser 381 /************************************************************************************************/ 382 CUresult CUDAAPI cuvidDestroyVideoParser(CUvideoparser obj); 383 384 /**********************************************************************************************/ 385 386 #if defined(__cplusplus) 387 } 388 #endif /* __cplusplus */ 389 390 #endif // __NVCUVID_H__ 391 392 393