rocJPEG API reference

rocJPEG API reference#

2026-09-21

10 min read time

Applies to Linux

The rocJPEG API is exposed in rocjpeg.h.

enum RocJpegStatus#

Enumeration representing the status codes for the rocJPEG library.

Values:

enumerator ROCJPEG_STATUS_SUCCESS#

The operation completed successfully.

enumerator ROCJPEG_STATUS_NOT_INITIALIZED#

The rocJPEG library is not initialized.

enumerator ROCJPEG_STATUS_INVALID_PARAMETER#

An invalid parameter was passed to a function.

enumerator ROCJPEG_STATUS_BAD_JPEG#

The input JPEG data is corrupted or invalid.

enumerator ROCJPEG_STATUS_JPEG_NOT_SUPPORTED#

The JPEG format is not supported.

enumerator ROCJPEG_STATUS_OUTOF_MEMORY#

Out of memory error.

enumerator ROCJPEG_STATUS_EXECUTION_FAILED#

The execution of a function failed.

enumerator ROCJPEG_STATUS_ARCH_MISMATCH#

The architecture is not supported.

enumerator ROCJPEG_STATUS_INTERNAL_ERROR#

Internal error occurred.

enumerator ROCJPEG_STATUS_IMPLEMENTATION_NOT_SUPPORTED#

The requested implementation is not supported.

enumerator ROCJPEG_STATUS_HW_JPEG_DECODER_NOT_SUPPORTED#

Hardware JPEG decoder is not supported.

enumerator ROCJPEG_STATUS_RUNTIME_ERROR#

Runtime error occurred.

enumerator ROCJPEG_STATUS_NOT_IMPLEMENTED#

The requested feature is not implemented.

enumerator ROCJPEG_STATUS_MAX_VALUE#

Maximum status code value.

enum RocJpegChromaSubsampling#

Enum representing the chroma subsampling options for JPEG encoding/decoding.

The RocJpegChromaSubsampling enum defines the available chroma subsampling options for JPEG encoding/decoding. Chroma subsampling refers to the reduction of color information in an image to reduce file size.

The possible values are:

  • ROCJPEG_CSS_444: Full chroma resolution (4:4:4).

  • ROCJPEG_CSS_440: Chroma resolution reduced by half vertically (4:4:0).

  • ROCJPEG_CSS_422: Chroma resolution reduced by half horizontally (4:2:2).

  • ROCJPEG_CSS_420: Chroma resolution reduced by half both horizontally and vertically (4:2:0).

  • ROCJPEG_CSS_411: Chroma resolution reduced by a quarter horizontally (4:1:1).

  • ROCJPEG_CSS_400: No chroma information (4:0:0).

  • ROCJPEG_CSS_UNKNOWN: Unknown chroma subsampling.

Values:

enumerator ROCJPEG_CSS_444#
enumerator ROCJPEG_CSS_440#
enumerator ROCJPEG_CSS_422#
enumerator ROCJPEG_CSS_420#
enumerator ROCJPEG_CSS_411#
enumerator ROCJPEG_CSS_400#
enumerator ROCJPEG_CSS_UNKNOWN#
enum RocJpegOutputFormat#

Enum representing the output format options for the RocJpegImage.

The RocJpegOutputFormat enum specifies the different output formats that can be used when decoding a JPEG image using the VCN JPEG decoder.

The available output formats are:

  • ROCJPEG_OUTPUT_NATIVE: Returns the native unchanged decoded YUV image from the VCN JPEG decoder. The channel arrangement depends on the chroma subsampling format.

  • ROCJPEG_OUTPUT_YUV_PLANAR: Extracts the Y, U, and V channels from the decoded YUV image and writes them into separate channels of the RocJpegImage.

  • ROCJPEG_OUTPUT_Y: Returns only the luma component (Y) and writes it to the first channel of the RocJpegImage.

  • ROCJPEG_OUTPUT_RGB: Converts the decoded image to interleaved RGB format using the VCN JPEG decoder or HIP kernels and writes it to the first channel of the RocJpegImage.

  • ROCJPEG_OUTPUT_RGB_PLANAR: Converts the decoded image to RGB PLANAR format using the VCN JPEG decoder or HIP kernels and writes the RGB channels to separate channels of the RocJpegImage.

  • ROCJPEG_OUTPUT_FORMAT_MAX: Maximum allowed value for the output format.

Values:

enumerator ROCJPEG_OUTPUT_NATIVE#

