2 * This copyright notice applies to this header file only:
4 * Copyright (c) 2010-2015 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.
30 * NvEncodeAPI provides a NVENC Video Encoding interface to NVIDIA GPU devices based on the Kepler architecture.
32 * This file contains the interface constants, structure definitions and function prototypes.
35 #ifndef _NV_ENCODEAPI_H_
36 #define _NV_ENCODEAPI_H_
46 typedef __int32 int32_t;
47 typedef unsigned __int32 uint32_t;
48 typedef __int64 int64_t;
49 typedef unsigned __int64 uint64_t;
50 typedef signed char int8_t;
51 typedef unsigned char uint8_t;
52 typedef short int16_t;
53 typedef unsigned short uint16_t;
64 * \addtogroup ENCODER_STRUCTURE NvEncodeAPI Data structures
68 #if defined(_WIN32) || defined(__CYGWIN__)
69 #define NVENCAPI __stdcall
75 typedef RECT NVENC_RECT;
77 // =========================================================================================
81 * Abstracts the GUID structure for non-windows platforms.
83 // =========================================================================================
86 uint32_t Data1; /**< [in]: Specifies the first 8 hexadecimal digits of the GUID. */
87 uint16_t Data2; /**< [in]: Specifies the first group of 4 hexadecimal digits. */
88 uint16_t Data3; /**< [in]: Specifies the second group of 4 hexadecimal digits. */
89 uint8_t Data4[8]; /**< [in]: Array of 8 bytes. The first 2 bytes contain the third group of 4 hexadecimal digits.
90 The remaining 6 bytes contain the final 12 hexadecimal digits. */
96 * Defines a Rectangle. Used in ::NV_ENC_PREPROCESS_FRAME.
98 typedef struct _NVENC_RECT
100 uint32_t left; /**< [in]: X coordinate of the upper left corner of rectangular area to be specified. */
101 uint32_t top; /**< [in]: Y coordinate of the upper left corner of the rectangular area to be specified. */
102 uint32_t right; /**< [in]: X coordinate of the bottom right corner of the rectangular area to be specified. */
103 uint32_t bottom; /**< [in]: Y coordinate of the bottom right corner of the rectangular area to be specified. */
108 /** @} */ /* End of GUID and NVENC_RECT structure grouping*/
110 typedef void* NV_ENC_INPUT_PTR; /**< NVENCODE API input buffer */
111 typedef void* NV_ENC_OUTPUT_PTR; /**< NVENCODE API output buffer*/
112 typedef void* NV_ENC_REGISTERED_PTR; /**< A Resource that has been registered with NVENCODE API*/
114 #define NVENCAPI_MAJOR_VERSION 7
115 #define NVENCAPI_MINOR_VERSION 0
117 #define NVENCAPI_VERSION (NVENCAPI_MAJOR_VERSION | (NVENCAPI_MINOR_VERSION << 24))
120 * Macro to generate per-structure version for use with API.
122 #define NVENCAPI_STRUCT_VERSION(ver) ((uint32_t)NVENCAPI_VERSION | ((ver)<<16) | (0x7 << 28))
125 #define NVENC_INFINITE_GOPLENGTH 0xffffffff
127 #define NV_MAX_SEQ_HDR_LEN (512)
129 // =========================================================================================
130 // Encode Codec GUIDS supported by the NvEncodeAPI interface.
131 // =========================================================================================
133 // {6BC82762-4E63-4ca4-AA85-1E50F321F6BF}
134 static const GUID NV_ENC_CODEC_H264_GUID =
135 { 0x6bc82762, 0x4e63, 0x4ca4, { 0xaa, 0x85, 0x1e, 0x50, 0xf3, 0x21, 0xf6, 0xbf } };
137 // {790CDC88-4522-4d7b-9425-BDA9975F7603}
138 static const GUID NV_ENC_CODEC_HEVC_GUID =
139 { 0x790cdc88, 0x4522, 0x4d7b, { 0x94, 0x25, 0xbd, 0xa9, 0x97, 0x5f, 0x76, 0x3 } };
143 // =========================================================================================
144 // * Encode Profile GUIDS supported by the NvEncodeAPI interface.
145 // =========================================================================================
147 // {BFD6F8E7-233C-4341-8B3E-4818523803F4}
148 static const GUID NV_ENC_CODEC_PROFILE_AUTOSELECT_GUID =
149 { 0xbfd6f8e7, 0x233c, 0x4341, { 0x8b, 0x3e, 0x48, 0x18, 0x52, 0x38, 0x3, 0xf4 } };
151 // {0727BCAA-78C4-4c83-8C2F-EF3DFF267C6A}
152 static const GUID NV_ENC_H264_PROFILE_BASELINE_GUID =
153 { 0x727bcaa, 0x78c4, 0x4c83, { 0x8c, 0x2f, 0xef, 0x3d, 0xff, 0x26, 0x7c, 0x6a } };
155 // {60B5C1D4-67FE-4790-94D5-C4726D7B6E6D}
156 static const GUID NV_ENC_H264_PROFILE_MAIN_GUID =
157 { 0x60b5c1d4, 0x67fe, 0x4790, { 0x94, 0xd5, 0xc4, 0x72, 0x6d, 0x7b, 0x6e, 0x6d } };
159 // {E7CBC309-4F7A-4b89-AF2A-D537C92BE310}
160 static const GUID NV_ENC_H264_PROFILE_HIGH_GUID =
161 { 0xe7cbc309, 0x4f7a, 0x4b89, { 0xaf, 0x2a, 0xd5, 0x37, 0xc9, 0x2b, 0xe3, 0x10 } };
163 // {7AC663CB-A598-4960-B844-339B261A7D52}
164 static const GUID NV_ENC_H264_PROFILE_HIGH_444_GUID =
165 { 0x7ac663cb, 0xa598, 0x4960, { 0xb8, 0x44, 0x33, 0x9b, 0x26, 0x1a, 0x7d, 0x52 } };
167 // {40847BF5-33F7-4601-9084-E8FE3C1DB8B7}
168 static const GUID NV_ENC_H264_PROFILE_STEREO_GUID =
169 { 0x40847bf5, 0x33f7, 0x4601, { 0x90, 0x84, 0xe8, 0xfe, 0x3c, 0x1d, 0xb8, 0xb7 } };
171 // {CE788D20-AAA9-4318-92BB-AC7E858C8D36}
172 static const GUID NV_ENC_H264_PROFILE_SVC_TEMPORAL_SCALABILTY =
173 { 0xce788d20, 0xaaa9, 0x4318, { 0x92, 0xbb, 0xac, 0x7e, 0x85, 0x8c, 0x8d, 0x36 } };
175 // {B405AFAC-F32B-417B-89C4-9ABEED3E5978}
176 static const GUID NV_ENC_H264_PROFILE_PROGRESSIVE_HIGH_GUID =
177 { 0xb405afac, 0xf32b, 0x417b, { 0x89, 0xc4, 0x9a, 0xbe, 0xed, 0x3e, 0x59, 0x78 } };
179 // {AEC1BD87-E85B-48f2-84C3-98BCA6285072}
180 static const GUID NV_ENC_H264_PROFILE_CONSTRAINED_HIGH_GUID =
181 { 0xaec1bd87, 0xe85b, 0x48f2, { 0x84, 0xc3, 0x98, 0xbc, 0xa6, 0x28, 0x50, 0x72 } };
183 // {B514C39A-B55B-40fa-878F-F1253B4DFDEC}
184 static const GUID NV_ENC_HEVC_PROFILE_MAIN_GUID =
185 { 0xb514c39a, 0xb55b, 0x40fa, { 0x87, 0x8f, 0xf1, 0x25, 0x3b, 0x4d, 0xfd, 0xec } };
187 // {fa4d2b6c-3a5b-411a-8018-0a3f5e3c9be5}
188 static const GUID NV_ENC_HEVC_PROFILE_MAIN10_GUID =
189 { 0xfa4d2b6c, 0x3a5b, 0x411a, { 0x80, 0x18, 0x0a, 0x3f, 0x5e, 0x3c, 0x9b, 0xe5 } };
191 // For HEVC Main 444 8 bit and HEVC Main 444 10 bit profiles only
192 // {51ec32b5-1b4c-453c-9cbd-b616bd621341}
193 static const GUID NV_ENC_HEVC_PROFILE_FREXT_GUID =
194 { 0x51ec32b5, 0x1b4c, 0x453c, { 0x9c, 0xbd, 0xb6, 0x16, 0xbd, 0x62, 0x13, 0x41 } };
196 // =========================================================================================
197 // * Preset GUIDS supported by the NvEncodeAPI interface.
198 // =========================================================================================
199 // {B2DFB705-4EBD-4C49-9B5F-24A777D3E587}
200 static const GUID NV_ENC_PRESET_DEFAULT_GUID =
201 { 0xb2dfb705, 0x4ebd, 0x4c49, { 0x9b, 0x5f, 0x24, 0xa7, 0x77, 0xd3, 0xe5, 0x87 } };
203 // {60E4C59F-E846-4484-A56D-CD45BE9FDDF6}
204 static const GUID NV_ENC_PRESET_HP_GUID =
205 { 0x60e4c59f, 0xe846, 0x4484, { 0xa5, 0x6d, 0xcd, 0x45, 0xbe, 0x9f, 0xdd, 0xf6 } };
207 // {34DBA71D-A77B-4B8F-9C3E-B6D5DA24C012}
208 static const GUID NV_ENC_PRESET_HQ_GUID =
209 { 0x34dba71d, 0xa77b, 0x4b8f, { 0x9c, 0x3e, 0xb6, 0xd5, 0xda, 0x24, 0xc0, 0x12 } };
211 // {82E3E450-BDBB-4e40-989C-82A90DF9EF32}
212 static const GUID NV_ENC_PRESET_BD_GUID =
213 { 0x82e3e450, 0xbdbb, 0x4e40, { 0x98, 0x9c, 0x82, 0xa9, 0xd, 0xf9, 0xef, 0x32 } };
215 // {49DF21C5-6DFA-4feb-9787-6ACC9EFFB726}
216 static const GUID NV_ENC_PRESET_LOW_LATENCY_DEFAULT_GUID =
217 { 0x49df21c5, 0x6dfa, 0x4feb, { 0x97, 0x87, 0x6a, 0xcc, 0x9e, 0xff, 0xb7, 0x26 } };
219 // {C5F733B9-EA97-4cf9-BEC2-BF78A74FD105}
220 static const GUID NV_ENC_PRESET_LOW_LATENCY_HQ_GUID =
221 { 0xc5f733b9, 0xea97, 0x4cf9, { 0xbe, 0xc2, 0xbf, 0x78, 0xa7, 0x4f, 0xd1, 0x5 } };
223 // {67082A44-4BAD-48FA-98EA-93056D150A58}
224 static const GUID NV_ENC_PRESET_LOW_LATENCY_HP_GUID =
225 { 0x67082a44, 0x4bad, 0x48fa, { 0x98, 0xea, 0x93, 0x5, 0x6d, 0x15, 0xa, 0x58 } };
227 // {D5BFB716-C604-44e7-9BB8-DEA5510FC3AC}
228 static const GUID NV_ENC_PRESET_LOSSLESS_DEFAULT_GUID =
229 { 0xd5bfb716, 0xc604, 0x44e7, { 0x9b, 0xb8, 0xde, 0xa5, 0x51, 0xf, 0xc3, 0xac } };
231 // {149998E7-2364-411d-82EF-179888093409}
232 static const GUID NV_ENC_PRESET_LOSSLESS_HP_GUID =
233 { 0x149998e7, 0x2364, 0x411d, { 0x82, 0xef, 0x17, 0x98, 0x88, 0x9, 0x34, 0x9 } };
236 * \addtogroup ENCODER_STRUCTURE NvEncodeAPI Data structures
241 * Input frame encode modes
243 typedef enum _NV_ENC_PARAMS_FRAME_FIELD_MODE
245 NV_ENC_PARAMS_FRAME_FIELD_MODE_FRAME = 0x01, /**< Frame mode */
246 NV_ENC_PARAMS_FRAME_FIELD_MODE_FIELD = 0x02, /**< Field mode */
247 NV_ENC_PARAMS_FRAME_FIELD_MODE_MBAFF = 0x03 /**< MB adaptive frame/field */
248 } NV_ENC_PARAMS_FRAME_FIELD_MODE;
253 typedef enum _NV_ENC_PARAMS_RC_MODE
255 NV_ENC_PARAMS_RC_CONSTQP = 0x0, /**< Constant QP mode */
256 NV_ENC_PARAMS_RC_VBR = 0x1, /**< Variable bitrate mode */
257 NV_ENC_PARAMS_RC_CBR = 0x2, /**< Constant bitrate mode */
258 NV_ENC_PARAMS_RC_VBR_MINQP = 0x4, /**< Variable bitrate mode with MinQP */
259 NV_ENC_PARAMS_RC_2_PASS_QUALITY = 0x8, /**< Multi pass encoding optimized for image quality and works only with low latency mode */
260 NV_ENC_PARAMS_RC_2_PASS_FRAMESIZE_CAP = 0x10, /**< Multi pass encoding optimized for maintaining frame size and works only with low latency mode */
261 NV_ENC_PARAMS_RC_2_PASS_VBR = 0x20 /**< Multi pass VBR */
262 } NV_ENC_PARAMS_RC_MODE;
264 #define NV_ENC_PARAMS_RC_CBR2 NV_ENC_PARAMS_RC_CBR /**< Deprecated */
267 * Input picture structure
269 typedef enum _NV_ENC_PIC_STRUCT
271 NV_ENC_PIC_STRUCT_FRAME = 0x01, /**< Progressive frame */
272 NV_ENC_PIC_STRUCT_FIELD_TOP_BOTTOM = 0x02, /**< Field encoding top field first */
273 NV_ENC_PIC_STRUCT_FIELD_BOTTOM_TOP = 0x03 /**< Field encoding bottom field first */
279 typedef enum _NV_ENC_PIC_TYPE
281 NV_ENC_PIC_TYPE_P = 0x0, /**< Forward predicted */
282 NV_ENC_PIC_TYPE_B = 0x01, /**< Bi-directionally predicted picture */
283 NV_ENC_PIC_TYPE_I = 0x02, /**< Intra predicted picture */
284 NV_ENC_PIC_TYPE_IDR = 0x03, /**< IDR picture */
285 NV_ENC_PIC_TYPE_BI = 0x04, /**< Bi-directionally predicted with only Intra MBs */
286 NV_ENC_PIC_TYPE_SKIPPED = 0x05, /**< Picture is skipped */
287 NV_ENC_PIC_TYPE_INTRA_REFRESH = 0x06, /**< First picture in intra refresh cycle */
288 NV_ENC_PIC_TYPE_UNKNOWN = 0xFF /**< Picture type unknown */
292 * Motion vector precisions
294 typedef enum _NV_ENC_MV_PRECISION
296 NV_ENC_MV_PRECISION_DEFAULT = 0x0, /**<Driver selects QuarterPel motion vector precision by default*/
297 NV_ENC_MV_PRECISION_FULL_PEL = 0x01, /**< FullPel motion vector precision */
298 NV_ENC_MV_PRECISION_HALF_PEL = 0x02, /**< HalfPel motion vector precision */
299 NV_ENC_MV_PRECISION_QUARTER_PEL = 0x03 /**< QuarterPel motion vector precision */
300 } NV_ENC_MV_PRECISION;
304 * Input buffer formats
306 typedef enum _NV_ENC_BUFFER_FORMAT
308 NV_ENC_BUFFER_FORMAT_UNDEFINED = 0x00000000, /**< Undefined buffer format */
310 NV_ENC_BUFFER_FORMAT_NV12 = 0x00000001, /**< Semi-Planar YUV [Y plane followed by interleaved UV plane] */
311 NV_ENC_BUFFER_FORMAT_YV12 = 0x00000010, /**< Planar YUV [Y plane followed by V and U planes] */
312 NV_ENC_BUFFER_FORMAT_IYUV = 0x00000100, /**< Planar YUV [Y plane followed by U and V planes] */
313 NV_ENC_BUFFER_FORMAT_YUV444 = 0x00001000, /**< Planar YUV [Y plane followed by U and V planes] */
314 NV_ENC_BUFFER_FORMAT_YUV420_10BIT = 0x00010000, /**< 10 bit Semi-Planar YUV [Y plane followed by interleaved UV plane]. Each pixel of size 2 bytes. Most Significant 10 bits contain pixel data. */
315 NV_ENC_BUFFER_FORMAT_YUV444_10BIT = 0x00100000, /**< 10 bit Planar YUV444 [Y plane followed by U and V planes]. Each pixel of size 2 bytes. Most Significant 10 bits contain pixel data. */
316 NV_ENC_BUFFER_FORMAT_ARGB = 0x01000000, /**< 8 bit Packed A8R8G8B8 */
317 NV_ENC_BUFFER_FORMAT_ARGB10 = 0x02000000, /**< 10 bit Packed A2R10G10B10. Each pixel of size 2 bytes. Most Significant 10 bits contain pixel data. */
318 NV_ENC_BUFFER_FORMAT_AYUV = 0x04000000, /**< 8 bit Packed A8Y8U8V8 */
319 NV_ENC_BUFFER_FORMAT_ABGR = 0x10000000, /**< 8 bit Packed A8B8G8R8 */
320 NV_ENC_BUFFER_FORMAT_ABGR10 = 0x20000000, /**< 10 bit Packed A2B10G10R10. Each pixel of size 2 bytes. Most Significant 10 bits contain pixel data. */
321 } NV_ENC_BUFFER_FORMAT;
323 #define NV_ENC_BUFFER_FORMAT_NV12_PL NV_ENC_BUFFER_FORMAT_NV12
324 #define NV_ENC_BUFFER_FORMAT_YV12_PL NV_ENC_BUFFER_FORMAT_YV12
325 #define NV_ENC_BUFFER_FORMAT_IYUV_PL NV_ENC_BUFFER_FORMAT_IYUV
326 #define NV_ENC_BUFFER_FORMAT_YUV444_PL NV_ENC_BUFFER_FORMAT_YUV444
331 typedef enum _NV_ENC_LEVEL
333 NV_ENC_LEVEL_AUTOSELECT = 0,
335 NV_ENC_LEVEL_H264_1 = 10,
336 NV_ENC_LEVEL_H264_1b = 9,
337 NV_ENC_LEVEL_H264_11 = 11,
338 NV_ENC_LEVEL_H264_12 = 12,
339 NV_ENC_LEVEL_H264_13 = 13,
340 NV_ENC_LEVEL_H264_2 = 20,
341 NV_ENC_LEVEL_H264_21 = 21,
342 NV_ENC_LEVEL_H264_22 = 22,
343 NV_ENC_LEVEL_H264_3 = 30,
344 NV_ENC_LEVEL_H264_31 = 31,
345 NV_ENC_LEVEL_H264_32 = 32,
346 NV_ENC_LEVEL_H264_4 = 40,
347 NV_ENC_LEVEL_H264_41 = 41,
348 NV_ENC_LEVEL_H264_42 = 42,
349 NV_ENC_LEVEL_H264_5 = 50,
350 NV_ENC_LEVEL_H264_51 = 51,
351 NV_ENC_LEVEL_H264_52 = 52,
354 NV_ENC_LEVEL_HEVC_1 = 30,
355 NV_ENC_LEVEL_HEVC_2 = 60,
356 NV_ENC_LEVEL_HEVC_21 = 63,
357 NV_ENC_LEVEL_HEVC_3 = 90,
358 NV_ENC_LEVEL_HEVC_31 = 93,
359 NV_ENC_LEVEL_HEVC_4 = 120,
360 NV_ENC_LEVEL_HEVC_41 = 123,
361 NV_ENC_LEVEL_HEVC_5 = 150,
362 NV_ENC_LEVEL_HEVC_51 = 153,
363 NV_ENC_LEVEL_HEVC_52 = 156,
364 NV_ENC_LEVEL_HEVC_6 = 180,
365 NV_ENC_LEVEL_HEVC_61 = 183,
366 NV_ENC_LEVEL_HEVC_62 = 186,
368 NV_ENC_TIER_HEVC_MAIN = 0,
369 NV_ENC_TIER_HEVC_HIGH = 1
375 typedef enum _NVENCSTATUS
378 * This indicates that API call returned with no errors.
383 * This indicates that no encode capable devices were detected.
385 NV_ENC_ERR_NO_ENCODE_DEVICE,
388 * This indicates that devices pass by the client is not supported.
390 NV_ENC_ERR_UNSUPPORTED_DEVICE,
393 * This indicates that the encoder device supplied by the client is not
396 NV_ENC_ERR_INVALID_ENCODERDEVICE,
399 * This indicates that device passed to the API call is invalid.
401 NV_ENC_ERR_INVALID_DEVICE,
404 * This indicates that device passed to the API call is no longer available and
405 * needs to be reinitialized. The clients need to destroy the current encoder
406 * session by freeing the allocated input output buffers and destroying the device
407 * and create a new encoding session.
409 NV_ENC_ERR_DEVICE_NOT_EXIST,
412 * This indicates that one or more of the pointers passed to the API call
415 NV_ENC_ERR_INVALID_PTR,
418 * This indicates that completion event passed in ::NvEncEncodePicture() call
421 NV_ENC_ERR_INVALID_EVENT,
424 * This indicates that one or more of the parameter passed to the API call
427 NV_ENC_ERR_INVALID_PARAM,
430 * This indicates that an API call was made in wrong sequence/order.
432 NV_ENC_ERR_INVALID_CALL,
435 * This indicates that the API call failed because it was unable to allocate
436 * enough memory to perform the requested operation.
438 NV_ENC_ERR_OUT_OF_MEMORY,
441 * This indicates that the encoder has not been initialized with
442 * ::NvEncInitializeEncoder() or that initialization has failed.
443 * The client cannot allocate input or output buffers or do any encoding
444 * related operation before successfully initializing the encoder.
446 NV_ENC_ERR_ENCODER_NOT_INITIALIZED,
449 * This indicates that an unsupported parameter was passed by the client.
451 NV_ENC_ERR_UNSUPPORTED_PARAM,
454 * This indicates that the ::NvEncLockBitstream() failed to lock the output
455 * buffer. This happens when the client makes a non blocking lock call to
456 * access the output bitstream by passing NV_ENC_LOCK_BITSTREAM::doNotWait flag.
457 * This is not a fatal error and client should retry the same operation after
460 NV_ENC_ERR_LOCK_BUSY,
463 * This indicates that the size of the user buffer passed by the client is
464 * insufficient for the requested operation.
466 NV_ENC_ERR_NOT_ENOUGH_BUFFER,
469 * This indicates that an invalid struct version was used by the client.
471 NV_ENC_ERR_INVALID_VERSION,
474 * This indicates that ::NvEncMapInputResource() API failed to map the client
475 * provided input resource.
477 NV_ENC_ERR_MAP_FAILED,
480 * This indicates encode driver requires more input buffers to produce an output
481 * bitstream. If this error is returned from ::NvEncEncodePicture() API, this
482 * is not a fatal error. If the client is encoding with B frames then,
483 * ::NvEncEncodePicture() API might be buffering the input frame for re-ordering.
485 * A client operating in synchronous mode cannot call ::NvEncLockBitstream()
486 * API on the output bitstream buffer if ::NvEncEncodePicture() returned the
487 * ::NV_ENC_ERR_NEED_MORE_INPUT error code.
488 * The client must continue providing input frames until encode driver returns
489 * ::NV_ENC_SUCCESS. After receiving ::NV_ENC_SUCCESS status the client can call
490 * ::NvEncLockBitstream() API on the output buffers in the same order in which
491 * it has called ::NvEncEncodePicture().
493 NV_ENC_ERR_NEED_MORE_INPUT,
496 * This indicates that the HW encoder is busy encoding and is unable to encode
497 * the input. The client should call ::NvEncEncodePicture() again after few
500 NV_ENC_ERR_ENCODER_BUSY,
503 * This indicates that the completion event passed in ::NvEncEncodePicture()
504 * API has not been registered with encoder driver using ::NvEncRegisterAsyncEvent().
506 NV_ENC_ERR_EVENT_NOT_REGISTERD,
509 * This indicates that an unknown internal error has occurred.
514 * This indicates that the client is attempting to use a feature
515 * that is not available for the license type for the current system.
517 NV_ENC_ERR_INCOMPATIBLE_CLIENT_KEY,
520 * This indicates that the client is attempting to use a feature
521 * that is not implemented for the current version.
523 NV_ENC_ERR_UNIMPLEMENTED,
526 * This indicates that the ::NvEncRegisterResource API failed to register the resource.
528 NV_ENC_ERR_RESOURCE_REGISTER_FAILED,
531 * This indicates that the client is attempting to unregister a resource
532 * that has not been successfully registered.
534 NV_ENC_ERR_RESOURCE_NOT_REGISTERED,
537 * This indicates that the client is attempting to unmap a resource
538 * that has not been successfully mapped.
540 NV_ENC_ERR_RESOURCE_NOT_MAPPED,
545 * Encode Picture encode flags.
547 typedef enum _NV_ENC_PIC_FLAGS
549 NV_ENC_PIC_FLAG_FORCEINTRA = 0x1, /**< Encode the current picture as an Intra picture */
550 NV_ENC_PIC_FLAG_FORCEIDR = 0x2, /**< Encode the current picture as an IDR picture.
551 This flag is only valid when Picture type decision is taken by the Encoder
552 [_NV_ENC_INITIALIZE_PARAMS::enablePTD == 1]. */
553 NV_ENC_PIC_FLAG_OUTPUT_SPSPPS = 0x4, /**< Write the sequence and picture header in encoded bitstream of the current picture */
554 NV_ENC_PIC_FLAG_EOS = 0x8, /**< Indicates end of the input stream */
558 * Memory heap to allocate input and output buffers.
560 typedef enum _NV_ENC_MEMORY_HEAP
562 NV_ENC_MEMORY_HEAP_AUTOSELECT = 0, /**< Memory heap to be decided by the encoder driver based on the usage */
563 NV_ENC_MEMORY_HEAP_VID = 1, /**< Memory heap is in local video memory */
564 NV_ENC_MEMORY_HEAP_SYSMEM_CACHED = 2, /**< Memory heap is in cached system memory */
565 NV_ENC_MEMORY_HEAP_SYSMEM_UNCACHED = 3 /**< Memory heap is in uncached system memory */
566 } NV_ENC_MEMORY_HEAP;
570 * H.264 entropy coding modes.
572 typedef enum _NV_ENC_H264_ENTROPY_CODING_MODE
574 NV_ENC_H264_ENTROPY_CODING_MODE_AUTOSELECT = 0x0, /**< Entropy coding mode is auto selected by the encoder driver */
575 NV_ENC_H264_ENTROPY_CODING_MODE_CABAC = 0x1, /**< Entropy coding mode is CABAC */
576 NV_ENC_H264_ENTROPY_CODING_MODE_CAVLC = 0x2 /**< Entropy coding mode is CAVLC */
577 } NV_ENC_H264_ENTROPY_CODING_MODE;
580 * H.264 specific Bdirect modes
582 typedef enum _NV_ENC_H264_BDIRECT_MODE
584 NV_ENC_H264_BDIRECT_MODE_AUTOSELECT = 0x0, /**< BDirect mode is auto selected by the encoder driver */
585 NV_ENC_H264_BDIRECT_MODE_DISABLE = 0x1, /**< Disable BDirect mode */
586 NV_ENC_H264_BDIRECT_MODE_TEMPORAL = 0x2, /**< Temporal BDirect mode */
587 NV_ENC_H264_BDIRECT_MODE_SPATIAL = 0x3 /**< Spatial BDirect mode */
588 } NV_ENC_H264_BDIRECT_MODE;
591 * H.264 specific FMO usage
593 typedef enum _NV_ENC_H264_FMO_MODE
595 NV_ENC_H264_FMO_AUTOSELECT = 0x0, /**< FMO usage is auto selected by the encoder driver */
596 NV_ENC_H264_FMO_ENABLE = 0x1, /**< Enable FMO */
597 NV_ENC_H264_FMO_DISABLE = 0x2, /**< Disble FMO */
598 } NV_ENC_H264_FMO_MODE;
601 * H.264 specific Adaptive Transform modes
603 typedef enum _NV_ENC_H264_ADAPTIVE_TRANSFORM_MODE
605 NV_ENC_H264_ADAPTIVE_TRANSFORM_AUTOSELECT = 0x0, /**< Adaptive Transform 8x8 mode is auto selected by the encoder driver*/
606 NV_ENC_H264_ADAPTIVE_TRANSFORM_DISABLE = 0x1, /**< Adaptive Transform 8x8 mode disabled */
607 NV_ENC_H264_ADAPTIVE_TRANSFORM_ENABLE = 0x2, /**< Adaptive Transform 8x8 mode should be used */
608 } NV_ENC_H264_ADAPTIVE_TRANSFORM_MODE;
611 * Stereo frame packing modes.
613 typedef enum _NV_ENC_STEREO_PACKING_MODE
615 NV_ENC_STEREO_PACKING_MODE_NONE = 0x0, /**< No Stereo packing required */
616 NV_ENC_STEREO_PACKING_MODE_CHECKERBOARD = 0x1, /**< Checkerboard mode for packing stereo frames */
617 NV_ENC_STEREO_PACKING_MODE_COLINTERLEAVE = 0x2, /**< Column Interleave mode for packing stereo frames */
618 NV_ENC_STEREO_PACKING_MODE_ROWINTERLEAVE = 0x3, /**< Row Interleave mode for packing stereo frames */
619 NV_ENC_STEREO_PACKING_MODE_SIDEBYSIDE = 0x4, /**< Side-by-side mode for packing stereo frames */
620 NV_ENC_STEREO_PACKING_MODE_TOPBOTTOM = 0x5, /**< Top-Bottom mode for packing stereo frames */
621 NV_ENC_STEREO_PACKING_MODE_FRAMESEQ = 0x6 /**< Frame Sequential mode for packing stereo frames */
622 } NV_ENC_STEREO_PACKING_MODE;
625 * Input Resource type
627 typedef enum _NV_ENC_INPUT_RESOURCE_TYPE
629 NV_ENC_INPUT_RESOURCE_TYPE_DIRECTX = 0x0, /**< input resource type is a directx9 surface*/
630 NV_ENC_INPUT_RESOURCE_TYPE_CUDADEVICEPTR = 0x1, /**< input resource type is a cuda device pointer surface*/
631 NV_ENC_INPUT_RESOURCE_TYPE_CUDAARRAY = 0x2, /**< input resource type is a cuda array surface */
632 } NV_ENC_INPUT_RESOURCE_TYPE;
635 * Encoder Device type
637 typedef enum _NV_ENC_DEVICE_TYPE
639 NV_ENC_DEVICE_TYPE_DIRECTX = 0x0, /**< encode device type is a directx9 device */
640 NV_ENC_DEVICE_TYPE_CUDA = 0x1, /**< encode device type is a cuda device */
641 } NV_ENC_DEVICE_TYPE;
644 * Encoder capabilities enumeration.
646 typedef enum _NV_ENC_CAPS
649 * Maximum number of B-Frames supported.
651 NV_ENC_CAPS_NUM_MAX_BFRAMES,
654 * Rate control modes supported.
655 * \n The API return value is a bitmask of the values in NV_ENC_PARAMS_RC_MODE.
657 NV_ENC_CAPS_SUPPORTED_RATECONTROL_MODES,
660 * Indicates HW support for field mode encoding.
661 * \n 0 : Interlaced mode encoding is not supported.
662 * \n 1 : Interlaced field mode encoding is supported.
663 * \n 2 : Interlaced frame encoding and field mode encoding are both supported.
665 NV_ENC_CAPS_SUPPORT_FIELD_ENCODING,
668 * Indicates HW support for monochrome mode encoding.
669 * \n 0 : Monochrome mode not supported.
670 * \n 1 : Monochrome mode supported.
672 NV_ENC_CAPS_SUPPORT_MONOCHROME,
675 * Indicates HW support for FMO.
676 * \n 0 : FMO not supported.
677 * \n 1 : FMO supported.
679 NV_ENC_CAPS_SUPPORT_FMO,
682 * Indicates HW capability for Quarter pel motion estimation.
683 * \n 0 : QuarterPel Motion Estimation not supported.
684 * \n 1 : QuarterPel Motion Estimation supported.
686 NV_ENC_CAPS_SUPPORT_QPELMV,
689 * H.264 specific. Indicates HW support for BDirect modes.
690 * \n 0 : BDirect mode encoding not supported.
691 * \n 1 : BDirect mode encoding supported.
693 NV_ENC_CAPS_SUPPORT_BDIRECT_MODE,
696 * H264 specific. Indicates HW support for CABAC entropy coding mode.
697 * \n 0 : CABAC entropy coding not supported.
698 * \n 1 : CABAC entropy coding supported.
700 NV_ENC_CAPS_SUPPORT_CABAC,
703 * Indicates HW support for Adaptive Transform.
704 * \n 0 : Adaptive Transform not supported.
705 * \n 1 : Adaptive Transform supported.
707 NV_ENC_CAPS_SUPPORT_ADAPTIVE_TRANSFORM,
710 * Reserved enum field.
712 NV_ENC_CAPS_SUPPORT_RESERVED,
715 * Indicates HW support for encoding Temporal layers.
716 * \n 0 : Encoding Temporal layers not supported.
717 * \n 1 : Encoding Temporal layers supported.
719 NV_ENC_CAPS_NUM_MAX_TEMPORAL_LAYERS,
722 * Indicates HW support for Hierarchical P frames.
723 * \n 0 : Hierarchical P frames not supported.
724 * \n 1 : Hierarchical P frames supported.
726 NV_ENC_CAPS_SUPPORT_HIERARCHICAL_PFRAMES,
729 * Indicates HW support for Hierarchical B frames.
730 * \n 0 : Hierarchical B frames not supported.
731 * \n 1 : Hierarchical B frames supported.
733 NV_ENC_CAPS_SUPPORT_HIERARCHICAL_BFRAMES,
736 * Maximum Encoding level supported (See ::NV_ENC_LEVEL for details).
738 NV_ENC_CAPS_LEVEL_MAX,
741 * Minimum Encoding level supported (See ::NV_ENC_LEVEL for details).
743 NV_ENC_CAPS_LEVEL_MIN,
746 * Indicates HW support for separate colour plane encoding.
747 * \n 0 : Separate colour plane encoding not supported.
748 * \n 1 : Separate colour plane encoding supported.
750 NV_ENC_CAPS_SEPARATE_COLOUR_PLANE,
753 * Maximum output width supported.
755 NV_ENC_CAPS_WIDTH_MAX,
758 * Maximum output height supported.
760 NV_ENC_CAPS_HEIGHT_MAX,
763 * Indicates Temporal Scalability Support.
764 * \n 0 : Temporal SVC encoding not supported.
765 * \n 1 : Temporal SVC encoding supported.
767 NV_ENC_CAPS_SUPPORT_TEMPORAL_SVC,
770 * Indicates Dynamic Encode Resolution Change Support.
771 * Support added from NvEncodeAPI version 2.0.
772 * \n 0 : Dynamic Encode Resolution Change not supported.
773 * \n 1 : Dynamic Encode Resolution Change supported.
775 NV_ENC_CAPS_SUPPORT_DYN_RES_CHANGE,
778 * Indicates Dynamic Encode Bitrate Change Support.
779 * Support added from NvEncodeAPI version 2.0.
780 * \n 0 : Dynamic Encode bitrate change not supported.
781 * \n 1 : Dynamic Encode bitrate change supported.
783 NV_ENC_CAPS_SUPPORT_DYN_BITRATE_CHANGE,
786 * Indicates Forcing Constant QP On The Fly Support.
787 * Support added from NvEncodeAPI version 2.0.
788 * \n 0 : Forcing constant QP on the fly not supported.
789 * \n 1 : Forcing constant QP on the fly supported.
791 NV_ENC_CAPS_SUPPORT_DYN_FORCE_CONSTQP,
794 * Indicates Dynamic rate control mode Change Support.
795 * \n 0 : Dynamic rate control mode change not supported.
796 * \n 1 : Dynamic rate control mode change supported.
798 NV_ENC_CAPS_SUPPORT_DYN_RCMODE_CHANGE,
801 * Indicates Subframe readback support for slice-based encoding.
802 * \n 0 : Subframe readback not supported.
803 * \n 1 : Subframe readback supported.
805 NV_ENC_CAPS_SUPPORT_SUBFRAME_READBACK,
808 * Indicates Constrained Encoding mode support.
809 * Support added from NvEncodeAPI version 2.0.
810 * \n 0 : Constrained encoding mode not supported.
811 * \n 1 : Constarined encoding mode supported.
812 * If this mode is supported client can enable this during initialisation.
813 * Client can then force a picture to be coded as constrained picture where
814 * each slice in a constrained picture will have constrained_intra_pred_flag set to 1
815 * and disable_deblocking_filter_idc will be set to 2 and prediction vectors for inter
816 * macroblocks in each slice will be restricted to the slice region.
818 NV_ENC_CAPS_SUPPORT_CONSTRAINED_ENCODING,
821 * Indicates Intra Refresh Mode Support.
822 * Support added from NvEncodeAPI version 2.0.
823 * \n 0 : Intra Refresh Mode not supported.
824 * \n 1 : Intra Refresh Mode supported.
826 NV_ENC_CAPS_SUPPORT_INTRA_REFRESH,
829 * Indicates Custom VBV Bufer Size support. It can be used for capping frame size.
830 * Support added from NvEncodeAPI version 2.0.
831 * \n 0 : Custom VBV buffer size specification from client, not supported.
832 * \n 1 : Custom VBV buffer size specification from client, supported.
834 NV_ENC_CAPS_SUPPORT_CUSTOM_VBV_BUF_SIZE,
837 * Indicates Dynamic Slice Mode Support.
838 * Support added from NvEncodeAPI version 2.0.
839 * \n 0 : Dynamic Slice Mode not supported.
840 * \n 1 : Dynamic Slice Mode supported.
842 NV_ENC_CAPS_SUPPORT_DYNAMIC_SLICE_MODE,
845 * Indicates Reference Picture Invalidation Support.
846 * Support added from NvEncodeAPI version 2.0.
847 * \n 0 : Reference Picture Invalidation not supported.
848 * \n 1 : Reference Picture Invalidation supported.
850 NV_ENC_CAPS_SUPPORT_REF_PIC_INVALIDATION,
853 * Indicates support for PreProcessing.
854 * The API return value is a bitmask of the values defined in ::NV_ENC_PREPROC_FLAGS
856 NV_ENC_CAPS_PREPROC_SUPPORT,
859 * Indicates support Async mode.
860 * \n 0 : Async Encode mode not supported.
861 * \n 1 : Async Encode mode supported.
863 NV_ENC_CAPS_ASYNC_ENCODE_SUPPORT,
866 * Maximum MBs per frame supported.
868 NV_ENC_CAPS_MB_NUM_MAX,
871 * Maximum aggregate throughput in MBs per sec.
873 NV_ENC_CAPS_MB_PER_SEC_MAX,
876 * Indicates HW support for YUV444 mode encoding.
877 * \n 0 : YUV444 mode encoding not supported.
878 * \n 1 : YUV444 mode encoding supported.
880 NV_ENC_CAPS_SUPPORT_YUV444_ENCODE,
883 * Indicates HW support for lossless encoding.
884 * \n 0 : lossless encoding not supported.
885 * \n 1 : lossless encoding supported.
887 NV_ENC_CAPS_SUPPORT_LOSSLESS_ENCODE,
890 * Indicates HW support for Sample Adaptive Offset.
891 * \n 0 : SAO not supported.
892 * \n 1 : SAO encoding supported.
894 NV_ENC_CAPS_SUPPORT_SAO,
897 * Indicates HW support for MEOnly Mode.
898 * \n 0 : MEOnly Mode not supported.
899 * \n 1 : MEOnly Mode supported.
901 NV_ENC_CAPS_SUPPORT_MEONLY_MODE,
904 * Indicates HW support for lookahead encoding (enableLookahead=1).
905 * \n 0 : Lookahead not supported.
906 * \n 1 : Lookahead supported.
908 NV_ENC_CAPS_SUPPORT_LOOKAHEAD,
911 * Indicates HW support for temporal AQ encoding (enableTemporalAQ=1).
912 * \n 0 : Temporal AQ not supported.
913 * \n 1 : Temporal AQ supported.
915 NV_ENC_CAPS_SUPPORT_TEMPORAL_AQ,
917 * Indicates HW support for 10 bit encoding.
918 * \n 0 : 10 bit encoding not supported.
919 * \n 1 : 10 bit encoding supported.
921 NV_ENC_CAPS_SUPPORT_10BIT_ENCODE,
924 * Reserved - Not to be used by clients.
926 NV_ENC_CAPS_EXPOSED_COUNT
932 typedef enum _NV_ENC_HEVC_CUSIZE
934 NV_ENC_HEVC_CUSIZE_AUTOSELECT = 0,
935 NV_ENC_HEVC_CUSIZE_8x8 = 1,
936 NV_ENC_HEVC_CUSIZE_16x16 = 2,
937 NV_ENC_HEVC_CUSIZE_32x32 = 3,
938 NV_ENC_HEVC_CUSIZE_64x64 = 4,
942 * Input struct for querying Encoding capabilities.
944 typedef struct _NV_ENC_CAPS_PARAM
946 uint32_t version; /**< [in]: Struct version. Must be set to ::NV_ENC_CAPS_PARAM_VER */
947 NV_ENC_CAPS capsToQuery; /**< [in]: Specifies the encode capability to be queried. Client should pass a member for ::NV_ENC_CAPS enum. */
948 uint32_t reserved[62]; /**< [in]: Reserved and must be set to 0 */
951 /** NV_ENC_CAPS_PARAM struct version. */
952 #define NV_ENC_CAPS_PARAM_VER NVENCAPI_STRUCT_VERSION(1)
956 * Creation parameters for input buffer.
958 typedef struct _NV_ENC_CREATE_INPUT_BUFFER
960 uint32_t version; /**< [in]: Struct version. Must be set to ::NV_ENC_CREATE_INPUT_BUFFER_VER */
961 uint32_t width; /**< [in]: Input buffer width */
962 uint32_t height; /**< [in]: Input buffer width */
963 NV_ENC_MEMORY_HEAP memoryHeap; /**< [in]: Deprecated. Will be removed in sdk 8.0 */
964 NV_ENC_BUFFER_FORMAT bufferFmt; /**< [in]: Input buffer format */
965 uint32_t reserved; /**< [in]: Reserved and must be set to 0 */
966 NV_ENC_INPUT_PTR inputBuffer; /**< [out]: Pointer to input buffer */
967 void* pSysMemBuffer; /**< [in]: Pointer to existing sysmem buffer */
968 uint32_t reserved1[57]; /**< [in]: Reserved and must be set to 0 */
969 void* reserved2[63]; /**< [in]: Reserved and must be set to NULL */
970 } NV_ENC_CREATE_INPUT_BUFFER;
972 /** NV_ENC_CREATE_INPUT_BUFFER struct version. */
973 #define NV_ENC_CREATE_INPUT_BUFFER_VER NVENCAPI_STRUCT_VERSION(1)
976 * Creation parameters for output bitstream buffer.
978 typedef struct _NV_ENC_CREATE_BITSTREAM_BUFFER
980 uint32_t version; /**< [in]: Struct version. Must be set to ::NV_ENC_CREATE_BITSTREAM_BUFFER_VER */
981 uint32_t size; /**< [in]: Size of the bitstream buffer to be created */
982 NV_ENC_MEMORY_HEAP memoryHeap; /**< [in]: Deprecated. Will be removed in sdk 8.0 */
983 uint32_t reserved; /**< [in]: Reserved and must be set to 0 */
984 NV_ENC_OUTPUT_PTR bitstreamBuffer; /**< [out]: Pointer to the output bitstream buffer */
985 void* bitstreamBufferPtr; /**< [out]: Reserved and should not be used */
986 uint32_t reserved1[58]; /**< [in]: Reserved and should be set to 0 */
987 void* reserved2[64]; /**< [in]: Reserved and should be set to NULL */
988 } NV_ENC_CREATE_BITSTREAM_BUFFER;
990 /** NV_ENC_CREATE_BITSTREAM_BUFFER struct version. */
991 #define NV_ENC_CREATE_BITSTREAM_BUFFER_VER NVENCAPI_STRUCT_VERSION(1)
994 * Structs needed for ME only mode.
996 typedef struct _NV_ENC_MVECTOR
998 int16_t mvx; /**< the x component of MV in qpel units */
999 int16_t mvy; /**< the y component of MV in qpel units */
1003 * Motion vector structure per macroblock for H264 motion estimation.
1005 typedef struct _NV_ENC_H264_MV_DATA
1007 NV_ENC_MVECTOR mv[4]; /**< up to 4 vectors for 8x8 partition */
1008 uint8_t mbType; /**< 0 (I), 1 (P), 2 (IPCM), 3 (B) */
1009 uint8_t partitionType; /**< Specifies the block partition type. 0:16x16, 1:8x8, 2:16x8, 3:8x16 */
1010 uint16_t reserved; /**< reserved padding for alignment */
1012 } NV_ENC_H264_MV_DATA;
1015 * Motion vector structure per CU for HEVC motion estimation.
1017 typedef struct _NV_ENC_HEVC_MV_DATA
1019 NV_ENC_MVECTOR mv[4]; /**< up to 4 vectors within a CU */
1020 uint8_t cuType; /**< 0 (I), 1(P), 2 (Skip) */
1021 uint8_t cuSize; /**< 0: 8x8, 1: 16x16, 2: 32x32, 3: 64x64 */
1022 uint8_t partitionMode; /**< The CU partition mode
1023 0 (2Nx2N), 1 (2NxN), 2(Nx2N), 3 (NxN),
1024 4 (2NxnU), 5 (2NxnD), 6(nLx2N), 7 (nRx2N) */
1025 uint8_t lastCUInCTB; /**< Marker to separate CUs in the current CTB from CUs in the next CTB */
1026 } NV_ENC_HEVC_MV_DATA;
1029 * Creation parameters for output motion vector buffer for ME only mode.
1031 typedef struct _NV_ENC_CREATE_MV_BUFFER
1033 uint32_t version; /**< [in]: Struct version. Must be set to NV_ENC_CREATE_MV_BUFFER_VER */
1034 NV_ENC_OUTPUT_PTR mvBuffer; /**< [out]: Pointer to the output motion vector buffer */
1035 uint32_t reserved1[255]; /**< [in]: Reserved and should be set to 0 */
1036 void* reserved2[63]; /**< [in]: Reserved and should be set to NULL */
1037 } NV_ENC_CREATE_MV_BUFFER;
1039 /** NV_ENC_CREATE_MV_BUFFER struct version*/
1040 #define NV_ENC_CREATE_MV_BUFFER_VER NVENCAPI_STRUCT_VERSION(1)
1043 * QP value for frames
1045 typedef struct _NV_ENC_QP
1053 * Rate Control Configuration Paramters
1055 typedef struct _NV_ENC_RC_PARAMS
1058 NV_ENC_PARAMS_RC_MODE rateControlMode; /**< [in]: Specifies the rate control mode. Check support for various rate control modes using ::NV_ENC_CAPS_SUPPORTED_RATECONTROL_MODES caps. */
1059 NV_ENC_QP constQP; /**< [in]: Specifies the initial QP to be used for encoding, these values would be used for all frames if in Constant QP mode. */
1060 uint32_t averageBitRate; /**< [in]: Specifies the average bitrate(in bits/sec) used for encoding. */
1061 uint32_t maxBitRate; /**< [in]: Specifies the maximum bitrate for the encoded output. This is used for VBR and ignored for CBR mode. */
1062 uint32_t vbvBufferSize; /**< [in]: Specifies the VBV(HRD) buffer size. in bits. Set 0 to use the default VBV buffer size. */
1063 uint32_t vbvInitialDelay; /**< [in]: Specifies the VBV(HRD) initial delay in bits. Set 0 to use the default VBV initial delay .*/
1064 uint32_t enableMinQP :1; /**< [in]: Set this to 1 if minimum QP used for rate control. */
1065 uint32_t enableMaxQP :1; /**< [in]: Set this to 1 if maximum QP used for rate control. */
1066 uint32_t enableInitialRCQP :1; /**< [in]: Set this to 1 if user suppplied initial QP is used for rate control. */
1067 uint32_t enableAQ :1; /**< [in]: Set this to 1 to enable adaptive quantization (Spatial). */
1068 uint32_t enableExtQPDeltaMap :1; /**< [in]: Set this to 1 to enable additional QP modifier for each MB supplied by client though signed byte array pointed to by NV_ENC_PIC_PARAMS::qpDeltaMap (Not Supported when AQ(Spatial/Temporal) is enabled) */
1069 uint32_t enableLookahead :1; /**< [in]: Set this to 1 to enable lookahead with depth <lookaheadDepth> (if lookahead is enabled, input frames must remain available to the encoder until encode completion) */
1070 uint32_t disableIadapt :1; /**< [in]: Set this to 1 to disable adaptive I-frame insertion at scene cuts (only has an effect when lookahead is enabled) */
1071 uint32_t disableBadapt :1; /**< [in]: Set this to 1 to disable adaptive B-frame decision (only has an effect when lookahead is enabled) */
1072 uint32_t enableTemporalAQ :1; /**< [in]: Set this to 1 to enable temporal AQ for H.264 */
1073 uint32_t zeroReorderDelay :1; /**< [in]: Set this to 1 to indicate zero latency operation (no reordering delay, num_reorder_frames=0) */
1074 uint32_t enableNonRefP :1; /**< [in]: Set this to 1 to enable automatic insertion of non-reference P-frames (no effect if enablePTD=0) */
1075 uint32_t strictGOPTarget :1; /**< [in]: Set this to 1 to minimize GOP-to-GOP rate fluctuations */
1076 uint32_t aqStrength :4; /**< [in]: When AQ (Spatial) is enabled (i.e. NV_ENC_RC_PARAMS::enableAQ is set), this field is used to specify AQ strength. AQ strength scale is from 1 (low) - 15 (aggressive). If not set, strength is autoselected by driver. Currently supported only with h264 */
1077 uint32_t reservedBitFields :16; /**< [in]: Reserved bitfields and must be set to 0 */
1078 NV_ENC_QP minQP; /**< [in]: Specifies the minimum QP used for rate control. Client must set NV_ENC_CONFIG::enableMinQP to 1. */
1079 NV_ENC_QP maxQP; /**< [in]: Specifies the maximum QP used for rate control. Client must set NV_ENC_CONFIG::enableMaxQP to 1. */
1080 NV_ENC_QP initialRCQP; /**< [in]: Specifies the initial QP used for rate control. Client must set NV_ENC_CONFIG::enableInitialRCQP to 1. */
1081 uint32_t temporallayerIdxMask; /**< [in]: Specifies the temporal layers (as a bitmask) whose QPs have changed. Valid max bitmask is [2^NV_ENC_CAPS_NUM_MAX_TEMPORAL_LAYERS - 1] */
1082 uint8_t temporalLayerQP[8]; /**< [in]: Specifies the temporal layer QPs used for rate control. Temporal layer index is used as as the array index */
1083 uint16_t targetQuality; /**< [in]: Target CQ (Constant Quality) level for VBR mode (range 0-51 with 0-automatic) */
1084 uint16_t lookaheadDepth; /**< [in]: Maximum depth of lookahead with range 0-32 (only used if enableLookahead=1) */
1085 uint32_t reserved[9];
1088 /** macro for constructing the version field of ::_NV_ENC_RC_PARAMS */
1089 #define NV_ENC_RC_PARAMS_VER NVENCAPI_STRUCT_VERSION(1)
1094 * \struct _NV_ENC_CONFIG_H264_VUI_PARAMETERS
1095 * H264 Video Usability Info parameters
1097 typedef struct _NV_ENC_CONFIG_H264_VUI_PARAMETERS
1099 uint32_t overscanInfoPresentFlag; /**< [in]: if set to 1 , it specifies that the overscanInfo is present */
1100 uint32_t overscanInfo; /**< [in]: Specifies the overscan info(as defined in Annex E of the ITU-T Specification). */
1101 uint32_t videoSignalTypePresentFlag; /**< [in]: If set to 1, it specifies that the videoFormat, videoFullRangeFlag and colourDescriptionPresentFlag are present. */
1102 uint32_t videoFormat; /**< [in]: Specifies the source video format(as defined in Annex E of the ITU-T Specification).*/
1103 uint32_t videoFullRangeFlag; /**< [in]: Specifies the output range of the luma and chroma samples(as defined in Annex E of the ITU-T Specification). */
1104 uint32_t colourDescriptionPresentFlag; /**< [in]: If set to 1, it specifies that the colourPrimaries, transferCharacteristics and colourMatrix are present. */
1105 uint32_t colourPrimaries; /**< [in]: Specifies color primaries for converting to RGB(as defined in Annex E of the ITU-T Specification) */
1106 uint32_t transferCharacteristics; /**< [in]: Specifies the opto-electronic transfer characteristics to use (as defined in Annex E of the ITU-T Specification) */
1107 uint32_t colourMatrix; /**< [in]: Specifies the matrix coefficients used in deriving the luma and chroma from the RGB primaries (as defined in Annex E of the ITU-T Specification). */
1108 uint32_t chromaSampleLocationFlag; /**< [in]: if set to 1 , it specifies that the chromaSampleLocationTop and chromaSampleLocationBot are present.*/
1109 uint32_t chromaSampleLocationTop; /**< [in]: Specifies the chroma sample location for top field(as defined in Annex E of the ITU-T Specification) */
1110 uint32_t chromaSampleLocationBot; /**< [in]: Specifies the chroma sample location for bottom field(as defined in Annex E of the ITU-T Specification) */
1111 uint32_t bitstreamRestrictionFlag; /**< [in]: if set to 1, it specifies the bitstream restriction parameters are present in the bitstream.*/
1112 uint32_t reserved[15];
1113 }NV_ENC_CONFIG_H264_VUI_PARAMETERS;
1115 typedef NV_ENC_CONFIG_H264_VUI_PARAMETERS NV_ENC_CONFIG_HEVC_VUI_PARAMETERS;
1118 * \struct _NVENC_EXTERNAL_ME_HINT_COUNTS_PER_BLOCKTYPE
1119 * External motion vector hint counts per block type.
1121 typedef struct _NVENC_EXTERNAL_ME_HINT_COUNTS_PER_BLOCKTYPE
1123 uint32_t numCandsPerBlk16x16 : 4; /**< [in]: Specifies the number of candidates per 16x16 block. */
1124 uint32_t numCandsPerBlk16x8 : 4; /**< [in]: Specifies the number of candidates per 16x8 block. */
1125 uint32_t numCandsPerBlk8x16 : 4; /**< [in]: Specifies the number of candidates per 8x16 block. */
1126 uint32_t numCandsPerBlk8x8 : 4; /**< [in]: Specifies the number of candidates per 8x8 block. */
1127 uint32_t reserved : 16; /**< [in]: Reserved for padding. */
1128 uint32_t reserved1[3]; /**< [in]: Reserved for future use. */
1129 } NVENC_EXTERNAL_ME_HINT_COUNTS_PER_BLOCKTYPE;
1133 * \struct _NVENC_EXTERNAL_ME_HINT
1134 * External Motion Vector hint structure.
1136 typedef struct _NVENC_EXTERNAL_ME_HINT
1138 int32_t mvx : 12; /**< [in]: Specifies the x component of integer pixel MV (relative to current MB) S12.0. */
1139 int32_t mvy : 10; /**< [in]: Specifies the y component of integer pixel MV (relative to current MB) S10.0 .*/
1140 int32_t refidx : 5; /**< [in]: Specifies the reference index (31=invalid). Current we support only 1 reference frame per direction for external hints, so \p refidx must be 0. */
1141 int32_t dir : 1; /**< [in]: Specifies the direction of motion estimation . 0=L0 1=L1.*/
1142 int32_t partType : 2; /**< [in]: Specifies the block partition type.0=16x16 1=16x8 2=8x16 3=8x8 (blocks in partition must be consecutive).*/
1143 int32_t lastofPart : 1; /**< [in]: Set to 1 for the last MV of (sub) partition */
1144 int32_t lastOfMB : 1; /**< [in]: Set to 1 for the last MV of macroblock. */
1145 } NVENC_EXTERNAL_ME_HINT;
1149 * \struct _NV_ENC_CONFIG_H264
1150 * H264 encoder configuration parameters
1152 typedef struct _NV_ENC_CONFIG_H264
1154 uint32_t enableTemporalSVC :1; /**< [in]: Set to 1 to enable SVC temporal*/
1155 uint32_t enableStereoMVC :1; /**< [in]: Set to 1 to enable stereo MVC*/
1156 uint32_t hierarchicalPFrames :1; /**< [in]: Set to 1 to enable hierarchical PFrames */
1157 uint32_t hierarchicalBFrames :1; /**< [in]: Set to 1 to enable hierarchical BFrames */
1158 uint32_t outputBufferingPeriodSEI :1; /**< [in]: Set to 1 to write SEI buffering period syntax in the bitstream */
1159 uint32_t outputPictureTimingSEI :1; /**< [in]: Set to 1 to write SEI picture timing syntax in the bitstream */
1160 uint32_t outputAUD :1; /**< [in]: Set to 1 to write access unit delimiter syntax in bitstream */
1161 uint32_t disableSPSPPS :1; /**< [in]: Set to 1 to disable writing of Sequence and Picture parameter info in bitstream */
1162 uint32_t outputFramePackingSEI :1; /**< [in]: Set to 1 to enable writing of frame packing arrangement SEI messages to bitstream */
1163 uint32_t outputRecoveryPointSEI :1; /**< [in]: Set to 1 to enable writing of recovery point SEI message */
1164 uint32_t enableIntraRefresh :1; /**< [in]: Set to 1 to enable gradual decoder refresh or intra refresh. If the GOP structure uses B frames this will be ignored */
1165 uint32_t enableConstrainedEncoding :1; /**< [in]: Set this to 1 to enable constrainedFrame encoding where each slice in the constarined picture is independent of other slices
1166 Check support for constrained encoding using ::NV_ENC_CAPS_SUPPORT_CONSTRAINED_ENCODING caps. */
1167 uint32_t repeatSPSPPS :1; /**< [in]: Set to 1 to enable writing of Sequence and Picture parameter for every IDR frame */
1168 uint32_t enableVFR :1; /**< [in]: Set to 1 to enable variable frame rate. */
1169 uint32_t enableLTR :1; /**< [in]: Currently this feature is not available and must be set to 0. Set to 1 to enable LTR support and auto-mark the first */
1170 uint32_t qpPrimeYZeroTransformBypassFlag :1; /**< [in]: To enable lossless encode set this to 1, set QP to 0 and RC_mode to NV_ENC_PARAMS_RC_CONSTQP and profile to HIGH_444_PREDICTIVE_PROFILE.
1171 Check support for lossless encoding using ::NV_ENC_CAPS_SUPPORT_LOSSLESS_ENCODE caps. */
1172 uint32_t useConstrainedIntraPred :1; /**< [in]: Set 1 to enable constrained intra prediction. */
1173 uint32_t reservedBitFields :15; /**< [in]: Reserved bitfields and must be set to 0 */
1174 uint32_t level; /**< [in]: Specifies the encoding level. Client is recommended to set this to NV_ENC_LEVEL_AUTOSELECT in order to enable the NvEncodeAPI interface to select the correct level. */
1175 uint32_t idrPeriod; /**< [in]: Specifies the IDR interval. If not set, this is made equal to gopLength in NV_ENC_CONFIG.Low latency application client can set IDR interval to NVENC_INFINITE_GOPLENGTH so that IDR frames are not inserted automatically. */
1176 uint32_t separateColourPlaneFlag; /**< [in]: Set to 1 to enable 4:4:4 separate colour planes */
1177 uint32_t disableDeblockingFilterIDC; /**< [in]: Specifies the deblocking filter mode. Permissible value range: [0,2] */
1178 uint32_t numTemporalLayers; /**< [in]: Specifies max temporal layers to be used for hierarchical coding. Valid value range is [1,::NV_ENC_CAPS_NUM_MAX_TEMPORAL_LAYERS] */
1179 uint32_t spsId; /**< [in]: Specifies the SPS id of the sequence header. Currently reserved and must be set to 0. */
1180 uint32_t ppsId; /**< [in]: Specifies the PPS id of the picture header. Currently reserved and must be set to 0. */
1181 NV_ENC_H264_ADAPTIVE_TRANSFORM_MODE adaptiveTransformMode; /**< [in]: Specifies the AdaptiveTransform Mode. Check support for AdaptiveTransform mode using ::NV_ENC_CAPS_SUPPORT_ADAPTIVE_TRANSFORM caps. */
1182 NV_ENC_H264_FMO_MODE fmoMode; /**< [in]: Specified the FMO Mode. Check support for FMO using ::NV_ENC_CAPS_SUPPORT_FMO caps. */
1183 NV_ENC_H264_BDIRECT_MODE bdirectMode; /**< [in]: Specifies the BDirect mode. Check support for BDirect mode using ::NV_ENC_CAPS_SUPPORT_BDIRECT_MODE caps.*/
1184 NV_ENC_H264_ENTROPY_CODING_MODE entropyCodingMode; /**< [in]: Specifies the entropy coding mode. Check support for CABAC mode using ::NV_ENC_CAPS_SUPPORT_CABAC caps. */
1185 NV_ENC_STEREO_PACKING_MODE stereoMode; /**< [in]: Specifies the stereo frame packing mode which is to be signalled in frame packing arrangement SEI */
1186 uint32_t intraRefreshPeriod; /**< [in]: Specifies the interval between successive intra refresh if enableIntrarefresh is set. Requires enableIntraRefresh to be set.
1187 Will be disabled if NV_ENC_CONFIG::gopLength is not set to NVENC_INFINITE_GOPLENGTH. */
1188 uint32_t intraRefreshCnt; /**< [in]: Specifies the length of intra refresh in number of frames for periodic intra refresh. This value should be smaller than intraRefreshPeriod */
1189 uint32_t maxNumRefFrames; /**< [in]: Specifies the DPB size used for encoding. Setting it to 0 will let driver use the default dpb size.
1190 The low latency application which wants to invalidate reference frame as an error resilience tool
1191 is recommended to use a large DPB size so that the encoder can keep old reference frames which can be used if recent
1192 frames are invalidated. */
1193 uint32_t sliceMode; /**< [in]: This parameter in conjunction with sliceModeData specifies the way in which the picture is divided into slices
1194 sliceMode = 0 MB based slices, sliceMode = 1 Byte based slices, sliceMode = 2 MB row based slices, sliceMode = 3, numSlices in Picture
1195 When forceIntraRefreshWithFrameCnt is set it will have priority over sliceMode setting
1196 When sliceMode == 0 and sliceModeData == 0 whole picture will be coded with one slice */
1197 uint32_t sliceModeData; /**< [in]: Specifies the parameter needed for sliceMode. For:
1198 sliceMode = 0, sliceModeData specifies # of MBs in each slice (except last slice)
1199 sliceMode = 1, sliceModeData specifies maximum # of bytes in each slice (except last slice)
1200 sliceMode = 2, sliceModeData specifies # of MB rows in each slice (except last slice)
1201 sliceMode = 3, sliceModeData specifies number of slices in the picture. Driver will divide picture into slices optimally */
1202 NV_ENC_CONFIG_H264_VUI_PARAMETERS h264VUIParameters; /**< [in]: Specifies the H264 video usability info pamameters */
1203 uint32_t ltrNumFrames; /**< [in]: Specifies the number of LTR frames used.
1204 If ltrTrustMode=1, encoder will mark first numLTRFrames base layer reference frames within each IDR interval as LTR.
1205 If ltrMarkFrame=1, ltrNumFrames specifies maximum number of ltr frames in DPB.
1206 If ltrNumFrames value is more that DPB size(maxNumRefFrames) encoder will take decision on its own. */
1207 uint32_t ltrTrustMode; /**< [in]: Specifies the LTR operating mode.
1208 Set to 0 to disallow encoding using LTR frames until later specified.
1209 Set to 1 to allow encoding using LTR frames unless later invalidated.*/
1210 uint32_t chromaFormatIDC; /**< [in]: Specifies the chroma format. Should be set to 1 for yuv420 input, 3 for yuv444 input.
1211 Check support for YUV444 encoding using ::NV_ENC_CAPS_SUPPORT_YUV444_ENCODE caps.*/
1212 uint32_t maxTemporalLayers; /**< [in]: Specifies the max temporal layer used for hierarchical coding. */
1213 uint32_t reserved1[270]; /**< [in]: Reserved and must be set to 0 */
1214 void* reserved2[64]; /**< [in]: Reserved and must be set to NULL */
1215 } NV_ENC_CONFIG_H264;
1219 * \struct _NV_ENC_CONFIG_HEVC
1220 * HEVC encoder configuration parameters to be set during initialization.
1222 typedef struct _NV_ENC_CONFIG_HEVC
1224 uint32_t level; /**< [in]: Specifies the level of the encoded bitstream.*/
1225 uint32_t tier; /**< [in]: Specifies the level tier of the encoded bitstream.*/
1226 NV_ENC_HEVC_CUSIZE minCUSize; /**< [in]: Specifies the minimum size of luma coding unit.*/
1227 NV_ENC_HEVC_CUSIZE maxCUSize; /**< [in]: Specifies the maximum size of luma coding unit. Currently NVENC SDK only supports maxCUSize equal to NV_ENC_HEVC_CUSIZE_32x32.*/
1228 uint32_t useConstrainedIntraPred :1; /**< [in]: Set 1 to enable constrained intra prediction. */
1229 uint32_t disableDeblockAcrossSliceBoundary :1; /**< [in]: Set 1 to disable in loop filtering across slice boundary.*/
1230 uint32_t outputBufferingPeriodSEI :1; /**< [in]: Set 1 to write SEI buffering period syntax in the bitstream */
1231 uint32_t outputPictureTimingSEI :1; /**< [in]: Set 1 to write SEI picture timing syntax in the bitstream */
1232 uint32_t outputAUD :1; /**< [in]: Set 1 to write Access Unit Delimiter syntax. */
1233 uint32_t enableLTR :1; /**< [in]: Set 1 to enable use of long term reference pictures for inter prediction. */
1234 uint32_t disableSPSPPS :1; /**< [in]: Set 1 to disable VPS,SPS and PPS signalling in the bitstream. */
1235 uint32_t repeatSPSPPS :1; /**< [in]: Set 1 to output VPS,SPS and PPS for every IDR frame.*/
1236 uint32_t enableIntraRefresh :1; /**< [in]: Set 1 to enable gradual decoder refresh or intra refresh. If the GOP structure uses B frames this will be ignored */
1237 uint32_t chromaFormatIDC :2; /**< [in]: Specifies the chroma format. Should be set to 1 for yuv420 input, 3 for yuv444 input.*/
1238 uint32_t pixelBitDepthMinus8 :3; /**< [in]: Specifies pixel bit depth minus 8. Should be set to 0 for 8 bit input, 2 for 10 bit input.*/
1239 uint32_t reserved :18; /**< [in]: Reserved bitfields.*/
1240 uint32_t idrPeriod; /**< [in]: Specifies the IDR interval. If not set, this is made equal to gopLength in NV_ENC_CONFIG.Low latency application client can set IDR interval to NVENC_INFINITE_GOPLENGTH so that IDR frames are not inserted automatically. */
1241 uint32_t intraRefreshPeriod; /**< [in]: Specifies the interval between successive intra refresh if enableIntrarefresh is set. Requires enableIntraRefresh to be set.
1242 Will be disabled if NV_ENC_CONFIG::gopLength is not set to NVENC_INFINITE_GOPLENGTH. */
1243 uint32_t intraRefreshCnt; /**< [in]: Specifies the length of intra refresh in number of frames for periodic intra refresh. This value should be smaller than intraRefreshPeriod */
1244 uint32_t maxNumRefFramesInDPB; /**< [in]: Specifies the maximum number of references frames in the DPB.*/
1245 uint32_t ltrNumFrames; /**< [in]: Specifies the number of LTR frames used.
1246 If ltrTrustMode=1, encoder will mark first numLTRFrames base layer reference frames within each IDR interval as LTR.
1247 If ltrMarkFrame=1, ltrNumFrames specifies maximum number of ltr frames in DPB.
1248 If ltrNumFrames value is more that DPB size(maxNumRefFramesInDPB) encoder will take decision on its own. */
1249 uint32_t vpsId; /**< [in]: Specifies the VPS id of the video parameter set. Currently reserved and must be set to 0. */
1250 uint32_t spsId; /**< [in]: Specifies the SPS id of the sequence header. Currently reserved and must be set to 0. */
1251 uint32_t ppsId; /**< [in]: Specifies the PPS id of the picture header. Currently reserved and must be set to 0. */
1252 uint32_t sliceMode; /**< [in]: This parameter in conjunction with sliceModeData specifies the way in which the picture is divided into slices
1253 sliceMode = 0 CTU based slices, sliceMode = 1 Byte based slices, sliceMode = 2 CTU row based slices, sliceMode = 3, numSlices in Picture
1254 When sliceMode == 0 and sliceModeData == 0 whole picture will be coded with one slice */
1255 uint32_t sliceModeData; /**< [in]: Specifies the parameter needed for sliceMode. For:
1256 sliceMode = 0, sliceModeData specifies # of CTUs in each slice (except last slice)
1257 sliceMode = 1, sliceModeData specifies maximum # of bytes in each slice (except last slice)
1258 sliceMode = 2, sliceModeData specifies # of CTU rows in each slice (except last slice)
1259 sliceMode = 3, sliceModeData specifies number of slices in the picture. Driver will divide picture into slices optimally */
1260 uint32_t maxTemporalLayersMinus1; /**< [in]: Specifies the max temporal layer used for hierarchical coding. */
1261 NV_ENC_CONFIG_HEVC_VUI_PARAMETERS hevcVUIParameters; /**< [in]: Specifies the HEVC video usability info pamameters */
1262 uint32_t ltrTrustMode; /**< [in]: Specifies the LTR operating mode.
1263 Set to 0 to disallow encoding using LTR frames until later specified.
1264 Set to 1 to allow encoding using LTR frames unless later invalidated.*/
1265 uint32_t reserved1[217]; /**< [in]: Reserved and must be set to 0.*/
1266 void* reserved2[64]; /**< [in]: Reserved and must be set to NULL */
1267 } NV_ENC_CONFIG_HEVC;
1270 * \struct _NV_ENC_CODEC_CONFIG
1271 * Codec-specific encoder configuration parameters to be set during initialization.
1273 typedef union _NV_ENC_CODEC_CONFIG
1275 NV_ENC_CONFIG_H264 h264Config; /**< [in]: Specifies the H.264-specific encoder configuration. */
1276 NV_ENC_CONFIG_HEVC hevcConfig; /**< [in]: Specifies the HEVC-specific encoder configuration. */
1277 uint32_t reserved[256]; /**< [in]: Reserved and must be set to 0 */
1278 } NV_ENC_CODEC_CONFIG;
1282 * \struct _NV_ENC_CONFIG
1283 * Encoder configuration parameters to be set during initialization.
1285 typedef struct _NV_ENC_CONFIG
1287 uint32_t version; /**< [in]: Struct version. Must be set to ::NV_ENC_CONFIG_VER. */
1288 GUID profileGUID; /**< [in]: Specifies the codec profile guid. If client specifies \p NV_ENC_CODEC_PROFILE_AUTOSELECT_GUID the NvEncodeAPI interface will select the appropriate codec profile. */
1289 uint32_t gopLength; /**< [in]: Specifies the number of pictures in one GOP. Low latency application client can set goplength to NVENC_INFINITE_GOPLENGTH so that keyframes are not inserted automatically. */
1290 int32_t frameIntervalP; /**< [in]: Specifies the GOP pattern as follows: \p frameIntervalP = 0: I, 1: IPP, 2: IBP, 3: IBBP If goplength is set to NVENC_INFINITE_GOPLENGTH \p frameIntervalP should be set to 1. */
1291 uint32_t monoChromeEncoding; /**< [in]: Set this to 1 to enable monochrome encoding for this session. */
1292 NV_ENC_PARAMS_FRAME_FIELD_MODE frameFieldMode; /**< [in]: Specifies the frame/field mode.
1293 Check support for field encoding using ::NV_ENC_CAPS_SUPPORT_FIELD_ENCODING caps.
1294 Using a frameFieldMode other than NV_ENC_PARAMS_FRAME_FIELD_MODE_FRAME for RGB input is not supported. */
1295 NV_ENC_MV_PRECISION mvPrecision; /**< [in]: Specifies the desired motion vector prediction precision. */
1296 NV_ENC_RC_PARAMS rcParams; /**< [in]: Specifies the rate control parameters for the current encoding session. */
1297 NV_ENC_CODEC_CONFIG encodeCodecConfig; /**< [in]: Specifies the codec specific config parameters through this union. */
1298 uint32_t reserved [278]; /**< [in]: Reserved and must be set to 0 */
1299 void* reserved2[64]; /**< [in]: Reserved and must be set to NULL */
1302 /** macro for constructing the version field of ::_NV_ENC_CONFIG */
1303 #define NV_ENC_CONFIG_VER (NVENCAPI_STRUCT_VERSION(6) | ( 1<<31 ))
1307 * \struct _NV_ENC_INITIALIZE_PARAMS
1308 * Encode Session Initialization parameters.
1310 typedef struct _NV_ENC_INITIALIZE_PARAMS
1312 uint32_t version; /**< [in]: Struct version. Must be set to ::NV_ENC_INITIALIZE_PARAMS_VER. */
1313 GUID encodeGUID; /**< [in]: Specifies the Encode GUID for which the encoder is being created. ::NvEncInitializeEncoder() API will fail if this is not set, or set to unsupported value. */
1314 GUID presetGUID; /**< [in]: Specifies the preset for encoding. If the preset GUID is set then , the preset configuration will be applied before any other parameter. */
1315 uint32_t encodeWidth; /**< [in]: Specifies the encode width. If not set ::NvEncInitializeEncoder() API will fail. */
1316 uint32_t encodeHeight; /**< [in]: Specifies the encode height. If not set ::NvEncInitializeEncoder() API will fail. */
1317 uint32_t darWidth; /**< [in]: Specifies the display aspect ratio Width. */
1318 uint32_t darHeight; /**< [in]: Specifies the display aspect ratio height. */
1319 uint32_t frameRateNum; /**< [in]: Specifies the numerator for frame rate used for encoding in frames per second ( Frame rate = frameRateNum / frameRateDen ). */
1320 uint32_t frameRateDen; /**< [in]: Specifies the denominator for frame rate used for encoding in frames per second ( Frame rate = frameRateNum / frameRateDen ). */
1321 uint32_t enableEncodeAsync; /**< [in]: Set this to 1 to enable asynchronous mode and is expected to use events to get picture completion notification. */
1322 uint32_t enablePTD; /**< [in]: Set this to 1 to enable the Picture Type Decision is be taken by the NvEncodeAPI interface. */
1323 uint32_t reportSliceOffsets :1; /**< [in]: Set this to 1 to enable reporting slice offsets in ::_NV_ENC_LOCK_BITSTREAM. NV_ENC_INITIALIZE_PARAMS::enableEncodeAsync must be set to 0 to use this feature. Client must set this to 0 if NV_ENC_CONFIG_H264::sliceMode is 1 on Kepler GPUs */
1324 uint32_t enableSubFrameWrite :1; /**< [in]: Set this to 1 to write out available bitstream to memory at subframe intervals */
1325 uint32_t enableExternalMEHints :1; /**< [in]: Set to 1 to enable external ME hints for the current frame. For NV_ENC_INITIALIZE_PARAMS::enablePTD=1 with B frames, programming L1 hints is optional for B frames since Client doesn't know internal GOP structure.
1326 NV_ENC_PIC_PARAMS::meHintRefPicDist should preferably be set with enablePTD=1. */
1327 uint32_t enableMEOnlyMode :1; /**< [in]: Set to 1 to enable ME Only Mode .*/
1328 uint32_t reservedBitFields :28; /**< [in]: Reserved bitfields and must be set to 0 */
1329 uint32_t privDataSize; /**< [in]: Reserved private data buffer size and must be set to 0 */
1330 void* privData; /**< [in]: Reserved private data buffer and must be set to NULL */
1331 NV_ENC_CONFIG* encodeConfig; /**< [in]: Specifies the advanced codec specific structure. If client has sent a valid codec config structure, it will override parameters set by the NV_ENC_INITIALIZE_PARAMS::presetGUID parameter. If set to NULL the NvEncodeAPI interface will use the NV_ENC_INITIALIZE_PARAMS::presetGUID to set the codec specific parameters.
1332 Client can also optionally query the NvEncodeAPI interface to get codec specific parameters for a presetGUID using ::NvEncGetEncodePresetConfig() API. It can then modify (if required) some of the codec config parameters and send down a custom config structure as part of ::_NV_ENC_INITIALIZE_PARAMS.
1333 Even in this case client is recommended to pass the same preset guid it has used in ::NvEncGetEncodePresetConfig() API to query the config structure; as NV_ENC_INITIALIZE_PARAMS::presetGUID. This will not override the custom config structure but will be used to determine other Encoder HW specific parameters not exposed in the API. */
1334 uint32_t maxEncodeWidth; /**< [in]: Maximum encode width to be used for current Encode session.
1335 Client should allocate output buffers according to this dimension for dynamic resolution change. If set to 0, Encoder will not allow dynamic resolution change. */
1336 uint32_t maxEncodeHeight; /**< [in]: Maximum encode height to be allowed for current Encode session.
1337 Client should allocate output buffers according to this dimension for dynamic resolution change. If set to 0, Encode will not allow dynamic resolution change. */
1338 NVENC_EXTERNAL_ME_HINT_COUNTS_PER_BLOCKTYPE maxMEHintCountsPerBlock[2]; /**< [in]: If Client wants to pass external motion vectors in NV_ENC_PIC_PARAMS::meExternalHints buffer it must specify the maximum number of hint candidates per block per direction for the encode session.
1339 The NV_ENC_INITIALIZE_PARAMS::maxMEHintCountsPerBlock[0] is for L0 predictors and NV_ENC_INITIALIZE_PARAMS::maxMEHintCountsPerBlock[1] is for L1 predictors.
1340 This client must also set NV_ENC_INITIALIZE_PARAMS::enableExternalMEHints to 1. */
1341 uint32_t reserved [289]; /**< [in]: Reserved and must be set to 0 */
1342 void* reserved2[64]; /**< [in]: Reserved and must be set to NULL */
1343 } NV_ENC_INITIALIZE_PARAMS;
1345 /** macro for constructing the version field of ::_NV_ENC_INITIALIZE_PARAMS */
1346 #define NV_ENC_INITIALIZE_PARAMS_VER (NVENCAPI_STRUCT_VERSION(5) | ( 1<<31 ))
1350 * \struct _NV_ENC_RECONFIGURE_PARAMS
1351 * Encode Session Reconfigured parameters.
1353 typedef struct _NV_ENC_RECONFIGURE_PARAMS
1355 uint32_t version; /**< [in]: Struct version. Must be set to ::NV_ENC_RECONFIGURE_PARAMS_VER. */
1356 NV_ENC_INITIALIZE_PARAMS reInitEncodeParams; /**< [in]: Encoder session re-initialization parameters. */
1357 uint32_t resetEncoder :1; /**< [in]: This resets the rate control states and other internal encoder states. This should be used only with an IDR frame.
1358 If NV_ENC_INITIALIZE_PARAMS::enablePTD is set to 1, encoder will force the frame type to IDR */
1359 uint32_t forceIDR :1; /**< [in]: Encode the current picture as an IDR picture. This flag is only valid when Picture type decision is taken by the Encoder
1360 [_NV_ENC_INITIALIZE_PARAMS::enablePTD == 1]. */
1361 uint32_t reserved :30;
1363 }NV_ENC_RECONFIGURE_PARAMS;
1365 /** macro for constructing the version field of ::_NV_ENC_RECONFIGURE_PARAMS */
1366 #define NV_ENC_RECONFIGURE_PARAMS_VER (NVENCAPI_STRUCT_VERSION(1) | ( 1<<31 ))
1369 * \struct _NV_ENC_PRESET_CONFIG
1370 * Encoder preset config
1372 typedef struct _NV_ENC_PRESET_CONFIG
1374 uint32_t version; /**< [in]: Struct version. Must be set to ::NV_ENC_PRESET_CONFIG_VER. */
1375 NV_ENC_CONFIG presetCfg; /**< [out]: preset config returned by the Nvidia Video Encoder interface. */
1376 uint32_t reserved1[255]; /**< [in]: Reserved and must be set to 0 */
1377 void* reserved2[64]; /**< [in]: Reserved and must be set to NULL */
1378 }NV_ENC_PRESET_CONFIG;
1380 /** macro for constructing the version field of ::_NV_ENC_PRESET_CONFIG */
1381 #define NV_ENC_PRESET_CONFIG_VER (NVENCAPI_STRUCT_VERSION(4) | ( 1<<31 ))
1385 * \struct _NV_ENC_SEI_PAYLOAD
1388 typedef struct _NV_ENC_SEI_PAYLOAD
1390 uint32_t payloadSize; /**< [in] SEI payload size in bytes. SEI payload must be byte aligned, as described in Annex D */
1391 uint32_t payloadType; /**< [in] SEI payload types and syntax can be found in Annex D of the H.264 Specification. */
1392 uint8_t *payload; /**< [in] pointer to user data */
1393 } NV_ENC_SEI_PAYLOAD;
1395 #define NV_ENC_H264_SEI_PAYLOAD NV_ENC_SEI_PAYLOAD
1398 * \struct _NV_ENC_PIC_PARAMS_H264
1399 * H264 specific enc pic params. sent on a per frame basis.
1401 typedef struct _NV_ENC_PIC_PARAMS_H264
1403 uint32_t displayPOCSyntax; /**< [in]: Specifies the display POC syntax This is required to be set if client is handling the picture type decision. */
1404 uint32_t reserved3; /**< [in]: Reserved and must be set to 0 */
1405 uint32_t refPicFlag; /**< [in]: Set to 1 for a reference picture. This is ignored if NV_ENC_INITIALIZE_PARAMS::enablePTD is set to 1. */
1406 uint32_t colourPlaneId; /**< [in]: Specifies the colour plane ID associated with the current input. */
1407 uint32_t forceIntraRefreshWithFrameCnt; /**< [in]: Forces an intra refresh with duration equal to intraRefreshFrameCnt.
1408 When outputRecoveryPointSEI is set this is value is used for recovery_frame_cnt in recovery point SEI message
1409 forceIntraRefreshWithFrameCnt cannot be used if B frames are used in the GOP structure specified */
1410 uint32_t constrainedFrame :1; /**< [in]: Set to 1 if client wants to encode this frame with each slice completely independent of other slices in the frame.
1411 NV_ENC_INITIALIZE_PARAMS::enableConstrainedEncoding should be set to 1 */
1412 uint32_t sliceModeDataUpdate :1; /**< [in]: Set to 1 if client wants to change the sliceModeData field to specify new sliceSize Parameter
1413 When forceIntraRefreshWithFrameCnt is set it will have priority over sliceMode setting */
1414 uint32_t ltrMarkFrame :1; /**< [in]: Set to 1 if client wants to mark this frame as LTR */
1415 uint32_t ltrUseFrames :1; /**< [in]: Set to 1 if client allows encoding this frame using the LTR frames specified in ltrFrameBitmap */
1416 uint32_t reservedBitFields :28; /**< [in]: Reserved bit fields and must be set to 0 */
1417 uint8_t* sliceTypeData; /**< [in]: Deprecated. */
1418 uint32_t sliceTypeArrayCnt; /**< [in]: Deprecated. */
1419 uint32_t seiPayloadArrayCnt; /**< [in]: Specifies the number of elements allocated in seiPayloadArray array. */
1420 NV_ENC_SEI_PAYLOAD* seiPayloadArray; /**< [in]: Array of SEI payloads which will be inserted for this frame. */
1421 uint32_t sliceMode; /**< [in]: This parameter in conjunction with sliceModeData specifies the way in which the picture is divided into slices
1422 sliceMode = 0 MB based slices, sliceMode = 1 Byte based slices, sliceMode = 2 MB row based slices, sliceMode = 3, numSlices in Picture
1423 When forceIntraRefreshWithFrameCnt is set it will have priority over sliceMode setting
1424 When sliceMode == 0 and sliceModeData == 0 whole picture will be coded with one slice */
1425 uint32_t sliceModeData; /**< [in]: Specifies the parameter needed for sliceMode. For:
1426 sliceMode = 0, sliceModeData specifies # of MBs in each slice (except last slice)
1427 sliceMode = 1, sliceModeData specifies maximum # of bytes in each slice (except last slice)
1428 sliceMode = 2, sliceModeData specifies # of MB rows in each slice (except last slice)
1429 sliceMode = 3, sliceModeData specifies number of slices in the picture. Driver will divide picture into slices optimally */
1430 uint32_t ltrMarkFrameIdx; /**< [in]: Specifies the long term referenceframe index to use for marking this frame as LTR.*/
1431 uint32_t ltrUseFrameBitmap; /**< [in]: Specifies the the associated bitmap of LTR frame indices when encoding this frame. */
1432 uint32_t ltrUsageMode; /**< [in]: Specifies additional usage constraints for encoding using LTR frames from this point further. 0: no constraints, 1: no short term refs older than current, no previous LTR frames.*/
1433 uint32_t reserved [243]; /**< [in]: Reserved and must be set to 0. */
1434 void* reserved2[62]; /**< [in]: Reserved and must be set to NULL. */
1435 } NV_ENC_PIC_PARAMS_H264;
1438 * \struct _NV_ENC_PIC_PARAMS_HEVC
1439 * HEVC specific enc pic params. sent on a per frame basis.
1441 typedef struct _NV_ENC_PIC_PARAMS_HEVC
1443 uint32_t displayPOCSyntax; /**< [in]: Specifies the display POC syntax This is required to be set if client is handling the picture type decision. */
1444 uint32_t refPicFlag; /**< [in]: Set to 1 for a reference picture. This is ignored if NV_ENC_INITIALIZE_PARAMS::enablePTD is set to 1. */
1445 uint32_t temporalId; /**< [in]: Specifies the temporal id of the picture */
1446 uint32_t forceIntraRefreshWithFrameCnt; /**< [in]: Forces an intra refresh with duration equal to intraRefreshFrameCnt.
1447 When outputRecoveryPointSEI is set this is value is used for recovery_frame_cnt in recovery point SEI message
1448 forceIntraRefreshWithFrameCnt cannot be used if B frames are used in the GOP structure specified */
1449 uint32_t constrainedFrame :1; /**< [in]: Set to 1 if client wants to encode this frame with each slice completely independent of other slices in the frame.
1450 NV_ENC_INITIALIZE_PARAMS::enableConstrainedEncoding should be set to 1 */
1451 uint32_t sliceModeDataUpdate :1; /**< [in]: Set to 1 if client wants to change the sliceModeData field to specify new sliceSize Parameter
1452 When forceIntraRefreshWithFrameCnt is set it will have priority over sliceMode setting */
1453 uint32_t ltrMarkFrame :1; /**< [in]: Set to 1 if client wants to mark this frame as LTR */
1454 uint32_t ltrUseFrames :1; /**< [in]: Set to 1 if client allows encoding this frame using the LTR frames specified in ltrFrameBitmap */
1455 uint32_t reservedBitFields :28; /**< [in]: Reserved bit fields and must be set to 0 */
1456 uint8_t* sliceTypeData; /**< [in]: Array which specifies the slice type used to force intra slice for a particular slice. Currently supported only for NV_ENC_CONFIG_H264::sliceMode == 3.
1457 Client should allocate array of size sliceModeData where sliceModeData is specified in field of ::_NV_ENC_CONFIG_H264
1458 Array element with index n corresponds to nth slice. To force a particular slice to intra client should set corresponding array element to NV_ENC_SLICE_TYPE_I
1459 all other array elements should be set to NV_ENC_SLICE_TYPE_DEFAULT */
1460 uint32_t sliceTypeArrayCnt; /**< [in]: Client should set this to the number of elements allocated in sliceTypeData array. If sliceTypeData is NULL then this should be set to 0 */
1461 uint32_t sliceMode; /**< [in]: This parameter in conjunction with sliceModeData specifies the way in which the picture is divided into slices
1462 sliceMode = 0 CTU based slices, sliceMode = 1 Byte based slices, sliceMode = 2 CTU row based slices, sliceMode = 3, numSlices in Picture
1463 When forceIntraRefreshWithFrameCnt is set it will have priority over sliceMode setting
1464 When sliceMode == 0 and sliceModeData == 0 whole picture will be coded with one slice */
1465 uint32_t sliceModeData; /**< [in]: Specifies the parameter needed for sliceMode. For:
1466 sliceMode = 0, sliceModeData specifies # of CTUs in each slice (except last slice)
1467 sliceMode = 1, sliceModeData specifies maximum # of bytes in each slice (except last slice)
1468 sliceMode = 2, sliceModeData specifies # of CTU rows in each slice (except last slice)
1469 sliceMode = 3, sliceModeData specifies number of slices in the picture. Driver will divide picture into slices optimally */
1470 uint32_t ltrMarkFrameIdx; /**< [in]: Specifies the long term reference frame index to use for marking this frame as LTR.*/
1471 uint32_t ltrUseFrameBitmap; /**< [in]: Specifies the associated bitmap of LTR frame indices when encoding this frame. */
1472 uint32_t ltrUsageMode; /**< [in]: Specifies additional usage constraints for encoding using LTR frames from this point further. 0: no constraints, 1: no short term refs older than current, no previous LTR frames.*/
1473 uint32_t seiPayloadArrayCnt; /**< [in]: Specifies the number of elements allocated in seiPayloadArray array. */
1474 uint32_t reserved; /**< [in]: Reserved and must be set to 0. */
1475 NV_ENC_SEI_PAYLOAD* seiPayloadArray; /**< [in]: Array of SEI payloads which will be inserted for this frame. */
1476 uint32_t reserved2 [244]; /**< [in]: Reserved and must be set to 0. */
1477 void* reserved3[61]; /**< [in]: Reserved and must be set to NULL. */
1478 } NV_ENC_PIC_PARAMS_HEVC;
1482 * Codec specific per-picture encoding parameters.
1484 typedef union _NV_ENC_CODEC_PIC_PARAMS
1486 NV_ENC_PIC_PARAMS_H264 h264PicParams; /**< [in]: H264 encode picture params. */
1487 NV_ENC_PIC_PARAMS_HEVC hevcPicParams; /**< [in]: HEVC encode picture params. Currently unsupported and must not to be used. */
1488 uint32_t reserved[256]; /**< [in]: Reserved and must be set to 0. */
1489 } NV_ENC_CODEC_PIC_PARAMS;
1492 * \struct _NV_ENC_PIC_PARAMS
1493 * Encoding parameters that need to be sent on a per frame basis.
1495 typedef struct _NV_ENC_PIC_PARAMS
1497 uint32_t version; /**< [in]: Struct version. Must be set to ::NV_ENC_PIC_PARAMS_VER. */
1498 uint32_t inputWidth; /**< [in]: Specifies the input buffer width */
1499 uint32_t inputHeight; /**< [in]: Specifies the input buffer height */
1500 uint32_t inputPitch; /**< [in]: Specifies the input buffer pitch. If pitch value is not known, set this to inputWidth. */
1501 uint32_t encodePicFlags; /**< [in]: Specifies bit-wise OR`ed encode pic flags. See ::NV_ENC_PIC_FLAGS enum. */
1502 uint32_t frameIdx; /**< [in]: Specifies the frame index associated with the input frame [optional]. */
1503 uint64_t inputTimeStamp; /**< [in]: Specifies presentation timestamp associated with the input picture. */
1504 uint64_t inputDuration; /**< [in]: Specifies duration of the input picture */
1505 NV_ENC_INPUT_PTR inputBuffer; /**< [in]: Specifies the input buffer pointer. Client must use a pointer obtained from ::NvEncCreateInputBuffer() or ::NvEncMapInputResource() APIs.*/
1506 NV_ENC_OUTPUT_PTR outputBitstream; /**< [in]: Specifies the pointer to output buffer. Client should use a pointer obtained from ::NvEncCreateBitstreamBuffer() API. */
1507 void* completionEvent; /**< [in]: Specifies an event to be signalled on completion of encoding of this Frame [only if operating in Asynchronous mode]. Each output buffer should be associated with a distinct event pointer. */
1508 NV_ENC_BUFFER_FORMAT bufferFmt; /**< [in]: Specifies the input buffer format. */
1509 NV_ENC_PIC_STRUCT pictureStruct; /**< [in]: Specifies structure of the input picture. */
1510 NV_ENC_PIC_TYPE pictureType; /**< [in]: Specifies input picture type. Client required to be set explicitly by the client if the client has not set NV_ENC_INITALIZE_PARAMS::enablePTD to 1 while calling NvInitializeEncoder. */
1511 NV_ENC_CODEC_PIC_PARAMS codecPicParams; /**< [in]: Specifies the codec specific per-picture encoding parameters. */
1512 NVENC_EXTERNAL_ME_HINT_COUNTS_PER_BLOCKTYPE meHintCountsPerBlock[2]; /**< [in]: Specifies the number of hint candidates per block per direction for the current frame. meHintCountsPerBlock[0] is for L0 predictors and meHintCountsPerBlock[1] is for L1 predictors.
1513 The candidate count in NV_ENC_PIC_PARAMS::meHintCountsPerBlock[lx] must never exceed NV_ENC_INITIALIZE_PARAMS::maxMEHintCountsPerBlock[lx] provided during encoder intialization. */
1514 NVENC_EXTERNAL_ME_HINT *meExternalHints; /**< [in]: Specifies the pointer to ME external hints for the current frame. The size of ME hint buffer should be equal to number of macroblocks multiplied by the total number of candidates per macroblock.
1515 The total number of candidates per MB per direction = 1*meHintCountsPerBlock[Lx].numCandsPerBlk16x16 + 2*meHintCountsPerBlock[Lx].numCandsPerBlk16x8 + 2*meHintCountsPerBlock[Lx].numCandsPerBlk8x8
1516 + 4*meHintCountsPerBlock[Lx].numCandsPerBlk8x8. For frames using bidirectional ME , the total number of candidates for single macroblock is sum of total number of candidates per MB for each direction (L0 and L1) */
1517 uint32_t reserved1[6]; /**< [in]: Reserved and must be set to 0 */
1518 void* reserved2[2]; /**< [in]: Reserved and must be set to NULL */
1519 int8_t *qpDeltaMap; /**< [in]: Specifies the pointer to signed byte array containing QP delta value per MB in raster scan order in the current picture. This QP modifier is applied on top of the QP chosen by rate control. */
1520 uint32_t qpDeltaMapSize; /**< [in]: Specifies the size in bytes of qpDeltaMap surface allocated by client and pointed to by NV_ENC_PIC_PARAMS::qpDeltaMap. Surface (array) should be picWidthInMbs * picHeightInMbs */
1521 uint32_t reservedBitFields; /**< [in]: Reserved bitfields and must be set to 0 */
1522 uint16_t meHintRefPicDist[2]; /**< [in]: Specifies temporal distance for reference picture (NVENC_EXTERNAL_ME_HINT::refidx = 0) used during external ME with NV_ENC_INITALIZE_PARAMS::enablePTD = 1 . meHintRefPicDist[0] is for L0 hints and meHintRefPicDist[1] is for L1 hints.
1523 If not set, will internally infer distance of 1. Ignored for NV_ENC_INITALIZE_PARAMS::enablePTD = 0 */
1524 uint32_t reserved3[286]; /**< [in]: Reserved and must be set to 0 */
1525 void* reserved4[60]; /**< [in]: Reserved and must be set to NULL */
1526 } NV_ENC_PIC_PARAMS;
1528 /** Macro for constructing the version field of ::_NV_ENC_PIC_PARAMS */
1529 #define NV_ENC_PIC_PARAMS_VER (NVENCAPI_STRUCT_VERSION(4) | ( 1<<31 ))
1533 * \struct _NV_ENC_MEONLY_PARAMS
1534 * MEOnly parameters that need to be sent on a per motion estimation basis.
1536 typedef struct _NV_ENC_MEONLY_PARAMS
1538 uint32_t version; /**< [in]: Struct version. Must be set to NV_ENC_MEONLY_PARAMS_VER.*/
1539 uint32_t inputWidth; /**< [in]: Specifies the input buffer width */
1540 uint32_t inputHeight; /**< [in]: Specifies the input buffer height */
1541 NV_ENC_INPUT_PTR inputBuffer; /**< [in]: Specifies the input buffer pointer. Client must use a pointer obtained from NvEncCreateInputBuffer() or NvEncMapInputResource() APIs. */
1542 NV_ENC_INPUT_PTR referenceFrame; /**< [in]: Specifies the reference frame pointer */
1543 NV_ENC_OUTPUT_PTR mvBuffer; /**< [in]: Specifies the pointer to motion vector data buffer allocated by NvEncCreateMVBuffer. Client must lock mvBuffer using ::NvEncLockBitstream() API to get the motion vector data. */
1544 NV_ENC_BUFFER_FORMAT bufferFmt; /**< [in]: Specifies the input buffer format. */
1545 void* completionEvent; /**< [in]: Specifies an event to be signalled on completion of motion estimation
1546 of this Frame [only if operating in Asynchronous mode].
1547 Each output buffer should be associated with a distinct event pointer. */
1548 uint32_t reserved1[252]; /**< [in]: Reserved and must be set to 0 */
1549 void* reserved2[60]; /**< [in]: Reserved and must be set to NULL */
1550 } NV_ENC_MEONLY_PARAMS;
1552 /** NV_ENC_MEONLY_PARAMS struct version*/
1553 #define NV_ENC_MEONLY_PARAMS_VER NVENCAPI_STRUCT_VERSION(2)
1557 * \struct _NV_ENC_LOCK_BITSTREAM
1558 * Bitstream buffer lock parameters.
1560 typedef struct _NV_ENC_LOCK_BITSTREAM
1562 uint32_t version; /**< [in]: Struct version. Must be set to ::NV_ENC_LOCK_BITSTREAM_VER. */
1563 uint32_t doNotWait :1; /**< [in]: If this flag is set, the NvEncodeAPI interface will return buffer pointer even if operation is not completed. If not set, the call will block until operation completes. */
1564 uint32_t ltrFrame :1; /**< [out]: Flag indicating this frame is marked as LTR frame */
1565 uint32_t reservedBitFields :30; /**< [in]: Reserved bit fields and must be set to 0 */
1566 void* outputBitstream; /**< [in]: Pointer to the bitstream buffer being locked. */
1567 uint32_t* sliceOffsets; /**< [in,out]: Array which receives the slice offsets. This is not supported if NV_ENC_CONFIG_H264::sliceMode is 1 on Kepler GPUs. Array size must be equal to size of frame in MBs. */
1568 uint32_t frameIdx; /**< [out]: Frame no. for which the bitstream is being retrieved. */
1569 uint32_t hwEncodeStatus; /**< [out]: The NvEncodeAPI interface status for the locked picture. */
1570 uint32_t numSlices; /**< [out]: Number of slices in the encoded picture. Will be reported only if NV_ENC_INITIALIZE_PARAMS::reportSliceOffsets set to 1. */
1571 uint32_t bitstreamSizeInBytes; /**< [out]: Actual number of bytes generated and copied to the memory pointed by bitstreamBufferPtr. */
1572 uint64_t outputTimeStamp; /**< [out]: Presentation timestamp associated with the encoded output. */
1573 uint64_t outputDuration; /**< [out]: Presentation duration associates with the encoded output. */
1574 void* bitstreamBufferPtr; /**< [out]: Pointer to the generated output bitstream.
1575 For MEOnly mode _NV_ENC_LOCK_BITSTREAM::bitstreamBufferPtr should be typecast to
1576 NV_ENC_H264_MV_DATA/NV_ENC_HEVC_MV_DATA pointer respectively for H264/HEVC */
1577 NV_ENC_PIC_TYPE pictureType; /**< [out]: Picture type of the encoded picture. */
1578 NV_ENC_PIC_STRUCT pictureStruct; /**< [out]: Structure of the generated output picture. */
1579 uint32_t frameAvgQP; /**< [out]: Average QP of the frame. */
1580 uint32_t frameSatd; /**< [out]: Total SATD cost for whole frame. */
1581 uint32_t ltrFrameIdx; /**< [out]: Frame index associated with this LTR frame. */
1582 uint32_t ltrFrameBitmap; /**< [out]: Bitmap of LTR frames indices which were used for encoding this frame. Value of 0 if no LTR frames were used. */
1583 uint32_t reserved [236]; /**< [in]: Reserved and must be set to 0 */
1584 void* reserved2[64]; /**< [in]: Reserved and must be set to NULL */
1585 } NV_ENC_LOCK_BITSTREAM;
1587 /** Macro for constructing the version field of ::_NV_ENC_LOCK_BITSTREAM */
1588 #define NV_ENC_LOCK_BITSTREAM_VER NVENCAPI_STRUCT_VERSION(1)
1592 * \struct _NV_ENC_LOCK_INPUT_BUFFER
1593 * Uncompressed Input Buffer lock parameters.
1595 typedef struct _NV_ENC_LOCK_INPUT_BUFFER
1597 uint32_t version; /**< [in]: Struct version. Must be set to ::NV_ENC_LOCK_INPUT_BUFFER_VER. */
1598 uint32_t doNotWait :1; /**< [in]: Set to 1 to make ::NvEncLockInputBuffer() a unblocking call. If the encoding is not completed, driver will return ::NV_ENC_ERR_ENCODER_BUSY error code. */
1599 uint32_t reservedBitFields :31; /**< [in]: Reserved bitfields and must be set to 0 */
1600 NV_ENC_INPUT_PTR inputBuffer; /**< [in]: Pointer to the input buffer to be locked, client should pass the pointer obtained from ::NvEncCreateInputBuffer() or ::NvEncMapInputResource API. */
1601 void* bufferDataPtr; /**< [out]: Pointed to the locked input buffer data. Client can only access input buffer using the \p bufferDataPtr. */
1602 uint32_t pitch; /**< [out]: Pitch of the locked input buffer. */
1603 uint32_t reserved1[251]; /**< [in]: Reserved and must be set to 0 */
1604 void* reserved2[64]; /**< [in]: Reserved and must be set to NULL */
1605 } NV_ENC_LOCK_INPUT_BUFFER;
1607 /** Macro for constructing the version field of ::_NV_ENC_LOCK_INPUT_BUFFER */
1608 #define NV_ENC_LOCK_INPUT_BUFFER_VER NVENCAPI_STRUCT_VERSION(1)
1612 * \struct _NV_ENC_MAP_INPUT_RESOURCE
1613 * Map an input resource to a Nvidia Encoder Input Buffer
1615 typedef struct _NV_ENC_MAP_INPUT_RESOURCE
1617 uint32_t version; /**< [in]: Struct version. Must be set to ::NV_ENC_MAP_INPUT_RESOURCE_VER. */
1618 uint32_t subResourceIndex; /**< [in]: Deprecated. Do not use. */
1619 void* inputResource; /**< [in]: Deprecated. Do not use. */
1620 NV_ENC_REGISTERED_PTR registeredResource; /**< [in]: The Registered resource handle obtained by calling NvEncRegisterInputResource. */
1621 NV_ENC_INPUT_PTR mappedResource; /**< [out]: Mapped pointer corresponding to the registeredResource. This pointer must be used in NV_ENC_PIC_PARAMS::inputBuffer parameter in ::NvEncEncodePicture() API. */
1622 NV_ENC_BUFFER_FORMAT mappedBufferFmt; /**< [out]: Buffer format of the outputResource. This buffer format must be used in NV_ENC_PIC_PARAMS::bufferFmt if client using the above mapped resource pointer. */
1623 uint32_t reserved1[251]; /**< [in]: Reserved and must be set to 0. */
1624 void* reserved2[63]; /**< [in]: Reserved and must be set to NULL */
1625 } NV_ENC_MAP_INPUT_RESOURCE;
1627 /** Macro for constructing the version field of ::_NV_ENC_MAP_INPUT_RESOURCE */
1628 #define NV_ENC_MAP_INPUT_RESOURCE_VER NVENCAPI_STRUCT_VERSION(4)
1631 * \struct _NV_ENC_REGISTER_RESOURCE
1632 * Register a resource for future use with the Nvidia Video Encoder Interface.
1634 typedef struct _NV_ENC_REGISTER_RESOURCE
1636 uint32_t version; /**< [in]: Struct version. Must be set to ::NV_ENC_REGISTER_RESOURCE_VER. */
1637 NV_ENC_INPUT_RESOURCE_TYPE resourceType; /**< [in]: Specifies the type of resource to be registered. Supported values are ::NV_ENC_INPUT_RESOURCE_TYPE_DIRECTX, ::NV_ENC_INPUT_RESOURCE_TYPE_CUDADEVICEPTR. */
1638 uint32_t width; /**< [in]: Input buffer Width. */
1639 uint32_t height; /**< [in]: Input buffer Height. */
1640 uint32_t pitch; /**< [in]: Input buffer Pitch. */
1641 uint32_t subResourceIndex; /**< [in]: Subresource Index of the DirectX resource to be registered. Should be set to 0 for other interfaces. */
1642 void* resourceToRegister; /**< [in]: Handle to the resource that is being registered. */
1643 NV_ENC_REGISTERED_PTR registeredResource; /**< [out]: Registered resource handle. This should be used in future interactions with the Nvidia Video Encoder Interface. */
1644 NV_ENC_BUFFER_FORMAT bufferFormat; /**< [in]: Buffer format of resource to be registered. */
1645 uint32_t reserved1[248]; /**< [in]: Reserved and must be set to 0. */
1646 void* reserved2[62]; /**< [in]: Reserved and must be set to NULL. */
1647 } NV_ENC_REGISTER_RESOURCE;
1649 /** Macro for constructing the version field of ::_NV_ENC_REGISTER_RESOURCE */
1650 #define NV_ENC_REGISTER_RESOURCE_VER NVENCAPI_STRUCT_VERSION(3)
1653 * \struct _NV_ENC_STAT
1654 * Encode Stats structure.
1656 typedef struct _NV_ENC_STAT
1658 uint32_t version; /**< [in]: Struct version. Must be set to ::NV_ENC_STAT_VER. */
1659 uint32_t reserved; /**< [in]: Reserved and must be set to 0 */
1660 NV_ENC_OUTPUT_PTR outputBitStream; /**< [out]: Specifies the pointer to output bitstream. */
1661 uint32_t bitStreamSize; /**< [out]: Size of generated bitstream in bytes. */
1662 uint32_t picType; /**< [out]: Picture type of encoded picture. See ::NV_ENC_PIC_TYPE. */
1663 uint32_t lastValidByteOffset; /**< [out]: Offset of last valid bytes of completed bitstream */
1664 uint32_t sliceOffsets[16]; /**< [out]: Offsets of each slice */
1665 uint32_t picIdx; /**< [out]: Picture number */
1666 uint32_t reserved1[233]; /**< [in]: Reserved and must be set to 0 */
1667 void* reserved2[64]; /**< [in]: Reserved and must be set to NULL */
1670 /** Macro for constructing the version field of ::_NV_ENC_STAT */
1671 #define NV_ENC_STAT_VER NVENCAPI_STRUCT_VERSION(1)
1675 * \struct _NV_ENC_SEQUENCE_PARAM_PAYLOAD
1676 * Sequence and picture paramaters payload.
1678 typedef struct _NV_ENC_SEQUENCE_PARAM_PAYLOAD
1680 uint32_t version; /**< [in]: Struct version. Must be set to ::NV_ENC_INITIALIZE_PARAMS_VER. */
1681 uint32_t inBufferSize; /**< [in]: Specifies the size of the spsppsBuffer provied by the client */
1682 uint32_t spsId; /**< [in]: Specifies the SPS id to be used in sequence header. Default value is 0. */
1683 uint32_t ppsId; /**< [in]: Specifies the PPS id to be used in picture header. Default value is 0. */
1684 void* spsppsBuffer; /**< [in]: Specifies bitstream header pointer of size NV_ENC_SEQUENCE_PARAM_PAYLOAD::inBufferSize. It is the client's responsibility to manage this memory. */
1685 uint32_t* outSPSPPSPayloadSize; /**< [out]: Size of the sequence and picture header in bytes written by the NvEncodeAPI interface to the SPSPPSBuffer. */
1686 uint32_t reserved [250]; /**< [in]: Reserved and must be set to 0 */
1687 void* reserved2[64]; /**< [in]: Reserved and must be set to NULL */
1688 } NV_ENC_SEQUENCE_PARAM_PAYLOAD;
1690 /** Macro for constructing the version field of ::_NV_ENC_SEQUENCE_PARAM_PAYLOAD */
1691 #define NV_ENC_SEQUENCE_PARAM_PAYLOAD_VER NVENCAPI_STRUCT_VERSION(1)
1695 * Event registration/unregistration parameters.
1697 typedef struct _NV_ENC_EVENT_PARAMS
1699 uint32_t version; /**< [in]: Struct version. Must be set to ::NV_ENC_EVENT_PARAMS_VER. */
1700 uint32_t reserved; /**< [in]: Reserved and must be set to 0 */
1701 void* completionEvent; /**< [in]: Handle to event to be registered/unregistered with the NvEncodeAPI interface. */
1702 uint32_t reserved1[253]; /**< [in]: Reserved and must be set to 0 */
1703 void* reserved2[64]; /**< [in]: Reserved and must be set to NULL */
1704 } NV_ENC_EVENT_PARAMS;
1706 /** Macro for constructing the version field of ::_NV_ENC_EVENT_PARAMS */
1707 #define NV_ENC_EVENT_PARAMS_VER NVENCAPI_STRUCT_VERSION(1)
1710 * Encoder Session Creation parameters
1712 typedef struct _NV_ENC_OPEN_ENCODE_SESSIONEX_PARAMS
1714 uint32_t version; /**< [in]: Struct version. Must be set to ::NV_ENC_OPEN_ENCODE_SESSION_EX_PARAMS_VER. */
1715 NV_ENC_DEVICE_TYPE deviceType; /**< [in]: Specified the device Type */
1716 void* device; /**< [in]: Pointer to client device. */
1717 void* reserved; /**< [in]: Reserved and must be set to 0. */
1718 uint32_t apiVersion; /**< [in]: API version. Should be set to NVENCAPI_VERSION. */
1719 uint32_t reserved1[253]; /**< [in]: Reserved and must be set to 0 */
1720 void* reserved2[64]; /**< [in]: Reserved and must be set to NULL */
1721 } NV_ENC_OPEN_ENCODE_SESSION_EX_PARAMS;
1722 /** Macro for constructing the version field of ::_NV_ENC_OPEN_ENCODE_SESSIONEX_PARAMS */
1723 #define NV_ENC_OPEN_ENCODE_SESSION_EX_PARAMS_VER NVENCAPI_STRUCT_VERSION(1)
1725 /** @} */ /* END ENCODER_STRUCTURE */
1729 * \addtogroup ENCODE_FUNC NvEncodeAPI Functions
1733 // NvEncOpenEncodeSession
1735 * \brief Opens an encoding session.
1740 * ::NV_ENC_ERR_INVALID_CALL\n
1743 NVENCSTATUS NVENCAPI NvEncOpenEncodeSession (void* device, uint32_t deviceType, void** encoder);
1745 // NvEncGetEncodeGuidCount
1747 * \brief Retrieves the number of supported encode GUIDs.
1749 * The function returns the number of codec guids supported by the NvEncodeAPI
1752 * \param [in] encoder
1753 * Pointer to the NvEncodeAPI interface.
1754 * \param [out] encodeGUIDCount
1755 * Number of supported encode GUIDs.
1758 * ::NV_ENC_SUCCESS \n
1759 * ::NV_ENC_ERR_INVALID_PTR \n
1760 * ::NV_ENC_ERR_INVALID_ENCODERDEVICE \n
1761 * ::NV_ENC_ERR_DEVICE_NOT_EXIST \n
1762 * ::NV_ENC_ERR_UNSUPPORTED_PARAM \n
1763 * ::NV_ENC_ERR_OUT_OF_MEMORY \n
1764 * ::NV_ENC_ERR_INVALID_PARAM \n
1765 * ::NV_ENC_ERR_GENERIC \n
1768 NVENCSTATUS NVENCAPI NvEncGetEncodeGUIDCount (void* encoder, uint32_t* encodeGUIDCount);
1771 // NvEncGetEncodeGUIDs
1773 * \brief Retrieves an array of supported encoder codec GUIDs.
1775 * The function returns an array of codec guids supported by the NvEncodeAPI interface.
1776 * The client must allocate an array where the NvEncodeAPI interface can
1777 * fill the supported guids and pass the pointer in \p *GUIDs parameter.
1778 * The size of the array can be determined by using ::NvEncGetEncodeGUIDCount() API.
1779 * The Nvidia Encoding interface returns the number of codec guids it has actually
1780 * filled in the guid array in the \p GUIDCount parameter.
1782 * \param [in] encoder
1783 * Pointer to the NvEncodeAPI interface.
1784 * \param [in] guidArraySize
1785 * Number of GUIDs to retrieved. Should be set to the number retrieved using
1786 * ::NvEncGetEncodeGUIDCount.
1787 * \param [out] GUIDs
1788 * Array of supported Encode GUIDs.
1789 * \param [out] GUIDCount
1790 * Number of supported Encode GUIDs.
1793 * ::NV_ENC_SUCCESS \n
1794 * ::NV_ENC_ERR_INVALID_PTR \n
1795 * ::NV_ENC_ERR_INVALID_ENCODERDEVICE \n
1796 * ::NV_ENC_ERR_DEVICE_NOT_EXIST \n
1797 * ::NV_ENC_ERR_UNSUPPORTED_PARAM \n
1798 * ::NV_ENC_ERR_OUT_OF_MEMORY \n
1799 * ::NV_ENC_ERR_INVALID_PARAM \n
1800 * ::NV_ENC_ERR_GENERIC \n
1803 NVENCSTATUS NVENCAPI NvEncGetEncodeGUIDs (void* encoder, GUID* GUIDs, uint32_t guidArraySize, uint32_t* GUIDCount);
1806 // NvEncGetEncodeProfileGuidCount
1808 * \brief Retrieves the number of supported profile GUIDs.
1810 * The function returns the number of profile GUIDs supported for a given codec.
1811 * The client must first enumerate the codec guids supported by the NvEncodeAPI
1812 * interface. After determining the codec guid, it can query the NvEncodeAPI
1813 * interface to determine the number of profile guids supported for a particular
1816 * \param [in] encoder
1817 * Pointer to the NvEncodeAPI interface.
1818 * \param [in] encodeGUID
1819 * The codec guid for which the profile guids are being enumerated.
1820 * \param [out] encodeProfileGUIDCount
1821 * Number of encode profiles supported for the given encodeGUID.
1824 * ::NV_ENC_SUCCESS \n
1825 * ::NV_ENC_ERR_INVALID_PTR \n
1826 * ::NV_ENC_ERR_INVALID_ENCODERDEVICE \n
1827 * ::NV_ENC_ERR_DEVICE_NOT_EXIST \n
1828 * ::NV_ENC_ERR_UNSUPPORTED_PARAM \n
1829 * ::NV_ENC_ERR_OUT_OF_MEMORY \n
1830 * ::NV_ENC_ERR_INVALID_PARAM \n
1831 * ::NV_ENC_ERR_GENERIC \n
1834 NVENCSTATUS NVENCAPI NvEncGetEncodeProfileGUIDCount (void* encoder, GUID encodeGUID, uint32_t* encodeProfileGUIDCount);
1837 // NvEncGetEncodeProfileGUIDs
1839 * \brief Retrieves an array of supported encode profile GUIDs.
1841 * The function returns an array of supported profile guids for a particular
1842 * codec guid. The client must allocate an array where the NvEncodeAPI interface
1843 * can populate the profile guids. The client can determine the array size using
1844 * ::NvEncGetEncodeProfileGUIDCount() API. The client must also validiate that the
1845 * NvEncodeAPI interface supports the GUID the client wants to pass as \p encodeGUID
1848 * \param [in] encoder
1849 * Pointer to the NvEncodeAPI interface.
1850 * \param [in] encodeGUID
1851 * The encode guid whose profile guids are being enumerated.
1852 * \param [in] guidArraySize
1853 * Number of GUIDs to be retrieved. Should be set to the number retrieved using
1854 * ::NvEncGetEncodeProfileGUIDCount.
1855 * \param [out] profileGUIDs
1856 * Array of supported Encode Profile GUIDs
1857 * \param [out] GUIDCount
1858 * Number of valid encode profile GUIDs in \p profileGUIDs array.
1861 * ::NV_ENC_SUCCESS \n
1862 * ::NV_ENC_ERR_INVALID_PTR \n
1863 * ::NV_ENC_ERR_INVALID_ENCODERDEVICE \n
1864 * ::NV_ENC_ERR_DEVICE_NOT_EXIST \n
1865 * ::NV_ENC_ERR_UNSUPPORTED_PARAM \n
1866 * ::NV_ENC_ERR_OUT_OF_MEMORY \n
1867 * ::NV_ENC_ERR_INVALID_PARAM \n
1868 * ::NV_ENC_ERR_GENERIC \n
1871 NVENCSTATUS NVENCAPI NvEncGetEncodeProfileGUIDs (void* encoder, GUID encodeGUID, GUID* profileGUIDs, uint32_t guidArraySize, uint32_t* GUIDCount);
1873 // NvEncGetInputFormatCount
1875 * \brief Retrieve the number of supported Input formats.
1877 * The function returns the number of supported input formats. The client must
1878 * query the NvEncodeAPI interface to determine the supported input formats
1879 * before creating the input surfaces.
1881 * \param [in] encoder
1882 * Pointer to the NvEncodeAPI interface.
1883 * \param [in] encodeGUID
1884 * Encode GUID, corresponding to which the number of supported input formats
1885 * is to be retrieved.
1886 * \param [out] inputFmtCount
1887 * Number of input formats supported for specified Encode GUID.
1890 * ::NV_ENC_SUCCESS \n
1891 * ::NV_ENC_ERR_INVALID_PTR \n
1892 * ::NV_ENC_ERR_INVALID_ENCODERDEVICE \n
1893 * ::NV_ENC_ERR_DEVICE_NOT_EXIST \n
1894 * ::NV_ENC_ERR_UNSUPPORTED_PARAM \n
1895 * ::NV_ENC_ERR_OUT_OF_MEMORY \n
1896 * ::NV_ENC_ERR_INVALID_PARAM \n
1897 * ::NV_ENC_ERR_GENERIC \n
1899 NVENCSTATUS NVENCAPI NvEncGetInputFormatCount (void* encoder, GUID encodeGUID, uint32_t* inputFmtCount);
1902 // NvEncGetInputFormats
1904 * \brief Retrieves an array of supported Input formats
1906 * Returns an array of supported input formats The client must use the input
1907 * format to create input surface using ::NvEncCreateInputBuffer() API.
1909 * \param [in] encoder
1910 * Pointer to the NvEncodeAPI interface.
1911 * \param [in] encodeGUID
1912 * Encode GUID, corresponding to which the number of supported input formats
1913 * is to be retrieved.
1914 *\param [in] inputFmtArraySize
1915 * Size input format count array passed in \p inputFmts.
1916 *\param [out] inputFmts
1917 * Array of input formats supported for this Encode GUID.
1918 *\param [out] inputFmtCount
1919 * The number of valid input format types returned by the NvEncodeAPI
1920 * interface in \p inputFmts array.
1923 * ::NV_ENC_SUCCESS \n
1924 * ::NV_ENC_ERR_INVALID_PTR \n
1925 * ::NV_ENC_ERR_INVALID_ENCODERDEVICE \n
1926 * ::NV_ENC_ERR_DEVICE_NOT_EXIST \n
1927 * ::NV_ENC_ERR_UNSUPPORTED_PARAM \n
1928 * ::NV_ENC_ERR_OUT_OF_MEMORY \n
1929 * ::NV_ENC_ERR_INVALID_PARAM \n
1930 * ::NV_ENC_ERR_GENERIC \n
1933 NVENCSTATUS NVENCAPI NvEncGetInputFormats (void* encoder, GUID encodeGUID, NV_ENC_BUFFER_FORMAT* inputFmts, uint32_t inputFmtArraySize, uint32_t* inputFmtCount);
1936 // NvEncGetEncodeCaps
1938 * \brief Retrieves the capability value for a specified encoder attribute.
1940 * The function returns the capability value for a given encoder attribute. The
1941 * client must validate the encodeGUID using ::NvEncGetEncodeGUIDs() API before
1942 * calling this function. The encoder attribute being queried are enumerated in
1943 * ::NV_ENC_CAPS_PARAM enum.
1945 * \param [in] encoder
1946 * Pointer to the NvEncodeAPI interface.
1947 * \param [in] encodeGUID
1948 * Encode GUID, corresponding to which the capability attribute is to be retrieved.
1949 * \param [in] capsParam
1950 * Used to specify attribute being queried. Refer ::NV_ENC_CAPS_PARAM for more
1952 * \param [out] capsVal
1953 * The value corresponding to the capability attribute being queried.
1956 * ::NV_ENC_SUCCESS \n
1957 * ::NV_ENC_ERR_INVALID_PTR \n
1958 * ::NV_ENC_ERR_INVALID_ENCODERDEVICE \n
1959 * ::NV_ENC_ERR_DEVICE_NOT_EXIST \n
1960 * ::NV_ENC_ERR_UNSUPPORTED_PARAM \n
1961 * ::NV_ENC_ERR_OUT_OF_MEMORY \n
1962 * ::NV_ENC_ERR_INVALID_PARAM \n
1963 * ::NV_ENC_ERR_GENERIC \n
1965 NVENCSTATUS NVENCAPI NvEncGetEncodeCaps (void* encoder, GUID encodeGUID, NV_ENC_CAPS_PARAM* capsParam, int* capsVal);
1968 // NvEncGetEncodePresetCount
1970 * \brief Retrieves the number of supported preset GUIDs.
1972 * The function returns the number of preset GUIDs available for a given codec.
1973 * The client must validate the codec guid using ::NvEncGetEncodeGUIDs() API
1974 * before calling this function.
1976 * \param [in] encoder
1977 * Pointer to the NvEncodeAPI interface.
1978 * \param [in] encodeGUID
1979 * Encode GUID, corresponding to which the number of supported presets is to
1981 * \param [out] encodePresetGUIDCount
1982 * Receives the number of supported preset GUIDs.
1985 * ::NV_ENC_SUCCESS \n
1986 * ::NV_ENC_ERR_INVALID_PTR \n
1987 * ::NV_ENC_ERR_INVALID_ENCODERDEVICE \n
1988 * ::NV_ENC_ERR_DEVICE_NOT_EXIST \n
1989 * ::NV_ENC_ERR_UNSUPPORTED_PARAM \n
1990 * ::NV_ENC_ERR_OUT_OF_MEMORY \n
1991 * ::NV_ENC_ERR_INVALID_PARAM \n
1992 * ::NV_ENC_ERR_GENERIC \n
1995 NVENCSTATUS NVENCAPI NvEncGetEncodePresetCount (void* encoder, GUID encodeGUID, uint32_t* encodePresetGUIDCount);
1998 // NvEncGetEncodePresetGUIDs
2000 * \brief Receives an array of supported encoder preset GUIDs.
2002 * The function returns an array of encode preset guids available for a given codec.
2003 * The client can directly use one of the preset guids based upon the use case
2004 * or target device. The preset guid chosen can be directly used in
2005 * NV_ENC_INITIALIZE_PARAMS::presetGUID parameter to ::NvEncEncodePicture() API.
2006 * Alternately client can also use the preset guid to retrieve the encoding config
2007 * parameters being used by NvEncodeAPI interface for that given preset, using
2008 * ::NvEncGetEncodePresetConfig() API. It can then modify preset config parameters
2009 * as per its use case and send it to NvEncodeAPI interface as part of
2010 * NV_ENC_INITIALIZE_PARAMS::encodeConfig parameter for NvEncInitializeEncoder()
2014 * \param [in] encoder
2015 * Pointer to the NvEncodeAPI interface.
2016 * \param [in] encodeGUID
2017 * Encode GUID, corresponding to which the list of supported presets is to be
2019 * \param [in] guidArraySize
2020 * Size of array of preset guids passed in \p preset GUIDs
2021 * \param [out] presetGUIDs
2022 * Array of supported Encode preset GUIDs from the NvEncodeAPI interface
2024 * \param [out] encodePresetGUIDCount
2025 * Receives the number of preset GUIDs returned by the NvEncodeAPI
2029 * ::NV_ENC_SUCCESS \n
2030 * ::NV_ENC_ERR_INVALID_PTR \n
2031 * ::NV_ENC_ERR_INVALID_ENCODERDEVICE \n
2032 * ::NV_ENC_ERR_DEVICE_NOT_EXIST \n
2033 * ::NV_ENC_ERR_UNSUPPORTED_PARAM \n
2034 * ::NV_ENC_ERR_OUT_OF_MEMORY \n
2035 * ::NV_ENC_ERR_INVALID_PARAM \n
2036 * ::NV_ENC_ERR_GENERIC \n
2039 NVENCSTATUS NVENCAPI NvEncGetEncodePresetGUIDs (void* encoder, GUID encodeGUID, GUID* presetGUIDs, uint32_t guidArraySize, uint32_t* encodePresetGUIDCount);
2042 // NvEncGetEncodePresetConfig
2044 * \brief Returns a preset config structure supported for given preset GUID.
2046 * The function returns a preset config structure for a given preset guid. Before
2047 * using this function the client must enumerate the preset guids available for
2048 * a given codec. The preset config structure can be modified by the client depending
2049 * upon its use case and can be then used to initialize the encoder using
2050 * ::NvEncInitializeEncoder() API. The client can use this function only if it
2051 * wants to modify the NvEncodeAPI preset configuration, otherwise it can
2052 * directly use the preset guid.
2054 * \param [in] encoder
2055 * Pointer to the NvEncodeAPI interface.
2056 * \param [in] encodeGUID
2057 * Encode GUID, corresponding to which the list of supported presets is to be
2059 * \param [in] presetGUID
2060 * Preset GUID, corresponding to which the Encoding configurations is to be
2062 * \param [out] presetConfig
2063 * The requested Preset Encoder Attribute set. Refer ::_NV_ENC_CONFIG for
2067 * ::NV_ENC_SUCCESS \n
2068 * ::NV_ENC_ERR_INVALID_PTR \n
2069 * ::NV_ENC_ERR_INVALID_ENCODERDEVICE \n
2070 * ::NV_ENC_ERR_DEVICE_NOT_EXIST \n
2071 * ::NV_ENC_ERR_UNSUPPORTED_PARAM \n
2072 * ::NV_ENC_ERR_OUT_OF_MEMORY \n
2073 * ::NV_ENC_ERR_INVALID_PARAM \n
2074 * ::NV_ENC_ERR_INVALID_VERSION \n
2075 * ::NV_ENC_ERR_GENERIC \n
2078 NVENCSTATUS NVENCAPI NvEncGetEncodePresetConfig (void* encoder, GUID encodeGUID, GUID presetGUID, NV_ENC_PRESET_CONFIG* presetConfig);
2080 // NvEncInitializeEncoder
2082 * \brief Initialize the encoder.
2084 * This API must be used to initialize the encoder. The initialization parameter
2085 * is passed using \p *createEncodeParams The client must send the following
2086 * fields of the _NV_ENC_INITIALIZE_PARAMS structure with a valid value.
2087 * - NV_ENC_INITIALIZE_PARAMS::encodeGUID
2088 * - NV_ENC_INITIALIZE_PARAMS::encodeWidth
2089 * - NV_ENC_INITIALIZE_PARAMS::encodeHeight
2091 * The client can pass a preset guid directly to the NvEncodeAPI interface using
2092 * NV_ENC_INITIALIZE_PARAMS::presetGUID field. If the client doesn't pass
2093 * NV_ENC_INITIALIZE_PARAMS::encodeConfig structure, the codec specific parameters
2094 * will be selected based on the preset guid. The preset guid must have been
2095 * validated by the client using ::NvEncGetEncodePresetGUIDs() API.
2096 * If the client passes a custom ::_NV_ENC_CONFIG structure through
2097 * NV_ENC_INITIALIZE_PARAMS::encodeConfig , it will override the codec specific parameters
2098 * based on the preset guid. It is recommended that even if the client passes a custom config,
2099 * it should also send a preset guid. In this case, the preset guid passed by the client
2100 * will not override any of the custom config parameters programmed by the client,
2101 * it is only used as a hint by the NvEncodeAPI interface to determine certain encoder parameters
2102 * which are not exposed to the client.
2104 * There are two modes of operation for the encoder namely:
2105 * - Asynchronous mode
2106 * - Synchronous mode
2108 * The client can select asynchronous or synchronous mode by setting the \p
2109 * enableEncodeAsync field in ::_NV_ENC_INITIALIZE_PARAMS to 1 or 0 respectively.
2110 *\par Asynchronous mode of operation:
2111 * The Asynchronous mode can be enabled by setting NV_ENC_INITIALIZE_PARAMS::enableEncodeAsync to 1.
2112 * The client operating in asynchronous mode must allocate completion event object
2113 * for each output buffer and pass the completion event object in the
2114 * ::NvEncEncodePicture() API. The client can create another thread and wait on
2115 * the event object to be signalled by NvEncodeAPI interface on completion of the
2116 * encoding process for the output frame. This should unblock the main thread from
2117 * submitting work to the encoder. When the event is signalled the client can call
2118 * NvEncodeAPI interfaces to copy the bitstream data using ::NvEncLockBitstream()
2119 * API. This is the preferred mode of operation.
2121 * NOTE: Asynchronous mode is not supported on Linux.
2123 *\par Synchronous mode of operation:
2124 * The client can select synchronous mode by setting NV_ENC_INITIALIZE_PARAMS::enableEncodeAsync to 0.
2125 * The client working in synchronous mode can work in a single threaded or multi
2126 * threaded mode. The client need not allocate any event objects. The client can
2127 * only lock the bitstream data after NvEncodeAPI interface has returned
2128 * ::NV_ENC_SUCCESS from encode picture. The NvEncodeAPI interface can return
2129 * ::NV_ENC_ERR_NEED_MORE_INPUT error code from ::NvEncEncodePicture() API. The
2130 * client must not lock the output buffer in such case but should send the next
2131 * frame for encoding. The client must keep on calling ::NvEncEncodePicture() API
2132 * until it returns ::NV_ENC_SUCCESS. \n
2133 * The client must always lock the bitstream data in order in which it has submitted.
2134 * This is true for both asynchronous and synchronous mode.
2136 *\par Picture type decision:
2137 * If the client is taking the picture type decision and it must disable the picture
2138 * type decision module in NvEncodeAPI by setting NV_ENC_INITIALIZE_PARAMS::enablePTD
2139 * to 0. In this case the client is required to send the picture in encoding
2140 * order to NvEncodeAPI by doing the re-ordering for B frames. \n
2141 * If the client doesn't want to take the picture type decision it can enable
2142 * picture type decision module in the NvEncodeAPI interface by setting
2143 * NV_ENC_INITIALIZE_PARAMS::enablePTD to 1 and send the input pictures in display
2146 * \param [in] encoder
2147 * Pointer to the NvEncodeAPI interface.
2148 * \param [in] createEncodeParams
2149 * Refer ::_NV_ENC_INITIALIZE_PARAMS for details.
2152 * ::NV_ENC_SUCCESS \n
2153 * ::NV_ENC_ERR_INVALID_PTR \n
2154 * ::NV_ENC_ERR_INVALID_ENCODERDEVICE \n
2155 * ::NV_ENC_ERR_DEVICE_NOT_EXIST \n
2156 * ::NV_ENC_ERR_UNSUPPORTED_PARAM \n
2157 * ::NV_ENC_ERR_OUT_OF_MEMORY \n
2158 * ::NV_ENC_ERR_INVALID_PARAM \n
2159 * ::NV_ENC_ERR_INVALID_VERSION \n
2160 * ::NV_ENC_ERR_GENERIC \n
2163 NVENCSTATUS NVENCAPI NvEncInitializeEncoder (void* encoder, NV_ENC_INITIALIZE_PARAMS* createEncodeParams);
2166 // NvEncCreateInputBuffer
2168 * \brief Allocates Input buffer.
2170 * This function is used to allocate an input buffer. The client must enumerate
2171 * the input buffer format before allocating the input buffer resources. The
2172 * NV_ENC_INPUT_PTR returned by the NvEncodeAPI interface in the
2173 * NV_ENC_CREATE_INPUT_BUFFER::inputBuffer field can be directly used in
2174 * ::NvEncEncodePicture() API. The number of input buffers to be allocated by the
2175 * client must be at least 4 more than the number of B frames being used for encoding.
2177 * \param [in] encoder
2178 * Pointer to the NvEncodeAPI interface.
2179 * \param [in,out] createInputBufferParams
2180 * Pointer to the ::NV_ENC_CREATE_INPUT_BUFFER structure.
2183 * ::NV_ENC_SUCCESS \n
2184 * ::NV_ENC_ERR_INVALID_PTR \n
2185 * ::NV_ENC_ERR_INVALID_ENCODERDEVICE \n
2186 * ::NV_ENC_ERR_DEVICE_NOT_EXIST \n
2187 * ::NV_ENC_ERR_UNSUPPORTED_PARAM \n
2188 * ::NV_ENC_ERR_OUT_OF_MEMORY \n
2189 * ::NV_ENC_ERR_INVALID_PARAM \n
2190 * ::NV_ENC_ERR_INVALID_VERSION \n
2191 * ::NV_ENC_ERR_GENERIC \n
2194 NVENCSTATUS NVENCAPI NvEncCreateInputBuffer (void* encoder, NV_ENC_CREATE_INPUT_BUFFER* createInputBufferParams);
2197 // NvEncDestroyInputBuffer
2199 * \brief Release an input buffers.
2201 * This function is used to free an input buffer. If the client has allocated
2202 * any input buffer using ::NvEncCreateInputBuffer() API, it must free those
2203 * input buffers by calling this function. The client must release the input
2204 * buffers before destroying the encoder using ::NvEncDestroyEncoder() API.
2206 * \param [in] encoder
2207 * Pointer to the NvEncodeAPI interface.
2208 * \param [in] inputBuffer
2209 * Pointer to the input buffer to be released.
2212 * ::NV_ENC_SUCCESS \n
2213 * ::NV_ENC_ERR_INVALID_PTR \n
2214 * ::NV_ENC_ERR_INVALID_ENCODERDEVICE \n
2215 * ::NV_ENC_ERR_DEVICE_NOT_EXIST \n
2216 * ::NV_ENC_ERR_UNSUPPORTED_PARAM \n
2217 * ::NV_ENC_ERR_OUT_OF_MEMORY \n
2218 * ::NV_ENC_ERR_INVALID_PARAM \n
2219 * ::NV_ENC_ERR_INVALID_VERSION \n
2220 * ::NV_ENC_ERR_GENERIC \n
2223 NVENCSTATUS NVENCAPI NvEncDestroyInputBuffer (void* encoder, NV_ENC_INPUT_PTR inputBuffer);
2226 // NvEncCreateBitstreamBuffer
2228 * \brief Allocates an output bitstream buffer
2230 * This function is used to allocate an output bitstream buffer and returns a
2231 * NV_ENC_OUTPUT_PTR to bitstream buffer to the client in the
2232 * NV_ENC_CREATE_BITSTREAM_BUFFER::bitstreamBuffer field.
2233 * The client can only call this function after the encoder session has been
2234 * initialized using ::NvEncInitializeEncoder() API. The minimum number of output
2235 * buffers allocated by the client must be at least 4 more than the number of B
2236 * B frames being used for encoding. The client can only access the output
2237 * bitsteam data by locking the \p bitstreamBuffer using the ::NvEncLockBitstream()
2240 * \param [in] encoder
2241 * Pointer to the NvEncodeAPI interface.
2242 * \param [in,out] createBitstreamBufferParams
2243 * Pointer ::NV_ENC_CREATE_BITSTREAM_BUFFER for details.
2246 * ::NV_ENC_SUCCESS \n
2247 * ::NV_ENC_ERR_INVALID_PTR \n
2248 * ::NV_ENC_ERR_INVALID_ENCODERDEVICE \n
2249 * ::NV_ENC_ERR_DEVICE_NOT_EXIST \n
2250 * ::NV_ENC_ERR_UNSUPPORTED_PARAM \n
2251 * ::NV_ENC_ERR_OUT_OF_MEMORY \n
2252 * ::NV_ENC_ERR_INVALID_PARAM \n
2253 * ::NV_ENC_ERR_INVALID_VERSION \n
2254 * ::NV_ENC_ERR_ENCODER_NOT_INITIALIZED \n
2255 * ::NV_ENC_ERR_GENERIC \n
2258 NVENCSTATUS NVENCAPI NvEncCreateBitstreamBuffer (void* encoder, NV_ENC_CREATE_BITSTREAM_BUFFER* createBitstreamBufferParams);
2261 // NvEncDestroyBitstreamBuffer
2263 * \brief Release a bitstream buffer.
2265 * This function is used to release the output bitstream buffer allocated using
2266 * the ::NvEncCreateBitstreamBuffer() function. The client must release the output
2267 * bitstreamBuffer using this function before destroying the encoder session.
2269 * \param [in] encoder
2270 * Pointer to the NvEncodeAPI interface.
2271 * \param [in] bitstreamBuffer
2272 * Pointer to the bitstream buffer being released.
2275 * ::NV_ENC_SUCCESS \n
2276 * ::NV_ENC_ERR_INVALID_PTR \n
2277 * ::NV_ENC_ERR_INVALID_ENCODERDEVICE \n
2278 * ::NV_ENC_ERR_DEVICE_NOT_EXIST \n
2279 * ::NV_ENC_ERR_UNSUPPORTED_PARAM \n
2280 * ::NV_ENC_ERR_OUT_OF_MEMORY \n
2281 * ::NV_ENC_ERR_INVALID_PARAM \n
2282 * ::NV_ENC_ERR_INVALID_VERSION \n
2283 * ::NV_ENC_ERR_ENCODER_NOT_INITIALIZED \n
2284 * ::NV_ENC_ERR_GENERIC \n
2287 NVENCSTATUS NVENCAPI NvEncDestroyBitstreamBuffer (void* encoder, NV_ENC_OUTPUT_PTR bitstreamBuffer);
2289 // NvEncEncodePicture
2291 * \brief Submit an input picture for encoding.
2293 * This function is used to submit an input picture buffer for encoding. The
2294 * encoding parameters are passed using \p *encodePicParams which is a pointer
2295 * to the ::_NV_ENC_PIC_PARAMS structure.
2297 * If the client has set NV_ENC_INITIALIZE_PARAMS::enablePTD to 0, then it must
2298 * send a valid value for the following fields.
2299 * - NV_ENC_PIC_PARAMS::pictureType
2300 * - NV_ENC_PIC_PARAMS_H264::displayPOCSyntax (H264 only)
2301 * - NV_ENC_PIC_PARAMS_H264::frameNumSyntax(H264 only)
2302 * - NV_ENC_PIC_PARAMS_H264::refPicFlag(H264 only)
2305 *\par Asynchronous Encoding
2306 * If the client has enabled asynchronous mode of encoding by setting
2307 * NV_ENC_INITIALIZE_PARAMS::enableEncodeAsync to 1 in the ::NvEncInitializeEncoder()
2308 * API ,then the client must send a valid NV_ENC_PIC_PARAMS::completionEvent.
2309 * Incase of asynchronous mode of operation, client can queue the ::NvEncEncodePicture()
2310 * API commands from the main thread and then queue output buffers to be processed
2311 * to a secondary worker thread. Before the locking the output buffers in the
2312 * secondary thread , the client must wait on NV_ENC_PIC_PARAMS::completionEvent
2313 * it has queued in ::NvEncEncodePicture() API call. The client must always process
2314 * completion event and the output buffer in the same order in which they have been
2315 * submitted for encoding. The NvEncodeAPI interface is responsible for any
2316 * re-ordering required for B frames and will always ensure that encoded bitstream
2317 * data is written in the same order in which output buffer is submitted.
2319 The below example shows how asynchronous encoding in case of 1 B frames
2320 ------------------------------------------------------------------------
2321 Suppose the client allocated 4 input buffers(I1,I2..), 4 output buffers(O1,O2..)
2322 and 4 completion events(E1, E2, ...). The NvEncodeAPI interface will need to
2323 keep a copy of the input buffers for re-ordering and it allocates following
2324 internal buffers (NvI1, NvI2...). These internal buffers are managed by NvEncodeAPI
2325 and the client is not responsible for the allocating or freeing the memory of
2326 the internal buffers.
2328 a) The client main thread will queue the following encode frame calls.
2329 Note the picture type is unknown to the client, the decision is being taken by
2330 NvEncodeAPI interface. The client should pass ::_NV_ENC_PIC_PARAMS parameter
2331 consisting of allocated input buffer, output buffer and output events in successive
2332 ::NvEncEncodePicture() API calls along with other required encode picture params.
2334 1st EncodePicture parameters - (I1, O1, E1)
2335 2nd EncodePicture parameters - (I2, O2, E2)
2336 3rd EncodePicture parameters - (I3, O3, E3)
2338 b) NvEncodeAPI SW will receive the following encode Commands from the client.
2339 The left side shows input from client in the form (Input buffer, Output Buffer,
2340 Output Event). The right hand side shows a possible picture type decision take by
2341 the NvEncodeAPI interface.
2342 (I1, O1, E1) ---P1 Frame
2343 (I2, O2, E2) ---B2 Frame
2344 (I3, O3, E3) ---P3 Frame
2346 c) NvEncodeAPI interface will make a copy of the input buffers to its internal
2347 buffersfor re-ordering. These copies are done as part of nvEncEncodePicture
2348 function call from the client and NvEncodeAPI interface is responsible for
2349 synchronization of copy operation with the actual encoding operation.
2354 d) After returning from ::NvEncEncodePicture() call , the client must queue the output
2355 bitstream processing work to the secondary thread. The output bitstream processing
2356 for asynchronous mode consist of first waiting on completion event(E1, E2..)
2357 and then locking the output bitstream buffer(O1, O2..) for reading the encoded
2358 data. The work queued to the secondary thread by the client is in the following order
2362 Note they are in the same order in which client calls ::NvEncEncodePicture() API
2365 e) NvEncodeAPI interface will do the re-ordering such that Encoder HW will receive
2366 the following encode commands:
2367 (NvI1, O1, E1) ---P1 Frame
2368 (NvI3, O2, E2) ---P3 Frame
2369 (NvI2, O3, E3) ---B2 frame
2371 f) After the encoding operations are completed, the events will be signalled
2372 by NvEncodeAPI interface in the following order :
2373 (O1, E1) ---P1 Frame ,output bitstream copied to O1 and event E1 signalled.
2374 (O2, E2) ---P3 Frame ,output bitstream copied to O2 and event E2 signalled.
2375 (O3, E3) ---B2 Frame ,output bitstream copied to O3 and event E3 signalled.
2377 g) The client must lock the bitstream data using ::NvEncLockBitstream() API in
2378 the order O1,O2,O3 to read the encoded data, after waiting for the events
2379 to be signalled in the same order i.e E1, E2 and E3.The output processing is
2380 done in the secondary thread in the following order:
2381 Waits on E1, copies encoded bitstream from O1
2382 Waits on E2, copies encoded bitstream from O2
2383 Waits on E3, copies encoded bitstream from O3
2385 -Note the client will receive the events signalling and output buffer in the
2386 same order in which they have submitted for encoding.
2387 -Note the LockBitstream will have picture type field which will notify the
2388 output picture type to the clients.
2389 -Note the input, output buffer and the output completion event are free to be
2390 reused once NvEncodeAPI interfaced has signalled the event and the client has
2391 copied the data from the output buffer.
2395 *\par Synchronous Encoding
2396 * The client can enable synchronous mode of encoding by setting
2397 * NV_ENC_INITIALIZE_PARAMS::enableEncodeAsync to 0 in ::NvEncInitializeEncoder() API.
2398 * The NvEncodeAPI interface may return ::NV_ENC_ERR_NEED_MORE_INPUT error code for
2399 * some ::NvEncEncodePicture() API calls when NV_ENC_INITIALIZE_PARAMS::enablePTD
2400 * is set to 1, but the client must not treat it as a fatal error. The NvEncodeAPI
2401 * interface might not be able to submit an input picture buffer for encoding
2402 * immediately due to re-ordering for B frames. The NvEncodeAPI interface cannot
2403 * submit the input picture which is decided to be encoded as B frame as it waits
2404 * for backward reference from temporally subsequent frames. This input picture
2405 * is buffered internally and waits for more input picture to arrive. The client
2406 * must not call ::NvEncLockBitstream() API on the output buffers whose
2407 * ::NvEncEncodePicture() API returns ::NV_ENC_ERR_NEED_MORE_INPUT. The client must
2408 * wait for the NvEncodeAPI interface to return ::NV_ENC_SUCCESS before locking the
2409 * output bitstreams to read the encoded bitstream data. The following example
2410 * explains the scenario with synchronous encoding with 2 B frames.
2412 The below example shows how synchronous encoding works in case of 1 B frames
2413 -----------------------------------------------------------------------------
2414 Suppose the client allocated 4 input buffers(I1,I2..), 4 output buffers(O1,O2..)
2415 and 4 completion events(E1, E2, ...). The NvEncodeAPI interface will need to
2416 keep a copy of the input buffers for re-ordering and it allocates following
2417 internal buffers (NvI1, NvI2...). These internal buffers are managed by NvEncodeAPI
2418 and the client is not responsible for the allocating or freeing the memory of
2419 the internal buffers.
2421 The client calls ::NvEncEncodePicture() API with input buffer I1 and output buffer O1.
2422 The NvEncodeAPI decides to encode I1 as P frame and submits it to encoder
2423 HW and returns ::NV_ENC_SUCCESS.
2424 The client can now read the encoded data by locking the output O1 by calling
2425 NvEncLockBitstream API.
2427 The client calls ::NvEncEncodePicture() API with input buffer I2 and output buffer O2.
2428 The NvEncodeAPI decides to encode I2 as B frame and buffers I2 by copying it
2429 to internal buffer and returns ::NV_ENC_ERR_NEED_MORE_INPUT.
2430 The error is not fatal and it notifies client that it cannot read the encoded
2431 data by locking the output O2 by calling ::NvEncLockBitstream() API without submitting
2432 more work to the NvEncodeAPI interface.
2434 The client calls ::NvEncEncodePicture() with input buffer I3 and output buffer O3.
2435 The NvEncodeAPI decides to encode I3 as P frame and it first submits I3 for
2436 encoding which will be used as backward reference frame for I2.
2437 The NvEncodeAPI then submits I2 for encoding and returns ::NV_ENC_SUCESS. Both
2438 the submission are part of the same ::NvEncEncodePicture() function call.
2439 The client can now read the encoded data for both the frames by locking the output
2440 O2 followed by O3 ,by calling ::NvEncLockBitstream() API.
2442 The client must always lock the output in the same order in which it has submitted
2443 to receive the encoded bitstream in correct encoding order.
2447 * \param [in] encoder
2448 * Pointer to the NvEncodeAPI interface.
2449 * \param [in,out] encodePicParams
2450 * Pointer to the ::_NV_ENC_PIC_PARAMS structure.
2453 * ::NV_ENC_SUCCESS \n
2454 * ::NV_ENC_ERR_INVALID_PTR \n
2455 * ::NV_ENC_ERR_INVALID_ENCODERDEVICE \n
2456 * ::NV_ENC_ERR_DEVICE_NOT_EXIST \n
2457 * ::NV_ENC_ERR_UNSUPPORTED_PARAM \n
2458 * ::NV_ENC_ERR_OUT_OF_MEMORY \n
2459 * ::NV_ENC_ERR_INVALID_PARAM \n
2460 * ::NV_ENC_ERR_INVALID_VERSION \n
2461 * ::NV_ENC_ERR_ENCODER_BUSY \n
2462 * ::NV_ENC_ERR_NEED_MORE_INPUT \n
2463 * ::NV_ENC_ERR_ENCODER_NOT_INITIALIZED \n
2464 * ::NV_ENC_ERR_GENERIC \n
2467 NVENCSTATUS NVENCAPI NvEncEncodePicture (void* encoder, NV_ENC_PIC_PARAMS* encodePicParams);
2470 // NvEncLockBitstream
2472 * \brief Lock output bitstream buffer
2474 * This function is used to lock the bitstream buffer to read the encoded data.
2475 * The client can only access the encoded data by calling this function.
2476 * The pointer to client accessible encoded data is returned in the
2477 * NV_ENC_LOCK_BITSTREAM::bitstreamBufferPtr field. The size of the encoded data
2478 * in the output buffer is returned in the NV_ENC_LOCK_BITSTREAM::bitstreamSizeInBytes
2479 * The NvEncodeAPI interface also returns the output picture type and picture structure
2480 * of the encoded frame in NV_ENC_LOCK_BITSTREAM::pictureType and
2481 * NV_ENC_LOCK_BITSTREAM::pictureStruct fields respectively. If the client has
2482 * set NV_ENC_LOCK_BITSTREAM::doNotWait to 1, the function might return
2483 * ::NV_ENC_ERR_LOCK_BUSY if client is operating in synchronous mode. This is not
2484 * a fatal failure if NV_ENC_LOCK_BITSTREAM::doNotWait is set to 1. In the above case the client can
2485 * retry the function after few milliseconds.
2487 * \param [in] encoder
2488 * Pointer to the NvEncodeAPI interface.
2489 * \param [in,out] lockBitstreamBufferParams
2490 * Pointer to the ::_NV_ENC_LOCK_BITSTREAM structure.
2493 * ::NV_ENC_SUCCESS \n
2494 * ::NV_ENC_ERR_INVALID_PTR \n
2495 * ::NV_ENC_ERR_INVALID_ENCODERDEVICE \n
2496 * ::NV_ENC_ERR_DEVICE_NOT_EXIST \n
2497 * ::NV_ENC_ERR_UNSUPPORTED_PARAM \n
2498 * ::NV_ENC_ERR_OUT_OF_MEMORY \n
2499 * ::NV_ENC_ERR_INVALID_PARAM \n
2500 * ::NV_ENC_ERR_INVALID_VERSION \n
2501 * ::NV_ENC_ERR_LOCK_BUSY \n
2502 * ::NV_ENC_ERR_ENCODER_NOT_INITIALIZED \n
2503 * ::NV_ENC_ERR_GENERIC \n
2506 NVENCSTATUS NVENCAPI NvEncLockBitstream (void* encoder, NV_ENC_LOCK_BITSTREAM* lockBitstreamBufferParams);
2509 // NvEncUnlockBitstream
2511 * \brief Unlock the output bitstream buffer
2513 * This function is used to unlock the output bitstream buffer after the client
2514 * has read the encoded data from output buffer. The client must call this function
2515 * to unlock the output buffer which it has previously locked using ::NvEncLockBitstream()
2516 * function. Using a locked bitstream buffer in ::NvEncEncodePicture() API will cause
2517 * the function to fail.
2519 * \param [in] encoder
2520 * Pointer to the NvEncodeAPI interface.
2521 * \param [in,out] bitstreamBuffer
2522 * bitstream buffer pointer being unlocked
2525 * ::NV_ENC_SUCCESS \n
2526 * ::NV_ENC_ERR_INVALID_PTR \n
2527 * ::NV_ENC_ERR_INVALID_ENCODERDEVICE \n
2528 * ::NV_ENC_ERR_DEVICE_NOT_EXIST \n
2529 * ::NV_ENC_ERR_UNSUPPORTED_PARAM \n
2530 * ::NV_ENC_ERR_OUT_OF_MEMORY \n
2531 * ::NV_ENC_ERR_INVALID_PARAM \n
2532 * ::NV_ENC_ERR_ENCODER_NOT_INITIALIZED \n
2533 * ::NV_ENC_ERR_GENERIC \n
2536 NVENCSTATUS NVENCAPI NvEncUnlockBitstream (void* encoder, NV_ENC_OUTPUT_PTR bitstreamBuffer);
2539 // NvLockInputBuffer
2541 * \brief Locks an input buffer
2543 * This function is used to lock the input buffer to load the uncompressed YUV
2544 * pixel data into input buffer memory. The client must pass the NV_ENC_INPUT_PTR
2545 * it had previously allocated using ::NvEncCreateInputBuffer()in the
2546 * NV_ENC_LOCK_INPUT_BUFFER::inputBuffer field.
2547 * The NvEncodeAPI interface returns pointer to client accessible input buffer
2548 * memory in NV_ENC_LOCK_INPUT_BUFFER::bufferDataPtr field.
2550 * \param [in] encoder
2551 * Pointer to the NvEncodeAPI interface.
2552 * \param [in,out] lockInputBufferParams
2553 * Pointer to the ::_NV_ENC_LOCK_INPUT_BUFFER structure
2557 * ::NV_ENC_SUCCESS \n
2558 * ::NV_ENC_ERR_INVALID_PTR \n
2559 * ::NV_ENC_ERR_INVALID_ENCODERDEVICE \n
2560 * ::NV_ENC_ERR_DEVICE_NOT_EXIST \n
2561 * ::NV_ENC_ERR_UNSUPPORTED_PARAM \n
2562 * ::NV_ENC_ERR_OUT_OF_MEMORY \n
2563 * ::NV_ENC_ERR_INVALID_PARAM \n
2564 * ::NV_ENC_ERR_INVALID_VERSION \n
2565 * ::NV_ENC_ERR_LOCK_BUSY \n
2566 * ::NV_ENC_ERR_ENCODER_NOT_INITIALIZED \n
2567 * ::NV_ENC_ERR_GENERIC \n
2570 NVENCSTATUS NVENCAPI NvEncLockInputBuffer (void* encoder, NV_ENC_LOCK_INPUT_BUFFER* lockInputBufferParams);
2573 // NvUnlockInputBuffer
2575 * \brief Unlocks the input buffer
2577 * This function is used to unlock the input buffer memory previously locked for
2578 * uploading YUV pixel data. The input buffer must be unlocked before being used
2579 * again for encoding, otherwise NvEncodeAPI will fail the ::NvEncEncodePicture()
2581 * \param [in] encoder
2582 * Pointer to the NvEncodeAPI interface.
2583 * \param [in] inputBuffer
2584 * Pointer to the input buffer that is being unlocked.
2587 * ::NV_ENC_SUCCESS \n
2588 * ::NV_ENC_ERR_INVALID_PTR \n
2589 * ::NV_ENC_ERR_INVALID_ENCODERDEVICE \n
2590 * ::NV_ENC_ERR_DEVICE_NOT_EXIST \n
2591 * ::NV_ENC_ERR_UNSUPPORTED_PARAM \n
2592 * ::NV_ENC_ERR_OUT_OF_MEMORY \n
2593 * ::NV_ENC_ERR_INVALID_VERSION \n
2594 * ::NV_ENC_ERR_INVALID_PARAM \n
2595 * ::NV_ENC_ERR_ENCODER_NOT_INITIALIZED \n
2596 * ::NV_ENC_ERR_GENERIC \n
2600 NVENCSTATUS NVENCAPI NvEncUnlockInputBuffer (void* encoder, NV_ENC_INPUT_PTR inputBuffer);
2603 // NvEncGetEncodeStats
2605 * \brief Get encoding statistics.
2607 * This function is used to retrieve the encoding statistics.
2608 * This API is not supported when encode device type is CUDA.
2610 * \param [in] encoder
2611 * Pointer to the NvEncodeAPI interface.
2612 * \param [in,out] encodeStats
2613 * Pointer to the ::_NV_ENC_STAT structure.
2616 * ::NV_ENC_SUCCESS \n
2617 * ::NV_ENC_ERR_INVALID_PTR \n
2618 * ::NV_ENC_ERR_INVALID_ENCODERDEVICE \n
2619 * ::NV_ENC_ERR_DEVICE_NOT_EXIST \n
2620 * ::NV_ENC_ERR_UNSUPPORTED_PARAM \n
2621 * ::NV_ENC_ERR_OUT_OF_MEMORY \n
2622 * ::NV_ENC_ERR_INVALID_PARAM \n
2623 * ::NV_ENC_ERR_ENCODER_NOT_INITIALIZED \n
2624 * ::NV_ENC_ERR_GENERIC \n
2627 NVENCSTATUS NVENCAPI NvEncGetEncodeStats (void* encoder, NV_ENC_STAT* encodeStats);
2630 // NvEncGetSequenceParams
2632 * \brief Get encoded sequence and picture header.
2634 * This function can be used to retrieve the sequence and picture header out of
2635 * band. The client must call this function only after the encoder has been
2636 * initialized using ::NvEncInitializeEncoder() function. The client must
2637 * allocate the memory where the NvEncodeAPI interface can copy the bitstream
2638 * header and pass the pointer to the memory in NV_ENC_SEQUENCE_PARAM_PAYLOAD::spsppsBuffer.
2639 * The size of buffer is passed in the field NV_ENC_SEQUENCE_PARAM_PAYLOAD::inBufferSize.
2640 * The NvEncodeAPI interface will copy the bitstream header payload and returns
2641 * the actual size of the bitstream header in the field
2642 * NV_ENC_SEQUENCE_PARAM_PAYLOAD::outSPSPPSPayloadSize.
2643 * The client must call ::NvEncGetSequenceParams() function from the same thread which is
2644 * being used to call ::NvEncEncodePicture() function.
2646 * \param [in] encoder
2647 * Pointer to the NvEncodeAPI interface.
2648 * \param [in,out] sequenceParamPayload
2649 * Pointer to the ::_NV_ENC_SEQUENCE_PARAM_PAYLOAD structure.
2652 * ::NV_ENC_SUCCESS \n
2653 * ::NV_ENC_ERR_INVALID_PTR \n
2654 * ::NV_ENC_ERR_INVALID_ENCODERDEVICE \n
2655 * ::NV_ENC_ERR_DEVICE_NOT_EXIST \n
2656 * ::NV_ENC_ERR_UNSUPPORTED_PARAM \n
2657 * ::NV_ENC_ERR_OUT_OF_MEMORY \n
2658 * ::NV_ENC_ERR_INVALID_VERSION \n
2659 * ::NV_ENC_ERR_INVALID_PARAM \n
2660 * ::NV_ENC_ERR_ENCODER_NOT_INITIALIZED \n
2661 * ::NV_ENC_ERR_GENERIC \n
2664 NVENCSTATUS NVENCAPI NvEncGetSequenceParams (void* encoder, NV_ENC_SEQUENCE_PARAM_PAYLOAD* sequenceParamPayload);
2667 // NvEncRegisterAsyncEvent
2669 * \brief Register event for notification to encoding completion.
2671 * This function is used to register the completion event with NvEncodeAPI
2672 * interface. The event is required when the client has configured the encoder to
2673 * work in asynchronous mode. In this mode the client needs to send a completion
2674 * event with every output buffer. The NvEncodeAPI interface will signal the
2675 * completion of the encoding process using this event. Only after the event is
2676 * signalled the client can get the encoded data using ::NvEncLockBitstream() function.
2678 * \param [in] encoder
2679 * Pointer to the NvEncodeAPI interface.
2680 * \param [in] eventParams
2681 * Pointer to the ::_NV_ENC_EVENT_PARAMS structure.
2684 * ::NV_ENC_SUCCESS \n
2685 * ::NV_ENC_ERR_INVALID_PTR \n
2686 * ::NV_ENC_ERR_INVALID_ENCODERDEVICE \n
2687 * ::NV_ENC_ERR_DEVICE_NOT_EXIST \n
2688 * ::NV_ENC_ERR_UNSUPPORTED_PARAM \n
2689 * ::NV_ENC_ERR_OUT_OF_MEMORY \n
2690 * ::NV_ENC_ERR_INVALID_VERSION \n
2691 * ::NV_ENC_ERR_INVALID_PARAM \n
2692 * ::NV_ENC_ERR_ENCODER_NOT_INITIALIZED \n
2693 * ::NV_ENC_ERR_GENERIC \n
2696 NVENCSTATUS NVENCAPI NvEncRegisterAsyncEvent (void* encoder, NV_ENC_EVENT_PARAMS* eventParams);
2699 // NvEncUnregisterAsyncEvent
2701 * \brief Unregister completion event.
2703 * This function is used to unregister completion event which has been previously
2704 * registered using ::NvEncRegisterAsyncEvent() function. The client must unregister
2705 * all events before destroying the encoder using ::NvEncDestroyEncoder() function.
2707 * \param [in] encoder
2708 * Pointer to the NvEncodeAPI interface.
2709 * \param [in] eventParams
2710 * Pointer to the ::_NV_ENC_EVENT_PARAMS structure.
2713 * ::NV_ENC_SUCCESS \n
2714 * ::NV_ENC_ERR_INVALID_PTR \n
2715 * ::NV_ENC_ERR_INVALID_ENCODERDEVICE \n
2716 * ::NV_ENC_ERR_DEVICE_NOT_EXIST \n
2717 * ::NV_ENC_ERR_UNSUPPORTED_PARAM \n
2718 * ::NV_ENC_ERR_OUT_OF_MEMORY \n
2719 * ::NV_ENC_ERR_INVALID_VERSION \n
2720 * ::NV_ENC_ERR_INVALID_PARAM \n
2721 * ::NV_ENC_ERR_ENCODER_NOT_INITIALIZED \n
2722 * ::NV_ENC_ERR_GENERIC \n
2725 NVENCSTATUS NVENCAPI NvEncUnregisterAsyncEvent (void* encoder, NV_ENC_EVENT_PARAMS* eventParams);
2728 // NvEncMapInputResource
2730 * \brief Map an externally created input resource pointer for encoding.
2732 * Maps an externally allocated input resource [using and returns a NV_ENC_INPUT_PTR
2733 * which can be used for encoding in the ::NvEncEncodePicture() function. The
2734 * mapped resource is returned in the field NV_ENC_MAP_INPUT_RESOURCE::outputResourcePtr.
2735 * The NvEncodeAPI interface also returns the buffer format of the mapped resource
2736 * in the field NV_ENC_MAP_INPUT_RESOURCE::outbufferFmt.
2737 * This function provides synchronization guarantee that any direct3d or cuda
2738 * work submitted on the input buffer is completed before the buffer is used for encoding.
2739 * The client should not access any input buffer while they are mapped by the encoder.
2741 * \param [in] encoder
2742 * Pointer to the NvEncodeAPI interface.
2743 * \param [in,out] mapInputResParams
2744 * Pointer to the ::_NV_ENC_MAP_INPUT_RESOURCE structure.
2747 * ::NV_ENC_SUCCESS \n
2748 * ::NV_ENC_ERR_INVALID_PTR \n
2749 * ::NV_ENC_ERR_INVALID_ENCODERDEVICE \n
2750 * ::NV_ENC_ERR_DEVICE_NOT_EXIST \n
2751 * ::NV_ENC_ERR_UNSUPPORTED_PARAM \n
2752 * ::NV_ENC_ERR_OUT_OF_MEMORY \n
2753 * ::NV_ENC_ERR_INVALID_VERSION \n
2754 * ::NV_ENC_ERR_INVALID_PARAM \n
2755 * ::NV_ENC_ERR_ENCODER_NOT_INITIALIZED \n
2756 * ::NV_ENC_ERR_RESOURCE_NOT_REGISTERED \n
2757 * ::NV_ENC_ERR_MAP_FAILED \n
2758 * ::NV_ENC_ERR_GENERIC \n
2761 NVENCSTATUS NVENCAPI NvEncMapInputResource (void* encoder, NV_ENC_MAP_INPUT_RESOURCE* mapInputResParams);
2764 // NvEncUnmapInputResource
2766 * \brief UnMaps a NV_ENC_INPUT_PTR which was mapped for encoding
2769 * UnMaps an input buffer which was previously mapped using ::NvEncMapInputResource()
2770 * API. The mapping created using ::NvEncMapInputResource() should be invalidated
2771 * using this API before the external resource is destroyed by the client. The client
2772 * must unmap the buffer after ::NvEncLockBitstream() API returns succuessfully for encode
2773 * work submitted using the mapped input buffer.
2776 * \param [in] encoder
2777 * Pointer to the NvEncodeAPI interface.
2778 * \param [in] mappedInputBuffer
2779 * Pointer to the NV_ENC_INPUT_PTR
2782 * ::NV_ENC_SUCCESS \n
2783 * ::NV_ENC_ERR_INVALID_PTR \n
2784 * ::NV_ENC_ERR_INVALID_ENCODERDEVICE \n
2785 * ::NV_ENC_ERR_DEVICE_NOT_EXIST \n
2786 * ::NV_ENC_ERR_UNSUPPORTED_PARAM \n
2787 * ::NV_ENC_ERR_OUT_OF_MEMORY \n
2788 * ::NV_ENC_ERR_INVALID_VERSION \n
2789 * ::NV_ENC_ERR_INVALID_PARAM \n
2790 * ::NV_ENC_ERR_ENCODER_NOT_INITIALIZED \n
2791 * ::NV_ENC_ERR_RESOURCE_NOT_REGISTERED \n
2792 * ::NV_ENC_ERR_RESOURCE_NOT_MAPPED \n
2793 * ::NV_ENC_ERR_GENERIC \n
2796 NVENCSTATUS NVENCAPI NvEncUnmapInputResource (void* encoder, NV_ENC_INPUT_PTR mappedInputBuffer);
2798 // NvEncDestroyEncoder
2800 * \brief Destroy Encoding Session
2802 * Destroys the encoder session previously created using ::NvEncOpenEncodeSession()
2803 * function. The client must flush the encoder before freeing any resources. In order
2804 * to flush the encoder the client must pass a NULL encode picture packet and either
2805 * wait for the ::NvEncEncodePicture() function to return in synchronous mode or wait
2806 * for the flush event to be signaled by the encoder in asynchronous mode.
2807 * The client must free all the input and output resources created using the
2808 * NvEncodeAPI interface before destroying the encoder. If the client is operating
2809 * in asynchronous mode, it must also unregister the completion events previously
2812 * \param [in] encoder
2813 * Pointer to the NvEncodeAPI interface.
2816 * ::NV_ENC_SUCCESS \n
2817 * ::NV_ENC_ERR_INVALID_PTR \n
2818 * ::NV_ENC_ERR_INVALID_ENCODERDEVICE \n
2819 * ::NV_ENC_ERR_DEVICE_NOT_EXIST \n
2820 * ::NV_ENC_ERR_UNSUPPORTED_PARAM \n
2821 * ::NV_ENC_ERR_OUT_OF_MEMORY \n
2822 * ::NV_ENC_ERR_INVALID_PARAM \n
2823 * ::NV_ENC_ERR_GENERIC \n
2826 NVENCSTATUS NVENCAPI NvEncDestroyEncoder (void* encoder);
2828 // NvEncInvalidateRefFrames
2830 * \brief Invalidate reference frames
2832 * Invalidates reference frame based on the time stamp provided by the client.
2833 * The encoder marks any reference frames or any frames which have been reconstructed
2834 * using the corrupt frame as invalid for motion estimation and uses older reference
2835 * frames for motion estimation. The encoded forces the current frame to be encoded
2836 * as an intra frame if no reference frames are left after invalidation process.
2837 * This is useful for low latency application for error resiliency. The client
2838 * is recommended to set NV_ENC_CONFIG_H264::maxNumRefFrames to a large value so
2839 * that encoder can keep a backup of older reference frames in the DPB and can use them
2840 * for motion estimation when the newer reference frames have been invalidated.
2841 * This API can be called multiple times.
2843 * \param [in] encoder
2844 * Pointer to the NvEncodeAPI interface.
2845 * \param [in] invalidRefFrameTimeStamp
2846 * Timestamp of the invalid reference frames which needs to be invalidated.
2849 * ::NV_ENC_SUCCESS \n
2850 * ::NV_ENC_ERR_INVALID_PTR \n
2851 * ::NV_ENC_ERR_INVALID_ENCODERDEVICE \n
2852 * ::NV_ENC_ERR_DEVICE_NOT_EXIST \n
2853 * ::NV_ENC_ERR_UNSUPPORTED_PARAM \n
2854 * ::NV_ENC_ERR_OUT_OF_MEMORY \n
2855 * ::NV_ENC_ERR_INVALID_PARAM \n
2856 * ::NV_ENC_ERR_GENERIC \n
2859 NVENCSTATUS NVENCAPI NvEncInvalidateRefFrames(void* encoder, uint64_t invalidRefFrameTimeStamp);
2861 // NvEncOpenEncodeSessionEx
2863 * \brief Opens an encoding session.
2865 * Opens an encoding session and returns a pointer to the encoder interface in
2866 * the \p **encoder parameter. The client should start encoding process by calling
2868 * The client must pass a pointer to IDirect3DDevice9/CUDA interface in the \p *device parameter.
2869 * If the creation of encoder session fails, the client must call ::NvEncDestroyEncoder API
2872 * \param [in] openSessionExParams
2873 * Pointer to a ::NV_ENC_OPEN_ENCODE_SESSION_EX_PARAMS structure.
2874 * \param [out] encoder
2875 * Encode Session pointer to the NvEncodeAPI interface.
2877 * ::NV_ENC_SUCCESS \n
2878 * ::NV_ENC_ERR_INVALID_PTR \n
2879 * ::NV_ENC_ERR_NO_ENCODE_DEVICE \n
2880 * ::NV_ENC_ERR_UNSUPPORTED_DEVICE \n
2881 * ::NV_ENC_ERR_INVALID_DEVICE \n
2882 * ::NV_ENC_ERR_DEVICE_NOT_EXIST \n
2883 * ::NV_ENC_ERR_UNSUPPORTED_PARAM \n
2884 * ::NV_ENC_ERR_GENERIC \n
2887 NVENCSTATUS NVENCAPI NvEncOpenEncodeSessionEx (NV_ENC_OPEN_ENCODE_SESSION_EX_PARAMS *openSessionExParams, void** encoder);
2889 // NvEncRegisterResource
2891 * \brief Registers a resource with the Nvidia Video Encoder Interface.
2893 * Registers a resource with the Nvidia Video Encoder Interface for book keeping.
2894 * The client is expected to pass the registered resource handle as well, while calling ::NvEncMapInputResource API.
2895 * This API is not implemented for the DirectX Interface.
2896 * DirectX based clients need not change their implementation.
2898 * \param [in] encoder
2899 * Pointer to the NVEncodeAPI interface.
2901 * \param [in] registerResParams
2902 * Pointer to a ::_NV_ENC_REGISTER_RESOURCE structure
2905 * ::NV_ENC_SUCCESS \n
2906 * ::NV_ENC_ERR_INVALID_PTR \n
2907 * ::NV_ENC_ERR_INVALID_ENCODERDEVICE \n
2908 * ::NV_ENC_ERR_DEVICE_NOT_EXIST \n
2909 * ::NV_ENC_ERR_UNSUPPORTED_PARAM \n
2910 * ::NV_ENC_ERR_OUT_OF_MEMORY \n
2911 * ::NV_ENC_ERR_INVALID_VERSION \n
2912 * ::NV_ENC_ERR_INVALID_PARAM \n
2913 * ::NV_ENC_ERR_ENCODER_NOT_INITIALIZED \n
2914 * ::NV_ENC_ERR_RESOURCE_REGISTER_FAILED \n
2915 * ::NV_ENC_ERR_GENERIC \n
2916 * ::NV_ENC_ERR_UNIMPLEMENTED \n
2919 NVENCSTATUS NVENCAPI NvEncRegisterResource (void* encoder, NV_ENC_REGISTER_RESOURCE* registerResParams);
2921 // NvEncUnregisterResource
2923 * \brief Unregisters a resource previously registered with the Nvidia Video Encoder Interface.
2925 * Unregisters a resource previously registered with the Nvidia Video Encoder Interface.
2926 * The client is expected to unregister any resource that it has registered with the
2927 * Nvidia Video Encoder Interface before destroying the resource.
2928 * This API is not implemented for the DirectX Interface.
2929 * DirectX based clients need not change their implementation.
2931 * \param [in] encoder
2932 * Pointer to the NVEncodeAPI interface.
2934 * \param [in] registeredResource
2935 * The registered resource pointer that was returned in ::NvEncRegisterResource.
2938 * ::NV_ENC_SUCCESS \n
2939 * ::NV_ENC_ERR_INVALID_PTR \n
2940 * ::NV_ENC_ERR_INVALID_ENCODERDEVICE \n
2941 * ::NV_ENC_ERR_DEVICE_NOT_EXIST \n
2942 * ::NV_ENC_ERR_UNSUPPORTED_PARAM \n
2943 * ::NV_ENC_ERR_OUT_OF_MEMORY \n
2944 * ::NV_ENC_ERR_INVALID_VERSION \n
2945 * ::NV_ENC_ERR_INVALID_PARAM \n
2946 * ::NV_ENC_ERR_ENCODER_NOT_INITIALIZED \n
2947 * ::NV_ENC_ERR_RESOURCE_NOT_REGISTERED \n
2948 * ::NV_ENC_ERR_GENERIC \n
2949 * ::NV_ENC_ERR_UNIMPLEMENTED \n
2952 NVENCSTATUS NVENCAPI NvEncUnregisterResource (void* encoder, NV_ENC_REGISTERED_PTR registeredResource);
2954 // NvEncReconfigureEncoder
2956 * \brief Reconfigure an existing encoding session.
2958 * Reconfigure an existing encoding session.
2959 * The client should call this API to change/reconfigure the parameter passed during
2960 * NvEncInitializeEncoder API call.
2961 * Currently Reconfiguration of following are not supported.
2962 * Change in GOP structure.
2963 * Change in sync-Async mode.
2964 * Change in MaxWidth & MaxHeight.
2965 * Change in PTDmode.
2967 * Resolution change is possible only if maxEncodeWidth & maxEncodeHeight of NV_ENC_INITIALIZE_PARAMS
2968 * is set while creating encoder session.
2970 * \param [in] encoder
2971 * Pointer to the NVEncodeAPI interface.
2973 * \param [in] reInitEncodeParams
2974 * Pointer to a ::NV_ENC_RECONFIGURE_PARAMS structure.
2976 * ::NV_ENC_SUCCESS \n
2977 * ::NV_ENC_ERR_INVALID_PTR \n
2978 * ::NV_ENC_ERR_NO_ENCODE_DEVICE \n
2979 * ::NV_ENC_ERR_UNSUPPORTED_DEVICE \n
2980 * ::NV_ENC_ERR_INVALID_DEVICE \n
2981 * ::NV_ENC_ERR_DEVICE_NOT_EXIST \n
2982 * ::NV_ENC_ERR_UNSUPPORTED_PARAM \n
2983 * ::NV_ENC_ERR_GENERIC \n
2986 NVENCSTATUS NVENCAPI NvEncReconfigureEncoder (void *encoder, NV_ENC_RECONFIGURE_PARAMS* reInitEncodeParams);
2990 // NvEncCreateMVBuffer
2992 * \brief Allocates output MV buffer for ME only mode.
2994 * This function is used to allocate an output MV buffer. The size of the mvBuffer is
2995 * dependent on the frame height and width of the last ::NvEncCreateInputBuffer() call.
2996 * The NV_ENC_OUTPUT_PTR returned by the NvEncodeAPI interface in the
2997 * ::NV_ENC_CREATE_MV_BUFFER::mvBuffer field should be used in
2998 * ::NvEncRunMotionEstimationOnly() API.
2999 * Client must lock ::NV_ENC_CREATE_MV_BUFFER::mvBuffer using ::NvEncLockBitstream() API to get the motion vector data.
3001 * \param [in] encoder
3002 * Pointer to the NvEncodeAPI interface.
3003 * \param [in,out] createMVBufferParams
3004 * Pointer to the ::NV_ENC_CREATE_MV_BUFFER structure.
3007 * ::NV_ENC_SUCCESS \n
3008 * ::NV_ENC_ERR_INVALID_PTR \n
3009 * ::NV_ENC_ERR_INVALID_ENCODERDEVICE \n
3010 * ::NV_ENC_ERR_DEVICE_NOT_EXIST \n
3011 * ::NV_ENC_ERR_UNSUPPORTED_PARAM \n
3012 * ::NV_ENC_ERR_OUT_OF_MEMORY \n
3013 * ::NV_ENC_ERR_INVALID_PARAM \n
3014 * ::NV_ENC_ERR_INVALID_VERSION \n
3015 * ::NV_ENC_ERR_GENERIC \n
3017 NVENCSTATUS NVENCAPI NvEncCreateMVBuffer (void* encoder, NV_ENC_CREATE_MV_BUFFER* createMVBufferParams);
3020 // NvEncDestroyMVBuffer
3022 * \brief Release an output MV buffer for ME only mode.
3024 * This function is used to release the output MV buffer allocated using
3025 * the ::NvEncCreateMVBuffer() function. The client must release the output
3026 * mvBuffer using this function before destroying the encoder session.
3028 * \param [in] encoder
3029 * Pointer to the NvEncodeAPI interface.
3030 * \param [in] mvBuffer
3031 * Pointer to the mvBuffer being released.
3034 * ::NV_ENC_SUCCESS \n
3035 * ::NV_ENC_ERR_INVALID_PTR \n
3036 * ::NV_ENC_ERR_INVALID_ENCODERDEVICE \n
3037 * ::NV_ENC_ERR_DEVICE_NOT_EXIST \n
3038 * ::NV_ENC_ERR_UNSUPPORTED_PARAM \n
3039 * ::NV_ENC_ERR_OUT_OF_MEMORY \n
3040 * ::NV_ENC_ERR_INVALID_PARAM \n
3041 * ::NV_ENC_ERR_INVALID_VERSION \n
3042 * ::NV_ENC_ERR_ENCODER_NOT_INITIALIZED \n
3043 * ::NV_ENC_ERR_GENERIC \n
3045 NVENCSTATUS NVENCAPI NvEncDestroyMVBuffer (void* encoder, NV_ENC_OUTPUT_PTR mvBuffer);
3048 // NvEncRunMotionEstimationOnly
3050 * \brief Submit an input picture and reference frame for motion estimation in ME only mode.
3052 * This function is used to submit the input frame and reference frame for motion
3053 * estimation. The ME parameters are passed using *meOnlyParams which is a pointer
3054 * to ::_NV_ENC_MEONLY_PARAMS structure.
3055 * Client must lock ::NV_ENC_CREATE_MV_BUFFER::mvBuffer using ::NvEncLockBitstream() API to get the motion vector data.
3056 * to get motion vector data.
3058 * \param [in] encoder
3059 * Pointer to the NvEncodeAPI interface.
3060 * \param [in] meOnlyParams
3061 * Pointer to the ::_NV_ENC_MEONLY_PARAMS structure.
3064 * ::NV_ENC_SUCCESS \n
3065 * ::NV_ENC_ERR_INVALID_PTR \n
3066 * ::NV_ENC_ERR_INVALID_ENCODERDEVICE \n
3067 * ::NV_ENC_ERR_DEVICE_NOT_EXIST \n
3068 * ::NV_ENC_ERR_UNSUPPORTED_PARAM \n
3069 * ::NV_ENC_ERR_OUT_OF_MEMORY \n
3070 * ::NV_ENC_ERR_INVALID_PARAM \n
3071 * ::NV_ENC_ERR_INVALID_VERSION \n
3072 * ::NV_ENC_ERR_NEED_MORE_INPUT \n
3073 * ::NV_ENC_ERR_ENCODER_NOT_INITIALIZED \n
3074 * ::NV_ENC_ERR_GENERIC \n
3076 NVENCSTATUS NVENCAPI NvEncRunMotionEstimationOnly (void* encoder, NV_ENC_MEONLY_PARAMS* meOnlyParams);
3078 // NvEncodeAPIGetMaxSupportedVersion
3080 * \brief Get the largest NvEncodeAPI version supported by the driver.
3082 * This function can be used by clients to determine if the driver supports
3083 * the NvEncodeAPI header the application was compiled with.
3085 * \param [out] version
3086 * Pointer to the requested value. The 4 least significant bits in the returned
3087 * indicate the minor version and the rest of the bits indicate the major
3088 * version of the largest supported version.
3091 * ::NV_ENC_SUCCESS \n
3092 * ::NV_ENC_ERR_INVALID_PTR \n
3094 NVENCSTATUS NVENCAPI NvEncodeAPIGetMaxSupportedVersion (uint32_t* version);
3099 * Defines API function pointers
3101 typedef NVENCSTATUS (NVENCAPI* PNVENCOPENENCODESESSION) (void* device, uint32_t deviceType, void** encoder);
3102 typedef NVENCSTATUS (NVENCAPI* PNVENCGETENCODEGUIDCOUNT) (void* encoder, uint32_t* encodeGUIDCount);
3103 typedef NVENCSTATUS (NVENCAPI* PNVENCGETENCODEGUIDS) (void* encoder, GUID* GUIDs, uint32_t guidArraySize, uint32_t* GUIDCount);
3104 typedef NVENCSTATUS (NVENCAPI* PNVENCGETENCODEPROFILEGUIDCOUNT) (void* encoder, GUID encodeGUID, uint32_t* encodeProfileGUIDCount);
3105 typedef NVENCSTATUS (NVENCAPI* PNVENCGETENCODEPROFILEGUIDS) (void* encoder, GUID encodeGUID, GUID* profileGUIDs, uint32_t guidArraySize, uint32_t* GUIDCount);
3106 typedef NVENCSTATUS (NVENCAPI* PNVENCGETINPUTFORMATCOUNT) (void* encoder, GUID encodeGUID, uint32_t* inputFmtCount);
3107 typedef NVENCSTATUS (NVENCAPI* PNVENCGETINPUTFORMATS) (void* encoder, GUID encodeGUID, NV_ENC_BUFFER_FORMAT* inputFmts, uint32_t inputFmtArraySize, uint32_t* inputFmtCount);
3108 typedef NVENCSTATUS (NVENCAPI* PNVENCGETENCODECAPS) (void* encoder, GUID encodeGUID, NV_ENC_CAPS_PARAM* capsParam, int* capsVal);
3109 typedef NVENCSTATUS (NVENCAPI* PNVENCGETENCODEPRESETCOUNT) (void* encoder, GUID encodeGUID, uint32_t* encodePresetGUIDCount);
3110 typedef NVENCSTATUS (NVENCAPI* PNVENCGETENCODEPRESETGUIDS) (void* encoder, GUID encodeGUID, GUID* presetGUIDs, uint32_t guidArraySize, uint32_t* encodePresetGUIDCount);
3111 typedef NVENCSTATUS (NVENCAPI* PNVENCGETENCODEPRESETCONFIG) (void* encoder, GUID encodeGUID, GUID presetGUID, NV_ENC_PRESET_CONFIG* presetConfig);
3112 typedef NVENCSTATUS (NVENCAPI* PNVENCINITIALIZEENCODER) (void* encoder, NV_ENC_INITIALIZE_PARAMS* createEncodeParams);
3113 typedef NVENCSTATUS (NVENCAPI* PNVENCCREATEINPUTBUFFER) (void* encoder, NV_ENC_CREATE_INPUT_BUFFER* createInputBufferParams);
3114 typedef NVENCSTATUS (NVENCAPI* PNVENCDESTROYINPUTBUFFER) (void* encoder, NV_ENC_INPUT_PTR inputBuffer);
3115 typedef NVENCSTATUS (NVENCAPI* PNVENCCREATEBITSTREAMBUFFER) (void* encoder, NV_ENC_CREATE_BITSTREAM_BUFFER* createBitstreamBufferParams);
3116 typedef NVENCSTATUS (NVENCAPI* PNVENCDESTROYBITSTREAMBUFFER) (void* encoder, NV_ENC_OUTPUT_PTR bitstreamBuffer);
3117 typedef NVENCSTATUS (NVENCAPI* PNVENCENCODEPICTURE) (void* encoder, NV_ENC_PIC_PARAMS* encodePicParams);
3118 typedef NVENCSTATUS (NVENCAPI* PNVENCLOCKBITSTREAM) (void* encoder, NV_ENC_LOCK_BITSTREAM* lockBitstreamBufferParams);
3119 typedef NVENCSTATUS (NVENCAPI* PNVENCUNLOCKBITSTREAM) (void* encoder, NV_ENC_OUTPUT_PTR bitstreamBuffer);
3120 typedef NVENCSTATUS (NVENCAPI* PNVENCLOCKINPUTBUFFER) (void* encoder, NV_ENC_LOCK_INPUT_BUFFER* lockInputBufferParams);
3121 typedef NVENCSTATUS (NVENCAPI* PNVENCUNLOCKINPUTBUFFER) (void* encoder, NV_ENC_INPUT_PTR inputBuffer);
3122 typedef NVENCSTATUS (NVENCAPI* PNVENCGETENCODESTATS) (void* encoder, NV_ENC_STAT* encodeStats);
3123 typedef NVENCSTATUS (NVENCAPI* PNVENCGETSEQUENCEPARAMS) (void* encoder, NV_ENC_SEQUENCE_PARAM_PAYLOAD* sequenceParamPayload);
3124 typedef NVENCSTATUS (NVENCAPI* PNVENCREGISTERASYNCEVENT) (void* encoder, NV_ENC_EVENT_PARAMS* eventParams);
3125 typedef NVENCSTATUS (NVENCAPI* PNVENCUNREGISTERASYNCEVENT) (void* encoder, NV_ENC_EVENT_PARAMS* eventParams);
3126 typedef NVENCSTATUS (NVENCAPI* PNVENCMAPINPUTRESOURCE) (void* encoder, NV_ENC_MAP_INPUT_RESOURCE* mapInputResParams);
3127 typedef NVENCSTATUS (NVENCAPI* PNVENCUNMAPINPUTRESOURCE) (void* encoder, NV_ENC_INPUT_PTR mappedInputBuffer);
3128 typedef NVENCSTATUS (NVENCAPI* PNVENCDESTROYENCODER) (void* encoder);
3129 typedef NVENCSTATUS (NVENCAPI* PNVENCINVALIDATEREFFRAMES) (void* encoder, uint64_t invalidRefFrameTimeStamp);
3130 typedef NVENCSTATUS (NVENCAPI* PNVENCOPENENCODESESSIONEX) (NV_ENC_OPEN_ENCODE_SESSION_EX_PARAMS *openSessionExParams, void** encoder);
3131 typedef NVENCSTATUS (NVENCAPI* PNVENCREGISTERRESOURCE) (void* encoder, NV_ENC_REGISTER_RESOURCE* registerResParams);
3132 typedef NVENCSTATUS (NVENCAPI* PNVENCUNREGISTERRESOURCE) (void* encoder, NV_ENC_REGISTERED_PTR registeredRes);
3133 typedef NVENCSTATUS (NVENCAPI* PNVENCRECONFIGUREENCODER) (void* encoder, NV_ENC_RECONFIGURE_PARAMS* reInitEncodeParams);
3135 typedef NVENCSTATUS (NVENCAPI* PNVENCCREATEMVBUFFER) (void* encoder, NV_ENC_CREATE_MV_BUFFER* createMVBufferParams);
3136 typedef NVENCSTATUS (NVENCAPI* PNVENCDESTROYMVBUFFER) (void* encoder, NV_ENC_OUTPUT_PTR mvBuffer);
3137 typedef NVENCSTATUS (NVENCAPI* PNVENCRUNMOTIONESTIMATIONONLY) (void* encoder, NV_ENC_MEONLY_PARAMS* meOnlyParams);
3143 /** @} */ /* END ENCODE_FUNC */
3146 * \ingroup ENCODER_STRUCTURE
3147 * NV_ENCODE_API_FUNCTION_LIST
3149 typedef struct _NV_ENCODE_API_FUNCTION_LIST
3151 uint32_t version; /**< [in]: Client should pass NV_ENCODE_API_FUNCTION_LIST_VER. */
3152 uint32_t reserved; /**< [in]: Reserved and should be set to 0. */
3153 PNVENCOPENENCODESESSION nvEncOpenEncodeSession; /**< [out]: Client should access ::NvEncOpenEncodeSession() API through this pointer. */
3154 PNVENCGETENCODEGUIDCOUNT nvEncGetEncodeGUIDCount; /**< [out]: Client should access ::NvEncGetEncodeGUIDCount() API through this pointer. */
3155 PNVENCGETENCODEPRESETCOUNT nvEncGetEncodeProfileGUIDCount; /**< [out]: Client should access ::NvEncGetEncodeProfileGUIDCount() API through this pointer.*/
3156 PNVENCGETENCODEPRESETGUIDS nvEncGetEncodeProfileGUIDs; /**< [out]: Client should access ::NvEncGetEncodeProfileGUIDs() API through this pointer. */
3157 PNVENCGETENCODEGUIDS nvEncGetEncodeGUIDs; /**< [out]: Client should access ::NvEncGetEncodeGUIDs() API through this pointer. */
3158 PNVENCGETINPUTFORMATCOUNT nvEncGetInputFormatCount; /**< [out]: Client should access ::NvEncGetInputFormatCount() API through this pointer. */
3159 PNVENCGETINPUTFORMATS nvEncGetInputFormats; /**< [out]: Client should access ::NvEncGetInputFormats() API through this pointer. */
3160 PNVENCGETENCODECAPS nvEncGetEncodeCaps; /**< [out]: Client should access ::NvEncGetEncodeCaps() API through this pointer. */
3161 PNVENCGETENCODEPRESETCOUNT nvEncGetEncodePresetCount; /**< [out]: Client should access ::NvEncGetEncodePresetCount() API through this pointer. */
3162 PNVENCGETENCODEPRESETGUIDS nvEncGetEncodePresetGUIDs; /**< [out]: Client should access ::NvEncGetEncodePresetGUIDs() API through this pointer. */
3163 PNVENCGETENCODEPRESETCONFIG nvEncGetEncodePresetConfig; /**< [out]: Client should access ::NvEncGetEncodePresetConfig() API through this pointer. */
3164 PNVENCINITIALIZEENCODER nvEncInitializeEncoder; /**< [out]: Client should access ::NvEncInitializeEncoder() API through this pointer. */
3165 PNVENCCREATEINPUTBUFFER nvEncCreateInputBuffer; /**< [out]: Client should access ::NvEncCreateInputBuffer() API through this pointer. */
3166 PNVENCDESTROYINPUTBUFFER nvEncDestroyInputBuffer; /**< [out]: Client should access ::NvEncDestroyInputBuffer() API through this pointer. */
3167 PNVENCCREATEBITSTREAMBUFFER nvEncCreateBitstreamBuffer; /**< [out]: Client should access ::NvEncCreateBitstreamBuffer() API through this pointer. */
3168 PNVENCDESTROYBITSTREAMBUFFER nvEncDestroyBitstreamBuffer; /**< [out]: Client should access ::NvEncDestroyBitstreamBuffer() API through this pointer. */
3169 PNVENCENCODEPICTURE nvEncEncodePicture; /**< [out]: Client should access ::NvEncEncodePicture() API through this pointer. */
3170 PNVENCLOCKBITSTREAM nvEncLockBitstream; /**< [out]: Client should access ::NvEncLockBitstream() API through this pointer. */
3171 PNVENCUNLOCKBITSTREAM nvEncUnlockBitstream; /**< [out]: Client should access ::NvEncUnlockBitstream() API through this pointer. */
3172 PNVENCLOCKINPUTBUFFER nvEncLockInputBuffer; /**< [out]: Client should access ::NvEncLockInputBuffer() API through this pointer. */
3173 PNVENCUNLOCKINPUTBUFFER nvEncUnlockInputBuffer; /**< [out]: Client should access ::NvEncUnlockInputBuffer() API through this pointer. */
3174 PNVENCGETENCODESTATS nvEncGetEncodeStats; /**< [out]: Client should access ::NvEncGetEncodeStats() API through this pointer. */
3175 PNVENCGETSEQUENCEPARAMS nvEncGetSequenceParams; /**< [out]: Client should access ::NvEncGetSequenceParams() API through this pointer. */
3176 PNVENCREGISTERASYNCEVENT nvEncRegisterAsyncEvent; /**< [out]: Client should access ::NvEncRegisterAsyncEvent() API through this pointer. */
3177 PNVENCUNREGISTERASYNCEVENT nvEncUnregisterAsyncEvent; /**< [out]: Client should access ::NvEncUnregisterAsyncEvent() API through this pointer. */
3178 PNVENCMAPINPUTRESOURCE nvEncMapInputResource; /**< [out]: Client should access ::NvEncMapInputResource() API through this pointer. */
3179 PNVENCUNMAPINPUTRESOURCE nvEncUnmapInputResource; /**< [out]: Client should access ::NvEncUnmapInputResource() API through this pointer. */
3180 PNVENCDESTROYENCODER nvEncDestroyEncoder; /**< [out]: Client should access ::NvEncDestroyEncoder() API through this pointer. */
3181 PNVENCINVALIDATEREFFRAMES nvEncInvalidateRefFrames; /**< [out]: Client should access ::NvEncInvalidateRefFrames() API through this pointer. */
3182 PNVENCOPENENCODESESSIONEX nvEncOpenEncodeSessionEx; /**< [out]: Client should access ::NvEncOpenEncodeSession() API through this pointer. */
3183 PNVENCREGISTERRESOURCE nvEncRegisterResource; /**< [out]: Client should access ::NvEncRegisterResource() API through this pointer. */
3184 PNVENCUNREGISTERRESOURCE nvEncUnregisterResource; /**< [out]: Client should access ::NvEncUnregisterResource() API through this pointer. */
3185 PNVENCRECONFIGUREENCODER nvEncReconfigureEncoder; /**< [out]: Client should access ::NvEncReconfigureEncoder() API through this pointer. */
3187 PNVENCCREATEMVBUFFER nvEncCreateMVBuffer; /**< [out]: Client should access ::NvEncCreateMVBuffer API through this pointer. */
3188 PNVENCDESTROYMVBUFFER nvEncDestroyMVBuffer; /**< [out]: Client should access ::NvEncDestroyMVBuffer API through this pointer. */
3189 PNVENCRUNMOTIONESTIMATIONONLY nvEncRunMotionEstimationOnly; /**< [out]: Client should access ::NvEncRunMotionEstimationOnly API through this pointer. */
3190 void* reserved2[281]; /**< [in]: Reserved and must be set to NULL */
3191 } NV_ENCODE_API_FUNCTION_LIST;
3193 /** Macro for constructing the version field of ::_NV_ENCODEAPI_FUNCTION_LIST. */
3194 #define NV_ENCODE_API_FUNCTION_LIST_VER NVENCAPI_STRUCT_VERSION(2)
3196 // NvEncodeAPICreateInstance
3198 * \ingroup ENCODE_FUNC
3199 * Entry Point to the NvEncodeAPI interface.
3201 * Creates an instance of the NvEncodeAPI interface, and populates the
3202 * pFunctionList with function pointers to the API routines implemented by the
3203 * NvEncodeAPI interface.
3205 * \param [out] functionList
3209 * ::NV_ENC_ERR_INVALID_PTR
3211 NVENCSTATUS NVENCAPI NvEncodeAPICreateInstance(NV_ENCODE_API_FUNCTION_LIST *functionList);