| NVENCSTATUS NVENCAPI NvEncEncodePicture | ( | void * | encoder, |
| NV_ENC_PIC_PARAMS * | encodePicParams | ||
| ) |
Submit an input picture for encoding.
This function is used to submit an input picture buffer for encoding. The encoding parameters are passed using *encodePicParams which is a pointer to the _NV_ENC_PIC_PARAMS structure.
If the client has set NV_ENC_INITIALIZE_PARAMS::enablePTD to 0, then it must send a valid value for the following fields.
- NV_ENC_PIC_PARAMS::pictureType
- NV_ENC_PIC_PARAMS_H264::displayPOCSyntax (H264 only)
- NV_ENC_PIC_PARAMS_H264::frameNumSyntax(H264 only)
- NV_ENC_PIC_PARAMS_H264::refPicFlag(H264 only)
- Asynchronous Encoding
-
If the client has enabled asynchronous mode of encoding by setting
NV_ENC_INITIALIZE_PARAMS::enableEncodeAsync to 1 in the
NvEncInitializeEncoder() API ,then the client must send a valid
NV_ENC_PIC_PARAMS::completionEvent. Incase of asynchronous mode of operation, client can queue the
NvEncEncodePicture() API commands from the main thread and then queue output buffers to be processed to a secondary worker thread. Before the locking the output buffers in the secondary thread , the client must wait on
NV_ENC_PIC_PARAMS::completionEvent it has queued in
NvEncEncodePicture() API call. The client must always process completion event and the output buffer in the same order in which they have been submitted for encoding. The NvEncodeAPI interface is responsible for any re-ordering required for B frames and will always ensure that encoded bitstream data is written in the same order in which output buffer is submitted.
The below example shows how asynchronous encoding 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 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 the internal buffers. a) The client main thread will queue the following encode frame calls. Note the picture type is unknown to the client, the decision is being taken by NvEncodeAPI interface. The client should pass ::_NV_ENC_PIC_PARAMS parameter consisting of allocated input buffer, output buffer and output events in successive ::NvEncEncodePicture() API calls along with other required encode picture params. For example: 1st EncodePicture parameters - (I1, O1, E1) 2nd EncodePicture parameters - (I2, O2, E2) 3rd EncodePicture parameters - (I3, O3, E3) b) NvEncodeAPI SW will receive the following encode Commands from the client. The left side shows input from client in the form (Input buffer, Output Buffer, Output Event). The right hand side shows a possible picture type decision take by the NvEncodeAPI interface. (I1, O1, E1) ---P1 Frame (I2, O2, E2) ---B2 Frame (I3, O3, E3) ---P3 Frame c) NvEncodeAPI interface will make a copy of the input buffers to its internal buffersfor re-ordering. These copies are done as part of nvEncEncodePicture function call from the client and NvEncodeAPI interface is responsible for synchronization of copy operation with the actual encoding operation. I1 --> NvI1 I2 --> NvI2 I3 --> NvI3 d) After returning from ::NvEncEncodePicture() call , the client must queue the output bitstream processing work to the secondary thread. The output bitstream processing for asynchronous mode consist of first waiting on completion event(E1, E2..) and then locking the output bitstream buffer(O1, O2..) for reading the encoded data. The work queued to the secondary thread by the client is in the following order (I1, O1, E1) (I2, O2, E2) (I3, O3, E3) 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 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 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 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: Waits on E1, copies encoded bitstream from O1 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 same order in which they have submitted for encoding. -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 event are free to be reused once NvEncodeAPI interfaced has signalled the event and the client has copied the data from the output buffer.
- Synchronous Encoding
-
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 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 output bitstreams to read the encoded bitstream data. The following example explains the scenario with synchronous encoding with 2 B frames.
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 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 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. 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 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 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. The client can now read the encoded data for both the frames by locking the output O2 followed by O3 ,by calling ::NvEncLockBitstream() API. The client must always lock the output in the same order in which it has submitted to receive the encoded bitstream in correct encoding order.
- Parameters:
-
[in] encoder Pointer to the NvEncodeAPI interface. [in,out] encodePicParams Pointer to the _NV_ENC_PIC_PARAMS structure.