NVIDIA DRIVE OS Linux API Reference

5.1.3.0 Release

 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Image JPEG Encoder

Detailed Description

The NvMediaIJPE object takes uncompressed image data and turns it into a jpeg bitstream.

Data Structures

struct  NvMediaJPHuffmanTableSpecfication
 image JPEG encoder HuffmanTable. More...
 
struct  NvMediaJPEncAttributes
 image JPEG encoder attributes. More...
 
struct  NvMediaIJPE
 image JPEG encoder object created by NvMediaIJPECreate. More...
 

Macros

#define NVMEDIA_IJPE_VERSION_MAJOR   1
 Major Version number. More...
 
#define NVMEDIA_IJPE_VERSION_MINOR   3
 Minor Version number. More...
 
#define NVMEDIA_JPEG_ENC_FLAG_NONE
 JPEG encoder flag empty. More...
 
#define NVMEDIA_JPEG_ENC_FLAG_SKIP_SOI
 JPEG encoder flag to skip SOI marker. More...
 
#define NVMEDIA_IMAGE_JPEG_ATTRIBUTE_QUALITY
 Quality. More...
 
#define NVMEDIA_IMAGE_JPEG_ATTRIBUTE_RESTARTINTERVAL
 Restart interval. More...
 
#define NVMEDIA_IMAGE_JPEG_ATTRIBUTE_TARGETSIZE
 encode frame target size More...
 
#define NVMEDIA_IMAGE_JPEG_ATTRIBUTE_QUANTTABLE
 Luma/Chroma quant table. More...
 
#define NVMEDIA_IMAGE_JPEG_ATTRIBUTE_HUFFTABLE
 Huffmann table. More...
 

Functions

NvMediaStatus NvMediaIJPEGetVersion (NvMediaVersion *version)
 Gets the version compatibility for the NvMedia IJPE library. More...
 
NvMediaIJPENvMediaIJPECreate (NvMediaDevice *device, NvMediaSurfaceType inputFormat, uint8_t maxOutputBuffering, uint32_t maxBitstreamBytes)
 Creates a JPEG encoder object capable of turning a stream of surfaces of the inputFormat into a JPEG stream. More...
 
void NvMediaIJPEDestroy (NvMediaIJPE *encoder)
 Destroys an NvMedia image JPEG encoder. More...
 
NvMediaStatus NvMediaIJPEFeedFrame (NvMediaIJPE *encoder, NvMediaImage *frame, uint8_t quality)
 Encodes the specified frame with input quality. More...
 
NvMediaStatus NvMediaIJPEFeedFrameQuant (NvMediaIJPE *encoder, NvMediaImage *frame, uint8_t *lumaQuant, uint8_t *chromaQuant)
 Encodes the specified frame with input Luma and Chroma quant tables. More...
 
NvMediaStatus NvMediaIJPEFeedFrameRateControl (NvMediaIJPE *encoder, NvMediaImage *frame, uint8_t *lumaQuant, uint8_t *chromaQuant, uint32_t targetImageSize)
 Encodes the specified frame with input Luma and Chroma quant tables and targetImageSize. More...
 
NvMediaStatus NvMediaIJPESetAttributes (NvMediaIJPE *encoder, uint32_t attributeMask, void *attributes)
 Sets the JPEG encoder attributes. More...
 
NvMediaStatus NvMediaIJPEGetBits (NvMediaIJPE *encoder, uint32_t *numBytes, void *buffer, uint32_t flags)
 Returns a frame's worth of bitstream into the provided buffer. More...
 
NvMediaStatus NvMediaIJPEGetBitsEx (NvMediaIJPE *encoder, uint32_t *numBytes, uint32_t numBitstreamBuffers, const NvMediaBitstreamBuffer *bitstreams, uint32_t flags)
 Performs the same operation as NvMediaIJPEGetBits() except NvMediaIJPEGetBitsEx() consumes an array of buffers. More...
 
NvMediaStatus NvMediaIJPEBitsAvailable (NvMediaIJPE *encoder, uint32_t *numBytesAvailable, NvMediaBlockingType blockingType, uint32_t millisecondTimeout)
 Returns the encode status and number of bytes available for the next frame (if any). More...
 

Macro Definition Documentation

#define NVMEDIA_IJPE_VERSION_MAJOR   1

