/home/docs/checkouts/readthedocs.org/user_builds/advanced-micro-devices-rocjpeg/checkouts/develop/projects/rocjpeg/api/rocjpeg/rocjpeg.h File Reference

/home/docs/checkouts/readthedocs.org/user_builds/advanced-micro-devices-rocjpeg/checkouts/develop/projects/rocjpeg/api/rocjpeg/rocjpeg.h File Reference#

13 min read time

Applies to Linux

rocJPEG: /home/docs/checkouts/readthedocs.org/user_builds/advanced-micro-devices-rocjpeg/checkouts/develop/projects/rocjpeg/api/rocjpeg/rocjpeg.h File Reference
Classes | Macros | Typedefs | Enumerations | Functions
rocjpeg.h File Reference

The AMD rocJPEG Library. More...

#include "hip/hip_runtime.h"

Go to the source code of this file.

Classes

struct  RocJpegImage
 Structure representing a JPEG image. More...
 
struct  RocJpegDecodeParams
 Structure containing parameters for JPEG decoding. More...
 

Macros

#define ROCJPEGAPI
 
#define ROCJPEG_MAX_COMPONENT   4
 

Typedefs

typedef void * RocJpegStreamHandle
 A handle representing a RocJpegStream instance. More...
 
typedef void * RocJpegHandle
 A handle representing a RocJpeg instance. More...
 

Enumerations

enum  RocJpegStatus {
  ROCJPEG_STATUS_SUCCESS = 0 , ROCJPEG_STATUS_NOT_INITIALIZED = -1 , ROCJPEG_STATUS_INVALID_PARAMETER = -2 , ROCJPEG_STATUS_BAD_JPEG = -3 ,
  ROCJPEG_STATUS_JPEG_NOT_SUPPORTED = -4 , ROCJPEG_STATUS_OUTOF_MEMORY = -5 , ROCJPEG_STATUS_EXECUTION_FAILED = -6 , ROCJPEG_STATUS_ARCH_MISMATCH = -7 ,
  ROCJPEG_STATUS_INTERNAL_ERROR = -8 , ROCJPEG_STATUS_IMPLEMENTATION_NOT_SUPPORTED = -9 , ROCJPEG_STATUS_HW_JPEG_DECODER_NOT_SUPPORTED = -10 , ROCJPEG_STATUS_RUNTIME_ERROR = -11 ,
  ROCJPEG_STATUS_NOT_IMPLEMENTED = -12 , ROCJPEG_STATUS_MAX_VALUE = -13
}
 Enumeration representing the status codes for the rocJPEG library. More...
 
enum  RocJpegChromaSubsampling {
  ROCJPEG_CSS_444 = 0 , ROCJPEG_CSS_440 = 1 , ROCJPEG_CSS_422 = 2 , ROCJPEG_CSS_420 = 3 ,
  ROCJPEG_CSS_411 = 4 , ROCJPEG_CSS_400 = 5 , ROCJPEG_CSS_UNKNOWN = -1
}
 Enum representing the chroma subsampling options for JPEG encoding/decoding. More...
 
enum  RocJpegOutputFormat {
  ROCJPEG_OUTPUT_NATIVE = 0 , ROCJPEG_OUTPUT_YUV_PLANAR = 1 , ROCJPEG_OUTPUT_Y = 2 , ROCJPEG_OUTPUT_RGB = 3 ,
  ROCJPEG_OUTPUT_RGB_PLANAR = 4 , ROCJPEG_OUTPUT_FORMAT_MAX = 5
}
 Enum representing the output format options for the RocJpegImage. More...
 
enum  RocJpegBackend { ROCJPEG_BACKEND_HARDWARE = 0 , ROCJPEG_BACKEND_HYBRID = 1 }
 The backend options for the rocJpeg library. More...
 

Functions

RocJpegStatus ROCJPEGAPI rocJpegStreamCreate (RocJpegStreamHandle *jpeg_stream_handle)
 Creates a RocJpegStreamHandle for JPEG stream processing. More...
 
