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

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

rocJPEG: /home/docs/checkouts/readthedocs.org/user_builds/advanced-micro-devices-rocjpeg/checkouts/docs-6.3.0/api/rocjpeg.h File Reference

api

The AMD rocJPEG Library. More...

#include "hip/hip_runtime.h"
#include "rocjpeg_version.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 }
	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...

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.

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

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.

◆ 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

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.

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

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	The decode parameters for the JPEG decoding process.
destinations	An array of rocJPEG images representing the output decoded images.

Returns: The status of the JPEG decoding 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

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.

◆ 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_status The 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

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.

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

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

◆ 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

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.

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

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

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ RocJpegHandle

◆ RocJpegStreamHandle

Enumeration Type Documentation

◆ RocJpegBackend

◆ RocJpegChromaSubsampling

◆ RocJpegOutputFormat

◆ RocJpegStatus

Function Documentation

◆ rocJpegCreate()

◆ rocJpegDecode()

◆ rocJpegDecodeBatched()

◆ rocJpegDestroy()

◆ rocJpegGetErrorName()

◆ rocJpegGetImageInfo()

◆ rocJpegStreamCreate()

◆ rocJpegStreamDestroy()

◆ rocJpegStreamParse()