API Reference#

Helper API#

nvjpeg2kStatus_t nvjpeg2kGetCudartProperty( libraryPropertyType type, int *value )#

Get the CUDA Toolkit version used to build the library.

Returns the numeric value for the major version, minor version, or the patch level of the CUDA toolkit that was used to build the nvJPEG2000 library.

Parameters:

type – [in] Version type: MAJOR_VERSION, MINOR_VERSION, or PATCH_LEVEL.
value – [out] The numeric value corresponding to the requested property.

Returns:

An error code as specified in API Return Status Codes.

nvjpeg2kStatus_t nvjpeg2kGetProperty( libraryPropertyType type, int *value )#

Get the nvJPEG2000 library version.

Returns the numeric value for the major version, minor version, or the patch level of the nvJPEG2000 library.

Parameters:

type – [in] Version type: MAJOR_VERSION, MINOR_VERSION, or PATCH_LEVEL.
value – [out] The numeric value corresponding to the requested property.

Returns:

An error code as specified in API Return Status Codes.

nvjpeg2kStatus_t nvjpeg2kCreateSimple(nvjpeg2kHandle_t *handle)#

Create an nvJPEG2000 library handle with default settings.

Creates an instance of the library handle with default backend and memory allocators.

Parameters:: handle – [in/out] Pointer to the library handle to initialize.
Returns:: An error code as specified in API Return Status Codes.

nvjpeg2kStatus_t nvjpeg2kCreate( nvjpeg2kBackend_t backend, nvjpeg2kDeviceAllocator_t *device_allocator, nvjpeg2kPinnedAllocator_t *pinned_allocator, nvjpeg2kHandle_t *handle )#

Create an nvJPEG2000 library handle with custom allocators.

Creates an instance of the library using the input arguments. The user has flexibility to choose the backend implementation and provide allocators.

Parameters:

backend – [in] Backend to use. Currently NVJPEG2K_BACKEND_DEFAULT is supported.
device_allocator – [in] See nvjpeg2kDeviceAllocator_t. If NULL, default cudaMalloc() / cudaFree() are used.
pinned_allocator – [in] See nvjpeg2kPinnedAllocator_t. If NULL, default cudaHostAlloc() / cudaFreeHost() are used.
handle – [in/out] Pointer to the library handle to initialize.

Returns:

An error code as specified in API Return Status Codes.

nvjpeg2kStatus_t nvjpeg2kCreateV2( nvjpeg2kBackend_t backend, nvjpeg2kDeviceAllocatorV2_t *dev_allocator, nvjpeg2kPinnedAllocatorV2_t *pinned_allocator, nvjpeg2kHandle_t *handle )#

Create an nvJPEG2000 library handle with extended custom allocators.

Creates an instance of the library using extended allocators that accept CUDA streams and user context.

Parameters:

backend – [in] Backend to use. Currently NVJPEG2K_BACKEND_DEFAULT is supported.
dev_allocator – [in] See nvjpeg2kDeviceAllocatorV2_t. Cannot be NULL.
pinned_allocator – [in] See nvjpeg2kPinnedAllocatorV2_t. Cannot be NULL.
handle – [in/out] Pointer to the library handle to initialize.

Returns:

An error code as specified in API Return Status Codes.

nvjpeg2kStatus_t nvjpeg2kDestroy(nvjpeg2kHandle_t handle)#

Release the nvJPEG2000 library handle and resources.

Parameters:: handle – [in] Library handle to release.
Returns:: An error code as specified in API Return Status Codes.

nvjpeg2kStatus_t nvjpeg2kSetDeviceMemoryPadding( size_t padding, nvjpeg2kHandle_t handle )#

Set 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 number of device memory reallocations.

Parameters:

padding – [in] Padding size in bytes.
handle – [in/out] Library handle.

Returns:

An error code as specified in API Return Status Codes.

nvjpeg2kStatus_t nvjpeg2kGetDeviceMemoryPadding( size_t *padding, nvjpeg2kHandle_t handle )#

Retrieve padding for device memory allocations.

Parameters:

padding – [out] Current device memory padding size in bytes.
handle – [in] Library handle.

Returns:

An error code as specified in API Return Status Codes.

nvjpeg2kStatus_t nvjpeg2kSetPinnedMemoryPadding( size_t padding, nvjpeg2kHandle_t handle )#

Set padding for pinned host memory allocations.

After success on this call, any pinned host memory allocation would be padded to the multiple of specified number of bytes. This helps minimize the number of pinned memory reallocations.

Parameters:

padding – [in] Padding size in bytes.
handle – [in/out] Library handle.

Returns:

An error code as specified in API Return Status Codes.

nvjpeg2kStatus_t nvjpeg2kGetPinnedMemoryPadding( size_t *padding, nvjpeg2kHandle_t handle )#

Retrieve padding for pinned host memory allocations.