RocJpegStatus ROCJPEGAPI rocJpegStreamParse (const unsigned char *data, size_t length, RocJpegStreamHandle jpeg_stream_handle)
 Parses a JPEG stream. More...
 
RocJpegStatus ROCJPEGAPI rocJpegStreamDestroy (RocJpegStreamHandle jpeg_stream_handle)
 Destroys a RocJpegStreamHandle object and releases associated resources. More...
 
RocJpegStatus ROCJPEGAPI rocJpegCreate (RocJpegBackend backend, int device_id, RocJpegHandle *handle)
 Creates a RocJpegHandle for JPEG decoding. More...
 
RocJpegStatus ROCJPEGAPI rocJpegDestroy (RocJpegHandle handle)
 Destroys a RocJpegHandle object. More...
 
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. More...
 
RocJpegStatus ROCJPEGAPI rocJpegDecode (RocJpegHandle handle, RocJpegStreamHandle jpeg_stream_handle, const RocJpegDecodeParams *decode_params, RocJpegImage *destination)
 Decodes a JPEG image using the rocJPEG library. More...
 
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. More...
 
const char *ROCJPEGAPI rocJpegGetErrorName (RocJpegStatus rocjpeg_status)
 Retrieves the name of the error associated with the given RocJpegStatus. More...
 
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. More...
 
RocJpegStatus ROCJPEGAPI rocJpegDecodeSync (RocJpegHandle handle, RocJpegImage *destination)
 Synchronizes a pending asynchronous JPEG decode and retrieves the decoded output. More...
 
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. More...
 
RocJpegStatus ROCJPEGAPI rocJpegDecodeBatchedSync (RocJpegHandle handle, RocJpegImage *destinations, int batch_size)
 Synchronizes a pending asynchronous batched JPEG decode and retrieves the decoded output. More...
 

Detailed Description

The AMD rocJPEG Library.

Typedef Documentation

◆ RocJpegHandle

typedef void* RocJpegHandle

A handle representing a RocJpeg instance.

The RocJpegHandle is a pointer type used to represent a RocJpeg instance. It is used as a handle to perform various operations on the rocJpeg library.

◆ RocJpegStreamHandle

typedef void* RocJpegStreamHandle

A handle representing a RocJpegStream instance.

The RocJpegStreamHandle is a pointer type used to represent a RocJpegStream instance. It is used as a handle to parse and store various parameters from a JPEG stream.

Enumeration Type Documentation

◆ RocJpegBackend

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.

Enumerator
ROCJPEG_BACKEND_HARDWARE 

Hardware backend option.

ROCJPEG_BACKEND_HYBRID 

Hybrid backend option.

◆ RocJpegChromaSubsampling

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.

◆ RocJpegOutputFormat

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

ROCJPEG_OUTPUT_YUV_PLANAR 

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

ROCJPEG_OUTPUT_Y 

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

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.

ROCJPEG_OUTPUT_FORMAT_MAX 

maximum allowed value

◆ RocJpegStatus

enum RocJpegStatus

Enumeration representing the status codes for the rocJPEG library.

Enumerator
ROCJPEG_STATUS_SUCCESS 

The operation completed successfully.

ROCJPEG_STATUS_NOT_INITIALIZED 

The rocJPEG library is not initialized.

ROCJPEG_STATUS_INVALID_PARAMETER 

An invalid parameter was passed to a function.

ROCJPEG_STATUS_BAD_JPEG 

The input JPEG data is corrupted or invalid.

ROCJPEG_STATUS_JPEG_NOT_SUPPORTED 

The JPEG format is not supported.

ROCJPEG_STATUS_OUTOF_MEMORY 

Out of memory error.

ROCJPEG_STATUS_EXECUTION_FAILED 

The execution of a function failed.

ROCJPEG_STATUS_ARCH_MISMATCH 

The architecture is not supported.

ROCJPEG_STATUS_INTERNAL_ERROR 

Internal error occurred.