Major Version number.

Definition at line 35 of file nvmedia_ijpe.h.

#define NVMEDIA_IJPE_VERSION_MINOR   3

Minor Version number.

Definition at line 37 of file nvmedia_ijpe.h.

#define NVMEDIA_IMAGE_JPEG_ATTRIBUTE_HUFFTABLE

Huffmann table.

Definition at line 76 of file nvmedia_ijpe.h.

#define NVMEDIA_IMAGE_JPEG_ATTRIBUTE_QUALITY

Quality.

Definition at line 56 of file nvmedia_ijpe.h.

#define NVMEDIA_IMAGE_JPEG_ATTRIBUTE_QUANTTABLE

Luma/Chroma quant table.

Definition at line 71 of file nvmedia_ijpe.h.

#define NVMEDIA_IMAGE_JPEG_ATTRIBUTE_RESTARTINTERVAL

Restart interval.

Definition at line 61 of file nvmedia_ijpe.h.

#define NVMEDIA_IMAGE_JPEG_ATTRIBUTE_TARGETSIZE

encode frame target size

Definition at line 66 of file nvmedia_ijpe.h.

#define NVMEDIA_JPEG_ENC_FLAG_NONE

JPEG encoder flag empty.

Definition at line 43 of file nvmedia_ijpe.h.

#define NVMEDIA_JPEG_ENC_FLAG_SKIP_SOI

JPEG encoder flag to skip SOI marker.

Normally, app inserts EXIF data in jpeg image which occurs after SOI marker. This flag be used to skip SOI marker insertion.

Definition at line 50 of file nvmedia_ijpe.h.

Function Documentation

NvMediaStatus NvMediaIJPEBitsAvailable ( NvMediaIJPE encoder,
uint32_t *  numBytesAvailable,
NvMediaBlockingType  blockingType,
uint32_t  millisecondTimeout 
)

Returns the encode status and number of bytes available for the next frame (if any).

The specific behavior depends on the specified blockingType. It is safe to call this function from a separate thread.

Parameters
[in]encoderThe encoder to use.
[in]numBytesAvailableThe number of bytes available in the next encoded frame. This is valid only when the return value is NVMEDIA_STATUS_OK.
[in]blockingTypeThe following are the supported blocking types:
  • NVMEDIA_ENCODE_BLOCKING_TYPE_NEVER
    This type never blocks. As a result, millisecondTimeout is ignored. With this blockingType value, the following return values are possible:
    NVMEDIA_STATUS_OK
    NVMEDIA_STATUS_PENDING
    NVMEDIA_STATUS_NONE_PENDING
  • NVMEDIA_ENCODE_BLOCKING_TYPE_IF_PENDING
    Same as NVMEDIA_ENCODE_BLOCKING_TYPE_NEVER except that the function never returns with NVMEDIA_STATUS_PENDING. If an encode is pending, then this function blocks until the status changes to NVMEDIA_STATUS_OK or until the timeout occurs. With this blockingType value, the following return values are possible:
    NVMEDIA_STATUS_OK
    NVMEDIA_STATUS_NONE_PENDING
    NVMEDIA_STATUS_TIMED_OUT
  • NVMEDIA_ENCODE_BLOCKING_TYPE_ALWAYS With this blockingType value, the function blocks until the conditions represented by those return values are satisfied. Only the following return values are possible:
    NVMEDIA_STATUS_OK
    NVMEDIA_STATUS_TIMED_OUT
[in]millisecondTimeoutTimeout in milliseconds or NVMEDIA_VIDEO_ENCODER_TIMEOUT_INFINITE if a timeout is not desired.
Returns
NvMediaStatus The completion status of the operation. Possible values are:
NVMEDIA_STATUS_OK
NVMEDIA_STATUS_BAD_PARAMETER if any of the input parameter is NULL.
NVMEDIA_STATUS_PENDING if an encode is in progress but not yet completed.
NVMEDIA_STATUS_NONE_PENDING if no encode is in progress.
NVMEDIA_STATUS_TIMED_OUT if the operation timed out.
NvMediaIJPE* NvMediaIJPECreate ( NvMediaDevice device,
NvMediaSurfaceType  inputFormat,
uint8_t  maxOutputBuffering,
uint32_t  maxBitstreamBytes 
)