Parameters:

padding – [out] Current pinned memory padding size in bytes.
handle – [in] Library handle.

Returns:

An error code as specified in API Return Status Codes.

nvjpeg2kStatus_t nvjpeg2kDecodeStateCreate( nvjpeg2kHandle_t handle, nvjpeg2kDecodeState_t *decode_state )#

Create an instance of the decode state.

Parameters:

handle – [in] Library handle.
decode_state – [in/out] Pointer to the decode state handle to initialize.

Returns:

An error code as specified in API Return Status Codes.

nvjpeg2kStatus_t nvjpeg2kDecodeStateDestroy( nvjpeg2kDecodeState_t decode_state )#

Release the decode state handle.

Parameters:: decode_state – [in] Decode state handle to release.
Returns:: An error code as specified in API Return Status Codes.

nvjpeg2kStatus_t nvjpeg2kStreamCreate( nvjpeg2kStream_t *stream_handle )#

Create an instance of the bitstream handle.

Parameters:: stream_handle – [in/out] Pointer to the bitstream handle to initialize.
Returns:: An error code as specified in API Return Status Codes.

nvjpeg2kStatus_t nvjpeg2kStreamDestroy( nvjpeg2kStream_t stream_handle )#

Release the bitstream handle.

Parameters:: stream_handle – [in] Bitstream handle to release.
Returns:: An error code as specified in API Return Status Codes.

nvjpeg2kStatus_t nvjpeg2kDecodeParamsCreate( nvjpeg2kDecodeParams_t *decode_params )#

Create an instance of the decode output parameters handle.

Parameters:: decode_params – [in/out] Pointer to the decode parameters handle to initialize.
Returns:: An error code as specified in API Return Status Codes.

nvjpeg2kStatus_t nvjpeg2kDecodeParamsDestroy( nvjpeg2kDecodeParams_t decode_params )#

Release the decode output parameters handle.

Parameters:: decode_params – [in] Decode parameters handle to release.
Returns:: An error code as specified in API Return Status Codes.

nvjpeg2kStatus_t nvjpeg2kEncoderCreateSimple( nvjpeg2kEncoder_t *enc_handle )#

Create an nvJPEG2000 encoder handle with default settings.

Parameters:: enc_handle – [in/out] Pointer to the encoder handle to initialize.
Returns:: An error code as specified in API Return Status Codes.

nvjpeg2kStatus_t nvjpeg2kEncoderDestroy(nvjpeg2kEncoder_t enc_handle)#

Release the nvJPEG2000 encoder handle.

Parameters:: enc_handle – [in] Encoder handle to release.
Returns:: An error code as specified in API Return Status Codes.

nvjpeg2kStatus_t nvjpeg2kEncodeStateCreate( nvjpeg2kEncoder_t enc_handle, nvjpeg2kEncodeState_t *encode_state )#

Create an instance of the encode state.

Parameters:

enc_handle – [in] Encoder handle.
encode_state – [in/out] Pointer to the encode state handle to initialize.

Returns:

An error code as specified in API Return Status Codes.

nvjpeg2kStatus_t nvjpeg2kEncodeStateDestroy( nvjpeg2kEncodeState_t encode_state )#

Release the encode state handle.

Parameters:: encode_state – [in] Encode state handle to release.
Returns:: An error code as specified in API Return Status Codes.

nvjpeg2kStatus_t nvjpeg2kEncodeParamsCreate( nvjpeg2kEncodeParams_t *encode_params )#

Create an instance of the encode parameters handle.

Parameters:: encode_params – [in/out] Pointer to the encode parameters handle to initialize.
Returns:: An error code as specified in API Return Status Codes.

nvjpeg2kStatus_t nvjpeg2kEncodeParamsDestroy( nvjpeg2kEncodeParams_t encode_params )#

Release the encode parameters handle.

Parameters:: encode_params – [in] Encode parameters handle to release.
Returns:: An error code as specified in API Return Status Codes.

Parser API#

nvjpeg2kStatus_t nvjpeg2kStreamParse( nvjpeg2kHandle_t handle, const unsigned char *data, size_t length, int save_metadata, int save_stream, nvjpeg2kStream_t stream_handle )#

Parse a JPEG2000 bitstream from a host memory buffer.

This function is the first step in decoding 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 stream handle and can be retrieved by the stream query APIs.

Parameters:

handle – [in] Library handle.
data – [in] Pointer to the JPEG2000 bitstream buffer in host memory.
length – [in] Size of the bitstream in bytes.
save_metadata – [in] Reserved for future use. Set to 0.
save_stream – [in] Reserved for future use. Set to 0.
stream_handle – [in] Bitstream handle to store parsed information.

Returns:

An error code as specified in API Return Status Codes.

nvjpeg2kStatus_t nvjpeg2kStreamParseFile( nvjpeg2kHandle_t handle, const char *filename, nvjpeg2kStream_t stream_handle )#

