nvJPEG2000 Documentation

Introduction

The nvJPEG2000 library accelerates the decoding and encoding of JPEG2000 images on NVIDIA GPUs. The library is built on the CUDA platform and is supported on Pascal+ GPU architectures.

Note

Throughout this document, the terms “CPU” and “Host” are used synonymously. Similarly, the terms “GPU” and “Device” are synonymous.

nvJPEG2000 Decoder

The library utilizes both CPU and GPU for decoding. Tier 2 decode stage (first stage of decode; please refer to the JPEG2000 specification for details) is run on the CPU. All other stages of the decoding process are offloaded to the GPU.

The nvJPEG2000 decoder supports the following:

JPEG2000 Options:

  • Up to 16 bits per component

  • No of components : 4

  • Reversible(5-3) and irreversible(9-7) wavelet transforms

  • Multiple tiles per image

  • Up to 20 layers per image

  • Chroma sub-sampling types - 444, 422, and 420

  • All progression orders

  • Image and tile start coordinates should be 0

  • Tile/Resolution based decoding

  • Partial decoding of tiles and images

  • jp2 file format and jpeg2000 codestream

Features:

nvJPEG2000 Encoder

The library utilizes both GPU and CPU to create JPEG2000 bitstreams. The encode APIs require that the input image is on device memory, and the compressed bitstream will be written to host memory.

The nvJPEG2000 encoder supports the following JPEG2000 options:

  • Up to 16 bits per component

  • No of components : 4

  • Reversible(5-3) and irreversible(9-7) wavelet transforms

  • Multiple tiles per image

  • Single layer per image

  • All progression orders

  • Chroma sub-sampling types - 444, 422, and 420

  • jp2 file format and jpeg2000 codestream

  • PSNR based rate control

Prerequisites

  • CUDA Toolkit version 11.0 and above

  • CUDA Driver version r450 and above

Platforms Supported

  • Linux versions:

Architecture

Distribution Information

Name

Version

Kernel

GCC

GLIBC

x86_64

RHEL/CentOS

8.3

4.18

8.3.1

2.28

7.9

3.10.0

6

2.17

Ubuntu

20.04.1

5.8.0

9.3.0

2.31

18.04.5

5.3.0

7.5.0

2.27

16.04.7

4.15.0

5.4.0

2.23

OpenSUSE Leap

15.2

5.3.18

7.5.0

2.26

SUSE SLES

15.2

5.3.18

7.5.0

2.26

Debian

10.8

4.19.0

8.3.0

2.28

Fedora

33

5.10.13

10.2.1

2.32

  • Windows versions:

    • Windows 10 and Windows Server 2019

    • Support added from version 0.1.0 onwards

Thread Safety

Not all nvJPEG2000 types are thread safe. The following should be instantiated separately for each thread: nvjpeg2kDecodeState_t and nvjpeg2kStream_t

Quick Start Guide

This section will explain how to use decoder and encoder APIs in a few quick steps. The API details will be covered in the next section.

JPEG2000 Decode

The library expects the bitstream to be on host memory and the decoded output will be written to device memory.

  1. Initialize the library handles listed below:

  • nvjpeg2kStream_t - is used to parse the bitstream and store the bitstream metadata

  • nvjpeg2kHandle_t - is the nvjpeg2k library handle

  • nvjpeg2kDecodeState_t - is used to store the work buffers required for decode

nvjpeg2kHandle_t nvjpeg2k_handle;
nvjpeg2kStream_t nvjpeg2k_stream;
nvjpeg2kDecodeState_t decode_state;

nvjpeg2kCreateSimple(&nvjpeg2k_handle);
nvjpeg2kDecodeStateCreate(&decode_state);
nvjpeg2kStreamCreate(&nvjpeg2k_stream);
  1. Read the JPEG2000 bitstream file from disk and store it in the host buffer. The library supports .jp2 files and JPEG2000 codestreams.

  2. Use the nvjpeg2kStreamParse API to parse the bitstream.

size_t length;
unsigned char *bitstream_buffer;  // host or pinned memory
// read the bitstream from and store it in bitstream_buffer;

// content of bitstream buffer should not be overwritten until the decoding is complete
nvjpeg2kStatus_t status = nvjpeg2kStreamParse(nvjpeg2k_handle, bitstream_buffer, length, 0, 0, nvjpeg2k_stream);
// make sure that nvjpeg2kStreamParse returns NVJPEG2K_STATUS_SUCCESS before proceeding to the next step

4. Extract the image dimensions for each component and allocate output memory on the device as shown in the below snippet. The decoded output is stored in nvjpeg2kImage_t. This data structure has the ability to handle data 8 and 16 bit precision outputs. The below snippet demonstrates initialization of nvjpeg2kImage_t for an 8 bit 3 channel image.

#define NUM_COMPONENTS 3
// extract image info
nvjpeg2kImageInfo_t image_info;
nvjpeg2kStreamGetImageInfo(nvjpeg2k_stream, &image_info);

// assuming the decoding of images with 8 bit precision, and 3 components

nvjpeg2kImageComponentInfo_t image_comp_info[NUM_COMPONENTS];

for (int c = 0; c < image_info.num_components; c++)
{
    nvjpeg2kStreamGetImageComponentInfo(nvjpeg2k_stream, &image_comp_info[c], c);
}

unsigned char *decode_output[NUM_COMPONENTS];
size_t*pitch_in_bytes[NUM_COMPONENTS];

nvjpeg2kImage_t output_image;
for (int c = 0; c < NUM_COMPONENTS; c++)
{
    cudaMallocPitch(&decode_output[c], &pitch_in_bytes[c], image_comp_info[c].comp_width, image_comp_info[c].comp_height );
}

output_image.pixel_data = decode_output;
output_image.pixel_type = NVJPEG2K_UINT8;
output_image.pitch_in_bytes = pitch_in_bytes;
  1. Call nvjpeg2kDecode(). One of the parameters of this function is cudaStream_t. If a stream identifier is passed then the API will use it to issue the asychronous cuda calls. cudaDeviceSynchronize() is required to complete the decoding process since nvjpeg2kDecode is asychronous with respect to the host.

