1 /* 2 * This copyright notice applies to this header file only: 3 * 4 * Copyright (c) 2010-2018 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-2018 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 reserved1; /**< Reserved for future use */ 103 unsigned int coded_width; /**< OUT: coded frame width in pixels */ 104 unsigned int coded_height; /**< OUT: coded frame height in pixels */ 105 /** 106 * area of the frame that should be displayed 107 * typical example: 108 * coded_width = 1920, coded_height = 1088 109 * display_area = { 0,0,1920,1080 } 110 */ 111 struct { 112 int left; /**< OUT: left position of display rect */ 113 int top; /**< OUT: top position of display rect */ 114 int right; /**< OUT: right position of display rect */ 115 int bottom; /**< OUT: bottom position of display rect */ 116 } display_area; 117 cudaVideoChromaFormat chroma_format; /**< OUT: Chroma format */ 118 unsigned int bitrate; /**< OUT: video bitrate (bps, 0=unknown) */ 119 /** 120 * OUT: Display Aspect Ratio = x:y (4:3, 16:9, etc) 121 */ 122 struct { 123 int x; 124 int y; 125 } display_aspect_ratio; 126 /** 127 * Video Signal Description 128 * Refer section E.2.1 (VUI parameters semantics) of H264 spec file 129 */ 130 struct { 131 unsigned char video_format : 3; /**< OUT: 0-Component, 1-PAL, 2-NTSC, 3-SECAM, 4-MAC, 5-Unspecified */ 132 unsigned char video_full_range_flag : 1; /**< OUT: indicates the black level and luma and chroma range */ 133 unsigned char reserved_zero_bits : 4; /**< Reserved bits */ 134 unsigned char color_primaries; /**< OUT: chromaticity coordinates of source primaries */ 135 unsigned char transfer_characteristics; /**< OUT: opto-electronic transfer characteristic of the source picture */ 136 unsigned char matrix_coefficients; /**< OUT: used in deriving luma and chroma signals from RGB primaries */ 137 } video_signal_description; 138 unsigned int seqhdr_data_length; /**< OUT: Additional bytes following (CUVIDEOFORMATEX) */ 139 } CUVIDEOFORMAT; 140 141 /****************************************************************/ 142 //! \ingroup STRUCTS 143 //! \struct CUVIDEOFORMATEX 144 //! Video format including raw sequence header information 145 //! Used in cuvidGetSourceVideoFormat API 146 /****************************************************************/ 147 typedef struct 148 { 149 CUVIDEOFORMAT format; /**< OUT: CUVIDEOFORMAT structure */ 150 unsigned char raw_seqhdr_data[1024]; /**< OUT: Sequence header data */ 151 } CUVIDEOFORMATEX; 152 153 /****************************************************************/ 154 //! \ingroup STRUCTS 155 //! \struct CUAUDIOFORMAT 156 //! Audio formats 157 //! Used in cuvidGetSourceAudioFormat API 158 /****************************************************************/ 159 typedef struct 160 { 161 cudaAudioCodec codec; /**< OUT: Compression format */ 162 unsigned int channels; /**< OUT: number of audio channels */ 163 unsigned int samplespersec; /**< OUT: sampling frequency */ 164 unsigned int bitrate; /**< OUT: For uncompressed, can also be used to determine bits per sample */ 165 unsigned int reserved1; /**< Reserved for future use */ 166 unsigned int reserved2; /**< Reserved for future use */ 167 } CUAUDIOFORMAT; 168 169 170 /***************************************************************/ 171 //! \enum CUvideopacketflags 172 //! Data packet flags 173 //! Used in CUVIDSOURCEDATAPACKET structure 174 /***************************************************************/ 175 typedef enum { 176 CUVID_PKT_ENDOFSTREAM = 0x01, /**< Set when this is the last packet for this stream */ 177 CUVID_PKT_TIMESTAMP = 0x02, /**< Timestamp is valid */ 178 CUVID_PKT_DISCONTINUITY = 0x04, /**< Set when a discontinuity has to be signalled */ 179 CUVID_PKT_ENDOFPICTURE = 0x08, /**< Set when the packet contains exactly one frame */ 180 } CUvideopacketflags; 181 182 /*****************************************************************************/ 183 //! \ingroup STRUCTS 184 //! \struct CUVIDSOURCEDATAPACKET 185 //! Data Packet 186 //! Used in cuvidParseVideoData API 187 //! IN for cuvidParseVideoData 188 /*****************************************************************************/ 189 typedef struct _CUVIDSOURCEDATAPACKET 190 { 191 unsigned long flags; /**< IN: Combination of CUVID_PKT_XXX flags */ 192 unsigned long payload_size; /**< IN: number of bytes in the payload (may be zero if EOS flag is set) */ 193 const unsigned char *payload; /**< IN: Pointer to packet payload data (may be NULL if EOS flag is set) */ 194 CUvideotimestamp timestamp; /**< IN: Presentation time stamp (10MHz clock), only valid if 195 CUVID_PKT_TIMESTAMP flag is set */ 196 } CUVIDSOURCEDATAPACKET; 197 198 // Callback for packet delivery 199 typedef int (CUDAAPI *PFNVIDSOURCECALLBACK)(void *, CUVIDSOURCEDATAPACKET *); 200 201 /**************************************************************************************************************************/ 202 //! \ingroup STRUCTS 203 //! \struct CUVIDSOURCEPARAMS 204 //! Describes parameters needed in cuvidCreateVideoSource API 205 //! NVDECODE API is intended for HW accelerated video decoding so CUvideosource doesn't have audio demuxer for all supported 206 //! containers. It's recommended to clients to use their own or third party demuxer if audio support is needed. 207 /**************************************************************************************************************************/ 208 typedef struct _CUVIDSOURCEPARAMS 209 { 210 unsigned int ulClockRate; /**< IN: Time stamp units in Hz (0=default=10000000Hz) */ 211 unsigned int uReserved1[7]; /**< Reserved for future use - set to zero */ 212 void *pUserData; /**< IN: User private data passed in to the data handlers */ 213 PFNVIDSOURCECALLBACK pfnVideoDataHandler; /**< IN: Called to deliver video packets */ 214 PFNVIDSOURCECALLBACK pfnAudioDataHandler; /**< IN: Called to deliver audio packets. */ 215 void *pvReserved2[8]; /**< Reserved for future use - set to NULL */ 216 } CUVIDSOURCEPARAMS; 217 218 219 /**********************************************/ 220 //! \ingroup ENUMS 221 //! \enum CUvideosourceformat_flags 222 //! CUvideosourceformat_flags 223 //! Used in cuvidGetSourceVideoFormat API 224 /**********************************************/ 225 typedef enum { 226 CUVID_FMT_EXTFORMATINFO = 0x100 /**< Return extended format structure (CUVIDEOFORMATEX) */ 227 } CUvideosourceformat_flags; 228 229 #if !defined(__APPLE__) 230 /***************************************************************************************************************************/ 231 //! \ingroup FUNCTS 232 //! \fn CUresult CUDAAPI cuvidCreateVideoSource(CUvideosource *pObj, const char *pszFileName, CUVIDSOURCEPARAMS *pParams) 233 //! Create CUvideosource object. CUvideosource spawns demultiplexer thread that provides two callbacks: 234 //! pfnVideoDataHandler() and pfnAudioDataHandler() 235 //! NVDECODE API is intended for HW accelerated video decoding so CUvideosource doesn't have audio demuxer for all supported 236 //! containers. It's recommended to clients to use their own or third party demuxer if audio support is needed. 237 /***************************************************************************************************************************/ 238 CUresult CUDAAPI cuvidCreateVideoSource(CUvideosource *pObj, const char *pszFileName, CUVIDSOURCEPARAMS *pParams); 239 240 /***************************************************************************************************************************/ 241 //! \ingroup FUNCTS 242 //! \fn CUresult CUDAAPI cuvidCreateVideoSourceW(CUvideosource *pObj, const wchar_t *pwszFileName, CUVIDSOURCEPARAMS *pParams) 243 //! Create video source 244 /***************************************************************************************************************************/ 245 CUresult CUDAAPI cuvidCreateVideoSourceW(CUvideosource *pObj, const wchar_t *pwszFileName, CUVIDSOURCEPARAMS *pParams); 246 247 /********************************************************************/ 248 //! \ingroup FUNCTS 249 //! \fn CUresult CUDAAPI cuvidDestroyVideoSource(CUvideosource obj) 250 //! Destroy video source 251 /********************************************************************/ 252 CUresult CUDAAPI cuvidDestroyVideoSource(CUvideosource obj); 253 254 /******************************************************************************************/ 255 //! \ingroup FUNCTS 256 //! \fn CUresult CUDAAPI cuvidSetVideoSourceState(CUvideosource obj, cudaVideoState state) 257 //! Set video source state to: 258 //! cudaVideoState_Started - to signal the source to run and deliver data 259 //! cudaVideoState_Stopped - to stop the source from delivering the data 260 //! cudaVideoState_Error - invalid source 261 /******************************************************************************************/ 262 CUresult CUDAAPI cuvidSetVideoSourceState(CUvideosource obj, cudaVideoState state); 263 264 /******************************************************************************************/ 265 //! \ingroup FUNCTS 266 //! \fn cudaVideoState CUDAAPI cuvidGetVideoSourceState(CUvideosource obj) 267 //! Get video source state 268 //! Returns: 269 //! cudaVideoState_Started - if Source is running and delivering data 270 //! cudaVideoState_Stopped - if Source is stopped or reached end-of-stream 271 //! cudaVideoState_Error - if Source is in error state 272 /******************************************************************************************/ 273 cudaVideoState CUDAAPI cuvidGetVideoSourceState(CUvideosource obj); 274 275 /******************************************************************************************************************/ 276 //! \ingroup FUNCTS 277 //! \fn CUresult CUDAAPI cuvidGetSourceVideoFormat(CUvideosource obj, CUVIDEOFORMAT *pvidfmt, unsigned int flags) 278 //! Gets video source format in pvidfmt, flags is set to combination of CUvideosourceformat_flags as per requirement 279 /******************************************************************************************************************/ 280 CUresult CUDAAPI cuvidGetSourceVideoFormat(CUvideosource obj, CUVIDEOFORMAT *pvidfmt, unsigned int flags); 281 282 /**************************************************************************************************************************/ 283 //! \ingroup FUNCTS 284 //! \fn CUresult CUDAAPI cuvidGetSourceAudioFormat(CUvideosource obj, CUAUDIOFORMAT *paudfmt, unsigned int flags) 285 //! Get audio source format 286 //! NVDECODE API is intended for HW accelerated video decoding so CUvideosource doesn't have audio demuxer for all supported 287 //! containers. It's recommended to clients to use their own or third party demuxer if audio support is needed. 288 /**************************************************************************************************************************/ 289 CUresult CUDAAPI cuvidGetSourceAudioFormat(CUvideosource obj, CUAUDIOFORMAT *paudfmt, unsigned int flags); 290 291 #endif 292 /**********************************************************************************/ 293 //! \ingroup STRUCTS 294 //! \struct CUVIDPARSERDISPINFO 295 //! Used in cuvidParseVideoData API with PFNVIDDISPLAYCALLBACK pfnDisplayPicture 296 /**********************************************************************************/ 297 typedef struct _CUVIDPARSERDISPINFO 298 { 299 int picture_index; /**< OUT: Index of the current picture */ 300 int progressive_frame; /**< OUT: 1 if progressive frame; 0 otherwise */ 301 int top_field_first; /**< OUT: 1 if top field is displayed first; 0 otherwise */ 302 int repeat_first_field; /**< OUT: Number of additional fields (1=ivtc, 2=frame doubling, 4=frame tripling, 303 -1=unpaired field) */ 304 CUvideotimestamp timestamp; /**< OUT: Presentation time stamp */ 305 } CUVIDPARSERDISPINFO; 306 307 /***********************************************************************************************************************/ 308 //! Parser callbacks 309 //! The parser will call these synchronously from within cuvidParseVideoData(), whenever there is seqeuence change or a picture 310 //! is ready to be decoded and/or displayed. First argument in functions is "void *pUserData" member of structure CUVIDSOURCEPARAMS 311 //! Return values from these callbacks are interpreted as: 312 //! PFNVIDSEQUENCECALLBACK : 0: fail, 1: suceeded, > 1: override dpb size of parser (set by CUVIDPARSERPARAMS::ulMaxNumDecodeSurfaces 313 //! while creating parser) 314 //! PFNVIDDECODECALLBACK : 0: fail, >=1: suceeded 315 //! PFNVIDDISPLAYCALLBACK : 0: fail, >=1: suceeded 316 /***********************************************************************************************************************/ 317 typedef int (CUDAAPI *PFNVIDSEQUENCECALLBACK)(void *, CUVIDEOFORMAT *); 318 typedef int (CUDAAPI *PFNVIDDECODECALLBACK)(void *, CUVIDPICPARAMS *); 319 typedef int (CUDAAPI *PFNVIDDISPLAYCALLBACK)(void *, CUVIDPARSERDISPINFO *); 320 321 /**************************************/ 322 //! \ingroup STRUCTS 323 //! \struct CUVIDPARSERPARAMS 324 //! Used in cuvidCreateVideoParser API 325 /**************************************/ 326 typedef struct _CUVIDPARSERPARAMS 327 { 328 cudaVideoCodec CodecType; /**< IN: cudaVideoCodec_XXX */ 329 unsigned int ulMaxNumDecodeSurfaces; /**< IN: Max # of decode surfaces (parser will cycle through these) */ 330 unsigned int ulClockRate; /**< IN: Timestamp units in Hz (0=default=10000000Hz) */ 331 unsigned int ulErrorThreshold; /**< IN: % Error threshold (0-100) for calling pfnDecodePicture (100=always 332 IN: call pfnDecodePicture even if picture bitstream is fully corrupted) */ 333 unsigned int ulMaxDisplayDelay; /**< IN: Max display queue delay (improves pipelining of decode with display) 334 0=no delay (recommended values: 2..4) */ 335 unsigned int uReserved1[5]; /**< IN: Reserved for future use - set to 0 */ 336 void *pUserData; /**< IN: User data for callbacks */ 337 PFNVIDSEQUENCECALLBACK pfnSequenceCallback; /**< IN: Called before decoding frames and/or whenever there is a fmt change */ 338 PFNVIDDECODECALLBACK pfnDecodePicture; /**< IN: Called when a picture is ready to be decoded (decode order) */ 339 PFNVIDDISPLAYCALLBACK pfnDisplayPicture; /**< IN: Called whenever a picture is ready to be displayed (display order) */ 340 void *pvReserved2[7]; /**< Reserved for future use - set to NULL */ 341 CUVIDEOFORMATEX *pExtVideoInfo; /**< IN: [Optional] sequence header data from system layer */ 342 } CUVIDPARSERPARAMS; 343 344 /************************************************************************************************/ 345 //! \ingroup FUNCTS 346 //! \fn CUresult CUDAAPI cuvidCreateVideoParser(CUvideoparser *pObj, CUVIDPARSERPARAMS *pParams) 347 //! Create video parser object and initialize 348 /************************************************************************************************/ 349 CUresult CUDAAPI cuvidCreateVideoParser(CUvideoparser *pObj, CUVIDPARSERPARAMS *pParams); 350 351 /************************************************************************************************/ 352 //! \ingroup FUNCTS 353 //! \fn CUresult CUDAAPI cuvidParseVideoData(CUvideoparser obj, CUVIDSOURCEDATAPACKET *pPacket) 354 //! Parse the video data from source data packet in pPacket 355 //! Extracts parameter sets like SPS, PPS, bitstream etc. from pPacket and 356 //! calls back pfnDecodePicture with CUVIDPICPARAMS data for kicking of HW decoding 357 //! calls back pfnSequenceCallback with CUVIDEOFORMAT data for initial sequence header or when 358 //! the decoder encounters a video format change 359 //! calls back pfnDisplayPicture with CUVIDPARSERDISPINFO data to display a video frame 360 /************************************************************************************************/ 361 CUresult CUDAAPI cuvidParseVideoData(CUvideoparser obj, CUVIDSOURCEDATAPACKET *pPacket); 362 363 /************************************************************************************************/ 364 //! \ingroup FUNCTS 365 //! \fn CUresult CUDAAPI cuvidDestroyVideoParser(CUvideoparser obj) 366 //! Destroy the video parser 367 /************************************************************************************************/ 368 CUresult CUDAAPI cuvidDestroyVideoParser(CUvideoparser obj); 369 370 /**********************************************************************************************/ 371 372 #if defined(__cplusplus) 373 } 374 #endif /* __cplusplus */ 375 376 #endif // __NVCUVID_H__ 377 378 379