Parse a JPEG2000 file from disk.

Accepts a JPEG2000 file on disk as input and parses the JPEG2000 header information. The parsed information is stored in the stream handle and can be retrieved by the stream query APIs.

Parameters:

handle – [in] Library handle.
filename – [in] Path to the JPEG2000 file on disk.
stream_handle – [in] Bitstream handle to store parsed information.

Returns:

An error code as specified in API Return Status Codes.

nvjpeg2kStatus_t nvjpeg2kStreamGetImageInfo( nvjpeg2kStream_t stream_handle, nvjpeg2kImageInfo_t *image_info )#

Retrieve image-level information from a parsed bitstream.

Retrieves the image information defined in nvjpeg2kImageInfo_t. This information is useful in allocating output buffers on device memory.

Parameters:

stream_handle – [in] Bitstream handle.
image_info – [out] Pointer to nvjpeg2kImageInfo_t to store the image information.

Returns:

An error code as specified in API Return Status Codes.

nvjpeg2kStatus_t nvjpeg2kStreamGetImageComponentInfo( nvjpeg2kStream_t stream_handle, nvjpeg2kImageComponentInfo_t *component_info, uint32_t component_id )#

Retrieve component-level information from a parsed bitstream.

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.

Parameters:

stream_handle – [in] Bitstream handle.
component_info – [out] Pointer to nvjpeg2kImageComponentInfo_t to store the component information.
component_id – [in] Component index.

Returns:

An error code as specified in API Return Status Codes.

nvjpeg2kStatus_t nvjpeg2kStreamGetResolutionsInTile( nvjpeg2kStream_t stream_handle, uint32_t tile_id, uint32_t *num_res )#

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

Parameters:

stream_handle – [in] Bitstream handle.
tile_id – [in] Raster scan based tile index.
num_res – [out] Number of resolutions present in the tile.

Returns:

An error code as specified in API Return Status Codes.

nvjpeg2kStatus_t nvjpeg2kStreamGetTileComponentDim( nvjpeg2kStream_t stream_handle, uint32_t component_id, uint32_t tile_id, uint32_t *tile_width, uint32_t *tile_height )#

Retrieve tile dimensions for a tile component.

This function is useful when the tile dimensions in nvjpeg2kImageInfo_t are not a multiple of the image dimensions.

Parameters:

stream_handle – [in] Bitstream handle.
component_id – [in] Component index.
tile_id – [in] Raster scan based tile index.
tile_width – [out] Tile width for the specified tile component.
tile_height – [out] Tile height for the specified tile component.

Returns:

An error code as specified in API Return Status Codes.

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 )#

Retrieve dimensions at a resolution level for a tile component.

The resolution dimensions are computed 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

Parameters:

stream_handle – [in] Bitstream handle.
component_id – [in] Component index.
tile_id – [in] Raster scan based tile index.
res_level – [in] Resolution level.
res_width – [out] Resolution width for the specified tile component and resolution level.
res_height – [out] Resolution height for the specified tile component and resolution level.

Returns:

An error code as specified in API Return Status Codes.

nvjpeg2kStatus_t nvjpeg2kStreamGetColorSpace( nvjpeg2kStream_t stream_handle, nvjpeg2kColorSpace_t *color_space )#

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

Parameters:

stream_handle – [in] Bitstream handle.
color_space – [out] Color space of the parsed image.

Returns:

An error code as specified in API Return Status Codes.

Decode API#

nvjpeg2kStatus_t nvjpeg2kDecode( nvjpeg2kHandle_t handle, nvjpeg2kDecodeState_t decode_state, nvjpeg2kStream_t jpeg2k_stream, nvjpeg2kImage_t *decode_output, cudaStream_t stream )#

Decode a single JPEG2000 image.

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, the user must parse the bitstream using nvjpeg2kStreamParse() such that the bitstream information is stored in jpeg2k_stream.

Parameters:

handle – [in] Library handle.
decode_state – [in] Decode state handle.
jpeg2k_stream – [in] Bitstream handle with parsed information.
decode_output – [in/out] Decode output struct. The struct should be on host memory. The image component pointers should point to device memory. See nvjpeg2kImage_t.
stream – [in] CUDA stream. Can be set to 0.

Returns:

An error code as specified in API Return Status Codes.

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 )#

Decode a single JPEG2000 image with decode parameters.

Parameters:

handle – [in] Library handle.
decode_state – [in] Decode state handle.
jpeg2k_stream – [in] Bitstream handle with parsed information.
decode_params – [in] Decode parameters to control output (e.g. area of interest, RGB output). Can be set to NULL.
decode_output – [in/out] Decode output struct. The struct should be on host memory. The image component pointers should point to device memory. See nvjpeg2kImage_t.
stream – [in] CUDA stream. Can be set to 0.