return native unchanged decoded YUV image from the VCN JPEG decoder. For ROCJPEG_CSS_444 and ROCJPEG_CSS_440 write Y, U, and V to first, second, and third channels of RocJpegImage For ROCJPEG_CSS_422 write YUYV (packed) to first channel of RocJpegImage For ROCJPEG_CSS_420 write Y to first channel and UV (interleaved) to second channel of RocJpegImage For ROCJPEG_CSS_400 write Y to first channel of RocJpegImage extract Y, U, and V channels from the decoded YUV image from the VCN JPEG decoder and write into first, second, and third channel of RocJpegImage. For ROCJPEG_CSS_400 write Y to first channel of RocJpegImage

enumerator ROCJPEG_OUTPUT_YUV_PLANAR#

return luma component (Y) and write to first channel of RocJpegImage

enumerator ROCJPEG_OUTPUT_Y#

convert to interleaved RGB using VCN JPEG decoder (on MI300+) or using HIP kernels and write to first channel of RocJpegImage

enumerator ROCJPEG_OUTPUT_RGB#

convert to RGB PLANAR using VCN JPEG decoder (on MI300+) or HIP kernels and write to first, second, and third channel of RocJpegImage.

enumerator ROCJPEG_OUTPUT_RGB_PLANAR#
enumerator ROCJPEG_OUTPUT_FORMAT_MAX#

maximum allowed value

enum RocJpegBackend#

The backend options for the rocJpeg library.

This enum defines the available backend options for the rocJpeg library. The backend can be either hardware or hybrid.

Values:

enumerator ROCJPEG_BACKEND_HARDWARE#

Hardware backend option.

enumerator ROCJPEG_BACKEND_HYBRID#

Hybrid backend option.

RocJpegStatus ROCJPEGAPI rocJpegStreamCreate (RocJpegStreamHandle *jpeg_stream_handle)

Creates a RocJpegStreamHandle for JPEG stream processing.

This function creates a RocJpegStreamHandle, which is used for processing JPEG streams. The created handle is stored in the jpeg_stream_handle parameter.

Parameters:

jpeg_stream_handle – Pointer to a RocJpegStreamHandle variable that will hold the created handle.

Returns:

RocJpegStatus Returns the status of the operation. Possible values are:

  • ROCJPEG_STATUS_SUCCESS: The operation was successful.

  • ROCJPEG_STATUS_INVALID_ARGUMENT: The jpeg_stream_handle parameter is NULL.

  • ROCJPEG_STATUS_OUT_OF_MEMORY: Failed to allocate memory for the handle.

  • ROCJPEG_STATUS_UNKNOWN_ERROR: An unknown error occurred.

RocJpegStatus ROCJPEGAPI rocJpegStreamParse (const unsigned char *data, size_t length, RocJpegStreamHandle jpeg_stream_handle)

Parses a JPEG stream.

This function parses a JPEG stream represented by the data parameter of length length. The parsed stream is associated with the jpeg_stream_handle provided.

Parameters:

  • data – The pointer to the JPEG stream data.

  • length – The length of the JPEG stream data.

  • jpeg_stream_handle – The handle to the JPEG stream.

Returns:

The status of the JPEG stream parsing operation.

RocJpegStatus ROCJPEGAPI rocJpegStreamDestroy (RocJpegStreamHandle jpeg_stream_handle)

Destroys a RocJpegStreamHandle object and releases associated resources.

This function destroys the RocJpegStreamHandle object specified by jpeg_stream_handle and releases any resources associated with it. After calling this function, the jpeg_stream_handle becomes invalid and should not be used anymore.

Parameters:

jpeg_stream_handle – The handle to the RocJpegStreamHandle object to be destroyed.

Returns:

The status of the operation. Returns ROCJPEG_STATUS_SUCCESS if the operation is successful, or an error code if an error occurs.

RocJpegStatus ROCJPEGAPI rocJpegCreate (RocJpegBackend backend, int device_id, RocJpegHandle *handle)

Creates a RocJpegHandle for JPEG decoding.

This function creates a RocJpegHandle for JPEG decoding using the specified backend and device ID.

Parameters:

  • backend – The backend to be used for JPEG decoding.

  • device_id – The ID of the device to be used for JPEG decoding.

  • handle – Pointer to a RocJpegHandle variable to store the created handle.

Returns:

The status of the operation. Returns ROCJPEG_STATUS_INVALID_PARAMETER if handle is nullptr, ROCJPEG_STATUS_NOT_INITIALIZED if the rocJPEG handle initialization fails, or the status returned by the InitializeDecoder function of the rocjpeg_decoder.

