AI/rocm-systems
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add/update comments to the code (#25)

Browse Source 
* Add/update comments to the code

* update comments

* Update comments

[ROCm/rocjpeg commit: 73c0b10f6a]
This commit is contained in:
Aryan Salmanpour
2024-05-15 13:44:51 -04:00
committed by GitHub
parent 93d163fa33
commit ab073db426
14 changed files with 2181 additions and 805 deletions
Download Patch File Download Diff File Expand all files Collapse all files
projects/rocjpeg/src/rocjpeg_api.cpp
+95 -72
View File
@@ -24,11 +24,17 @@ THE SOFTWARE.
#include "rocjpeg_api_decoder_handle.h"
#include "rocjpeg_commons.h"
/*****************************************************************************************************/
//! \fn RocJpegStatus ROCJPEGAPI rocJpegStreamCreate(RocJpegStreamHandle *jpeg_stream_handle)
//! \ingroup group_amd_rocjpeg
//! Create the rocJPEG stream parser handle. This handle is used to parse and retrieve the information from the JPEG stream.
/*****************************************************************************************************/
/**
* @brief Creates a RocJpegStreamHandle for JPEG stream processing.
*
* This function creates a RocJpegStreamHandle, which is used for processing JPEG streams.
* The created handle is assigned to the provided jpeg_stream_handle pointer.
*
* @param jpeg_stream_handle A pointer to a RocJpegStreamHandle variable that will hold the created handle.
* @return RocJpegStatus The status of the operation. Returns ROCJPEG_STATUS_SUCCESS if successful,
* ROCJPEG_STATUS_INVALID_PARAMETER if the jpeg_stream_handle pointer is nullptr,
* or ROCJPEG_STATUS_NOT_INITIALIZED if the rocJPEG stream handle failed to initialize.
*/
RocJpegStatus ROCJPEGAPI rocJpegStreamCreate(RocJpegStreamHandle *jpeg_stream_handle) {
if (jpeg_stream_handle == nullptr) {
return ROCJPEG_STATUS_INVALID_PARAMETER;
@@ -45,11 +51,20 @@ RocJpegStatus ROCJPEGAPI rocJpegStreamCreate(RocJpegStreamHandle *jpeg_stream_ha
return ROCJPEG_STATUS_SUCCESS;
}
/*****************************************************************************************************/
//! \fn RocJpegStatus ROCJPEGAPI rocJpegStreamParse(const unsigned char *data, size_t length, RocJpegStreamHandle jpeg_stream_handle)
//! \ingroup group_amd_rocjpeg
//! Parses a jpeg stream and stores the information from the stream to be used in subsequent API calls for retrieving the image information and decoding it.
/*****************************************************************************************************/
/**
* @brief Parses a JPEG stream.
*
* This function parses a JPEG stream represented by the input data and length,
* and updates the provided JPEG stream handle accordingly.
*
* @param data The pointer to the JPEG stream data.
* @param length The length of the JPEG stream data.
* @param jpeg_stream_handle The handle to the JPEG stream.
* @return The status of the JPEG stream parsing operation.
* - ROCJPEG_STATUS_SUCCESS if the parsing is successful.
* - ROCJPEG_STATUS_INVALID_PARAMETER if the input parameters are invalid.
* - ROCJPEG_STATUS_BAD_JPEG if the JPEG stream is invalid.
*/
RocJpegStatus ROCJPEGAPI rocJpegStreamParse(const unsigned char *data, size_t length, RocJpegStreamHandle jpeg_stream_handle) {
if (data == nullptr || jpeg_stream_handle == nullptr) {
return ROCJPEG_STATUS_INVALID_PARAMETER;
@@ -61,11 +76,13 @@ RocJpegStatus ROCJPEGAPI rocJpegStreamParse(const unsigned char *data, size_t le
return ROCJPEG_STATUS_SUCCESS;
}
/*****************************************************************************************************/
//! \fn RocJpegStatus ROCJPEGAPI rocJpegStreamDestroy(RocJpegStreamHandle jpeg_stream_handle)
//! \ingroup group_amd_rocjpeg
//! Release the jpeg parser object and resources.
/*****************************************************************************************************/
/**
* @brief Destroys a RocJpegStreamHandle object and releases associated resources.
*
* @param jpeg_stream_handle The handle to the RocJpegStreamHandle object to be destroyed.
* @return RocJpegStatus The status of the operation. Returns ROCJPEG_STATUS_SUCCESS if successful,
* or ROCJPEG_STATUS_INVALID_PARAMETER if the input handle is nullptr.
*/
RocJpegStatus ROCJPEGAPI rocJpegStreamDestroy(RocJpegStreamHandle jpeg_stream_handle) {
if (jpeg_stream_handle == nullptr) {
return ROCJPEG_STATUS_INVALID_PARAMETER;
@@ -75,11 +92,18 @@ RocJpegStatus ROCJPEGAPI rocJpegStreamDestroy(RocJpegStreamHandle jpeg_stream_ha
return ROCJPEG_STATUS_SUCCESS;
}
/*****************************************************************************************************/
//! \fn RocJpegStatus ROCJPEGAPI rocJpegCreate(RocJpegBackend backend, int device_id, RocJpegHandle *handle)
//! \ingroup group_amd_rocjpeg
//! Create the decoder object based on backend and device_id. A handle to the created decoder is returned
/*****************************************************************************************************/
/**
* @brief Creates a RocJpegHandle for JPEG decoding.
*
* This function creates a RocJpegHandle for JPEG decoding using the specified backend and device ID.
*
* @param backend The backend to be used for JPEG decoding.
* @param device_id The ID of the device to be used for JPEG decoding.
* @param handle Pointer to a RocJpegHandle variable to store the created handle.
* @return 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 rocJpegCreate(RocJpegBackend backend, int device_id, RocJpegHandle *handle) {
if (handle == nullptr) {
return ROCJPEG_STATUS_INVALID_PARAMETER;
@@ -95,11 +119,16 @@ RocJpegStatus ROCJPEGAPI rocJpegCreate(RocJpegBackend backend, int device_id, Ro
return static_cast<RocJpegDecoderHandle *>(rocjpeg_handle)->rocjpeg_decoder->InitializeDecoder();
}
/*****************************************************************************************************/
//! \fn RocJpegStatus ROCJPEGAPI rocJpegDestroy(RocJpegHandle handle)
//! \ingroup group_amd_rocjpeg
//! Release the decoder object and resources.
/*****************************************************************************************************/
/**
* @brief 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.
*
* @param handle The handle to the RocJpegHandle object to be destroyed.
* @return 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 rocJpegDestroy(RocJpegHandle handle) {
if (handle == nullptr) {
return ROCJPEG_STATUS_INVALID_PARAMETER;
@@ -109,12 +138,25 @@ RocJpegStatus ROCJPEGAPI rocJpegDestroy(RocJpegHandle handle) {
return ROCJPEG_STATUS_SUCCESS;
}
/*****************************************************************************************************/
//! \fn RocJpegStatus ROCJPEGAPI rocJpegGetImageInfo(RocJpegHandle handle, RocJpegStreamHandle jpeg_stream_handle,
//! int *num_components, RocJpegChromaSubsampling *subsampling, int *widths, int *heights)
//! \ingroup group_amd_rocjpeg
//! Retrieve the image info, including channel, width and height of each component, and chroma subsampling.
/*****************************************************************************************************/
/**
* @brief 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`.
*
* @param handle The handle to the RocJpegDecoder instance.
* @param jpeg_stream_handle The handle to the RocJpegStream instance representing the JPEG image.
* @param num_components A pointer to an unsigned 8-bit integer that will store the number of components in the JPEG image.
* @param subsampling A pointer to a RocJpegChromaSubsampling enum that will store the chroma subsampling information.
* @param widths A pointer to an unsigned 32-bit integer array that will store the width of each component in the JPEG image.
* @param heights A pointer to an unsigned 32-bit integer array that will store the height of each component in the JPEG image.
*
* @return 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 rocJpegGetImageInfo(RocJpegHandle handle, RocJpegStreamHandle jpeg_stream_handle, uint8_t *num_components,
RocJpegChromaSubsampling *subsampling, uint32_t *widths, uint32_t *heights) {
if (handle == nullptr || num_components == nullptr ||
@@ -134,16 +176,19 @@ RocJpegStatus ROCJPEGAPI rocJpegGetImageInfo(RocJpegHandle handle, RocJpegStream
return rocjpeg_status;
}
/*****************************************************************************************************/
//! \fn RocJpegStatus ROCJPEGAPI rocJpegDecode(RocJpegHandle handle, RocJpegStreamHandle jpeg_stream_handle, const RocJpegDecodeParams *decode_params, RocJpegImage *destination);
//! \ingroup group_amd_rocjpeg
//! Decodes single image based on the backend used to create the rocJpeg handle in rocJpegCreate API.
//! Destination buffers should be large enough to be able to store output of specified format.
//! These buffers should be pre-allocted by the user in the device memories.
//! For each color plane (channel) sizes could be retrieved for image using rocJpegGetImageInfo API
//! and minimum required memory buffer for each plane is plane_height * plane_pitch where plane_pitch >= plane_width for
//! planar output formats and plane_pitch >= plane_width * num_components for interleaved output format.
/*****************************************************************************************************/
/**
* @brief 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.
*
* @param handle The rocJpegHandle representing the rocJPEG decoder instance.
* @param jpeg_stream_handle The rocJpegStreamHandle representing the input JPEG stream.
* @param decode_params A pointer to RocJpegDecodeParams containing the decoding parameters.
* @param destination A pointer to RocJpegImage where the decoded image will be stored.
* @return A RocJpegStatus indicating the success or failure of the decoding operation.
*/
RocJpegStatus ROCJPEGAPI rocJpegDecode(RocJpegHandle handle, RocJpegStreamHandle jpeg_stream_handle, const RocJpegDecodeParams *decode_params,
RocJpegImage *destination) {
@@ -163,11 +208,14 @@ RocJpegStatus ROCJPEGAPI rocJpegDecode(RocJpegHandle handle, RocJpegStreamHandle
return rocjpeg_status;
}
/*****************************************************************************************************/
//! \fn extern const char* ROCDECAPI rocJpegGetErrorName(RocJpegStatus rocjpeg_status);
//! \ingroup group_amd_rocjpeg
//! Return name of the specified error code in text form.
/*****************************************************************************************************/
/**
* @brief Returns the error name corresponding to the given RocJpegStatus.
*
* This function takes a RocJpegStatus enum value and returns the corresponding error name as a string.
*
* @param rocjpeg_status The RocJpegStatus enum value.
* @return The error name as a string.
*/
extern const char* ROCJPEGAPI rocJpegGetErrorName(RocJpegStatus rocjpeg_status) {
switch (rocjpeg_status) {
case ROCJPEG_STATUS_SUCCESS:
@@ -199,29 +247,4 @@ extern const char* ROCJPEGAPI rocJpegGetErrorName(RocJpegStatus rocjpeg_status)
default:
return "UNKNOWN_ERROR";
}
}
/*****************************************************************************************************/
//! \fn RocJpegStatus ROCJPEGAPI rocJpegDecodeBatchedInitialize(RocJpegHandle handle, int batch_size, int max_cpu_threads, RocJpegOutputFormat output_format);
//! \ingroup group_amd_rocjpeg
//! Resets and initializes batch decoder for working on the batches of specified size
//! Should be called once for decoding batches of this specific size, also use to reset failed batches
//! \return ROCJPEG_STATUS_SUCCESS if successful
/*****************************************************************************************************/
RocJpegStatus ROCJPEGAPI rocJpegDecodeBatchedInitialize(RocJpegHandle handle, int batch_size, int max_cpu_threads, RocJpegOutputFormat output_format) {
return ROCJPEG_STATUS_NOT_IMPLEMENTED;
}
/*****************************************************************************************************/
//! \fn RocJpegStatus ROCJPEGAPI rocJpegDecodeBatched(RocJpegHandle handle, const uint8_t *data, const size_t *lengths, RocJpegImage *destinations, hipStream_t stream);
//! \ingroup group_amd_rocjpeg
//! Decodes batch of images. Output buffers should be large enough to be able to store
//! outputs of specified format, see single image decoding description for details. Call to
//! rocjpegDecodeBatchedInitialize() is required prior to this call, batch size is expected to be the same as
//! parameter to this batch initialization function.
//! \return ROCJPEG_STATUS_SUCCESS if successful
/*****************************************************************************************************/
RocJpegStatus ROCJPEGAPI rocJpegDecodeBatched(RocJpegHandle handle, const uint8_t *data, const size_t *lengths, RocJpegImage *destinations) {
return ROCJPEG_STATUS_NOT_IMPLEMENTED;
}
}