nvjpeg2kStatus_t status = nvjpeg2kDecode(nvjpeg2k_handle, decode_state, nvjpeg2k_stream, &output_image, 0); // 0 corresponds to cudaStream_t
cudaDeviceSynchronize()
  1. Go to step 2 to decode another image. Once all images are decoded, release the nvJPEG2000 library resources by calling the corresponding destroy APIs.

JPEG2000 Encode

The library expects the input image to be on device memory in planar format and the compressed output will written to host memory.

  1. Initialize the library handles listed below:

  • nvjpeg2kEncoder_t - is the nvJPEG2000 encoder handle

  • nvjpeg2kEncodeState_t - is used to store the encoder work buffers and intermediate results

  • nvjpeg2kEncodeParams_t - stores various parameters that control the compressed output

nvjpeg2kEncoder_t enc_handle;
nvjpeg2kEncodeState_t enc_state;
nvjpeg2kEncodeParams_t enc_params;

nvjpeg2kEncoderCreateSimple(&enc_handle);
nvjpeg2kEncodeStateCreate(&enc_state);
nvjpeg2kEncodeParamsCreate(&enc_params);

2. Copy the input image to device memory in planar format. Store the image buffer pointers in nvjpeg2kImage_t. The below snippet demonstrates initialization of nvjpeg2kImage_t and nvjpeg2kImageComponentInfo_t for a 8 bit 3 channel RGB image.

#define NUM_COMPONENTS 3
unsigned char *pixel_data[NUM_COMPONENTS];
size_t *pitch_in_bytes[NUM_COMPONENTS];

nvjpeg2kImageComponentInfo_t image_comp_info[NUM_COMPONENTS];

uint32_t image_width  =  // assign image width
uint32_t image_height =  // assign image height

for (int c = 0; c < image_info.num_components; c++)
{
    image_comp_info[c].component_width  = image_width;
    image_comp_info[c].component_height = image_height;
    image_comp_info[c].precision        = 8;
    image_comp_info[c].sgn              = 0;
}

nvjpeg2kImage_t input_image;
for (int c = 0; c < NUM_COMPONENTS; c++)
{
    cudaMallocPitch(&pixel_data[c], &pitch_in_bytes[c], image_comp_info[c].comp_width, image_comp_info[c].comp_height);
    // cudaMallocPitch is used to let cuda deterimine the pitch. cudaMalloc can be used if required.
}

// Copy the image to the device buffers.

input_image.pixel_data = pixel_data;
input_image.pixel_type = NVJPEG2K_UINT8;
input_image.pitch_in_bytes = pitch_in_bytes;

3. Populate the nvjpeg2kEncodeConfig_t structure and call nvjpeg2kEncodeParamsSetEncodeConfig. The below code snippet documents the settings to generate a JPEG2000 bitstream using reversible wavelet transform with 64x64 code block size.

Note

The valid values for each field in nvjpeg2kEncodeConfig_t are documented here.

nvjpeg2kEncodeConfig_t enc_config;
memset(&enc_config, 0, sizeof(enc_config));
enc_config.stream_type      =  NVJPEG2K_STREAM_JP2; // the bitstream will be in JP2 container format
enc_config.color_space      =  NVJPEG2K_COLORSPACE_SRGB; // input image is in RGB format
enc_config.image_width      =  image_width;
enc_config.image_height     =  image_height;
enc_config.num_components   =  NUM_COMPONENTS;
enc_config.image_comp_info  =  &image_comp_info;
enc_config.code_block_w     =  64;
enc_config.code_block_h     =  64;
enc_config.irreversible     =  0
enc_config.mct_mode         =  1;
enc_config.prog_order       =  NVJPEG2K_LRCP;
enc_config.num_resolutions  =  6;

nvjpeg2kStatus_t status = nvjpeg2kEncodeParamsSetEncodeConfig(enc_params, &enc_config);

Note

All nvJPEG2000 APIs should return NVJPEG2K_STATUS_SUCCESS. The results may not be valid otherwise.

  1. For lossy encode, set the target PSNR in decibels(dB) as shown below. It is not required to call this API for lossless encode.

double target_psnr = 50;
status = nvjpeg2kEncodeParamsSetQuality(enc_params, target_psnr));
  1. Call nvjpeg2kEncode. One of the parameters of this function is cudaStream_t. If a stream identifier is passed then the API will use it to issue the asychronous cuda calls.

status = nvjpeg2kEncode(enc_handle, enc_state, enc_params, &input_image, NULL));

6. Retrieve the compressed JPEG2000 bitstream to host memory as shown in the below code snippet. If a stream identifier is passed, then the API will use it to issue the asynchronous cuda calls. cudaDeviceSynchronize() is required to complete the encoding process since the APIs are asynchronous with respect to the host.

// set the compressed_data buffer to NULL to retrieve the bitstream size
size_t compressed_size;
status = nvjpeg2kEncodeRetrieveBitstream(enc_handle, enc_state, NULL, &compressed_size);

// allocate output buffer
unsigned char *compressed_data = new unsigned char [compressed_size]
status = nvjpeg2kEncodeRetrieveBitstream(enc_handle, enc_state, compressed_data, &compressed_size,
    params.stream));
cudaDeviceSynchronize();

7 Go to step 2 to encode another image. Once all images are encoded, release the nvJPEG2000 library resources by calling the corresponding destroy APIs.

Type Declarations

API Return Status Codes

The return codes of the nvJPEG2000 APIs are listed below:

typedef enum
{
    NVJPEG2K_STATUS_SUCCESS                       = 0,
    NVJPEG2K_STATUS_NOT_INITIALIZED               = 1,
    NVJPEG2K_STATUS_INVALID_PARAMETER             = 2,
    NVJPEG2K_STATUS_BAD_JPEG                      = 3,
    NVJPEG2K_STATUS_JPEG_NOT_SUPPORTED            = 4,
    NVJPEG2K_STATUS_ALLOCATOR_FAILURE             = 5,
    NVJPEG2K_STATUS_EXECUTION_FAILED              = 6,
    NVJPEG2K_STATUS_ARCH_MISMATCH                 = 7,
    NVJPEG2K_STATUS_INTERNAL_ERROR                = 8,
    NVJPEG2K_STATUS_IMPLEMENTATION_NOT_SUPPORTED  = 9,
} nvjpeg2kStatus_t;