RocJpegStatus ROCJPEGAPI rocJpegDestroy (RocJpegHandle handle)

Destroys a RocJpegHandle object.

This function destroys the RocJpegHandle object pointed to by the given handle. It releases any resources associated with the handle and frees the memory.

Parameters:

handle – The handle to the RocJpegHandle object to be destroyed.

Returns:

The status of the operation. Returns ROCJPEG_STATUS_SUCCESS if the handle was successfully destroyed, or ROCJPEG_STATUS_INVALID_PARAMETER if the handle is nullptr.

RocJpegStatus ROCJPEGAPI rocJpegGetImageInfo (RocJpegHandle handle, RocJpegStreamHandle jpeg_stream_handle, uint8_t *num_components, RocJpegChromaSubsampling *subsampling, uint32_t *widths, uint32_t *heights)

Retrieves information about the JPEG image.

This function retrieves the number of components, chroma subsampling, and dimensions (width and height) of the JPEG image specified by the jpeg_stream_handle. The information is stored in the provided output parameters num_components, subsampling, widths, and heights.

Parameters:

  • handle – The handle to the RocJpegDecoder instance.

  • jpeg_stream_handle – The handle to the RocJpegStream instance representing the JPEG image.

  • num_components – A pointer to an unsigned 8-bit integer that will store the number of components in the JPEG image.

  • subsampling – A pointer to a RocJpegChromaSubsampling enum that will store the chroma subsampling information.

  • widths – A pointer to an unsigned 32-bit integer array that will store the width of each component in the JPEG image.

  • heights – A pointer to an unsigned 32-bit integer array that will store the height of each component in the JPEG image.

Returns:

The RocJpegStatus indicating the success or failure of the operation.

  • ROCJPEG_STATUS_SUCCESS: The operation was successful.

  • ROCJPEG_STATUS_INVALID_PARAMETER: One or more input parameters are invalid.

  • ROCJPEG_STATUS_RUNTIME_ERROR: An exception occurred during the operation.

RocJpegStatus ROCJPEGAPI rocJpegDecode (RocJpegHandle handle, RocJpegStreamHandle jpeg_stream_handle, const RocJpegDecodeParams *decode_params, RocJpegImage *destination)

Decodes a JPEG image using the rocJPEG library.

This function decodes a JPEG image using the rocJPEG library. It takes a rocJpegHandle, a rocJpegStreamHandle, a pointer to RocJpegDecodeParams, and a pointer to RocJpegImage as input parameters. The function returns a RocJpegStatus indicating the success or failure of the decoding operation.

Parameters:

  • handle – The rocJpegHandle representing the rocJPEG decoder instance.

  • jpeg_stream_handle – The rocJpegStreamHandle representing the input JPEG stream.

  • decode_params – A pointer to RocJpegDecodeParams containing the decoding parameters.

  • destination – A pointer to RocJpegImage where the decoded image will be stored.

Returns:

A RocJpegStatus indicating the success or failure of the decoding operation.

RocJpegStatus ROCJPEGAPI rocJpegDecodeBatched (RocJpegHandle handle, RocJpegStreamHandle *jpeg_stream_handles, int batch_size, const RocJpegDecodeParams *decode_params, RocJpegImage *destinations)

Decodes a batch of JPEG images using the rocJPEG library.

This function decodes a batch of JPEG images using the rocJPEG library.

Parameters:

  • handle – The rocJPEG handle.

  • jpeg_stream_handles – An array of rocJPEG stream handles representing the input JPEG streams.

  • batch_size – The number of JPEG streams in the batch.

  • decode_params – An array of RocJpegDecodeParams structs representing the decode parameters for the batch of JPEG images.

  • destinations – An array of rocJPEG images representing the output decoded images.

Returns:

The status of the JPEG decoding operation.

const char *ROCJPEGAPI rocJpegGetErrorName (RocJpegStatus rocjpeg_status)

Retrieves the name of the error associated with the given RocJpegStatus.

This function returns a string representation of the error associated with the given RocJpegStatus.

Parameters:

rocjpeg_status – The RocJpegStatus for which to retrieve the error name.

Returns:

A pointer to a constant character string representing the error name.

RocJpegStatus ROCJPEGAPI rocJpegDecodeAsync (RocJpegHandle handle, RocJpegStreamHandle jpeg_stream_handle, const RocJpegDecodeParams *decode_params, RocJpegImage *destination)

