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

nvjpeg2kCreateV2()¶

Creates an instance of the library using extended allocators.

Signature:

nvjpeg2kStatus_t nvjpeg2kCreateV2(
        nvjpeg2kBackend_t backend,
        nvjpeg2kDeviceAllocatorV2_t*device_allocator,
        nvjpeg2kPinnedAllocatorV2_t*pinned_allocator,
        nvjpeg2kHandle_t *handle);

Parameters:

Parameter	Input/Output	Memory	Description
nvjpeg2kBackend_t backend	Input	Host	Backend parameter
nvjpeg2kDeviceAllocatorV2_t *device_allocator	Input	Host	Extended Device allocator. Cannot be NULL. See Extended Device Allocator Interface
nvjpeg2kPinnedAllocatorV2_t *pinned_allocator	Input	Host	Extended Pinnned allocator. Cannot be NULL. See Extended 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

nvjpeg2kSetDeviceMemoryPadding()¶

Sets padding for device memory allocations. After success on this call any device memory allocation would be padded to the multiple of specified number of bytes. This helps minimize the no of device memory reallocations

Signature:

nvjpeg2kStatus_t nvjpeg2kSetDeviceMemoryPadding(size_t padding,
        nvjpeg2kHandle_t decode_handle);

Parameters:

Parameter	Input/Output	Memory	Description
size_t padding	Input	Host	Device memory padding to be used for all further device memory allocation
nvjpeg2kHandle_t *handle	Input/Output	Host	nvjpeg2k library handle

Returns:

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

nvjpeg2kGetDeviceMemoryPadding()¶

Retrieves padding for device memory allocations

Signature:

nvjpeg2kStatus_t nvjpeg2kGetDeviceMemoryPadding(size_t *padding,
        nvjpeg2kHandle_t handle);

Parameters:

Parameter	Input/Output	Memory	Description
size_t *padding	Input	Host	Device memory padding currently in use
nvjpeg2kHandle_t *handle	Input/Output	Host	nvjpeg2k library handle

Returns:

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

nvjpeg2kSetPinnedMemoryPadding()¶

Sets padding for pinned memory allocations. After success on this call any pinned memory allocation would be padded to the multiple of specified number of bytes. This helps minimize the no of pinned memory reallocations

Signature:

nvjpeg2kStatus_t nvjpeg2kSetPinnedMemoryPadding(size_t padding,
        nvjpeg2kHandle_t decode_handle);

Parameters:

Parameter	Input/Output	Memory	Description
size_t padding	Input	Host	Pinned memory padding to be used for all further device memory allocation
nvjpeg2kHandle_t *handle	Input/Output	Host	nvjpeg2k library handle

Returns:

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

nvjpeg2kGetPinnedMemoryPadding()¶

Retrieves padding for pinned memory allocations

Signature:

nvjpeg2kStatus_t nvjpeg2kGetPinnedMemoryPadding(size_t *padding,
        nvjpeg2kHandle_t handle);

Parameters:

Parameter	Input/Output	Memory	Description
size_t *padding	Input	Host	Pinned memory padding currently in use
nvjpeg2kHandle_t *handle	Input/Output	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_t 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_t 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