Returns:

An error code as specified in API Return Status Codes.

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 )#

Decode a single tile within a JPEG2000 image.

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, the user must parse the bitstream using nvjpeg2kStreamParse() such that the bitstream information is stored in jpeg2k_stream.

Parameters:

handle – [in] Library handle.
decode_state – [in] Decode state handle.
jpeg2k_stream – [in] Bitstream handle with parsed information.
decode_params – [in] Decode parameters to control output. Can be set to NULL.
tile_id – [in] Raster scan based tile index.
num_res_levels – [in] Number of resolutions to decode within the tile. When set to 0, the image is decoded at full resolution. Maximum allowed resolutions in a tile can be determined using nvjpeg2kStreamGetResolutionsInTile().
decode_output – [in/out] Decode output struct. The struct should be on host memory. The image component pointers should point to device memory. See nvjpeg2kImage_t.
stream – [in] CUDA stream. Can be set to 0.

Returns:

An error code as specified in API Return Status Codes.

Decode Parameters API#

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().

nvjpeg2kStatus_t nvjpeg2kDecodeParamsSetDecodeArea( nvjpeg2kDecodeParams_t decode_params, uint32_t start_x, uint32_t end_x, uint32_t start_y, uint32_t end_y )#

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.

Parameters:

decode_params – [in/out] Decode parameters handle.
start_x – [in] Left coordinate of the decode area.
end_x – [in] Right coordinate of the decode area.
start_y – [in] Top coordinate of the decode area.
end_y – [in] Bottom coordinate of the decode area.

Returns:

An error code as specified in API Return Status Codes.

nvjpeg2kStatus_t nvjpeg2kDecodeParamsSetRGBOutput( nvjpeg2kDecodeParams_t decode_params, int32_t force_rgb )#

Enable RGB decode output for chroma-subsampled images.

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.

Parameters:

decode_params – [in/out] Decode parameters handle.
force_rgb – [in] Set to 1 to enable RGB output.

Returns:

An error code as specified in API Return Status Codes.

nvjpeg2kStatus_t nvjpeg2kDecodeParamsSetOutputFormat( nvjpeg2kDecodeParams_t decode_params, nvjpeg2kImageFormat_t format )#

Set the decode output format.

Sets the decode output format. When using NVJPEG2K_FORMAT_INTERLEAVED with 420/422 chroma subsampling, RGB output (nvjpeg2kDecodeParamsSetRGBOutput()) must also be enabled.

The decode output buffer should be allocated in the following manner to support NVJPEG2K_FORMAT_INTERLEAVED:

nvjpeg2kImage_t decode_output;

// When decode_output.pixel_type is NVJPEG2K_UINT8:  bytes_per_sample = 1
// When decode_output.pixel_type is NVJPEG2K_UINT16 or NVJPEG2K_INT16: bytes_per_sample = 2

decode_output.pitch_in_bytes[0] = image_width * num_components * bytes_per_sample;
decode_output.pixel_data[0]     = decode_output.pitch_in_bytes[0] * info.image_height;
decode_output.num_components    = num_components;

Parameters:

decode_params – [in/out] Decode parameters handle.
format – [in] Output format. Defaults to NVJPEG2K_FORMAT_PLANAR.

Returns:

An error code as specified in API Return Status Codes.

Encode API#

nvjpeg2kStatus_t nvjpeg2kEncode( nvjpeg2kEncoder_t enc_handle, nvjpeg2kEncodeState_t encode_state, const nvjpeg2kEncodeParams_t encode_params, const nvjpeg2kImage_t *input_image, cudaStream_t stream )#

Compress an image in JPEG2000 format.

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.

Parameters:

enc_handle – [in] Encoder handle.
encode_state – [in] Encode state handle containing intermediate buffers.
encode_params – [in] Encode parameters handle.
input_image – [in] Input image. The struct should be on host memory. The image component pointers should point to device memory. See nvjpeg2kImage_t.
stream – [in] CUDA stream for all device operations.

Returns:

An error code as specified in API Return Status Codes.

nvjpeg2kStatus_t nvjpeg2kEncodeRetrieveBitstream( nvjpeg2kEncoder_t enc_handle, nvjpeg2kEncodeState_t encode_state, unsigned char *compressed_data, size_t *length, cudaStream_t stream )#

Retrieve the compressed JPEG2000 bitstream.

Retrieves the compressed stream from the encoder state that was previously used by the encoder function.

If compressed_data 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 the 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 length.
When compressed_data is NULL, the API is synchronous with the host.
When compressed_data is not NULL, the application should call cudaStreamSynchronize() to ensure the bitstream copy is successful.

Parameters:

enc_handle – [in] Encoder handle.
encode_state – [in] Encode state handle.
compressed_data – [out] Pointer to the host buffer for the compressed stream. Can be NULL (see description).
length – [in/out] Pointer to the buffer size. The library will update the actual compressed stream size.
stream – [in] CUDA stream for device operations.