Description the Return Codes

Return Code

Description

NVJPEG2K_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.

NVJPEG2K_STATUS_NOT_INITIALIZED (1)

The library handle was not initialized.

NVJPEG2K_STATUS_INVALID_PARAMETER (2)

Wrong parameter was passed. For example, a null pointer as input data, or an invalid enum value

NVJPEG2K_STATUS_BAD_JPEG (3)

Cannot parse the JPEG2000 stream. Likely due to a corruption that cannot be handled

NVJPEG2K_STATUS_JPEG_NOT_SUPPORTED (4)

Attempting to decode a JPEG2000 stream that is not supported by the nvJPEG2000 library.

NVJPEG2K_STATUS_ALLOCATOR_FAILURE (5)

The user-provided allocator functions, for either memory allocation or for releasing the memory, returned a non-zero code.

NVJPEG2K_STATUS_EXECUTION_FAILED (6)

Error during the execution of the device tasks.

NVJPEG2K_STATUS_ARCH_MISMATCH (7)

The device capabilities are not enough for the set of input parameters provided.

NVJPEG2K_STATUS_INTERNAL_ERROR (8)

Unknown error occured in the library.

NVJPEG2K_STATUS_IMPLEMENTATION_NOT_SUPPORTED (9)

API is not supported by the backend.

Device Allocator Interface

typedef int (*nvjpeg2kDeviceMalloc)(void**, size_t);
typedef int (*nvjpeg2kDeviceFree)(void*);
typedef struct
{
    nvjpeg2kDeviceMalloc device_malloc;
    nvjpeg2kDeviceFree device_free;
} nvjpeg2kDeviceAllocator_t;

When the nvjpeg2kDeviceAllocator_t *allocator parameter in the nvjpeg2kCreate() function is set as a pointer to the above nvjpeg2kDeviceAllocator_t structure, then this structure is used for allocating and releasing the device memory. The function prototypes for the memory allocation and memory freeing functions are similar to the cudaMalloc() and cudaFree() functions. They should return 0 in case of success, and non-zero otherwise.

However, if the nvjpeg2kDeviceAllocator_t *allocator parameter in the nvjpeg2kCreate() function is set to NULL, then the default memory allocation functions cudaMalloc() and cudaFree() will be used. When using nvjpeg2kCreateSimple() function to create library handle the default device memory allocator will be used.

Pinned Allocator Interface

typedef int (*nvjpeg2kPinnedMalloc)(void**, size_t, unsigned int flags);
typedef int (*nvjpeg2kPinnedFree)(void*)
typedef struct
{
    nvjpeg2kPinnedMalloc pinned_malloc;
    nvjpeg2kPinnedFree   pinned_free;
} nvjpeg2kPinnedAllocator_t;

When the nvjpegPinnedAllocator_t *allocator parameter in the nvjpeg2kCreate() function is set as a pointer to the above nvjpegPinnedAllocator_t structure, then this structure will be used for allocating and releasing host pinned memory for copying data to/from device. The function prototypes for the memory allocation and memory freeing functions are similar to cudaHostAlloc() and cudaFreeHost() functions. They will return 0 in case of success, and non-zero otherwise.

However, if the nvjpeg2kPinnedAllocator_t *allocator parameter in the nvjpeg2kCreate() function is set to NULL, then the default memory allocation functions cudaHostAlloc() and cudaFreeHost() will be used. When using nvjpegCreateSimple() function to create library handle, the default host pinned memory allocator will be used.

Color Space

typedef enum
{
    NVJPEG2K_COLORSPACE_NOT_SUPPORTED = -1,
    NVJPEG2K_COLORSPACE_UNKNOWN       = 0,
    NVJPEG2K_COLORSPACE_SRGB          = 1,
    NVJPEG2K_COLORSPACE_GRAY          = 2,
    NVJPEG2K_COLORSPACE_SYCC          = 3
} nvjpeg2kColorSpace_t;

The nvjpeg2kColorSpace_t enum corresponds to the colorspace values which are part of the JP2 file format specification.

Library Backend

typedef enum
{
    NVJPEG2K_BACKEND_DEFAULT = 0
} nvjpeg2kBackend_t;

The nvjpeg2kBackend_t enum allows the user the option to select a different internal implementation. A single implementation is currently supported. Additional implementations may be added in the future.

Component Information

typedef struct
{
    uint32_t component_width;
    uint32_t component_height;
    uint8_t  precision;
    uint8_t  sgn;
} nvjpeg2kImageComponentInfo_t;

nvjpeg2kImageComponentInfo_t is used to retrieve component level information. This information can be used for allocating output buffers.

Image Information

typedef struct
{
    uint32_t image_width;
    uint32_t image_height;
    uint32_t tile_width;
    uint32_t tile_height;
    uint32_t num_tiles_x;
    uint32_t num_tiles_y;
    uint32_t num_components;
} nvjpeg2kImageInfo_t;

nvjpeg2kImageInfo_t is used to retrieve image information which can be used to allocate output buffers.

Image Type

typedef enum
{
    NVJPEG2K_UINT8 = 0,
    NVJPEG2K_UINT16 = 1
} nvjpeg2kImageType_t;

nvjpeg2kImageType_t describes the pixel data types supported by nvJPEG2000.

Image Data

typedef struct
{
    void **pixel_data;
    size_t *pitch_in_bytes;
    nvjpeg2kImageType_t pixel_type;
    uint32_t num_components;
} nvjpeg2kImage_t;

nvjpeg2kImage_t serves as an image container. It contains an array of void pointers. Each pointer corresponds to a component in the nvjpeg2k bitstream There is another corresponding array which defines the pitch of each component. pixel_type determines the data type of pixel_data. See Image Type for supported types.

Decoder

Decoder Handle

struct nvjpeg2kHandle;
typedef struct nvjpeg2kHandle* nvjpeg2kHandle_t;

