nvJPEG API Reference

This section describes the nvJPEG API.

nvJPEG Helper API Reference

The nvJPEG helper functions are used for initializing.

nvjpegGetProperty()

Gets the numeric value for the major or minor version, or the patch level, of the nvJPEG library.

Signature:

nvjpegStatus_t nvjpegGetProperty(
	libraryPropertyType   type, 
	int                   *value);

Parameters:

Parameter Input / Output Memory Description
libraryPropertyType type Input Host One of the supported libraryPropertyType values, that is, MAJOR_VERSION, MINOR_VERSION or PATCH_LEVEL.
int *value Output Host The numeric value corresponding to the specific libraryPropertyType requested.

Returns:

nvjpegStatus_t - An error code as specified in nvJPEG API Return Codes.

nvjpegCreate()

Allocates and initializes the library handle.

Signature:

nvjpegStatus_t nvjpegCreate(
	nvjpegBackend_t			backend,
	nvjpegDevAllocator_t 		*allocator,
	nvjpegHandle_t			*handle);

Parameters:

Parameter Input / Output Memory Description
nvjpegBackend_t backend Input Host A backend parameter for the library. This backend will be used for all the functions called with this handle. If this is set to DEFAULT then it automatically chooses one of the underlying algorithms.
nvjpegDevAllocator_t *allocator Input Host Device memory allocator. See nvjpegDevAllocator_t structure description. If NULL is provided, then the default CUDA runtime cudaMalloc() and cudaFree() functions will be used.
nvjpegHandle_t *handle Input/Output Host The library handle.

The nvjpegBackend_t parameter is an enum type, with the below enumerated list values: 

typedef enum {
	NVJPEG_BACKEND_DEFAULT = 0, 
	NVJPEG_BACKEND_HYBRID = 1,
} nvjpegBackend_t;

Returns:

nvjpegStatus_t - An error code as specified in nvJPEG API Return Codes.

nvjpegDestroy()

Releases the library handle.

Signature:

nvjpegStatus_t nvjpegDestroy(nvjpegHandle_t handle);

Parameters:

Parameter Input / Output Memory Description
nvjpegHandle_t handle Input/Output Host The library handle to release.

Returns:

nvjpegStatus_t - An error code as specified in nvJPEG API Return Codes.

nvjpegJpegStateCreate()

Allocates and initializes the internal structure required for the JPEG processing.

Signature:

nvjpegStatus_t nvjpegJpegStateCreate(
	nvjpegHandle_t      handle,
	nvjpegJpegState_t   *jpeg_handle);

Parameters:

Parameter Input / Output Memory Description
nvjpegHandle_t handle Input Host The library handle.
nvjpegJpegState_t *jpeg_handle Input/Output Host The image state handle.

Returns:

nvjpegStatus_t - An error code as specified in nvJPEG API Return Codes.

nvjpegJpegStateDestroy()

Releases the image internal structure.

Signature:

nvjpegStatus_t nvjpegJpegStateDestroy(nvjpegJpegState handle);

Parameters:

Parameter Input / Output Memory Description
nvjpegJpegState handle Input/Output Host The image state handle.

Returns:

nvjpegStatus_t - An error code as specified in nvJPEG API Return Codes.

Retrieve Encoded Image Information API

The helper functions for retrieving the encoded image information.

nvjpegGetImageInfo()

Decodes the JPEG header and retrieves the basic information about the image.

Signature:

nvjpegStatus_t nvjpegGetImageInfo(
	nvjpegHandle_t              handle, 
	const unsigned char         *data, 
	size_t                      length, 
	int                         *nComponents, 
	nvjpegChromaSubsampling_t   *subsampling, 
	int                         *widths, 
	int                         *heights);

Parameters:

Parameter Input / Output Memory Description
nvjpegHandle_t handle Input Host The library handle.
const unsigned char *data Input Host Pointer to the encoded data.
size_t length Input Host Size of the encoded data in bytes.
int *nComponents Output Host Chroma subsampling for the 1- or 3- channel encoding.
int *widths Output Host Pointer to the first element of array of size NVJPEG_MAX_COMPONENT, where the width of each channel (up to NVJPEG_MAX_COMPONENT) will be saved. If the channel is not encoded, then the corresponding value would be zero.
int *heights Output Host Pointer to the first element of array of size NVJPEG_MAX_COMPONENT, where the height of each channel (up to NVJPEG_MAX_COMPONENT) will be saved. If the channel is not encoded, then the corresponding value would be zero.

Returns:

nvjpegStatus_t - An error code as specified in nvJPEG API Return Codes.

Decode API -- Single Phase

Functions for decoding single image or batched images in a single phase.

​nvjpegDecode()

Decodes a single image, and writes the decoded image in the desired format to the output buffers. This function is asynchronous with respect to the host. All GPU tasks for this function will be submitted to the provided stream.

Signature:

nvjpegStatus_t nvjpegDecode(
	nvjpegHandle_t          handle,
	nvjpegJpegState_t       jpeg_handle,
	const unsigned char     *data,
	size_t                  length, 
	nvjpegOutputFormat_t    output_format,
	nvjpegImage_t           *destination,
	cudaStream_t            stream);

Parameters:

Parameter Input / Output Memory Description
nvjpegHandle_t handle Input Host The library handle.
nvjpegJpegState_t jpeg_handle Input Host The image state handle.
const unsigned char *data Input Host Pointer to the encoded data.
size_t length Input Host Size of the encoded data in bytes.
nvjpegOutputFormat_t output_format Input Host Format in which the decoded output will be saved.
nvjpegImage_t *destination Input/Output Host/Device Pointer to the structure that describes the output destination. This structure should be on the host (CPU), but the pointers in this structure should be pointing to the device (i.e., GPU) memory. See nvjpegImage_t.
cudaStream_t stream Input Host The CUDA stream where all of the GPU work will be submitted.

Returns:

nvjpegStatus_t - An error code as specified in nvJPEG API Return Codes.

​nvjpegDecodeBatchedInitialize()

This function initializes the batched decoder state. The initialization parameters include the batch size, the maximum number of CPU threads, and the specific output format in which the decoded image will be saved. This function should be called once, prior to decoding the batches of images. Any currently running batched decoding should be finished before calling this function.

Signature:

nvjpegStatus_t nvjpegDecodeBatchedInitialize(
 	nvjpegHandle_t          handle,
 	nvjpegJpegState_t       jpeg_handle,
 	int                     batch_size,
 	int                     max_cpu_threads,
 	nvjpegOutputFormat_t    output_format);

Parameters:

Parameter Input / Output Memory Description
nvjpegHandle_t handle Input Host The library handle.
nvjpegJpegState_t jpeg_handle Input Host The image state handle.
int batch_size Input Host Batch size.
int max_cpu_threads Input Host Maximum number of CPU threads that can participate in decoding a batch.
nvjpegOutputFormat_t output_format Input Host Format in which the decoded output will be saved.

Returns:

nvjpegStatus_t - An error code as specified in nvJPEG API Return Codes.

​nvjpegDecodeBatched()

Decodes the batch of images, and writes them to the buffers described in the destination parameter in a format provided to nvjpegDecodeBatchedInitialize() function. This function is asynchronous with respect to the host. All GPU tasks for this function will be submitted to the provided stream.

Signature:

nvjpegStatus_t nvjpegDecodeBatched(
 	nvjpegHandle_t             handle,
 	nvjpegJpegState_t          jpeg_handle,
 	const unsigned char *const *data,
 	const size_t               *lengths, 
 	nvjpegImage_t              *destinations,
 	cudaStream_t               stream);

Parameters:

Parameter Input / Output Memory Description
nvjpegHandle_t handle Input Host The library handle.
nvjpegJpegState_t jpeg_handle Input Host The image state handle.
const unsigned char *const *data Input Host Pointer to the first element of array of the input data. The size of the array is assumed to be batch_size provided to nvjpegDecodeBatchedInitialize() batch initialization function.
const size_t *lengths Input Host Pointer to the first element of array of input sizes. Size of array is assumed to be batch_size provided to nvjpegDecodeBatchedInitialize(), the batch initialization function.
nvjpegImage_t *destinations Input/Output Host/Device Pointer to the first element of array of output descriptors. The size of array is assumed to be batch_size provided to nvjpegDecodeBatchedInitialize(), the batch initialization function. See also nvjpegImage_t.
cudaStream_t stream Input Host

The CUDA stream where all the GPU work will be submitted.

Returns:

nvjpegStatus_t - An error code as specified in nvJPEG API Return Codes.

Decode API -- Multiple Phases

The nvJPEG library provides an ability to control the decoding process in phases. In the simple case of a single-image decode you can split the decoding into phases. For decoding multiple images, you can overlap the decoding phases of separate images within a single thread. Finally, for the batched decode you can use multiple threads to split the host tasks. Synchronization between phases should be handled with CUDA events and CUDA stream synchronization mechanisms, by the user.

Note: Note that first phases are synchronous with the respect to the host, while the second and third phases are asynchronous--for both single image and batched decode.

​nvjpegDecodePhaseOne()

The first phase of a single-image decode. You provide all the inputs, and the nvJPEG library performs any required preprocessing on the host. Any previous calls to nvjpegDecodePhaseOne() and nvjpegDecodePhaseTwo() with the same nvjpeg_handle parameter should be finished prior to this call.

Signature:

nvjpegStatus_t nvjpegDecodePhaseOne(
	nvjpegHandle_t          handle,
	nvjpegJpegState_t       jpeg_handle,
	const unsigned char     *data,
	size_t                  length,
	nvjpegOutputFormat_t    output_format,
	cudaStream_t            stream);

Parameters:

Parameter Input / Output Memory Description
nvjpegHandle_t handle Input Host The library handle.
nvjpegJpegState_t jpeg_handle Input Host The image state handle.
const unsigned char *data Input Host Pointer to the encoded stream.
size_t length Input Host Size of the encoded stream.
nvjpegOutputFormat_t output_format Input Host Format in which the decoded image will be saved.
cudaStream_t stream Input Host

The CUDA stream where all the GPU work will be submitted.

Returns:

nvjpegStatus_t - An error code as specified in nvJPEG API Return Codes.

​nvjpegDecodePhaseTwo()

In this second phase of the decoding process, the GPU (that is, the device) is involved. The decoding task is transferred to the device memory. Any required preprocessing is performed on the device. Any previous calls to nvjpegDecodePhaseTwo() and nvjpegDecodePhaseThree() with the same jpeg_handle parameter should be finished prior to this call.

Signature:

nvjpegStatus_t nvjpegDecodePhaseTwo(
 	nvjpegHandle_t       handle,
 	nvjpegJpegState_t    jpeg_handle,
 	cudaStream_t         stream);

Parameters:

Parameter Input / Output Memory Description
nvjpegHandle_t handle Input Host The library handle.
nvjpegJpegState_t jpeg_handle Input Host The image state handle.
cudaStream_t stream Input Host

The CUDA stream where all the GPU work will be submitted.

Returns:

nvjpegStatus_t - An error code as specified in nvJPEG API Return Codes.

​nvjpegDecodePhaseThree()

In this third phase of the decoding process, the decoded image is written to the output, in the specified decoding format.

Note: If the same jpeg_handle is shared for decoding multiple images simultaneously, then these multiple images should be of the same output_format.

Signature:

nvjpegStatus_t nvjpegDecodePhaseThree(
 	nvjpegHandle_t       handle,
 	nvjpegJpegState_t    jpeg_handle,
 	nvjpegImage_t        *destination,
 	cudaStream_t         stream);

Parameters:

Parameter Input / Output Memory Description
nvjpegHandle_t handle Input Host The library handle.
nvjpegJpegState_t jpeg_handle Input Host The image state handle.
nvjpegImage_t *destination Input/Output Host/Device Pointer to the structure that describes the output destination. This structure should be on host, but the pointers in this structure should be pointing to the device memory. See nvjpegImage_t description for details.
cudaStream_t stream Input Host

The CUDA stream where all the GPU work will be submitted.

Returns:

nvjpegStatus_t - An error code as specified in nvJPEG API Return Codes.

​nvjpegDecodeBatchedPhaseOne()

This first phase of the batched decoding should be called separately for each image in the batch. The batch initialization API, with appropriate batch parameters, should be called prior to starting the task with the batch.

If the batch parameters (batch size, number of threads, output format) did not change, then there is no need to initialize the batch again before starting the task.

It is possible to use multiple threads to split this first phase of the task. In which case, each thread should have a unique index. Provide the index of the image in the batch, and use the same JPEG decoding state parameter.

The thread index for the batch should be in the range of [0, max_cpu_threads-1]. The image index should be in the range of [0, batch_size-1]. Any previous calls to nvjpegDecodeBatchedPhaseOne() and nvjpegDecodeBatchedPhaseTwo() on a different batch with the same JPEG state handle parameter should be completed prior to this call.

Signature:

nvjpegStatus_t nvjpegDecodeBatchedPhaseOne(
 	nvjpegHandle_t          handle,
 	nvjpegJpegState_t       jpeg_handle,
 	const unsigned char     *data,
 	size_t                  length,
 	int                     image_idx,
 	int                     thread_idx,
 	cudaStream_t            stream);

Parameters:

Parameter Input / Output Memory Description
nvjpegHandle_t handle Input Host The library handle.
nvjpegJpegState_t jpeg_handle Input Host The image state handle.
const unsigned char *data Input Host Pointer to the encoded stream.
size_t length Input Host

Size of the encoded stream.
int image_idx Input Host Image index in the batch. Should be in the range from 0 to batch_size-1.
int thread_idx Input Host Thread index that calls this phase. Should be in the range from 0 to max_cpu_threads-1.
cudaStream_t stream Input Host The CUDA stream where all the GPU work will be submitted.

Returns:

nvjpegStatus_t - An error code as specified in nvJPEG API Return Codes.

nvjpegDecodeBatchedPhaseTwo()

This phase should be called once per batch. It should be called only after the nvjpegDecodeBatchedPhaseOne() calls for every image in the batch have finished. Any prior calls to nvjpegDecodeBatchedPhaseTwo() and nvjpegDecodeBatchedPhaseThree() for other batches with the same JPEG state handle parameter should be finished prior this call.

Signature:

nvjpegStatus_t nvjpegDecodeBatchedPhaseTwo(
	nvjpegHandle_t          handle, 
	nvjpegJpegState_t       jpeg_handle, 
	cudaStream_t            stream);

Parameters:

Parameter Input / Output Memory Description
nvjpegHandle_t handle Input Host The library handle.
nvjpegJpegState_t jpeg_handle Input Host The image state handle.
cudaStream_t stream Input Host The CUDA stream where all the GPU work will be submitted.

Returns:

nvjpegStatus_t - An error code as specified in nvJPEG API Return Codes.

nvjpegDecodeBatchedPhaseThree()

This phase should be called once per batch. It should be called only after the nvjpegDecodeBatchedPhaseTwo() call for the same batch has finished.

Between a call to nvjpegDecodeBatchedPhaseTwo() and a call to this function, no calls are allowed to nvjpegDecodeBatchedPhaseTwo() or nvjpegDecodeBatchedPhaseThree() for any other batch with the same JPEG state handle parameter.