ROCJPEG_STATUS_IMPLEMENTATION_NOT_SUPPORTED 

The requested implementation is not supported.

ROCJPEG_STATUS_HW_JPEG_DECODER_NOT_SUPPORTED 

Hardware JPEG decoder is not supported.

ROCJPEG_STATUS_RUNTIME_ERROR 

Runtime error occurred.

ROCJPEG_STATUS_NOT_IMPLEMENTED 

The requested feature is not implemented.

ROCJPEG_STATUS_MAX_VALUE 

Maximum status code value.

Function Documentation

◆ rocJpegCreate()

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
backendThe backend to be used for JPEG decoding.
device_idThe ID of the device to be used for JPEG decoding.
handlePointer 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.

◆ rocJpegDecode()

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
handleThe rocJpegHandle representing the rocJPEG decoder instance.
jpeg_stream_handleThe rocJpegStreamHandle representing the input JPEG stream.
decode_paramsA pointer to RocJpegDecodeParams containing the decoding parameters.
destinationA pointer to RocJpegImage where the decoded image will be stored.
Returns
A RocJpegStatus indicating the success or failure of the decoding operation.

◆ rocJpegDecodeAsync()

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
handleThe rocJPEG handle.
jpeg_stream_handleThe rocJPEG stream handle.
decode_paramsThe decoding parameters.
destinationThe output image.
Returns
A RocJpegStatus indicating the success or failure of the submit operation.

◆ rocJpegDecodeBatched()

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
handleThe rocJPEG handle.
jpeg_stream_handlesAn array of rocJPEG stream handles representing the input JPEG streams.
batch_sizeThe number of JPEG streams in the batch.
decode_paramsAn array of RocJpegDecodeParams structs representing the decode parameters for the batch of JPEG images.
destinationsAn array of rocJPEG images representing the output decoded images.
Returns
The status of the JPEG decoding operation.

◆ rocJpegDecodeBatchedAsync()

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
handleThe rocJPEG handle.
jpeg_stream_handlesAn array of rocJPEG stream handles representing the input JPEG streams.
batch_sizeThe number of JPEG streams in the batch.
decode_paramsAn array of RocJpegDecodeParams structs representing the decode parameters for each image.
destinationsAn array of RocJpegImage structs representing the output decoded images.
Returns
A RocJpegStatus indicating the success or failure of the submit operation.

◆ rocJpegDecodeBatchedSync()

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
handleThe rocJPEG handle.
destinationsAn array of RocJpegImage pointers identifying the pending batch, as passed to rocJpegDecodeBatchedAsync.
batch_sizeThe number of images in the batch.
Returns
A RocJpegStatus indicating the success or failure of the sync operation.

◆ rocJpegDecodeSync()

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
handleThe rocJPEG handle.
destinationA pointer to RocJpegImage where the decoded image will be stored.
Returns
A RocJpegStatus indicating the success or failure of the sync operation.

◆ rocJpegDestroy()

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

◆ rocJpegGetErrorName()

const char *ROCDECAPI 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_statusThe RocJpegStatus for which to retrieve the error name.
Returns
A pointer to a constant character string representing the error name.

◆ rocJpegGetImageInfo()

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
handleThe handle to the RocJpegDecoder instance.
jpeg_stream_handleThe handle to the RocJpegStream instance representing the JPEG image.
num_componentsA pointer to an unsigned 8-bit integer that will store the number of components in the JPEG image.
subsamplingA pointer to a RocJpegChromaSubsampling enum that will store the chroma subsampling information.
widthsA pointer to an unsigned 32-bit integer array that will store the width of each component in the JPEG image.
heightsA 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.

◆ rocJpegStreamCreate()

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

◆ rocJpegStreamDestroy()

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

◆ rocJpegStreamParse()

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
dataThe pointer to the JPEG stream data.
lengthThe length of the JPEG stream data.
jpeg_stream_handleThe handle to the JPEG stream.
Returns
The status of the JPEG stream parsing operation.