From 88488dea32f27c4f024d9d5ba934349e96e29052 Mon Sep 17 00:00:00 2001 From: BtbN Date: Tue, 8 Dec 2015 11:18:32 +0100 Subject: [PATCH] Bump NVENC SDK header to version 6.0.1 --- ObsNvenc/inc/nvEncodeAPI.h | 980 +++++++++++++++++++++++-------------- 1 file changed, 613 insertions(+), 367 deletions(-) diff --git a/ObsNvenc/inc/nvEncodeAPI.h b/ObsNvenc/inc/nvEncodeAPI.h index 4fc09511..fa4ecfcd 100644 --- a/ObsNvenc/inc/nvEncodeAPI.h +++ b/ObsNvenc/inc/nvEncodeAPI.h @@ -1,67 +1,34 @@ /* - * Copyright 1993-2013 NVIDIA Corporation. All rights reserved. + * This copyright notice applies to this header file only: * - * NOTICE TO LICENSEE: + * Copyright (c) 2010-2015 NVIDIA Corporation * - * This source code and/or documentation ("Licensed Deliverables") are - * subject to NVIDIA intellectual property rights under U.S. and - * international Copyright laws. + * Permission is hereby granted, free of charge, to any person + * obtaining a copy of this software and associated documentation + * files (the "Software"), to deal in the Software without + * restriction, including without limitation the rights to use, + * copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the software, and to permit persons to whom the + * software is furnished to do so, subject to the following + * conditions: * - * These Licensed Deliverables contained herein is PROPRIETARY and - * CONFIDENTIAL to NVIDIA and is being provided under the terms and - * conditions of a form of NVIDIA software license agreement by and - * between NVIDIA and Licensee ("License Agreement") or electronically - * accepted by Licensee. Notwithstanding any terms or conditions to - * the contrary in the License Agreement, reproduction or disclosure - * of the Licensed Deliverables to any third party without the express - * written consent of NVIDIA is prohibited. + * The above copyright notice and this permission notice shall be + * included in all copies or substantial portions of the Software. * - * ALL NVIDIA DESIGN SPECIFICATIONS, REFERENCE BOARDS, FILES, DRAWINGS, - * DIAGNOSTICS, LISTS, AND OTHER DOCUMENTS (TOGETHER AND SEPARATELY, - * "MATERIALS") ARE BEING PROVIDED "AS IS." WITHOUT EXPRESS OR IMPLIED - * WARRANTY OF ANY KIND. NVIDIA DISCLAIMS ALL WARRANTIES WITH REGARD - * TO THESE LICENSED DELIVERABLES, INCLUDING ALL IMPLIED WARRANTIES OF - * MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE. - * NOTWITHSTANDING ANY TERMS OR CONDITIONS TO THE CONTRARY IN THE LICENSE - * AGREEMENT, IN NO EVENT SHALL NVIDIA BE LIABLE FOR ANY SPECIAL, INDIRECT, - * INCIDENTAL, OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING - * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, - * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION - * WITH THE USE OR PERFORMANCE OF THESE LICENSED DELIVERABLES. - * - * Information furnished is believed to be accurate and reliable. However, - * NVIDIA assumes no responsibility for the consequences of use of such - * information nor for any infringement of patents or other rights of - * third parties, which may result from its use. No License is granted - * by implication or otherwise under any patent or patent rights of NVIDIA - * Corporation. Specifications mentioned in the software are subject to - * change without notice. This publication supersedes and replaces all - * other information previously supplied. - * - * NVIDIA Corporation products are not authorized for use as critical - * components in life support devices or systems without express written - * approval of NVIDIA Corporation. - * - * U.S. Government End Users. These Licensed Deliverables are a - * "commercial item" as that term is defined at 48 C.F.R. 2.101 (OCT - * 1995), consisting of "commercial computer software" and "commercial - * computer software documentation" as such terms are used in 48 - * C.F.R. 12.212 (SEPT 1995) and is provided to the U.S. Government - * only as a commercial end item. Consistent with 48 C.F.R.12.212 and - * 48 C.F.R. 227.7202-1 through 227.7202-4 (JUNE 1995), all - * U.S. Government End Users acquire the Licensed Deliverables with - * only those rights set forth herein. - * - * Any use of the Licensed Deliverables in individual and commercial - * software must include, in the user documentation and internal - * comments to the code, the above Disclaimer and U.S. Government End - * Users Notice. + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES + * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT + * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, + * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR + * OTHER DEALINGS IN THE SOFTWARE. */ /** * \file nvEncodeAPI.h * NvEncodeAPI provides a NVENC Video Encoding interface to NVIDIA GPU devices based on the Kepler architecture. - * \date 2011-2013 + * \date 2011-2015 * This file contains the interface constants, structure definitions and function prototypes. */ @@ -93,6 +60,11 @@ typedef unsigned short uint16_t; extern "C" { #endif +/** + * \addtogroup ENCODER_STRUCTURE NvEncodeAPI Data structures + * @{ + */ + #ifdef _WIN32 #define NVENCAPI __stdcall typedef RECT NVENC_RECT; @@ -107,41 +79,43 @@ typedef RECT NVENC_RECT; // ========================================================================================= typedef struct { - uint32_t Data1; - uint16_t Data2; - uint16_t Data3; - uint8_t Data4[8]; + uint32_t Data1; /**< [in]: Specifies the first 8 hexadecimal digits of the GUID. */ + uint16_t Data2; /**< [in]: Specifies the first group of 4 hexadecimal digits. */ + uint16_t Data3; /**< [in]: Specifies the second group of 4 hexadecimal digits. */ + uint8_t Data4[8]; /**< [in]: Array of 8 bytes. The first 2 bytes contain the third group of 4 hexadecimal digits. + The remaining 6 bytes contain the final 12 hexadecimal digits. */ } GUID; #endif // GUID /** - * \struct NVENC_RECT + * \struct _NVENC_RECT * Defines a Rectangle. Used in ::NV_ENC_PREPROCESS_FRAME. */ typedef struct _NVENC_RECT { - uint32_t left; /**< [in]: X coordinate of the upper left corner of rectangular area to be specified. */ - uint32_t top; /**< [in]: Y coordinate of the upper left corner of the rectangular area to be specified. */ - uint32_t right; /**< [in]: X coordinate of the bottom right corner of the rectangular area to be specified. */ - uint32_t bottom; /**< [in]: Y coordinate of the bottom right corner of the rectangular area to be specified. */ + uint32_t left; /**< [in]: X coordinate of the upper left corner of rectangular area to be specified. */ + uint32_t top; /**< [in]: Y coordinate of the upper left corner of the rectangular area to be specified. */ + uint32_t right; /**< [in]: X coordinate of the bottom right corner of the rectangular area to be specified. */ + uint32_t bottom; /**< [in]: Y coordinate of the bottom right corner of the rectangular area to be specified. */ } NVENC_RECT; #endif // _WIN32 +/** @} */ /* End of GUID and NVENC_RECT structure grouping*/ typedef void* NV_ENC_INPUT_PTR; /**< NVENCODE API input buffer */ typedef void* NV_ENC_OUTPUT_PTR; /**< NVENCODE API output buffer*/ -typedef void* NV_ENC_REGISTERED_PTR; /**< A Resource that has beenr egistered with NVENCODE API*/ +typedef void* NV_ENC_REGISTERED_PTR; /**< A Resource that has been registered with NVENCODE API*/ -#define NVENCAPI_MAJOR_VERSION 4 +#define NVENCAPI_MAJOR_VERSION 6 #define NVENCAPI_MINOR_VERSION 0 -#define NVENCAPI_VERSION ((NVENCAPI_MAJOR_VERSION << 4) | (NVENCAPI_MINOR_VERSION)) +#define NVENCAPI_VERSION (NVENCAPI_MAJOR_VERSION | (NVENCAPI_MINOR_VERSION << 24)) /** * Macro to generate per-structure version for use with API. */ -#define NVENCAPI_STRUCT_VERSION(typeName, ver) (uint32_t)(sizeof(typeName) | ((ver)<<16) | (NVENCAPI_VERSION << 24)) +#define NVENCAPI_STRUCT_VERSION(ver) ((uint32_t)NVENCAPI_VERSION | ((ver)<<16) | (0x7 << 28)) #define NVENC_INFINITE_GOPLENGTH 0xffffffff @@ -156,6 +130,10 @@ typedef void* NV_ENC_REGISTERED_PTR; /**< A Resource that has beenr egist static const GUID NV_ENC_CODEC_H264_GUID = { 0x6bc82762, 0x4e63, 0x4ca4, { 0xaa, 0x85, 0x1e, 0x50, 0xf3, 0x21, 0xf6, 0xbf } }; +// {790CDC88-4522-4d7b-9425-BDA9975F7603} +static const GUID NV_ENC_CODEC_HEVC_GUID = +{ 0x790cdc88, 0x4522, 0x4d7b, { 0x94, 0x25, 0xbd, 0xa9, 0x97, 0x5f, 0x76, 0x3 } }; + // ========================================================================================= @@ -163,7 +141,7 @@ static const GUID NV_ENC_CODEC_H264_GUID = // ========================================================================================= // {BFD6F8E7-233C-4341-8B3E-4818523803F4} -static const GUID NV_ENC_CODEC_PROFILE_AUTOSELECT_GUID = +static const GUID NV_ENC_CODEC_PROFILE_AUTOSELECT_GUID = { 0xbfd6f8e7, 0x233c, 0x4341, { 0x8b, 0x3e, 0x48, 0x18, 0x52, 0x38, 0x3, 0xf4 } }; // {0727BCAA-78C4-4c83-8C2F-EF3DFF267C6A} @@ -179,7 +157,7 @@ static const GUID NV_ENC_H264_PROFILE_HIGH_GUID = { 0xe7cbc309, 0x4f7a, 0x4b89, { 0xaf, 0x2a, 0xd5, 0x37, 0xc9, 0x2b, 0xe3, 0x10 } }; // {7AC663CB-A598-4960-B844-339B261A7D52} -static const GUID NV_ENC_H264_PROFILE_HIGH_444_GUID = +static const GUID NV_ENC_H264_PROFILE_HIGH_444_GUID = { 0x7ac663cb, 0xa598, 0x4960, { 0xb8, 0x44, 0x33, 0x9b, 0x26, 0x1a, 0x7d, 0x52 } }; // {40847BF5-33F7-4601-9084-E8FE3C1DB8B7} @@ -190,10 +168,18 @@ static const GUID NV_ENC_H264_PROFILE_STEREO_GUID = static const GUID NV_ENC_H264_PROFILE_SVC_TEMPORAL_SCALABILTY = { 0xce788d20, 0xaaa9, 0x4318, { 0x92, 0xbb, 0xac, 0x7e, 0x85, 0x8c, 0x8d, 0x36 } }; +// {B405AFAC-F32B-417B-89C4-9ABEED3E5978} +static const GUID NV_ENC_H264_PROFILE_PROGRESSIVE_HIGH_GUID = +{ 0xb405afac, 0xf32b, 0x417b, { 0x89, 0xc4, 0x9a, 0xbe, 0xed, 0x3e, 0x59, 0x78 } }; + // {AEC1BD87-E85B-48f2-84C3-98BCA6285072} -static const GUID NV_ENC_H264_PROFILE_CONSTRAINED_HIGH_GUID = +static const GUID NV_ENC_H264_PROFILE_CONSTRAINED_HIGH_GUID = { 0xaec1bd87, 0xe85b, 0x48f2, { 0x84, 0xc3, 0x98, 0xbc, 0xa6, 0x28, 0x50, 0x72 } }; +// {B514C39A-B55B-40fa-878F-F1253B4DFDEC} +static const GUID NV_ENC_HEVC_PROFILE_MAIN_GUID = +{ 0xb514c39a, 0xb55b, 0x40fa, { 0x87, 0x8f, 0xf1, 0x25, 0x3b, 0x4d, 0xfd, 0xec } }; + // ========================================================================================= @@ -212,15 +198,15 @@ static const GUID NV_ENC_PRESET_HQ_GUID = { 0x34dba71d, 0xa77b, 0x4b8f, { 0x9c, 0x3e, 0xb6, 0xd5, 0xda, 0x24, 0xc0, 0x12 } }; // {82E3E450-BDBB-4e40-989C-82A90DF9EF32} -static const GUID NV_ENC_PRESET_BD_GUID = +static const GUID NV_ENC_PRESET_BD_GUID = { 0x82e3e450, 0xbdbb, 0x4e40, { 0x98, 0x9c, 0x82, 0xa9, 0xd, 0xf9, 0xef, 0x32 } }; // {49DF21C5-6DFA-4feb-9787-6ACC9EFFB726} -static const GUID NV_ENC_PRESET_LOW_LATENCY_DEFAULT_GUID = +static const GUID NV_ENC_PRESET_LOW_LATENCY_DEFAULT_GUID = { 0x49df21c5, 0x6dfa, 0x4feb, { 0x97, 0x87, 0x6a, 0xcc, 0x9e, 0xff, 0xb7, 0x26 } }; // {C5F733B9-EA97-4cf9-BEC2-BF78A74FD105} -static const GUID NV_ENC_PRESET_LOW_LATENCY_HQ_GUID = +static const GUID NV_ENC_PRESET_LOW_LATENCY_HQ_GUID = { 0xc5f733b9, 0xea97, 0x4cf9, { 0xbe, 0xc2, 0xbf, 0x78, 0xa7, 0x4f, 0xd1, 0x5 } }; // {67082A44-4BAD-48FA-98EA-93056D150A58} @@ -228,11 +214,11 @@ static const GUID NV_ENC_PRESET_LOW_LATENCY_HP_GUID = { 0x67082a44, 0x4bad, 0x48fa, { 0x98, 0xea, 0x93, 0x5, 0x6d, 0x15, 0xa, 0x58 } }; // {D5BFB716-C604-44e7-9BB8-DEA5510FC3AC} -static const GUID NV_ENC_PRESET_LOSSLESS_DEFAULT_GUID = +static const GUID NV_ENC_PRESET_LOSSLESS_DEFAULT_GUID = { 0xd5bfb716, 0xc604, 0x44e7, { 0x9b, 0xb8, 0xde, 0xa5, 0x51, 0xf, 0xc3, 0xac } }; // {149998E7-2364-411d-82EF-179888093409} -static const GUID NV_ENC_PRESET_LOSSLESS_HP_GUID = +static const GUID NV_ENC_PRESET_LOSSLESS_HP_GUID = { 0x149998e7, 0x2364, 0x411d, { 0x82, 0xef, 0x17, 0x98, 0x88, 0x9, 0x34, 0x9 } }; /** @@ -291,57 +277,46 @@ typedef enum _NV_ENC_PIC_TYPE NV_ENC_PIC_TYPE_UNKNOWN = 0xFF /**< Picture type unknown */ } NV_ENC_PIC_TYPE; -/** - * Input slice type - */ -typedef enum _NV_ENC_SLICE_TYPE -{ - NV_ENC_SLICE_TYPE_DEFAULT = 0x0, /**< Slice type is same as picture type */ - NV_ENC_SLICE_TYPE_I = 0x02, /**< Intra predicted slice */ - NV_ENC_SLICE_TYPE_UNKNOWN = 0xFF /**< Slice type unknown */ -} NV_ENC_SLICE_TYPE; - /** * Motion vector precisions */ typedef enum _NV_ENC_MV_PRECISION { + NV_ENC_MV_PRECISION_DEFAULT = 0x0, /** NvI1 - I2 --> NvI2 + I1 --> NvI1 + I2 --> NvI2 I3 --> NvI3 d) After returning from ::NvEncEncodePicture() call , the client must queue the output @@ -2134,22 +2278,22 @@ NVENCSTATUS NVENCAPI NvEncDestroyBitstreamBuffer (void* encoder, (I1, O1, E1) (I2, O2, E2) (I3, O3, E3) - Note they are in the same order in which client calls ::NvEncEncodePicture() API + Note they are in the same order in which client calls ::NvEncEncodePicture() API in \p step a). - e) NvEncodeAPI interface will do the re-ordering such that Encoder HW will receive + e) NvEncodeAPI interface will do the re-ordering such that Encoder HW will receive the following encode commands: (NvI1, O1, E1) ---P1 Frame (NvI3, O2, E2) ---P3 Frame (NvI2, O3, E3) ---B2 frame - f) After the encoding operations are completed, the events will be signalled + f) After the encoding operations are completed, the events will be signalled by NvEncodeAPI interface in the following order : (O1, E1) ---P1 Frame ,output bitstream copied to O1 and event E1 signalled. (O2, E2) ---P3 Frame ,output bitstream copied to O2 and event E2 signalled. (O3, E3) ---B2 Frame ,output bitstream copied to O3 and event E3 signalled. - g) The client must lock the bitstream data using ::NvEncLockBitstream() API in + g) The client must lock the bitstream data using ::NvEncLockBitstream() API in the order O1,O2,O3 to read the encoded data, after waiting for the events to be signalled in the same order i.e E1, E2 and E3.The output processing is done in the secondary thread in the following order: @@ -2157,57 +2301,57 @@ NVENCSTATUS NVENCAPI NvEncDestroyBitstreamBuffer (void* encoder, Waits on E2, copies encoded bitstream from O2 Waits on E3, copies encoded bitstream from O3 - -Note the client will receive the events signalling and output buffer in the + -Note the client will receive the events signalling and output buffer in the same order in which they have submitted for encoding. - -Note the LockBitstream will have picture type field which will notify the + -Note the LockBitstream will have picture type field which will notify the output picture type to the clients. - -Note the input, output buffer and the output completion eventare free to be + -Note the input, output buffer and the output completion event are free to be reused once NvEncodeAPI interfaced has signalled the event and the client has copied the data from the output buffer. * \endcode * *\par Synchronous Encoding - * The client can enable synchronous mode of encoding by setting + * The client can enable synchronous mode of encoding by setting * NV_ENC_INITIALIZE_PARAMS::enableEncodeAsync to 0 in ::NvEncInitializeEncoder() API. * The NvEncodeAPI interface may return ::NV_ENC_ERR_NEED_MORE_INPUT error code for - * some ::NvEncEncodePicture() API calls when NV_ENC_INITIALIZE_PARAMS::enablePTD - * is set to 1, but the client must not treat it as a fatal error. The NvEncodeAPI - * interface might not be able to submit an input picture buffer for encoding - * immediately due to re-ordering for B frames. The NvEncodeAPI interface cannot - * submit the input picture which is decided to be encoded as B frame as it waits + * some ::NvEncEncodePicture() API calls when NV_ENC_INITIALIZE_PARAMS::enablePTD + * is set to 1, but the client must not treat it as a fatal error. The NvEncodeAPI + * interface might not be able to submit an input picture buffer for encoding + * immediately due to re-ordering for B frames. The NvEncodeAPI interface cannot + * submit the input picture which is decided to be encoded as B frame as it waits * for backward reference from temporally subsequent frames. This input picture * is buffered internally and waits for more input picture to arrive. The client - * must not call ::NvEncLockBitstream() API on the output buffers whose - * ::NvEncEncodePicture() API returns ::NV_ENC_ERR_NEED_MORE_INPUT. The client must - * wait for the NvEncodeAPI interface to return ::NV_ENC_SUCCESS before locking the + * must not call ::NvEncLockBitstream() API on the output buffers whose + * ::NvEncEncodePicture() API returns ::NV_ENC_ERR_NEED_MORE_INPUT. The client must + * wait for the NvEncodeAPI interface to return ::NV_ENC_SUCCESS before locking the * output bitstreams to read the encoded bitstream data. The following example * explains the scenario with synchronous encoding with 2 B frames. *\code The below example shows how synchronous encoding works in case of 1 B frames ----------------------------------------------------------------------------- - Suppose the client allocated 4 input buffers(I1,I2..), 4 output buffers(O1,O2..) - and 4 completion events(E1, E2, ...). The NvEncodeAPI interface will need to - keep a copy of the input buffers for re-ordering and it allocates following + Suppose the client allocated 4 input buffers(I1,I2..), 4 output buffers(O1,O2..) + and 4 completion events(E1, E2, ...). The NvEncodeAPI interface will need to + keep a copy of the input buffers for re-ordering and it allocates following internal buffers (NvI1, NvI2...). These internal buffers are managed by NvEncodeAPI - and the client is not responsible for the allocating or freeing the memory of + and the client is not responsible for the allocating or freeing the memory of the internal buffers. The client calls ::NvEncEncodePicture() API with input buffer I1 and output buffer O1. The NvEncodeAPI decides to encode I1 as P frame and submits it to encoder - HW and returns ::NV_ENC_SUCCESS. + HW and returns ::NV_ENC_SUCCESS. The client can now read the encoded data by locking the output O1 by calling NvEncLockBitstream API. The client calls ::NvEncEncodePicture() API with input buffer I2 and output buffer O2. The NvEncodeAPI decides to encode I2 as B frame and buffers I2 by copying it to internal buffer and returns ::NV_ENC_ERR_NEED_MORE_INPUT. - The error is not fatal and it notifies client that it cannot read the encoded + The error is not fatal and it notifies client that it cannot read the encoded data by locking the output O2 by calling ::NvEncLockBitstream() API without submitting more work to the NvEncodeAPI interface. - + The client calls ::NvEncEncodePicture() with input buffer I3 and output buffer O3. - The NvEncodeAPI decides to encode I3 as P frame and it first submits I3 for + The NvEncodeAPI decides to encode I3 as P frame and it first submits I3 for encoding which will be used as backward reference frame for I2. The NvEncodeAPI then submits I2 for encoding and returns ::NV_ENC_SUCESS. Both the submission are part of the same ::NvEncEncodePicture() function call. @@ -2247,16 +2391,16 @@ NVENCSTATUS NVENCAPI NvEncEncodePicture (void* encoder, * \brief Lock output bitstream buffer * * This function is used to lock the bitstream buffer to read the encoded data. - * The client can only access the encoded data by calling this function. - * The pointer to client accessible encoded data is returned in the + * The client can only access the encoded data by calling this function. + * The pointer to client accessible encoded data is returned in the * NV_ENC_LOCK_BITSTREAM::bitstreamBufferPtr field. The size of the encoded data * in the output buffer is returned in the NV_ENC_LOCK_BITSTREAM::bitstreamSizeInBytes - * The NvEncodeAPI interface also returns the output picture type and picture structure + * The NvEncodeAPI interface also returns the output picture type and picture structure * of the encoded frame in NV_ENC_LOCK_BITSTREAM::pictureType and * NV_ENC_LOCK_BITSTREAM::pictureStruct fields respectively. If the client has * set NV_ENC_LOCK_BITSTREAM::doNotWait to 1, the function might return - * ::NV_ENC_ERR_LOCK_BUSY if client is operating in synchronous mode. This is not - * a fatal failure if NV_ENC_LOCK_BITSTREAM::doNotWait is set to 1. In the above case the client can + * ::NV_ENC_ERR_LOCK_BUSY if client is operating in synchronous mode. This is not + * a fatal failure if NV_ENC_LOCK_BITSTREAM::doNotWait is set to 1. In the above case the client can * retry the function after few milliseconds. * * \param [in] encoder @@ -2318,9 +2462,9 @@ NVENCSTATUS NVENCAPI NvEncUnlockBitstream (void* encoder, * This function is used to lock the input buffer to load the uncompressed YUV * pixel data into input buffer memory. The client must pass the NV_ENC_INPUT_PTR * it had previously allocated using ::NvEncCreateInputBuffer()in the - * NV_ENC_LOCK_INPUT_BUFFER::inputBuffer field. - * The NvEncodeAPI interface returns pointer to client accessible input buffer - * memory in NV_ENC_LOCK_INPUT_BUFFER::bufferDataPtr field. + * NV_ENC_LOCK_INPUT_BUFFER::inputBuffer field. + * The NvEncodeAPI interface returns pointer to client accessible input buffer + * memory in NV_ENC_LOCK_INPUT_BUFFER::bufferDataPtr field. * * \param [in] encoder * Pointer to the NvEncodeAPI interface. @@ -2406,16 +2550,16 @@ NVENCSTATUS NVENCAPI NvEncGetEncodeStats (void* encoder, /** * \brief Get encoded sequence and picture header. * - * This function can be used to retrieve the sequence and picture header out of - * band. The client must call this function only after the encoder has been - * initialized using ::NvEncInitializeEncoder() function. The client must + * This function can be used to retrieve the sequence and picture header out of + * band. The client must call this function only after the encoder has been + * initialized using ::NvEncInitializeEncoder() function. The client must * allocate the memory where the NvEncodeAPI interface can copy the bitstream - * header and pass the pointer to the memory in NV_ENC_SEQUENCE_PARAM_PAYLOAD::spsppsBuffer. + * header and pass the pointer to the memory in NV_ENC_SEQUENCE_PARAM_PAYLOAD::spsppsBuffer. * The size of buffer is passed in the field NV_ENC_SEQUENCE_PARAM_PAYLOAD::inBufferSize. - * The NvEncodeAPI interface will copy the bitstream header payload and returns + * The NvEncodeAPI interface will copy the bitstream header payload and returns * the actual size of the bitstream header in the field * NV_ENC_SEQUENCE_PARAM_PAYLOAD::outSPSPPSPayloadSize. - * The client must call ::NvEncGetSequenceParams() function from the same thread which is + * The client must call ::NvEncGetSequenceParams() function from the same thread which is * being used to call ::NvEncEncodePicture() function. * * \param [in] encoder @@ -2433,7 +2577,7 @@ NVENCSTATUS NVENCAPI NvEncGetEncodeStats (void* encoder, * ::NV_ENC_ERR_INVALID_VERSION \n * ::NV_ENC_ERR_INVALID_PARAM \n * ::NV_ENC_ERR_ENCODER_NOT_INITIALIZED \n - * ::NV_ENC_ERR_GENERIC \n + * ::NV_ENC_ERR_GENERIC \n * */ NVENCSTATUS NVENCAPI NvEncGetSequenceParams (void* encoder, NV_ENC_SEQUENCE_PARAM_PAYLOAD* sequenceParamPayload); @@ -2443,11 +2587,11 @@ NVENCSTATUS NVENCAPI NvEncGetSequenceParams (void* encoder, /** * \brief Register event for notification to encoding completion. * - * This function is used to register the completion event with NvEncodeAPI - * interface. The event is required when the client has configured the encoder to + * This function is used to register the completion event with NvEncodeAPI + * interface. The event is required when the client has configured the encoder to * work in asynchronous mode. In this mode the client needs to send a completion - * event with every output buffer. The NvEncodeAPI interface will signal the - * completion of the encoding process using this event. Only after the event is + * event with every output buffer. The NvEncodeAPI interface will signal the + * completion of the encoding process using this event. Only after the event is * signalled the client can get the encoded data using ::NvEncLockBitstream() function. * * \param [in] encoder @@ -2500,7 +2644,7 @@ NVENCSTATUS NVENCAPI NvEncRegisterAsyncEvent (void* encoder, NVENCSTATUS NVENCAPI NvEncUnregisterAsyncEvent (void* encoder, NV_ENC_EVENT_PARAMS* eventParams); -// NvEncMapInputResource +// NvEncMapInputResource /** * \brief Map an externally created input resource pointer for encoding. * @@ -2509,6 +2653,9 @@ NVENCSTATUS NVENCAPI NvEncUnregisterAsyncEvent (void* encoder, * mapped resource is returned in the field NV_ENC_MAP_INPUT_RESOURCE::outputResourcePtr. * The NvEncodeAPI interface also returns the buffer format of the mapped resource * in the field NV_ENC_MAP_INPUT_RESOURCE::outbufferFmt. + * This function provides synchronization guarantee that any direct3d or cuda + * work submitted on the input buffer is completed before the buffer is used for encoding. + * The client should not access any input buffer while they are mapped by the encoder. * * \param [in] encoder * Pointer to the NvEncodeAPI interface. @@ -2533,14 +2680,16 @@ NVENCSTATUS NVENCAPI NvEncUnregisterAsyncEvent (void* encoder, NVENCSTATUS NVENCAPI NvEncMapInputResource (void* encoder, NV_ENC_MAP_INPUT_RESOURCE* mapInputResParams); -// NvEncUnmapInputResource +// NvEncUnmapInputResource /** * \brief UnMaps a NV_ENC_INPUT_PTR which was mapped for encoding * * * UnMaps an input buffer which was previously mapped using ::NvEncMapInputResource() * API. The mapping created using ::NvEncMapInputResource() should be invalidated - * using this API before the external resource is destroyed by the client. + * using this API before the external resource is destroyed by the client. The client + * must unmap the buffer after ::NvEncLockBitstream() API returns succuessfully for encode + * work submitted using the mapped input buffer. * * * \param [in] encoder @@ -2570,14 +2719,14 @@ NVENCSTATUS NVENCAPI NvEncUnmapInputResource (void* enco * \brief Destroy Encoding Session * * Destroys the encoder session previously created using ::NvEncOpenEncodeSession() - * function. The client must flush the encoder before freeing any resources. In order - * to flush the encoder the client must pass a NULL encode picture packet and either - * wait for the ::NvEncEncodePicture() function to return in synchronous mode or wait + * function. The client must flush the encoder before freeing any resources. In order + * to flush the encoder the client must pass a NULL encode picture packet and either + * wait for the ::NvEncEncodePicture() function to return in synchronous mode or wait * for the flush event to be signaled by the encoder in asynchronous mode. * The client must free all the input and output resources created using the * NvEncodeAPI interface before destroying the encoder. If the client is operating * in asynchronous mode, it must also unregister the completion events previously - * registered. + * registered. * * \param [in] encoder * Pointer to the NvEncodeAPI interface. @@ -2597,15 +2746,15 @@ NVENCSTATUS NVENCAPI NvEncDestroyEncoder (void* encoder); // NvEncInvalidateRefFrames /** - * \brief Invalidate reference frames + * \brief Invalidate reference frames * - * Invalidates reference frame based on the time stamp provided by the client. - * The encoder marks any reference frames or any frames which havev been reconstructed + * Invalidates reference frame based on the time stamp provided by the client. + * The encoder marks any reference frames or any frames which have been reconstructed * using the corrupt frame as invalid for motion estimation and uses older reference * frames for motion estimation. The encoded forces the current frame to be encoded * as an intra frame if no reference frames are left after invalidation process. - * This is usefull for low latency application for error resiliency. The client - * is recommended to set NV_ENC_CONFIG_H264::maxNumRefFrames to a large value so + * This is useful for low latency application for error resiliency. The client + * is recommended to set NV_ENC_CONFIG_H264::maxNumRefFrames to a large value so * that encoder can keep a backup of older reference frames in the DPB and can use them * for motion estimation when the newer reference frames have been invalidated. * This API can be called multiple times. @@ -2631,12 +2780,12 @@ NVENCSTATUS NVENCAPI NvEncInvalidateRefFrames(void* encoder, uint64_t invalidRef // NvEncOpenEncodeSessionEx /** * \brief Opens an encoding session. - * + * * Opens an encoding session and returns a pointer to the encoder interface in * the \p **encoder parameter. The client should start encoding process by calling - * this API first. - * The client must pass a pointer to IDirect3DDevice9 interface \p *device parameter. - * If the Encoder session fails, the client must call ::NvEncDestroyEncoder API + * this API first. + * The client must pass a pointer to IDirect3DDevice9/CUDA interface in the \p *device parameter. + * If the creation of encoder session fails, the client must call ::NvEncDestroyEncoder API * before exiting. * * \param [in] openSessionExParams @@ -2659,7 +2808,7 @@ NVENCSTATUS NVENCAPI NvEncOpenEncodeSessionEx (NV_ENC_OPEN_ENC // NvEncRegisterResource /** * \brief Registers a resource with the Nvidia Video Encoder Interface. - * + * * Registers a resource with the Nvidia Video Encoder Interface for book keeping. * The client is expected to pass the registered resource handle as well, while calling ::NvEncMapInputResource API. * This API is not implemented for the DirectX Interface. @@ -2670,7 +2819,7 @@ NVENCSTATUS NVENCAPI NvEncOpenEncodeSessionEx (NV_ENC_OPEN_ENC * * \param [in] registerResParams * Pointer to a ::_NV_ENC_REGISTER_RESOURCE structure - * + * * \return * ::NV_ENC_SUCCESS \n * ::NV_ENC_ERR_INVALID_PTR \n @@ -2691,9 +2840,9 @@ NVENCSTATUS NVENCAPI NvEncRegisterResource (void* encoder, // NvEncUnregisterResource /** * \brief Unregisters a resource previously registered with the Nvidia Video Encoder Interface. - * + * * Unregisters a resource previously registered with the Nvidia Video Encoder Interface. - * The client is expected to unregister any resource that it has registered with the + * The client is expected to unregister any resource that it has registered with the * Nvidia Video Encoder Interface before destroying the resource. * This API is not implemented for the DirectX Interface. * DirectX based clients need not change their implementation. @@ -2724,19 +2873,19 @@ NVENCSTATUS NVENCAPI NvEncUnregisterResource (void* encoder, // NvEncReconfigureEncoder /** * \brief Reconfigure an existing encoding session. - * + * * Reconfigure an existing encoding session. - * The client should call this API to change/reconfigure the parameter passed during + * The client should call this API to change/reconfigure the parameter passed during * NvEncInitializeEncoder API call. * Currently Reconfiguration of following are not supported. * Change in GOP structure. * Change in sync-Async mode. * Change in MaxWidth & MaxHeight. * Change in PTDmode. - * + * * Resolution change is possible only if maxEncodeWidth & maxEncodeHeight of NV_ENC_INITIALIZE_PARAMS * is set while creating encoder session. - * + * * \param [in] encoder * Pointer to the NVEncodeAPI interface. * @@ -2756,9 +2905,97 @@ NVENCSTATUS NVENCAPI NvEncUnregisterResource (void* encoder, NVENCSTATUS NVENCAPI NvEncReconfigureEncoder (void *encoder, NV_ENC_RECONFIGURE_PARAMS* reInitEncodeParams); + +// NvEncCreateMVBuffer +/** + * \brief Allocates output MV buffer for ME only mode. + * + * This function is used to allocate an output MV buffer. The size of the MVBuffer is + * dependent on the frame height and width of the last NVEncCreateInputBuffer call. + * The NV_ENC_OUTPUT_PTR returned by the NvEncodeAPI interface in the + * NV_ENC_CREATE_MV_BUFFER::MVBuffer field can be used in + * ::NvEncRunMotionEstimationOnly() API. + * + * \param [in] encoder + * Pointer to the NvEncodeAPI interface. + * \param [in,out] createMVBufferParams + * Pointer to the ::NV_ENC_CREATE_MV_BUFFER structure. + * + * \return + * ::NV_ENC_SUCCESS \n + * ::NV_ENC_ERR_INVALID_PTR \n + * ::NV_ENC_ERR_INVALID_ENCODERDEVICE \n + * ::NV_ENC_ERR_DEVICE_NOT_EXIST \n + * ::NV_ENC_ERR_UNSUPPORTED_PARAM \n + * ::NV_ENC_ERR_OUT_OF_MEMORY \n + * ::NV_ENC_ERR_INVALID_PARAM \n + * ::NV_ENC_ERR_INVALID_VERSION \n + * ::NV_ENC_ERR_GENERIC \n + */ +NVENCSTATUS NVENCAPI NvEncCreateMVBuffer (void* encoder, NV_ENC_CREATE_MV_BUFFER* createMVBufferParams); + + +// NvEncDestroyMVBuffer +/** + * \brief Release an output MV buffer for ME only mode. + * + * This function is used to release the output MV buffer allocated using + * the :: NvEncCreateMVBuffer() function. The client must release the output + * MVBuffer using this function before destroying the encoder session. + * + * \param [in] encoder + * Pointer to the NvEncodeAPI interface. + * \param [in] MVBuffer + * Pointer to the MVBuffer being released. + * + * \return + * ::NV_ENC_SUCCESS \n + * ::NV_ENC_ERR_INVALID_PTR \n + * ::NV_ENC_ERR_INVALID_ENCODERDEVICE \n + * ::NV_ENC_ERR_DEVICE_NOT_EXIST \n + * ::NV_ENC_ERR_UNSUPPORTED_PARAM \n + * ::NV_ENC_ERR_OUT_OF_MEMORY \n + * ::NV_ENC_ERR_INVALID_PARAM \n + * ::NV_ENC_ERR_INVALID_VERSION \n + * ::NV_ENC_ERR_ENCODER_NOT_INITIALIZED \n + * ::NV_ENC_ERR_GENERIC \n + */ +NVENCSTATUS NVENCAPI NvEncDestroyMVBuffer (void* encoder, NV_ENC_OUTPUT_PTR MVBuffer); + + +// NvEncRunMotionEstimationOnly +/** + * \brief Submit an input picture and reference frame for motion estimation in ME only mode. + * + * This function is used to submit the input frame and reference frame for motion + * estimation. The ME parameters are passed using *MEOnlyParams which is a pointer + * to ::NV_ENC_MEONLY_PARAMS structure. The output motion vector data will be returned + * to the buffer NV_ENC_MEONLY_PARAMS::outputMV. + * + * \param [in] encoder + * Pointer to the NvEncodeAPI interface. + * \param [in,out] MEOnlyParams + * Pointer to the ::_NV_ENC_MEONLY_PARAMS structure. + * + * \return + * ::NV_ENC_SUCCESS \n + * ::NV_ENC_ERR_INVALID_PTR \n + * ::NV_ENC_ERR_INVALID_ENCODERDEVICE \n + * ::NV_ENC_ERR_DEVICE_NOT_EXIST \n + * ::NV_ENC_ERR_UNSUPPORTED_PARAM \n + * ::NV_ENC_ERR_OUT_OF_MEMORY \n + * ::NV_ENC_ERR_INVALID_PARAM \n + * ::NV_ENC_ERR_INVALID_VERSION \n + * ::NV_ENC_ERR_NEED_MORE_INPUT \n + * ::NV_ENC_ERR_ENCODER_NOT_INITIALIZED \n + * ::NV_ENC_ERR_GENERIC \n + */ +NVENCSTATUS NVENCAPI NvEncRunMotionEstimationOnly (void* encoder, NV_ENC_MEONLY_PARAMS* MEOnlyParams); + + /// \cond API PFN /* - * Defines API function pointers + * Defines API function pointers */ typedef NVENCSTATUS (NVENCAPI* PNVENCOPENENCODESESSION) (void* device, uint32_t deviceType, void** encoder); typedef NVENCSTATUS (NVENCAPI* PNVENCGETENCODEGUIDCOUNT) (void* encoder, uint32_t* encodeGUIDCount); @@ -2794,6 +3031,11 @@ typedef NVENCSTATUS (NVENCAPI* PNVENCREGISTERRESOURCE) (void* encoder, typedef NVENCSTATUS (NVENCAPI* PNVENCUNREGISTERRESOURCE) (void* encoder, NV_ENC_REGISTERED_PTR registeredRes); typedef NVENCSTATUS (NVENCAPI* PNVENCRECONFIGUREENCODER) (void* encoder, NV_ENC_RECONFIGURE_PARAMS* reInitEncodeParams); +typedef NVENCSTATUS (NVENCAPI* PNVENCCREATEMVBUFFER) (void* encoder, NV_ENC_CREATE_MV_BUFFER* createMVBufferParams); +typedef NVENCSTATUS (NVENCAPI* PNVENCDESTROYMVBUFFER) (void* encoder, NV_ENC_OUTPUT_PTR MVBuffer); +typedef NVENCSTATUS (NVENCAPI* PNVENCRUNMOTIONESTIMATIONONLY) (void* encoder, NV_ENC_MEONLY_PARAMS* MEOnlyParams); + + /// \endcond @@ -2810,7 +3052,7 @@ typedef struct _NV_ENCODE_API_FUNCTION_LIST PNVENCOPENENCODESESSION nvEncOpenEncodeSession; /**< [out]: Client should access ::NvEncOpenEncodeSession() API through this pointer. */ PNVENCGETENCODEGUIDCOUNT nvEncGetEncodeGUIDCount; /**< [out]: Client should access ::NvEncGetEncodeGUIDCount() API through this pointer. */ PNVENCGETENCODEPRESETCOUNT nvEncGetEncodeProfileGUIDCount; /**< [out]: Client should access ::NvEncGetEncodeProfileGUIDCount() API through this pointer.*/ - PNVENCGETENCODEPRESETGUIDS nvEncGetEncodeProfileGUIDs; /**< [out]: Client should access ::NvEncGetEncodeProfileGUIDs() API through this pointer. */ + PNVENCGETENCODEPRESETGUIDS nvEncGetEncodeProfileGUIDs; /**< [out]: Client should access ::NvEncGetEncodeProfileGUIDs() API through this pointer. */ PNVENCGETENCODEGUIDS nvEncGetEncodeGUIDs; /**< [out]: Client should access ::NvEncGetEncodeGUIDs() API through this pointer. */ PNVENCGETINPUTFORMATCOUNT nvEncGetInputFormatCount; /**< [out]: Client should access ::NvEncGetInputFormatCount() API through this pointer. */ PNVENCGETINPUTFORMATS nvEncGetInputFormats; /**< [out]: Client should access ::NvEncGetInputFormats() API through this pointer. */ @@ -2840,17 +3082,21 @@ typedef struct _NV_ENCODE_API_FUNCTION_LIST PNVENCREGISTERRESOURCE nvEncRegisterResource; /**< [out]: Client should access ::NvEncRegisterResource() API through this pointer. */ PNVENCUNREGISTERRESOURCE nvEncUnregisterResource; /**< [out]: Client should access ::NvEncUnregisterResource() API through this pointer. */ PNVENCRECONFIGUREENCODER nvEncReconfigureEncoder; /**< [out]: Client should access ::NvEncReconfigureEncoder() API through this pointer. */ - void* reserved2[285]; /**< [in]: Reserved and must be set to NULL */ + void* reserved1; + PNVENCCREATEMVBUFFER nvEncCreateMVBuffer; /**< [out]: Client should access ::NvEncCreateMVBuffer API through this pointer. */ + PNVENCDESTROYMVBUFFER nvEncDestroyMVBuffer; /**< [out]: Client should access ::NvEncDestroyMVBuffer API through this pointer. */ + PNVENCRUNMOTIONESTIMATIONONLY nvEncRunMotionEstimationOnly; /**< [out]: Client should access ::NvEncRunMotionEstimationOnly API through this pointer. */ + void* reserved2[281]; /**< [in]: Reserved and must be set to NULL */ } NV_ENCODE_API_FUNCTION_LIST; /** Macro for constructing the version field of ::_NV_ENCODEAPI_FUNCTION_LIST. */ -#define NV_ENCODE_API_FUNCTION_LIST_VER NVENCAPI_STRUCT_VERSION(NV_ENCODE_API_FUNCTION_LIST, 2) +#define NV_ENCODE_API_FUNCTION_LIST_VER NVENCAPI_STRUCT_VERSION(2) // NvEncodeAPICreateInstance /** * \ingroup ENCODE_FUNC * Entry Point to the NvEncodeAPI interface. - * + * * Creates an instance of the NvEncodeAPI interface, and populates the * pFunctionList with function pointers to the API routines implemented by the * NvEncodeAPI interface.