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 38 #include "host-common/dynlink_cuviddec.h" 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 */ 69 } cudaVideoState; 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 */ 83 } cudaAudioCodec; 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 */ 155 } CUVIDEOFORMATEX; 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 */ 184 } CUvideopacketflags; 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 unsigned long flags; /**< IN: Combination of CUVID_PKT_XXX flags */ 196 unsigned long 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; 201 202 // Callback for packet delivery 203 typedef int (CUDAAPI *PFNVIDSOURCECALLBACK)(void *, CUVIDSOURCEDATAPACKET *); 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 */ 220 } CUVIDSOURCEPARAMS; 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) */ 231 } CUvideosourceformat_flags; 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 /******************************************************************************************/ 259 typedef CUresult CUDAAPI tcuvidSetVideoSourceState(CUvideosource obj, cudaVideoState state); 260 261 /******************************************************************************************/ 262 //! \fn cudaVideoState CUDAAPI cuvidGetVideoSourceState(CUvideosource obj) 263 //! Get video source state 264 /******************************************************************************************/ 265 typedef cudaVideoState CUDAAPI tcuvidGetVideoSourceState(CUvideosource obj); 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 */ 295 } CUVIDPARSERDISPINFO; 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 /***********************************************************************************************************************/ 302 typedef int (CUDAAPI *PFNVIDSEQUENCECALLBACK)(void *, CUVIDEOFORMAT *); 303 typedef int (CUDAAPI *PFNVIDDECODECALLBACK)(void *, CUVIDPICPARAMS *); 304 typedef int (CUDAAPI *PFNVIDDISPLAYCALLBACK)(void *, CUVIDPARSERDISPINFO *); 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 */ 327 } CUVIDPARSERPARAMS; 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 extern tcuvidCreateVideoSource *cuvidCreateVideoSource; 349 extern tcuvidCreateVideoSourceW *cuvidCreateVideoSourceW; 350 extern tcuvidDestroyVideoSource *cuvidDestroyVideoSource; 351 extern tcuvidSetVideoSourceState *cuvidSetVideoSourceState; 352 extern tcuvidGetVideoSourceState *cuvidGetVideoSourceState; 353 extern tcuvidGetSourceVideoFormat *cuvidGetSourceVideoFormat; 354 extern tcuvidGetSourceAudioFormat *cuvidGetSourceAudioFormat; 355 356 extern tcuvidCreateVideoParser *cuvidCreateVideoParser; 357 extern tcuvidParseVideoData *cuvidParseVideoData; 358 extern tcuvidDestroyVideoParser *cuvidDestroyVideoParser; 359 360 /**********************************************************************************************/ 361 362 #if defined(__cplusplus) 363 } 364 #endif /* __cplusplus */ 365 366 #endif // __NVCUVID_H__ 367 368 369