Returns:

An error code as specified in API Return Status Codes.

Encode Parameters API#

nvjpeg2kStatus_t nvjpeg2kEncodeParamsSetEncodeConfig( nvjpeg2kEncodeParams_t encode_params, nvjpeg2kEncodeConfig_t *encoder_config )#

Set the JPEG2000 encode configuration.

Sets the JPEG2000 header parameters defined in nvjpeg2kEncodeConfig_t. This function should always be called during the encode process.

Parameters:

encode_params – [in/out] Encode parameters handle.
encoder_config – [in] Pointer to nvjpeg2kEncodeConfig_t.

Returns:

An error code as specified in API Return Status Codes.

nvjpeg2kStatus_t nvjpeg2kEncodeParamsSpecifyQuality( nvjpeg2kEncodeParams_t encode_params, nvjpeg2kQualityType_t quality_type, double quality_value )#

Set quality type and value for lossy encoding.

Allows the application to set quality type (algorithm) and quality value, which controls how good the encoded image should look. Refer to nvjpeg2kQualityType_t for the allowed values for each quality type. Will overwrite any existing quality setting.

nvjpeg2kEncodeParamsSetEncodeConfig() should be called before this function.

Will return NVJPEG2K_STATUS_INVALID_PARAMETER if:

nvjpeg2kEncodeParamsSetEncodeConfig() was not yet called
quality_value is negative
Encoding mode is set to reversible
Quality type is NVJPEG2K_QUALITY_TYPE_TARGET_PSNR and HT encoder is enabled
Quality type is NVJPEG2K_QUALITY_TYPE_Q_FACTOR and quality_value is larger than 100
Quality type is NVJPEG2K_QUALITY_TYPE_Q_FACTOR and mct = 0 and input color space is sRGB

Parameters:

encode_params – [in/out] Encode parameters handle.
quality_type – [in] Quality type (algorithm) to use. See nvjpeg2kQualityType_t.
quality_value – [in] Quality value. Interpretation depends on quality_type.

Returns:

An error code as specified in API Return Status Codes.

nvjpeg2kStatus_t nvjpeg2kEncodeParamsSetInputFormat( nvjpeg2kEncodeParams_t encode_params, nvjpeg2kImageFormat_t format )#

Set the encode input format.

Sets the encode input format. NVJPEG2K_FORMAT_INTERLEAVED is supported by the encoder only when all component dimensions are the same.

The encode input buffer should be allocated in the following manner to support NVJPEG2K_FORMAT_INTERLEAVED:

nvjpeg2kImage_t encode_input;

// When encode_input.pixel_type is NVJPEG2K_UINT8:  bytes_per_sample = 1
// When encode_input.pixel_type is NVJPEG2K_UINT16 or NVJPEG2K_INT16: bytes_per_sample = 2

encode_input.pitch_in_bytes[0] = image_width * num_components * bytes_per_sample;
encode_input.pixel_data[0]     = encode_input.pitch_in_bytes[0] * info.image_height;
encode_input.num_components    = num_components;

Parameters:

encode_params – [in/out] Encode parameters handle.
format – [in] Input format. Defaults to NVJPEG2K_FORMAT_PLANAR.

Returns:

An error code as specified in API Return Status Codes.

Type Declarations#

API Return Status Codes#

enum nvjpeg2kStatus_t#

Return status codes for nvJPEG2000 APIs.

Values:

enumerator NVJPEG2K_STATUS_SUCCESS#: The API call finished successfully. Note that many calls are asynchronous and some errors may only appear after synchronization.

enumerator NVJPEG2K_STATUS_NOT_INITIALIZED#: The library handle was not initialized.

enumerator NVJPEG2K_STATUS_INVALID_PARAMETER#: Wrong parameter was passed. For example, a null pointer as input data, or an invalid enum value.

enumerator NVJPEG2K_STATUS_BAD_JPEG#: Cannot parse the JPEG2000 stream. Likely due to a corruption that cannot be handled.

enumerator NVJPEG2K_STATUS_JPEG_NOT_SUPPORTED#: Attempting to decode a JPEG2000 stream that is not supported by the nvJPEG2000 library.

enumerator NVJPEG2K_STATUS_ALLOCATOR_FAILURE#: The user-provided allocator functions, for either memory allocation or for releasing the memory, returned a non-zero code.

enumerator NVJPEG2K_STATUS_EXECUTION_FAILED#: Error during the execution of the device tasks.

enumerator NVJPEG2K_STATUS_ARCH_MISMATCH#: The device capabilities are not enough for the set of input parameters provided.

enumerator NVJPEG2K_STATUS_INTERNAL_ERROR#: Unknown error occurred in the library.

enumerator NVJPEG2K_STATUS_IMPLEMENTATION_NOT_SUPPORTED#: API is not supported by the backend.