Signature:

nvjpegStatus_t nvjpegDecodeBatchedPhaseThree(
	nvjpegHandle_t            handle, 
	nvjpegJpegState_t         jpeg_handle, 
	nvjpegImage_t             *destinations, 
	cudaStream_t              stream);

Parameters:

Parameter Input / Output Memory Description
nvjpegHandle_t handle Input Host The library handle.
nvjpegJpegState_t jpeg_handle Input Host The image state handle.
nvjpegImage_t *destinations Input/Output Host/Device

Pointer to the first element of the array of output descriptors. The size of the array is assumed to be the batch_size parameter that was provided to the batch initialization function. See nvjpegImage_t description for details.

cudaStream_t stream Input Host The CUDA stream to which all the GPU tasks will be submitted.

Returns:

nvjpegStatus_t - An error code as specified in nvJPEG API Return Codes.

nvjpeg-api-return-codes

The nvJPEG API adheres to the following return codes and their indicators: 

typedef enum
{
 NVJPEG_STATUS_SUCCESS = 0,
 NVJPEG_STATUS_NOT_INITIALIZED = 1,
 NVJPEG_STATUS_INVALID_PARAMETER = 2,
 NVJPEG_STATUS_BAD_JPEG = 3,
 NVJPEG_STATUS_JPEG_NOT_SUPPORTED = 4,
 NVJPEG_STATUS_ALLOCATOR_FAILURE = 5,
 NVJPEG_STATUS_EXECUTION_FAILED = 6,
 NVJPEG_STATUS_ARCH_MISMATCH = 7,
 NVJPEG_STATUS_INTERNAL_ERROR = 8,
} nvjpegStatus_t;

Description of the returned error codes:

Returned Error (Returned Code) Description
NVJPEG_STATUS_SUCCESS (0) The API call has finished successfully. Note that many of the calls are asynchronous and some of the errors may be seen only after synchronization.
NVJPEG_STATUS_NOT_INITIALIZED (1) The library handle was not initialized. A call to nvjpegCreate() is required to initialize the handle.
NVJPEG_STATUS_INVALID_PARAMETER (2) Wrong parameter was passed. For example, a null pointer as input data, or an image index not in the allowed range.
NVJPEG_STATUS_BAD_JPEG (3) Cannot parse the JPEG stream. Check that the encoded JPEG stream and its size parameters are correct.
NVJPEG_STATUS_JPEG_NOT_SUPPORTED (4) Attempting to decode a JPEG stream that is not supported by the nvJPEG library.
NVJPEG_STATUS_ALLOCATOR_FAILURE (5) The user-provided allocator functions, for either memory allocation or for releasing the memory, returned a non-zero code.
NVJPEG_STATUS_EXECUTION_FAILED (6) Error during the execution of the device tasks.
NVJPEG_STATUS_ARCH_MISMATCH (7) The device capabilities are not enough for the set of input parameters provided (input parameters such as backend, encoded stream parameters, output format).
NVJPEG_STATUS_INTERNAL_ERROR (8) Error during the execution of the device tasks.

nvjpeg-chroma-subsampling

One of the outputs of the nvjpegGetImageInfo() API is nvjpegChromaSubsampling_t. This parameter is an enum type, and its enumerator list comprises of the chroma subsampling property retrieved from the encoded JPEG image. Below are the chroma subsampling types the nvjpegGetImageInfo() function currently supports: 

typedef enum
{
 NVJPEG_CSS_444,
 NVJPEG_CSS_422,
 NVJPEG_CSS_420,
 NVJPEG_CSS_440,
 NVJPEG_CSS_411,
 NVJPEG_CSS_410,
 NVJPEG_CSS_GRAY,
 NVJPEG_CSS_UNKNOWN
} nvjpegChromaSubsampling_t;

Reference Documents

Refer to the JPEG standard: https://jpeg.org/jpeg/