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

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

Decode API Reference

nvjpeg2kDecode()

Decodes a single image, and writes it to the output device buffers. The function is synchronous 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	pointer to an instance of component_info
cudaStream_t stream	Input	Host	Decode output struct. The struct should be on host memory. The image component pointers should point to device memory. See Image Data

Returns:

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