Creates a JPEG encoder object capable of turning a stream of surfaces of the inputFormat into a JPEG stream.

Surfaces are fed to the encoder with NvMediaIJPEFeedFrame() and bitstream buffers are retrieved with NvMediaIJPEGetBits().

Parameters
[in]deviceThe device this image JPEG encoder will use.
[in]inputFormatSpecifies the stream of surfaces to convert to JPEG.
[in]maxOutputBufferingThis determines how many frames of encoded bitstream can be held by the NvMediaIJPE object before it must be retrieved using NvMediaIJPEGetBits(). This number must be greater than or equal to maxInputBuffering and is clamped to between maxInputBuffering and 16. If maxOutputBuffering frames worth of encoded bitstream are yet unretrieved by NvMediaIJPEGetBits(), then NvMediaIJPEFeedFrame() returns NVMEDIA_STATUS_INSUFFICIENT_BUFFERING. One or more frames must be retrieved with NvMediaIJPEGetBits() before frame feeding can continue.
[in]maxBitstreamBytesDetermines the maximum bytes that JPEG encoder can produce for each feed frame.
Return values
NvMediaIJPEThe new image JPEG encoder device's handle or NULL if unsuccessful.
void NvMediaIJPEDestroy ( NvMediaIJPE encoder)

Destroys an NvMedia image JPEG encoder.

Parameters
[in]encoderThe JPEG encoder to destroy.
NvMediaStatus NvMediaIJPEFeedFrame ( NvMediaIJPE encoder,
NvMediaImage frame,
uint8_t  quality 
)

Encodes the specified frame with input quality.

Parameters
[in]encoderThe encoder to use.
[in]frameThis must be of the same sourceType as in the the NvMediaIJPE object. There is no limit on the size of this surface.
[in]qualityThis specifies the encode quality. JPEG encode will generate quant tables for luma and chroma according to the quality value
Supported quality value: 1..100
Returns
NvMediaStatus The completion status of the operation. Possible values are:
NVMEDIA_STATUS_OK if successful.
NVMEDIA_STATUS_BAD_PARAMETER if any of the input parameter is NULL or invalid.
NVMEDIA_STATUS_INSUFFICIENT_BUFFERING if NvMediaIJPEGetBits() has not been called frequently enough and the maximum internal bitstream buffering (determined by maxOutputBuffering passed to NvMediaIJPECreate()) has been exhausted.
NvMediaStatus NvMediaIJPEFeedFrameQuant ( NvMediaIJPE encoder,
NvMediaImage frame,
uint8_t *  lumaQuant,
uint8_t *  chromaQuant 
)

Encodes the specified frame with input Luma and Chroma quant tables.

Parameters
[in]encoderThe encoder to use.
[in]frameThis must be of the same sourceType as in the NvMediaIJPE object. There is no limit on the size of this surface.
[in]lumaQuantThis specifies Luma quant table used for encode
[in]chromaQuantThis specifies Chroma quant table used for encode
Returns
NvMediaStatus The completion status of the operation. Possible values are:
NVMEDIA_STATUS_OK if successful.
NVMEDIA_STATUS_INSUFFICIENT_BUFFERING if NvMediaIJPEGetBits() has not been called frequently enough and the maximum internal bitstream buffering (determined by maxOutputBuffering passed to NvMediaIJPECreate()) has been exhausted.
NVMEDIA_STATUS_BAD_PARAMETER if any of the input parameter is NULL or invalid.
NvMediaStatus NvMediaIJPEFeedFrameRateControl ( NvMediaIJPE encoder,
NvMediaImage frame,
uint8_t *  lumaQuant,
uint8_t *  chromaQuant,
uint32_t  targetImageSize 
)

Encodes the specified frame with input Luma and Chroma quant tables and targetImageSize.

Parameters
[in]encoderThe encoder to use.
[in]frameThis must be of the same sourceType as in the NvMediaIJPE object. There is no limit on the size of this surface.
[in]lumaQuantThis specifies Luma quant table used for encode
[in]chromaQuantThis specifies Chroma quant table used for encode
[in]targetImageSizeThis specifies target image size in bytes
Returns
NvMediaStatus The completion status of the operation. Possible values are:
NVMEDIA_STATUS_OK if successful.
NVMEDIA_STATUS_INSUFFICIENT_BUFFERING if NvMediaIJPEGetBits() has not been called frequently enough and the maximum internal bitstream buffering (determined by maxOutputBuffering passed to NvMediaIJPECreate()) has been exhausted.
NVMEDIA_STATUS_BAD_PARAMETER if any of the input parameter is NULL or invalid.
NvMediaStatus NvMediaIJPEGetBits ( NvMediaIJPE encoder,
uint32_t *  numBytes,
void *  buffer,
uint32_t  flags 
)

