nvJPEG (PDF) - v10.0.130 (older) - Last updated August 25, 2018 - Send Feedback

## 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/