Device Allocator Interface#

typedef int (*nvjpeg2kDeviceMalloc)(void**, size_t)#

Prototype for device memory allocation, modelled after cudaMalloc().

Parameters: pointer to allocated memory (out), size in bytes to allocate (in).

Return:: 0 on success, non-zero on failure.

typedef int (*nvjpeg2kDeviceFree)(void*)#

Prototype for device memory release, modelled after cudaFree().

Parameters: pointer to memory to free (in).

Return:: 0 on success, non-zero on failure.

struct nvjpeg2kDeviceAllocator_t#

Device memory allocator interface.

When passed to nvjpeg2kCreate(), this structure is used for allocating and releasing device memory. If NULL is passed instead, the default cudaMalloc() / cudaFree() functions are used. When using nvjpeg2kCreateSimple() to create the library handle, the default device memory allocator will be used.

Public Members

nvjpeg2kDeviceMalloc device_malloc#: Device memory allocation callback.

nvjpeg2kDeviceFree device_free#: Device memory free callback.

Pinned Allocator Interface#

typedef int (*nvjpeg2kPinnedMalloc)(void**, size_t, unsigned int flags)#

Prototype for pinned memory allocation, modelled after cudaHostAlloc().

Parameters: pointer to allocated memory (out), size in bytes to allocate (in), allocation flags (in).

Return:: 0 on success, non-zero on failure.

typedef int (*nvjpeg2kPinnedFree)(void*)#

Prototype for pinned memory release, modelled after cudaFreeHost().

Parameters: pointer to memory to free (in).

Return:: 0 on success, non-zero on failure.

struct nvjpeg2kPinnedAllocator_t#

Pinned memory allocator interface.

When passed to nvjpeg2kCreate(), this structure is used for allocating and releasing host pinned memory for copying data to/from device. If NULL is passed instead, the default cudaHostAlloc() / cudaFreeHost() functions are used. When using nvjpeg2kCreateSimple() to create the library handle, the default host pinned memory allocator will be used.

Public Members

nvjpeg2kPinnedMalloc pinned_malloc#: Pinned memory allocation callback.

nvjpeg2kPinnedFree pinned_free#: Pinned memory free callback.

Extended Device Allocator Interface#

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

Prototype for extended device memory allocation with stream and context.

Param ctx:: [in] User-defined context pointer.
Param ptr:: [out] Pointer to allocated memory.
Param size:: [in] Size in bytes to allocate.
Param stream:: [in] CUDA stream for ordered allocation.
Return:: 0 on success, non-zero on failure.

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

Prototype for extended device memory release with stream and context.

Param ctx:: [in] User-defined context pointer.
Param ptr:: [in] Pointer to memory to free.
Param size:: [in] Size in bytes of the allocation.
Param stream:: [in] CUDA stream for ordered deallocation.
Return:: 0 on success, non-zero on failure.

struct nvjpeg2kDeviceAllocatorV2_t#

Extended device memory allocator interface with stream and context support.

Allows the user to provide device allocators which accept CUDA streams and user context. Extended device allocators can be passed as input to the library using nvjpeg2kCreateV2().

Public Members

nvjpeg2kDeviceMallocV2 device_malloc#: Extended device memory allocation callback.

nvjpeg2kDeviceFreeV2 device_free#: Extended device memory free callback.

void *device_ctx#: User-defined context pointer.

Extended Pinned Allocator Interface#

typedef int (*nvjpeg2kPinnedMallocV2)(void *ctx, void **ptr, size_t size, cudaStream_t stream)#

Prototype for extended pinned memory allocation with stream and context.

Param ctx:: [in] User-defined context pointer.
Param ptr:: [out] Pointer to allocated memory.
Param size:: [in] Size in bytes to allocate.
Param stream:: [in] CUDA stream for ordered allocation.
Return:: 0 on success, non-zero on failure.

typedef int (*nvjpeg2kPinnedFreeV2)(void *ctx, void *ptr, size_t size, cudaStream_t stream)#

Prototype for extended pinned memory release with stream and context.

Param ctx:: [in] User-defined context pointer.
Param ptr:: [in] Pointer to memory to free.
Param size:: [in] Size in bytes of the allocation.
Param stream:: [in] CUDA stream for ordered deallocation.
Return:: 0 on success, non-zero on failure.

struct nvjpeg2kPinnedAllocatorV2_t#

Extended pinned memory allocator interface with stream and context support.

Allows the user to provide pinned allocators which accept CUDA streams and user context. Extended pinned allocators can be passed as input to the library using nvjpeg2kCreateV2().

Public Members

nvjpeg2kPinnedMallocV2 pinned_malloc#: Extended pinned memory allocation callback.

nvjpeg2kPinnedFreeV2 pinned_free#: Extended pinned memory free callback.