Returns a frame's worth of bitstream into the provided buffer.


numBytes returns the size of this bitstream. It is safe to call this function from a separate thread. The return value and behavior is the same as that of NvMediaIJPEBitsAvailable() when called with NVMEDIA_ENCODE_BLOCKING_TYPE_NEVER except that when NVMEDIA_STATUS_OK is returned, the buffer will be filled in addition to the numBytes.

Before calling this function:

  1. Call NvMediaIJPEBitsAvailable() to determine the number of bytes required for the next frame.
  2. Allocate a buffer that can hold the next frame.
Parameters
[in]encoderThe encoder to use.
[out]numBytesReturns the size of the filled bitstream.
[in,out]bufferThe buffer to be filled with the encoded data. If buffer is NULL, this function returns without copying the encoded bitstream.
[in]flagsThe flags for special handlings Current support flag NVMEDIA_JPEG_ENC_FLAG_NONE or NVMEDIA_JPEG_ENC_FLAG_SKIP_SOI
Returns
NvMediaStatus The completion status of the operation. Possible values are:
NVMEDIA_STATUS_OK
NVMEDIA_STATUS_BAD_PARAMETER if any of the input parameter is NULL.
NVMEDIA_STATUS_PENDING if an encode is in progress but not yet completed.
NVMEDIA_STATUS_NONE_PENDING if no encode is in progress.
NvMediaStatus NvMediaIJPEGetBitsEx ( NvMediaIJPE encoder,
uint32_t *  numBytes,
uint32_t  numBitstreamBuffers,
const NvMediaBitstreamBuffer bitstreams,
uint32_t  flags 
)

Performs the same operation as NvMediaIJPEGetBits() except NvMediaIJPEGetBitsEx() consumes an array of buffers.

Please see NvMediaIJPEGetBits() for usage.

Parameters
[in]encoderThe encoder to use.
[out]numBytesReturns the size of the filled bitstream.
[in]numBitstreamBuffersNumber of buffers provided to encoder
[in,out]bitstreamsPointer pointing to the array of buffers of type NvMediaBitstreamBuffer. These buffer to be filled with the encoded data. If it is NULL, this function returns without copying the encoded bitstreams.
[in]flagsThe flags for special handlings Current support flag NVMEDIA_JPEG_ENC_FLAG_NONE or NVMEDIA_JPEG_ENC_FLAG_SKIP_SOI
Returns
NvMediaStatus The completion status of the operation. Possible values are:
NVMEDIA_STATUS_OK
NVMEDIA_STATUS_BAD_PARAMETER if any of the input parameter is NULL.
NVMEDIA_STATUS_PENDING if an encode is in progress but not yet completed.
NVMEDIA_STATUS_NONE_PENDING if no encode is in progress.
NvMediaStatus NvMediaIJPEGetVersion ( NvMediaVersion version)

Gets the version compatibility for the NvMedia IJPE library.

Parameters
[in]versionA pointer to a NvMediaVersion structure of the client.
Returns
NvMediaStatus The status of the operation. Possible values are:
NVMEDIA_STATUS_OK
NVMEDIA_STATUS_BAD_PARAMETER if the pointer is invalid.
NvMediaStatus NvMediaIJPESetAttributes ( NvMediaIJPE encoder,
uint32_t  attributeMask,
void *  attributes 
)

Sets the JPEG encoder attributes.

These go into effect at the next encode frame.

Parameters
[in]encoderThe encoder to use.
[in]attributeMaskAttribute mask.
[in]attributesAttributes data.
Supported attribute structures:
NvMediaJPEncAttributes
Returns
NvMediaStatus The completion status of the operation. Possible values are:
NVMEDIA_STATUS_OK if successful.
NVMEDIA_STATUS_BAD_PARAMETER if an input parameter is NULL.