|
| 1 | +.. meta:: |
| 2 | + :description: decoding a jpeg stream with rocJPEG |
| 3 | + :keywords: rocJPEG, ROCm, API, documentation, decoding, jpeg |
| 4 | + |
| 5 | + |
| 6 | +******************************************************************** |
| 7 | +Decoding a JPEG stream with rocJPEG |
| 8 | +******************************************************************** |
| 9 | + |
| 10 | +rocJPEG provides two functions, ``rocJpegDecode()`` and ``rocJpegDecodeBatched()``, for decoding JPEG image. |
| 11 | + |
| 12 | +.. code:: cpp |
| 13 | +
|
| 14 | + RocJpegStatus rocJpegDecode( |
| 15 | + RocJpegHandle handle, |
| 16 | + RocJpegStreamHandle jpeg_stream_handle, |
| 17 | + const RocJpegDecodeParams *decode_params, |
| 18 | + RocJpegImage *destination); |
| 19 | +
|
| 20 | + RocJpegStatus rocJpegDecodeBatched( |
| 21 | + RocJpegHandle handle, |
| 22 | + RocJpegStreamHandle *jpeg_stream_handles, |
| 23 | + int batch_size, |
| 24 | + const RocJpegDecodeParams *decode_params, |
| 25 | + RocJpegImage *destinations); |
| 26 | +
|
| 27 | +``rocJpegDecode()`` is used for decoding single images and ``rocJpegDecodeBatched()`` is used for decoding batches of JPEG images. ``rocJpegDecode()`` and ``rocJpegDecodeBatched()`` copy decoded images to a ``RocJpegImage`` struct. |
| 28 | + |
| 29 | +.. code:: cpp |
| 30 | +
|
| 31 | + typedef struct { |
| 32 | + uint8_t* channel[ROCJPEG_MAX_COMPONENT]; |
| 33 | + uint32_t pitch[ROCJPEG_MAX_COMPONENT]; |
| 34 | + } RocJpegImage; |
| 35 | +
|
| 36 | +``rocJpegDecodeBatched()`` behaves the same way as ``rocJpegDecode()`` except that ``rocJpegDecodeBatched()`` takes an array of stream handles and an array of decode parameters as input, decodes the batch of JPEG images, and stores the decoded images in an output array of destination images. |
| 37 | + |
| 38 | +``rocJpegDecodeBatched()`` is suited for use on ASICs with multiple JPEG cores and is more efficient than multiple calls to ``rocJpegDecode()``. Choosing a batch size that is a multiple of available JPEG cores is recommended. |
| 39 | + |
| 40 | +Memory has to be allocate to each channel of ``RocJpegImage``, including every channel of every ``RocJpegImage`` in the destination image array passed to ``rocJpegDecodeBatched()``. Use |hipmalloc|_ to allocate memory. |
| 41 | + |
| 42 | +.. |hipmalloc| replace:: ``hipMalloc()`` |
| 43 | +.. _hipmalloc: https://rocm.docs.amd.com/projects/HIP/en/latest/how-to/virtual_memory.html |
| 44 | + |
| 45 | +For example: |
| 46 | + |
| 47 | +.. code:: cpp |
| 48 | +
|
| 49 | + // Allocate device memory for the decoded output image |
| 50 | + RocJpegImage output_image = {}; |
| 51 | + RocJpegDecodeParams decode_params = {}; |
| 52 | + decode_params.output_format = ROCJPEG_OUTPUT_NATIVE; |
| 53 | +
|
| 54 | + // For this sample assuming the input image has a YUV420 chroma subsampling. |
| 55 | + // For YUV420 subsampling, the native decoded output image would be NV12 (i.e., the rocJPegDecode API copies Y to first channel and UV (interleaved) to second channel of RocJpegImage) |
| 56 | + output_image.pitch[1] = output_image.pitch[0] = widths[0]; |
| 57 | + hipError_t hip_status; |
| 58 | + hip_status = hipMalloc(&output_image.channel[0], output_image.pitch[0] * heights[0]); |
| 59 | + if (hip_status != hipSuccess) { |
| 60 | + std::cerr << "Failed to allocate device memory for the first channel" << std::endl; |
| 61 | + rocJpegStreamDestroy(rocjpeg_stream_handle); |
| 62 | + rocJpegDestroy(handle); |
| 63 | + return EXIT_FAILURE; |
| 64 | + } |
| 65 | +
|
| 66 | + hip_status = hipMalloc(&output_image.channel[1], output_image.pitch[1] * (heights[0] >> 1)); |
| 67 | + if (hip_status != hipSuccess) { |
| 68 | + std::cerr << "Failed to allocate device memory for the second channel" << std::endl; |
| 69 | + hipFree((void *)output_image.channel[0]); |
| 70 | + rocJpegStreamDestroy(rocjpeg_stream_handle); |
| 71 | + rocJpegDestroy(handle); |
| 72 | + return EXIT_FAILURE; |
| 73 | + } |
| 74 | +
|
| 75 | + // Decode the JPEG stream |
| 76 | + status = rocJpegDecode(handle, rocjpeg_stream_handle, &decode_params, &output_image); |
| 77 | + if (status != ROCJPEG_STATUS_SUCCESS) { |
| 78 | + std::cerr << "Failed to decode JPEG stream with error code: " << rocJpegGetErrorName(status) << std::endl; |
| 79 | + hipFree((void *)output_image.channel[0]); |
| 80 | + hipFree((void *)output_image.channel[1]); |
| 81 | + rocJpegStreamDestroy(rocjpeg_stream_handle); |
| 82 | + rocJpegDestroy(handle); |
| 83 | + return EXIT_FAILURE; |
| 84 | + } |
| 85 | +
|
| 86 | +
|
| 87 | +The behaviors of ``rocJpegDecode()`` and ``rocJpegDecodeBatched()`` depend on ``RocJpegOutputFormat`` and ``RocJpegDecodeParms``. |
| 88 | + |
| 89 | +``RocJpegOutputFormat`` specifies the output format to be used to decode the JPEG image. It can be set to any one of these output formats: |
| 90 | + |
| 91 | +.. csv-table:: |
| 92 | + :header: "Output format", "Meaning" |
| 93 | + |
| 94 | + "ROCJPEG_OUTPUT_NATIVE", "Return native unchanged decoded YUV image from the VCN JPEG deocder." |
| 95 | + "ROCJPEG_OUTPUT_YUV_PLANAR", "Return in the YUV planar format." |
| 96 | + "ROCJPEG_OUTPUT_Y", "Return the Y component only." |
| 97 | + "ROCJPEG_OUTPUT_RGB", "Convert to interleaved RGB." |
| 98 | + "ROCJPEG_OUTPUT_RGB_PLANAR", "Convert to planar RGB." |
| 99 | + |
| 100 | +``RocJpegOutputFormat`` is a member of the ``RocJpegDecodeParams`` struct. ``RocJpegDecodeParams`` defines the output format, crop rectangle, and target dimensions to use when decoding the image. |
| 101 | + |
| 102 | +.. code:: cpp |
| 103 | +
|
| 104 | + typedef struct { |
| 105 | + RocJpegOutputFormat output_format; /**< Output data format. See RocJpegOutputFormat for description. */ |
| 106 | + struct { |
| 107 | + int16_t left; /**< Left coordinate of the crop rectangle. */ |
| 108 | + int16_t top; /**< Top coordinate of the crop rectangle. */ |
| 109 | + int16_t right; /**< Right coordinate of the crop rectangle. */ |
| 110 | + int16_t bottom; /**< Bottom coordinate of the crop rectangle. */ |
| 111 | + } crop_rectangle; /**< Defines the region of interest (ROI) to be copied into the RocJpegImage output buffers. */ |
| 112 | + struct { |
| 113 | + uint32_t width; /**< Target width of the picture to be resized. */ |
| 114 | + uint32_t height; /**< Target height of the picture to be resized. */ |
| 115 | + } target_dimension; /**< (future use) Defines the target width and height of the picture to be resized. Both should be even. |
| 116 | + If specified, allocate the RocJpegImage buffers based on these dimensions. */ |
| 117 | + } RocJpegDecodeParams; |
| 118 | +
|
| 119 | +
|
| 120 | +For example, consider a situation where ``RocJpegOutputFormat`` is set to ``ROCJPEG_OUTPUT_NATIVE``. Based on the chroma subsampling of the input image, ``rocJpegDecode()`` does one of the following: |
| 121 | + |
| 122 | +* For ``ROCJPEG_CSS_444`` and ``ROCJPEG_CSS_440``: writes Y, U, and V to the first, second, and third channels of ``RocJpegImage``. |
| 123 | +* For ``ROCJPEG_CSS_422``: writes YUYV (packed) to the first channel of ``RocJpegImage``. |
| 124 | +* For ``ROCJPEG_CSS_420``: writes Y to the first channel and UV (interleaved) to the second channel of ``RocJpegImage``. |
| 125 | +* For ``ROCJPEG_CSS_400``: writes Y to the first channel of ``RocJpegImage``. |
| 126 | + |
| 127 | +If ``RocJpegOutputFormat`` is set to ``ROCJPEG_OUTPUT_Y`` or ``ROCJPEG_OUTPUT_RGB``, then ``rocJpegDecode()`` copies the output to the first channel of ``RocJpegImage``. |
| 128 | + |
| 129 | +If ``RocJpegOutputFormat`` is set to ``ROCJPEG_OUTPUT_YUV_PLANAR`` or ``ROCJPEG_OUTPUT_RGB_PLANAR``, the data is written to the corresponding channels of the ``RocJpegImage`` destination structure. |
| 130 | + |
| 131 | +The destination images must be large enough to store the output. |
| 132 | + |
| 133 | +Use |rocjpegimageinfo|_ to extract information and calculate the required memory sizes for the destination image following these guidelines:. |
| 134 | + |
| 135 | +.. |rocjpegimageinfo| replace:: ``rocJpegGetImageInfo()`` |
| 136 | +.. _rocjpegimageinfo: ./rocjpeg-retrieve-image-info.html |
| 137 | + |
| 138 | +.. csv-table:: |
| 139 | + :header: "Output format", "Chroma subsampling", "Minimum size of destination.pitch[c]", "Minimum size of destination.channel[c]" |
| 140 | + |
| 141 | + "ROCJPEG_OUTPUT_NATIVE", "ROCJPEG_CSS_444", "destination.pitch[c] = widths[c] for c = 0, 1, 2", "destination.channel[c] = destination.pitch[c] * heights[0] for c = 0, 1, 2" |
| 142 | + "ROCJPEG_OUTPUT_NATIVE", "ROCJPEG_CSS_440", "destination.pitch[c] = widths[c] for c = 0, 1, 2", "destination.channel[0] = destination.pitch[0] * heights[0], destination.channel[c] = destination.pitch[c] * heights[0] / 2 for c = 1, 2" |
| 143 | + "ROCJPEG_OUTPUT_NATIVE", "ROCJPEG_CSS_422", "destination.pitch[0] = widths[0] * 2", "destination.channel[0] = destination.pitch[0] * heights[0]" |
| 144 | + "ROCJPEG_OUTPUT_NATIVE", "ROCJPEG_CSS_420", "destination.pitch[1] = destination.pitch[0] = widths[0]", "destination.channel[0] = destination.pitch[0] * heights[0], destination.channel[1] = destination.pitch[1] * (heights[0] >> 1)" |
| 145 | + "ROCJPEG_OUTPUT_NATIVE", "ROCJPEG_CSS_400", "destination.pitch[0] = widths[0]", "destination.channel[0] = destination.pitch[0] * heights[0]" |
| 146 | + "ROCJPEG_OUTPUT_YUV_PLANAR", "ROCJPEG_CSS_444, ROCJPEG_CSS_440, ROCJPEG_CSS_422, ROCJPEG_CSS_420", "destination.pitch[c] = widths[c] for c = 0, 1, 2", "destination.channel[c] = destination.pitch[c] * heights[c] for c = 0, 1, 2" |
| 147 | + "ROCJPEG_OUTPUT_YUV_PLANAR", "ROCJPEG_CSS_400", "destination.pitch[0] = widths[0]", "destination.channel[0] = destination.pitch[0] * heights[0]" |
| 148 | + "ROCJPEG_OUTPUT_Y", "Any of the supported chroma subsampling", "destination.pitch[0] = widths[0]", "destination.channel[0] = destination.pitch[0] * heights[0]" |
| 149 | + "ROCJPEG_OUTPUT_RGB", "Any of the supported chroma subsampling", "destination.pitch[0] = widths[0] * 3", "destination.channel[0] = destination.pitch[0] * heights[0]" |
| 150 | + "ROCJPEG_OUTPUT_RGB_PLANAR", "Any of the supported chroma subsampling", "destination.pitch[c] = widths[c] for c = 0, 1, 2", "destination.channel[c] = destination.pitch[c] * heights[c] for c = 0, 1, 2" |
| 151 | + |
0 commit comments