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.4.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
uint32_t	tile_width		0
uint32_t	tile_height		0
uint32_t	num_components		4
nvjpeg2kImageComponentInfo_t	*image_comp_info		valid pointer
uint32_t	enable_SOP_marker		0
uint32_t	enable_EPH_marker		0
nvjpeg2kProgOrder	prog_order		NVJPEG2K_LRCP
uint32_t	num_layers		1
uint32_t	mct_mode		0 (YCC and Grayscale) , 1 (RGB)
uint32_t	num_resolutions		1 - 8
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