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

Extended Device Allocator Interface#

typedef int (*nvjpeg2kDeviceMallocV2)(void* ctx, void **ptr, size_t size, cudaStream_t stream);
typedef int (*nvjpeg2kDeviceFreeV2)(void* ctx, void *ptr, size_t size, cudaStream_t stream);

typedef struct nvjpeg2kDeviceAllocatorV2
{
    nvjpeg2kDeviceMallocV2 device_malloc;
    nvjpeg2kDeviceFreeV2 device_free;
    void *device_ctx;
} nvjpeg2kDeviceAllocatorV2_t;

Allows the user to provide device allocators which accept cuda streams and user context. They will return 0 in case of success, and non-zero otherwise. Extended device allocators can be passed as input to the library using nvjpeg2kCreateV2().

Extended Pinned Allocator Interface#

typedef int (*nvjpeg2kPinnedMallocV2)(void* ctx, void **ptr, size_t size, cudaStream_t stream);
typedef int (*nvjpeg2kPinnedFreeV2)(void* ctx, void *ptr, size_t size, cudaStream_t stream)
typedef struct nvjpeg2kPinnedAllocatorV2
{
    nvjpeg2kPinnedMallocV2 pinned_malloc;
    nvjpeg2kPinnedFreeV2   pinned_free;
    void *pinned_ctx;
} nvjpeg2kPinnedAllocatorV2_t;

Allows the user to provide pinned allocators which accept cuda streams and user context. They will return 0 in case of success, and non-zero otherwise. Extended pinned allocators can be passed as input to the library using nvjpeg2kCreateV2().

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,
    NVJPEG2K_INT16  = 2
} 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.

Image Format#

typedef enum
{
    NVJPEG2K_FORMAT_PLANAR = 0,
    NVJPEG2K_FORMAT_INTERLEAVED = 1
} nvjpeg2kImageFormat_t;

nvjpeg2kImageFormat_t describes how an image is stored in memory.

  • NVJPEG2K_FORMAT_PLANAR indicates that all components of an image are stored in separate planes.

  • NVJPEG2K_FORMAT_INTERLEAVED indicates that all component of an image are stored in interleaved order. It is not supported when the component dimensions of an image are different.

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.

High Throughout JPEG 2000 Rsiz Parameter#

#define NVJPEG2K_RSIZ_HT 0x4000

To enable High throughput JPEG 2000 Encode, set rsiz in nvjpeg2kEncodeConfig_t to NVJPEG2K_RSIZ_HT

High Throughput JPEG 2000 Code-block Stye Parameter#

#define NVJPEG2K_MODE_HT 0x40

To enable High throughput JPEG 2000 Encode, set encode_modes in nvjpeg2kEncodeConfig_t to NVJPEG2K_CBLK_HT

Progression Order#

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

Progression orders defined in the JPEG2000 standard.

Bitstream Type#

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

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

Quality Type#

Can be used with nvjpeg2kEncodeParamsSpecifyQuality()

typedef enum nvjpeg2kQualityType
{
    NVJPEG2K_QUALITY_TYPE_TARGET_PSNR = 0,
    NVJPEG2K_QUALITY_TYPE_QUANTIZATION_STEP = 1,
    NVJPEG2K_QUALITY_TYPE_Q_FACTOR = 2
} nvjpeg2kQualityType_t;

Description and requirements of the Quality Types:

Quality Type Code

Description

Requirements

NVJPEG2K_QUALITY_TYPE_TARGET_PSNR (0)

Quality value is interpreted as desired Peak Signal-to-Noise Ratio (PSNR) target for the encoded image. The higher the value, the better quality image is produced.

Quality value should be positive floating point. Cannot be used with HT encoder.

NVJPEG2K_QUALITY_TYPE_QUANTIZATION_STEP (1)

Quality value is interpreted as quantization step (by how much pixel data will be divided). The higher the value, the worse quality image is produced.

Quality value should be positive floating point.

NVJPEG2K_QUALITY_TYPE_Q_FACTOR (2)

Quality value is interpreted as JPEG-like quality.

Quality value should be in range from 1.0 (worst) to 100.0 (best). Can be used only when the input colorspace is YCC, Grayscale, or RGB with MCT enabled.

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

nvjpeg2kBitstreamType

stream_type

all enum values

nvjpeg2kColorSpace_t

color_space

all enum values

uint16_t

rsiz

0 (J2K) , 0x4000 (HTJ2K)

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 (J2K) , 64 (HTJ2K)

uint32_t

irreversible

0, 1

uint32_t

num_precincts_init

0, Number of valid precincts

uint32_t

precint_width[NVJPEG2K_MAXRES]

Should be a power of 2, valid only when num_precincts_init is non zero.

uint32_t

precint_height[NVJPEG2K_MAXRES]

Should be a power of 2, valid only when num_precincts_init is non zero.