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 NVJPEG2KAPI 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 NVJPEG2KAPI 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

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 jpeg 2000 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

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

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