This handle should be instantiated prior to using the any of the decode APIs. It is thread safe, and can be used by multiple threads simultaneously.

Decoder State

struct nvjpeg2kDecodeState;
typedef struct nvjpeg2kDecodeState* nvjpeg2kDecodeState_t;

The nvjpeg2kDecodeState_t handle stores intermediate decode information. This handle can be reused when decoding multiple images. User has to ensure that a stream or device synchronize CUDA call is made between the decoding of two images.

Bitstream Handle

struct nvjpeg2kStream;
typedef struct nvjpeg2kStream* nvjpeg2kStream_t;

This handle is used for parsing the bitstream. Bitstream metadata can be extracted by using the APIs defined in Parser API Reference.

Decode Parameters Handle

struct nvjpeg2kDecodeParams;
typedef struct nvjpeg2kDecodeParams* nvjpeg2kDecodeParams_t;

This handle is used to store the decode output parameters like the decode area of interest coordinates.

Encoder

Encoder Handle

struct nvjpeg2kEncoder;
typedef struct nvjpeg2kEncoder* nvjpeg2kEncoder_t;

This handle should be instantiated prior to using the any of the encode APIs. It is thread safe, and can be across host threads.

Encode State

struct nvjpeg2kEncodeState;
typedef struct nvjpeg2kEncodeState* nvjpeg2kEncodeState_t;

The nvjpeg2kEncodeState_t handle contains intermediate buffers required by the encoding process.

Encode Parameters Handle

struct nvjpeg2kEncodeParams;
typedef struct nvjpeg2kEncodeParams* nvjpeg2kEncodeParams_t;

This handle stores user provided parameters that control the encoding process.

Maximum Resolutions

#define NVJPEG2K_MAXRES 33

Maximum number of resolutions supported by the JPEG2000 standard.

Progression Order

typedef enum
{
    NVJPEG2K_LRCP = 0,
    NVJPEG2K_RLCP = 1,
    NVJPEG2K_RPCL = 2,
    NVJPEG2K_PCRL = 3,
    NVJPEG2K_CPRL = 4
} nvjpeg2kProgOrder;

Progression orders defined in the JPEG2000 standard. nvJPEG2000 v 0.4.0 supports all orders (decode) and only NVJPEG2K_LRCP (encode).

Bitstream Type

typedef enum
{
    NVJPEG2K_STREAM_J2K  = 0,
    NVJPEG2K_STREAM_JP2  = 1
} nvjpeg2kBitstreamType;

NVJPEG2K_STREAM_J2K corresponds to the JPEG2000 codestream. NVJPEG2K_STREAM_JP2 corresponds to the .jp2 container.

Encode Config

typedef struct
{
    nvjpeg2kBitstreamType stream_type;
    nvjpeg2kColorSpace_t color_space;
    uint16_t rsiz;
    uint32_t image_width;
    uint32_t image_height;
    uint32_t enable_tiling;
    uint32_t tile_width;
    uint32_t tile_height;
    uint32_t num_components;
    nvjpeg2kImageComponentInfo_t *image_comp_info;
    uint32_t enable_SOP_marker;
    uint32_t enable_EPH_marker;
    nvjpeg2kProgOrder prog_order;
    uint32_t num_layers;
    uint32_t mct_mode;
    uint32_t num_resolutions;
    uint32_t code_block_w;
    uint32_t code_block_h;
    uint32_t encode_modes;
    uint32_t irreversible;
    uint32_t enable_custom_precincts;
    uint32_t precint_width[NVJPEG2K_MAXRES];
    uint32_t precint_height[NVJPEG2K_MAXRES];
} nvjpeg2kEncodeConfig_t;

nvjpeg2kEncodeConfig_t primarily contains parameters defined in the SIZ and COD JPEG2000 headers. Not all parameters are supported and have to be set to 0. The below table captures the valid values of each parameter in nvjpeg2kEncodeConfig_t.

Datatype

Name

Valid values (v0.5.0)

nvjpeg2kBitstreamType

stream_type

all enum values

nvjpeg2kColorSpace_t

color_space

all enum values

uint16_t

rsiz

0

uint32_t

image_width

minimum value 1

uint32_t

image_height

minimum value 1

uint32_t

enable_tiling

0,1

uint32_t

tile_width

enable_tiling should be 1, should be less than image_width

uint32_t

tile_height

enable_tiling should be 1, should be less than image_height

uint32_t

num_components

1 - 4

nvjpeg2kImageComponentInfo_t

*image_comp_info

valid pointer

uint32_t

enable_SOP_marker

0

uint32_t

enable_EPH_marker

0

nvjpeg2kProgOrder

prog_order

all values defined here

uint32_t

num_layers

1

uint32_t

mct_mode

0 (YCC and Grayscale) , 1 (RGB)

uint32_t

num_resolutions

cannot be greater than image/tile dimensions

uint32_t

code_block_w

32, 64

uint32_t

code_block_h

32, 64

uint32_t

encode_modes

0

uint32_t

irreversible

0, 1

uint32_t

enable_custom_precincts

0

uint32_t

precint_width[NVJPEG2K_MAXRES]

0

uint32_t

precint_height[NVJPEG2K_MAXRES]

0

API Reference

Helper API Reference

nvjpeg2kGetCudartProperty()

Gets the numeric value for the major version, minor version, or the patch level of the CUDA toolkit that was used to build nvJPEG2000 library

Signature:

nvjpeg2kStatus_t nvjpeg2kGetCudartProperty(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.

nvjpeg2kGetProperty()

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

Signature:

nvjpeg2kStatus_t nvjpeg2kGetProperty(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.

nvjpeg2kCreateSimple()

Creates an instance of the library handle with default backend and memory allocators.

Signature:

nvjpeg2kStatus_t nvjpeg2kCreateSimple(nvjpeg2kHandle_t *handle);

Parameters:

Parameter

Input/Output

Memory

Description

nvjpeg2kHandle_t *handle

Input/Output

Host

nvjpeg2k library handle

Returns:

nvjpeg2kStatus_t - An error code as specified in API Return Status Codes

nvjpeg2kCreate()

Creates an instance of the library using the input arguments. User has flexibility to choose the backend implementation and provide allocators.

Signature:

nvjpeg2kStatus_t nvjpeg2kCreate(
        nvjpeg2kBackend_t backend,
        nvjpeg2kDeviceAllocator_t *device_allocator,
        nvjpeg2kPinnedAllocator_t *pinned_allocator,
        nvjpeg2kHandle_t *handle);

Parameters:

Parameter

Input/Output

Memory

Description

nvjpeg2kBackend_t backend

Input

Host

Backend parameter

nvjpeg2kDeviceAllocator_t *device_allocator

Input

Host

Device allocator. cudaMalloc and cudaFree are used if set to NULL. See Device Allocator Interface

nvjpeg2kPinnedAllocator_t *pinned_allocator

Input

Host

Pinnned allocator. cudaHostAlloc and cudaHost are used is set to NULL. See Pinned Allocator Interface

nvjpeg2kHandle_t *handle

Input/Output

Host

nvjpeg2k library handle

Returns:

nvjpeg2kStatus_t - An error code as specified in API Return Status Codes

nvjpeg2kDestroy()

Releases the nvjpeg2k library handle.

Signature:

nvjpeg2kStatus_t nvjpeg2kDestroy(nvjpeg2kHandle_t handle);

Parameters:

Parameter

Input/Output

Memory

Description

nvjpeg2kHandle_t handle

Input

Host

nvjpeg2k library handle

Returns:

nvjpeg2kStatus_t - An error code as specified in API Return Status Codes

nvjpeg2kDecodeStateCreate()

Creates an instance of the Decode State.

Signature:

nvjpeg2kStatus_t nvjpeg2kDecodeStateCreate(
        nvjpeg2kHandle_t handle,
        nvjpeg2kDecodeState_t *decode_state);

Parameters:

Parameter

Input/Output

Memory

Description

nvjpeg2kHandle_t handle

Input

Host

nvjpeg2k library handle

nvjpeg2kDecodeState_t *decode_state

Input/Output

Host

decode state handle

Returns:

nvjpeg2kStatus_t - An error code as specified in API Return Status Codes

nvjpeg2kDecodeStateDestroy()

Releases the Decode State handle.

Signature:

nvjpeg2kStatus_t nvjpeg2kDecodeStateDestroy(nvjpeg2kDecodeState_t decode_state);

Parameters:

Parameter

Input/Output

Memory

Description

nvjpeg2kDecodeState_t decode_state

Input

Host

decode state handle

Returns:

nvjpeg2kStatus_t - An error code as specified in API Return Status Codes

nvjpeg2kStreamCreate()

Creates an instance of the bitstream handle.

Signature:

nvjpeg2kStatus_t nvjpeg2kStreamCreate(nvjpeg2kStream_t *stream_handle);

Parameters:

Parameter

Input/Output

Memory

Description

nvjpeg2kStream_t *stream_handle

Input/Output

Host

nvjpeg2k bitstream handle

Returns:

nvjpeg2kStatus_t - An error code as specified in API Return Status Codes

nvjpeg2kStreamDestroy()

Releases the bitstream handle.

Signature:

nvjpeg2kStatus_t nvjpeg2kStreamDestroy(nvjpeg2kStream_t stream_handle);

Parameters:

Parameter

Input/Output

Memory

Description

nvjpeg2kStream_t stream_handle

Input

Host

nvjpeg2k bitstream handle

Returns:

nvjpeg2kStatus_t - An error code as specified in API Return Status Codes

nvjpeg2kDecodeParamsCreate()

Creates an instance of the decode output parameters handle.

Signature:

nvjpeg2kStatus_t nvjpeg2kDecodeParamsCreate(nvjpeg2kDecodeParams_t *decode_params);

Parameters:

Parameter

Input/Output

Memory

Description

nvjpeg2kDecodeParams_t *decode_params

Input/Output

Host

Decode output parameters handle

Returns:

nvjpeg2kStatus_t - An error code as specified in API Return Status Codes

nvjpeg2kDecodeParamsDestroy()

Releases the decode output parameters handle.

Signature:

nvjpeg2kStatus_t nvjpeg2kDecodeParamsDestroy(nvjpeg2kDecodeParams_t decode_params);

Parameters:

Parameter

Input/Output

Memory

Description

nvjpeg2kDecodeParams_t decode_params

Input

Host

Decode output parameters handle

Returns:

nvjpeg2kStatus_t - An error code as specified in API Return Status Codes

nvjpeg2kEncoderCreateSimple()

Creates an instance of the nvJPEG2000 encoder handle.

Signature:

nvjpeg2kStatus_t nvjpeg2kEncoderCreateSimple(nvjpeg2kEncoder_t *enc_handle);

Parameters:

Parameter

Input/Output

Memory

Description

nvjpeg2kEncoder_t *enc_handle

Input/Output

Host

nvJPEG2000 encoder handle

Returns:

nvjpeg2kStatus_t - An error code as specified in API Return Status Codes

nvjpeg2kEncoderDestroy()

Releases the nvJPEG2000 encoder handle.

Signature:

nvjpeg2kStatus_t nvjpeg2kEncoderDestroy(nvjpeg2kEncoder_t enc_handle);

Parameters:

Parameter

Input/Output

Memory

Description

nvjpeg2kEncoder_t enc_handle

Input

Host

nvJPEG2000 encoder handle

Returns:

nvjpeg2kStatus_t - An error code as specified in API Return Status Codes

nvjpeg2kEncodeStateCreate()

Creates an instance of the encode state.

Signature:

nvjpeg2kStatus_t nvjpeg2kEncodeStateCreate(
      nvjpeg2kEncoder_t enc_handle,
      nvjpeg2kEncodeState_t *encode_state);

Parameters:

Parameter

Input/Output

Memory

Description

nvjpeg2kEncoder_t enc_handle

Input

Host

nvJPEG2000 encoder handle

nvjpeg2kEncodeState_t *encode_state

Input/Output

Host

nvJPEG2000 encode state

Returns:

nvjpeg2kStatus_t - An error code as specified in API Return Status Codes

nvjpeg2kEncodeStateDestroy()

Releases the encode state handle.

Signature:

nvjpeg2kStatus_t nvjpeg2kEncodeStateDestroy(nvjpeg2kEncodeState_t encode_state);

Parameters:

Parameter

Input/Output

Memory

Description

nvjpeg2kEncodeState_t encode_state

Input

Host

nvJPEG2000 encode state

Returns:

nvjpeg2kStatus_t - An error code as specified in API Return Status Codes

nvjpeg2kEncodeParamsCreate()

Creates an instance of the encode parameters handle.

Signature:

nvjpeg2kStatus_t nvjpeg2kEncodeParamsCreate(nvjpeg2kEncodeParams_t *encode_params);

Parameters:

Parameter

Input/Output

Memory

Description

nvjpeg2kEncodeParams_t *encode_params

Input

Host

encode params handle

Returns:

nvjpeg2kStatus_t - An error code as specified in API Return Status Codes

nvjpeg2kEncodeParamsDestroy()

Releases the encode parameters handle.

Signature:

nvjpeg2kStatus_t nvjpeg2kEncodeParamsDestroy(nvjpeg2kEncodeParams_t encode_params);

Parameters:

Parameter

Input/Output

Memory

Description

nvjpeg2kEncodeParams_t encode_params

Input

Host

encode params handle

Returns:

nvjpeg2kStatus_t - An error code as specified in API Return Status Codes

Parser API Reference

nvjpeg2kStreamParse()

This function is the first step in the decoding of a JPEG2000 bitstream. It accepts the bitstream buffer on host memory as input and parses the JPEG2000 header information. The parsed information is stored in the nvjpeg2kStream_t handle and can be retrieved by the APIs documented in this section.

Signature:

nvjpeg2kStatus_t nvjpeg2kStreamParse(nvjpeg2kHandle_t handle,
        const unsigned char *data,
        size_t length,
        int save_metadata,
        int save_stream,
        nvjpeg2kStream_t *stream_handle);

Parameters:

Parameter

Input/Output

Memory

Description

nvjpeg2kHandle_t handle

Input

Host

library handle

const unsigned char *data

Input

Host

bitstream buffer

size_t length

Input

Host

bitstream size in bytes

int save_metadata

Input

Host

Set to 0. Added for future use

int save_stream

Input

Host

Set to 0. Added for future use

nvjpeg2kStream_t *stream_handle

Input

Host

bitstream handle

Returns:

nvjpeg2kStatus_t - An error code as specified in API Return Status Codes

nvjpeg2kStreamGetImageInfo()

Retrieves the image information defined in nvjpeg2kImageInfo_t. This information is useful in allocating output buffers on device memory.

Signature:

nvjpeg2kStatus_t nvjpeg2kStreamGetImageInfo(nvjpeg2kStream_t stream_handle,
        nvjpeg2kImageInfo_t* image_info);

Parameters:

Parameter

Input/Output

Memory

Description

nvjpeg2kStream_t *stream_handle

Input

Host

bitstream handle

nvjpeg2kImageInfo_t* image_info

Input/Output

Host

Pointer to nvjpeg2kImageInfo_t

Returns:

nvjpeg2kStatus_t - An error code as specified in API Return Status Codes

nvjpeg2kStreamGetImageComponentInfo()

Retrieves the component level information defined in nvjpeg2kImageComponentInfo_t This information can be used in allocating output buffers on device memory. Component level information is useful when the dimensions vary across components.

Signature:

nvjpeg2kStatus_t nvjpeg2kStreamGetImageComponentInfo(nvjpeg2kStream_t stream_handle,
        nvjpeg2kImageComponentInfo_t* component_info,
        uint32_t component_id);

Parameters:

Parameter

Input/Output

Memory

Description

nvjpeg2kStream_t stream_handle

Input

Host

bitstream handle

nvjpeg2kImageComponentInfo_t* component_info

Input/Output

Host

Pointer to nvjpeg2kImageInfo_t

uint32_t component_id

Input

Host

Component index

Returns:

nvjpeg2kStatus_t - An error code as specified in API Return Status Codes

nvjpeg2kStreamGetResolutionsInTile()

Retrieves the number of resolutions present in a tile. The number of resolutions is defined as: numResolutions = numWaveletDecompositionLevels + 1. Tiles in jpeg2000 are indexed in raster scan order. nvjpeg2kStreamGetImageInfo retrieves the number of tiles present along both the x and y directions. For tile coordinates tile_x, tile_y: tile_id = tile_y * num_tiles_x + tile_x, where tile_x and tile_y are in tile units.

Signature:

nvjpeg2kStatus_t nvjpeg2kStreamGetResolutionsInTile(
        nvjpeg2kStream *stream_handle,
        uint32_t tile_id,
        uint32_t* num_res);

Parameters:

Parameter

Input/Output

Memory

Description

nvjpeg2kStream_t stream_handle

Input

Host

bitstream handle

uint32_t tile_id

Input

Host

Raster scan based tile index

uint32_t* num_res

Output

Host

Number of resolutions present in the tile

Returns:

nvjpeg2kStatus_t - An error code as specified in API Return Status Codes

nvjpeg2kStreamGetTileComponentDim()

Retrieves the tile width and tile height for a tile component. This function is useful when the tile dimensions in Image Information are not a multiple of the image dimensions.

Signature:

nvjpeg2kStatus_t nvjpeg2kStreamGetTileComponentDim(
        nvjpeg2kStream *stream_handle,
        uint32_t component_id,
        uint32_t tile_id,
        uint32_t* tile_width,
        uint32_t* tile_height);

Parameters:

Returns:

nvjpeg2kStatus_t - An error code as specified in API Return Status Codes

nvjpeg2kStreamGetResolutionComponentDim()

Retrieves the dimensions at a resolution level for a tile component. The formula is as follows:

res_scale = 1 << (num_resolutions - res_level - 1)
res_width   = (tile_width  + res_scale - 1) >> res_scale
res_height  = (tile_height + res_scale - 1) >> res_scale

Signature:

nvjpeg2kStatus_t nvjpeg2kStreamGetResolutionComponentDim(
        nvjpeg2kStream_t   stream_handle,
        uint32_t component_id,
        uint32_t tile_id,
        uint32_t res_level,
        uint32_t* res_width,
        uint32_t* res_height);

Returns:

nvjpeg2kStatus_t - An error code as specified in API Return Status Codes

nvjpeg2kStreamGetColorSpace()

Retrieves color space information from a parsed JP2 file. For a jpeg2000 codestream (.j2k file), this function will retrieve NVJPEG2K_COLORSPACE_UNKNOWN since color space information is not available.

Signature:

nvjpeg2kStatus_t nvjpeg2kStreamGetColorSpace(nvjpeg2kStream_t stream_handle,
        nvjpeg2kColorSpace_t* color_space);

Parameters:

Parameter

Input/Output

Memory

Description

nvjpeg2kStream_t stream_handle

Input

Host

bitstream handle

nvjpeg2kColorSpace_t* color_space

Input/Output

Host

Color space of the parsed image

Returns:

nvjpeg2kStatus_t - An error code as specified in API Return Status Codes

Decode API Reference

nvjpeg2kDecode()

Decodes a single image, and writes it to the output device buffers. The function is asynchronous with respect to the host. All GPU tasks will be submitted to the provided stream. Prior to calling this function user must parse the bitstream using nvjpeg2kStreamParse() such that the bitstream information is stored in jpeg2k_stream.

Signature:

nvjpeg2kStatus_t nvjpeg2kDecode(nvjpeg2kHandle_t handle,
        nvjpeg2kDecodeState_t decode_state,
        nvjpeg2kStream_t jpeg2k_stream,
        nvjpeg2kImage_t* decode_output,
        cudaStream_t stream);

Parameters:

Parameter

Input/Output

Memory

Description

nvjpeg2kHandle_t handle

Input

Host

library handle

nvjpeg2kDecodeState_t decode_state

Input

Host

decode state handle

nvjpeg2kStream_t jpeg2k_stream

Input

Host

nvjpeg2k bitstream handle

nvjpeg2kImage_t* decode_output

Input/Output

Host

Decode output struct. The struct should be on host memory. The image component pointers should point to device memory. See Image Data

cudaStream_t stream

Input

Host

Instance of cudaStream_t. Can be set to 0.

Returns:

nvjpeg2kStatus_t - An error code as specified in API Return Status Codes

nvjpeg2kDecodeImage()

Decodes a single image, and writes it to the output device buffers. The function is asynchronous with respect to the host. All GPU tasks will be submitted to the provided stream. Prior to calling this function user must parse the bitstream using nvjpeg2kStreamParse() such that the bitstream information is stored in jpeg2k_stream. It is possible to control the decode output with this function using an instance of nvjpeg2kDecodeParams_t.

Signature:

nvjpeg2kStatus_t nvjpeg2kDecodeImage(nvjpeg2kHandle_t handle,
        nvjpeg2kDecodeState_t decode_state,
        nvjpeg2kStream_t jpeg2k_stream,
        nvjpeg2kDecodeParams_t decode_params,
        nvjpeg2kImage_t* decode_output,
        cudaStream_t stream);

Parameters:

Parameter

Input/Output

Memory

Description

nvjpeg2kHandle_t handle

Input

Host

library handle

nvjpeg2kDecodeState_t decode_state

Input

Host

decode state handle

nvjpeg2kStream_t jpeg2k_stream

Input

Host

nvjpeg2k bitstream handle

nvjpeg2kDecodeParams_t decode_params

Input

Host

Used to control the decoded output (like specifying an area of interest, or enabling RGB output). Can be set to NULL

nvjpeg2kImage_t* decode_output

Input/Output

Host

Decode output struct. The struct should be on host memory. The image component pointers should point to device memory. See Image Data

cudaStream_t stream

Input

Host

Instance of cudaStream_t. Can be set to 0.

Returns:

nvjpeg2kStatus_t - An error code as specified in API Return Status Codes

nvjpeg2kDecodeTile()

Decodes a tile within an image and writes it to the output device buffers. The function is asynchronous with respect to the host. All GPU tasks will be submitted to the provided stream. Prior to calling this function user must parse the bitstream using nvjpeg2kStreamParse() such that the bitstream information is stored in jpeg2k_stream.

Signature:

nvjpeg2kStatus_t nvjpeg2kDecodeTile(nvjpeg2kHandle_t handle,
        nvjpeg2kDecodeState_t decode_state,
        nvjpeg2kStream_t jpeg2k_stream,
        nvjpeg2kDecodeParams_t decode_params,
        uint32_t tile_id,
        uint32_t num_res_levels,
        nvjpeg2kImage_t* decode_output,
        cudaStream_t stream);

Parameters:

Parameter

Input/Output

Memory

Description

nvjpeg2kHandle_t handle

Input

Host

library handle

nvjpeg2kDecodeState_t decode_state

Input

Host

decode state handle

nvjpeg2kStream_t jpeg2k_stream

Input

Host

nvjpeg2k bitstream handle

nvjpeg2kDecodeParams_t decode_params

Input

Host

Used to control the decoded output (like specifying an area of interest) Can be set to NULL.

uint32_t tile_id

Input

Host

Raster scan based tile index

uint32_t num_res_levels

Input

Host

Number of Resolutions to be decoded within a tile, When set 0, image is decoded at full resolution Maximum allowed resolutions in a tile can be determined using nvjpeg2kStreamGetResolutionsInTile()

nvjpeg2kImage_t* decode_output

Input/Output

Host

Decode output struct. The struct should be on host memory. The image component pointers should point to device memory. See Image Data

cudaStream_t stream

Input

Host

Instance of cudaStream_t. Can be set to 0.

Returns:

nvjpeg2kStatus_t - An error code as specified in API Return Status Codes

Decode Parameters API Reference

The APIs under this category are used to initialize the decoding parameters as part of the nvjpeg2kDecodeParams_t handle. Once initialized, the handle can be passed as an input to nvjpeg2kDecodeTile()

nvjpeg2kDecodeParamsSetDecodeArea()

This function is used to set the decode area of interest. The coordinates are relative to the image origin and should be within the tile of interest. If the coordinates are set to 0, the entire tile will be decoded.

Signature:

nvjpeg2kStatus_t nvjpeg2kDecodeParamsSetDecodeArea(nvjpeg2kDecodeParams_t decode_params,
        uint32_t start_x,
        uint32_t end_x,
        uint32_t start_y,
        uint32_t end_y);

Parameters:

Parameter

Input/Output

Memory

Description

nvjpeg2kDecodeParams_t decode_params

Input/Output

Host

Decode output parameters handle

uint32_t start_x

Input

Host

Left coordinate of the decode area

uint32_t end_x

Input

Host

Right coordinate of the decode area

uint32_t start_y

Input

Host

Top coordinate of the decode area

uint32_t end_y

Input

Host

Bottom coordinate of the decode area

Returns:

nvjpeg2kStatus_t - An error code as specified in API Return Status Codes

nvjpeg2kDecodeParamsSetRGBOutput()

This function enables RGB decode output for images with 422/420 chroma subsampling. It is ignored for other chroma subsampling values. YCC to RGB conversion is based on sYCC, Amendment 1 to IEC 61966-2-1. The color conversion is applied at a tile granularity due to which the chroma reconstruction may not be accurate for tiles with odd dimensions.

Signature:

nvjpeg2kStatus_t nvjpeg2kDecodeParamsSetRGBOutput(nvjpeg2kDecodeParams_t decode_params,
        int32_t enable_RGB);

Parameters:

Parameter

Input/Output

Memory

Description

nvjpeg2kDecodeParams_t decode_params

Input/Output

Host

Decode output parameters handle

int32_t enable_RGB

Input

Host

Set to 1 to enable RGB output

Returns:

nvjpeg2kStatus_t - An error code as specified in API Return Status Codes

Encode API Reference

nvjpeg2kEncode()

Compresses the input image in JPEG2000 format and stores it within encode_state. All GPU tasks will be submitted to the provided stream. The function is asynchronous with respect to the host.

Signature:

nvjpeg2kStatus_t nvjpeg2kEncode(nvjpeg2kEncoder_t enc_handle,
        nvjpeg2kEncodeState_t encode_state,
        const nvjpeg2kEncodeParams_t encode_params,
        const nvjpeg2kImage_t *input_image,
        cudaStream_t stream);

Parameters:

Parameter

Input/Output

Memory

Description

nvjpeg2kEncoder_t enc_handle

Input

Host

Encoder handle

nvjpeg2kEncodeState_t encode_state

Input

Host

Encode State, contains intermediate buffers used for encode

const nvjpeg2kEncodeParams_t encode_params

Input

Host

Stores parameters that control the encode process

const nvjpeg2kImage_t *input_image

Input

Host/Device

Input Image. The struct should be on host memory. The image component pointers should point to device memory. See Image Data

cudaStream_t stream

Input

Host

CUDA stream - used for all device operations

Returns:

nvjpeg2kStatus_t - An error code as specified in API Return Status Codes

nvjpeg2kEncodeRetrieveBitstream()

Retrieves the compressed stream from the encoder state that was previously used by the encoder function.

  • If the compressed_data parameter is NULL, the encoder will return the compressed jpeg2000 bitstream size in the length parameter.

  • If compressed_data is not NULL, the length parameter should contain the data buffer size.

  • If the length is less than compressed stream size, an error will be returned. Otherwise the compressed stream will be stored in the data buffer and the actual compressed buffer size will be stored in the length parameter.

  • Asynchronous behavior

    • When the compressed_data parameter is NULL, the API can be assumed to be synchronous with the host

    • When the compressed_data parameter is not NULL, the application should call cudaStreamSynchronize() to make sure the bitstream copy is successful.

Signature:

nvjpeg2kStatus_t nvjpeg2kEncodeRetrieveBitstream(
        nvjpeg2kEncoder_t enc_handle,
        nvjpeg2kEncodeState_t encode_state,
        unsigned char *compressed_data,
        size_t *length,
        cudaStream_t stream);

Parameters:

Parameter

Input/Output

Memory

Description

nvjpeg2kEncoder_t enc_handle

Input

Host

Encoder handle

nvjpeg2kEncodeState_t encode_state

Input

Host

Encode State, contains intermediate buffers used for encode

unsigned char *data

Output

Host

Pointer to the buffer in the host memory where the compressed stream will be stored. Can be NULL (see description).

size_t *length,

Input/Output

Host

Pointer to the input buffer size. The library will update the actual compressed stream size in this parameter.

cudaStream_t stream

Input

Host

CUDA stream - used for all device operations.

Returns:

nvjpeg2kStatus_t - An error code as specified in API Return Status Codes

Encode Parameters API Reference

nvjpeg2kEncodeParamsSetEncodeConfig()

Sets the JPEG2000 header parameters that are defined in nvjpeg2kEncodeConfig_t. This API should always be called during the encode process.

Signature:

nvjpeg2kStatus_t nvjpeg2kEncodeParamsSetEncodeConfig(
        nvjpeg2kEncodeParams_t encode_params,
        nvjpeg2kEncodeConfig_t* encode_config);

Parameters:

Parameter

Input/Output

Memory

Description

nvjpeg2kEncodeParams_t encode_params

Input/Output

Host

encode parameters handle

nvjpeg2kEncodeConfig_t* encode_config

Input

Host

pointer to nvjpeg2kEncodeConfig_t

Returns:

nvjpeg2kStatus_t - An error code as specified in API Return Status Codes

nvjpeg2kEncodeParamsSetQuality()

This API allows the application to set the target PSNR value when lossy encode is required.

Signature:

nvjpeg2kStatus_t nvjpeg2kEncodeParamsSetQuality(
        nvjpeg2kEncodeParams_t encode_params,
        double target_psnr);

Parameters:

Parameter

Input/Output

Memory

Description

nvjpeg2kEncodeParams_t encode_params

Input/Output

Host

encode parameters handle

double target_psnr

Input

Host

target PSNR value in db

Returns:

nvjpeg2kStatus_t - An error code as specified in API Return Status Codes