void *pinned_ctx#: User-defined context pointer.

Color Space#

enum nvjpeg2kColorSpace_t#

Color space values for JP2 files.

Corresponds to the colorspace values which are part of the JP2 file format specification.

Values:

enumerator NVJPEG2K_COLORSPACE_NOT_SUPPORTED#: Color space is not supported.

enumerator NVJPEG2K_COLORSPACE_UNKNOWN#: Color space is unknown.

enumerator NVJPEG2K_COLORSPACE_SRGB#: sRGB color space.

enumerator NVJPEG2K_COLORSPACE_GRAY#: Grayscale.

enumerator NVJPEG2K_COLORSPACE_SYCC#: sYCC color space.

Library Backend#

enum nvjpeg2kBackend_t#

Backend selection for the nvJPEG2000 library.

Allows the user to select a different internal implementation. A single implementation is currently supported. Additional implementations may be added in the future.

Values:

enumerator NVJPEG2K_BACKEND_DEFAULT#: Default backend implementation.

Component Information#

struct nvjpeg2kImageComponentInfo_t#

Per-component image information.

Used to retrieve component level information. This information can be used for allocating output buffers.

Public Members

uint32_t component_width#: Width of the component in pixels.

uint32_t component_height#: Height of the component in pixels.

uint8_t precision#: Bit depth of the component.

uint8_t sgn#: 1 if the component samples are signed, 0 otherwise.

Image Information#

struct nvjpeg2kImageInfo_t#

Image-level information.

Used to retrieve image information which can be used to allocate output buffers.

Public Members

uint32_t image_width#: Width of the image in pixels.

uint32_t image_height#: Height of the image in pixels.

uint32_t tile_width#: Width of a tile in pixels.

uint32_t tile_height#: Height of a tile in pixels.

uint32_t num_tiles_x#: Number of tiles in the horizontal direction.

uint32_t num_tiles_y#: Number of tiles in the vertical direction.

uint32_t num_components#: Number of image components.

Image Type#

enum nvjpeg2kImageType_t#

Pixel data types supported by nvJPEG2000.

Values:

enumerator NVJPEG2K_UINT8#: Unsigned 8-bit integer.

enumerator NVJPEG2K_UINT16#: Unsigned 16-bit integer.

enumerator NVJPEG2K_INT16#: Signed 16-bit integer.

Image Data#

struct nvjpeg2kImage_t#

Image container for decode/encode operations.

Contains an array of pointers, one per component, and a corresponding array of pitch values. pixel_type determines the data type of pixel_data.

Public Members

void **pixel_data#: Array of pointers to component data in device memory.

size_t *pitch_in_bytes#: Array of pitch values (in bytes) for each component.

nvjpeg2kImageType_t pixel_type#: Pixel data type. See Image Type for supported types.

uint32_t num_components#: Number of image components.

Image Format#

enum nvjpeg2kImageFormat_t#

Image memory layout format.

Describes how an image is stored in memory.

Values:

enumerator NVJPEG2K_FORMAT_PLANAR#: All components are stored in separate planes.

enumerator NVJPEG2K_FORMAT_INTERLEAVED#: All components are stored in interleaved order. Not supported when component dimensions differ.

Decoder#

Decoder Handle#

typedef struct nvjpeg2kHandle *nvjpeg2kHandle_t#

Handle to the nvJPEG2000 library instance.

This handle should be instantiated prior to using any of the decode APIs. It is thread safe and can be used by multiple threads simultaneously.

Decoder State#

typedef struct nvjpeg2kDecodeState *nvjpeg2kDecodeState_t#

Handle to the nvJPEG2000 decode state.

Stores intermediate decode information. This handle can be reused when decoding multiple images. The user must ensure that a stream or device synchronize CUDA call is made between the decoding of two images.

Bitstream Handle#

typedef struct nvjpeg2kStream *nvjpeg2kStream_t#

Handle to the nvJPEG2000 bitstream.

Used for parsing the bitstream. Bitstream metadata can be extracted by using the APIs defined in Parser API Reference.

Decode Parameters Handle#

typedef struct nvjpeg2kDecodeParams *nvjpeg2kDecodeParams_t#

Handle to the nvJPEG2000 decode output parameters.

Used to store the decode output parameters like the decode area of interest coordinates.

Encoder#

Encoder Handle#

typedef struct nvjpeg2kEncoder *nvjpeg2kEncoder_t#

Handle to the nvJPEG2000 encoder instance.

This handle should be instantiated prior to using any of the encode APIs. It is thread safe and can be used across host threads.

Encode State#

typedef struct nvjpeg2kEncodeState *nvjpeg2kEncodeState_t#

Handle to the nvJPEG2000 encode state.

Contains intermediate buffers required by the encoding process.

Encode Parameters Handle#

typedef struct nvjpeg2kEncodeParams *nvjpeg2kEncodeParams_t#