Submits a JPEG decode operation without waiting for the output.

This function is one half of the rocJpegDecodeAsync/rocJpegDecodeSync pair. It submits the decode to hardware and returns immediately. The caller must subsequently call rocJpegDecodeSync() on the same handle to wait for completion and retrieve the decoded output. These two calls must not be issued concurrently on the same handle. The intended usage is a producer/consumer model where one thread calls rocJpegDecodeAsync() and a separate thread calls rocJpegDecodeSync().

Parameters:

  • handle – The rocJPEG handle.

  • jpeg_stream_handle – The rocJPEG stream handle.

  • decode_params – The decoding parameters.

  • destination – The output image.

Returns:

A RocJpegStatus indicating the success or failure of the submit operation.

RocJpegStatus ROCJPEGAPI rocJpegDecodeSync (RocJpegHandle handle, RocJpegImage *destination)

Synchronizes a pending asynchronous JPEG decode and retrieves the decoded output.

This function is one half of the rocJpegDecodeAsync/rocJpegDecodeSync pair. It must be called after rocJpegDecodeAsync() on the same handle to wait for the decode to complete and copy the result to the destination buffer. These two calls must not be issued concurrently on the same handle. The intended usage is a producer/consumer model where one thread calls rocJpegDecodeAsync() and a separate thread calls rocJpegDecodeSync().

Parameters:

  • handle – The rocJPEG handle.

  • destination – A pointer to RocJpegImage where the decoded image will be stored.

Returns:

A RocJpegStatus indicating the success or failure of the sync operation.

RocJpegStatus ROCJPEGAPI rocJpegDecodeBatchedAsync (RocJpegHandle handle, RocJpegStreamHandle *jpeg_stream_handles, int batch_size, const RocJpegDecodeParams *decode_params, RocJpegImage *destinations)

Submits a batch of JPEG decode operations without waiting for the output.

This function is one half of the rocJpegDecodeBatchedAsync/rocJpegDecodeBatchedSync pair. It submits all images in the batch to the hardware decoder and returns immediately without waiting for the decodes to complete or copying the results to the destination buffers. The caller must subsequently call rocJpegDecodeBatchedSync() on the same handle to wait for completion and retrieve the decoded output. These two calls must not be issued concurrently on the same handle. The intended usage is a producer/consumer model where one thread calls rocJpegDecodeBatchedAsync() and a separate thread calls rocJpegDecodeBatchedSync().

Parameters:

  • handle – The rocJPEG handle.

  • jpeg_stream_handles – An array of rocJPEG stream handles representing the input JPEG streams.

  • batch_size – The number of JPEG streams in the batch.

  • decode_params – An array of RocJpegDecodeParams structs representing the decode parameters for each image.

  • destinations – An array of RocJpegImage structs representing the output decoded images.

Returns:

A RocJpegStatus indicating the success or failure of the submit operation.

RocJpegStatus ROCJPEGAPI rocJpegDecodeBatchedSync (RocJpegHandle handle, RocJpegImage *destinations, int batch_size)

Synchronizes a pending asynchronous batched JPEG decode and retrieves the decoded output.

This function is one half of the rocJpegDecodeBatchedAsync/rocJpegDecodeBatchedSync pair. It must be called after rocJpegDecodeBatchedAsync() on the same handle to wait for all submitted decodes in the batch to complete and copy the results to the destination buffers. These two calls must not be issued concurrently on the same handle. The intended usage is a producer/consumer model where one thread calls rocJpegDecodeBatchedAsync() and a separate thread calls rocJpegDecodeBatchedSync().

Parameters:

  • handle – The rocJPEG handle.

  • destinations – An array of RocJpegImage pointers identifying the pending batch, as passed to rocJpegDecodeBatchedAsync.

  • batch_size – The number of images in the batch.

Returns:

A RocJpegStatus indicating the success or failure of the sync operation.

struct RocJpegImage#
#include <rocjpeg.h>

Structure representing a JPEG image.

This structure holds the information about a JPEG image, including the pointers to the image channels and the pitch (stride) of each channel.

struct RocJpegDecodeParams#
#include <rocjpeg.h>

Structure containing parameters for JPEG decoding.

This structure defines the parameters for decoding a JPEG image using the rocJpeg library. It specifies the output format, crop rectangle, and target dimensions for the decoded image. Note that if both the crop rectangle and target dimensions are defined, cropping is done first, followed by resizing the resulting ROI to the target dimension.

Contents