Handle to the nvJPEG2000 encode parameters.

Stores user provided parameters that control the encoding process.

Maximum Resolutions#

NVJPEG2K_MAXRES 33#: Maximum number of JPEG2000 resolutions.

High Throughput JPEG 2000 Rsiz Parameter#

NVJPEG2K_RSIZ_HT 0x4000#: To enable High throughput JPEG2000 Encode, set rsiz in nvjpeg2kEncodeConfig_t to NVJPEG2K_RSIZ_HT.

High Throughput JPEG 2000 Code-block Style Parameter#

NVJPEG2K_MODE_HT 0x40#: To enable High throughput JPEG2000 Encode, set encode_modes in nvjpeg2kEncodeConfig_t to NVJPEG2K_MODE_HT.

Progression Order#

enum nvjpeg2kProgOrder_t#

Progression orders defined in the JPEG2000 standard.

Values:

enumerator NVJPEG2K_LRCP#: Layer-Resolution-Component-Position.

enumerator NVJPEG2K_RLCP#: Resolution-Layer-Component-Position.

enumerator NVJPEG2K_RPCL#: Resolution-Position-Component-Layer.

enumerator NVJPEG2K_PCRL#: Position-Component-Resolution-Layer.

enumerator NVJPEG2K_CPRL#: Component-Position-Resolution-Layer.

Bitstream Type#

enum nvjpeg2kBitstreamType_t#

JPEG2000 bitstream type.

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

Values:

enumerator NVJPEG2K_STREAM_J2K#: JPEG2000 codestream (.j2k).

enumerator NVJPEG2K_STREAM_JP2#: JP2 container (.jp2).

Quality Type#

enum nvjpeg2kQualityType_t#

Quality type selection for lossy encoding.

Can be used with nvjpeg2kEncodeParamsSpecifyQuality().

Values:

enumerator NVJPEG2K_QUALITY_TYPE_TARGET_PSNR#: Quality value is interpreted as desired Peak Signal-to-Noise Ratio (PSNR) target. The higher the value, the better quality image is produced. Quality value should be positive floating point. Cannot be used with HT encoder.

enumerator NVJPEG2K_QUALITY_TYPE_QUANTIZATION_STEP#: 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.

enumerator NVJPEG2K_QUALITY_TYPE_Q_FACTOR#: Quality value is interpreted as JPEG-like quality factor (1.0 worst to 100.0 best). Can only be used when the input colorspace is YCC, Grayscale, or RGB with MCT enabled.

Encode Config#

struct nvjpeg2kEncodeConfig_t#

JPEG2000 encode configuration.

Contains parameters present in the COD and SIZ headers of the JPEG2000 bitstream. Not all parameters are supported and some must be set to 0.

Public Members

nvjpeg2kBitstreamType_t stream_type#: Bitstream type (J2K or JP2).

nvjpeg2kColorSpace_t color_space#: Color space of the image.

uint16_t rsiz#: Should be set to 0 for J2K or NVJPEG2K_RSIZ_HT for HTJ2K.

uint32_t image_width#: Image width in pixels. Minimum value 1.

uint32_t image_height#: Image height in pixels. Minimum value 1.

uint32_t enable_tiling#: Set to 1 to enable tiling, 0 to disable.

uint32_t tile_width#: Tile width. Valid only when enable_tiling is 1. Should be less than image_width.

uint32_t tile_height#: Tile height. Valid only when enable_tiling is 1. Should be less than image_height.

uint32_t num_components#: Number of image components (1-4).

nvjpeg2kImageComponentInfo_t *image_comp_info#: Pointer to per-component information. Must be a valid pointer.

uint32_t enable_SOP_marker#: Should be set to 0.

uint32_t enable_EPH_marker#: Should be set to 0.

nvjpeg2kProgOrder_t prog_order#: Progression order.

uint32_t num_layers#: Number of quality layers. Should be set to 1.

uint32_t mct_mode#: Multi-component transform mode. 0 for YCC/Grayscale, 1 for RGB.

uint32_t num_resolutions#: Number of resolutions. Cannot be greater than image/tile dimensions.

uint32_t code_block_w#: Code block width. Valid values: 32, 64.

uint32_t code_block_h#: Code block height. Valid values: 32, 64.

uint32_t encode_modes#: Should be set to 0 for J2K or NVJPEG2K_MODE_HT for HTJ2K.

uint32_t irreversible#: Set to 1 for irreversible (lossy) transform, 0 for reversible (lossless).

uint32_t num_precincts_init#: Number of valid precinct entries. Set to 0 to disable custom precincts.

uint32_t precinct_width[33]#: Precinct widths per resolution. Should be a power of 2. Valid only when num_precincts_init is non-zero.

uint32_t precinct_height[33]#: Precinct heights per resolution. Should be a power of 2. Valid only when num_precincts_init is non-zero.