.. |br| raw:: html

  <br />

.. _nvjpeg2kstreamparse-label:

nvjpeg2kStreamParse()
*********************
This function is the first step in the decoding of a JPEG2000 bitstream. It accepts the bitstream buffer on host memory as input
and parses the JPEG2000 header information. The parsed information is stored in the :code:`nvjpeg2kStream_t` handle and can be
retrieved by the APIs documented in this section.

**Signature**:

.. code-block:: cpp

    nvjpeg2kStatus_t nvjpeg2kStreamParse(nvjpeg2kHandle_t handle,
            const unsigned char *data, 
            size_t length, 
            int save_metadata,
            int save_stream,
            nvjpeg2kStream_t *stream_handle);

**Parameters:**

.. list-table::
  :header-rows: 1
  :widths: 15 10 10 20

  * - Parameter
    - Input/Output
    - Memory
    - Description
  * - nvjpeg2kHandle_t handle
    - Input
    - Host
    - library handle
  * - const unsigned char *data
    - Input
    - Host
    - bitstream buffer
  * - size_t length
    - Input
    - Host
    - bitstream size in bytes
  * - int save_metadata
    - Input
    - Host
    - Set to 0. Added for future use
  * - int save_stream
    - Input
    - Host
    - Set to 0. Added for future use
  * - nvjpeg2kStream_t *stream_handle
    - Input
    - Host
    - bitstream handle

**Returns:**

:code:`nvjpeg2kStatus_t` - An error code as specified in :ref:`nvjpeg2kapireturncodes-label`

.. _nvjpeg2kstreamgetimage-label:

nvjpeg2kStreamGetImageInfo()
****************************
Retrieves the image information defined in :ref:`nvjpeg2kImageInfo_t<nvjpeg2kimageinformation-label>`. 
This information is useful in allocating output buffers on device memory.

**Signature**:

.. code-block:: cpp

    nvjpeg2kStatus_t nvjpeg2kStreamGetImageInfo(nvjpeg2kStream_t stream_handle,
            nvjpeg2kImageInfo_t* image_info);

**Parameters:**

.. list-table::
  :header-rows: 1
  :widths: 15 10 10 20

  * - Parameter
    - Input/Output
    - Memory
    - Description
  * - nvjpeg2kStream_t *stream_handle
    - Input
    - Host
    - bitstream handle
  * - nvjpeg2kImageInfo_t* image_info
    - Input/Output
    - Host
    - Pointer to nvjpeg2kImageInfo_t

**Returns:**

:code:`nvjpeg2kStatus_t` - An error code as specified in :ref:`nvjpeg2kapireturncodes-label`

nvjpeg2kStreamGetImageComponentInfo()
**************************************
Retrieves the component level information defined in :ref:`nvjpeg2kImageComponentInfo_t<nvjpeg2kcomponeninfo-label>`
This information can be used in allocating output buffers on device memory. Component level information is useful 
when the dimensions vary across components.

**Signature:**

.. code-block:: cpp

    nvjpeg2kStatus_t nvjpeg2kStreamGetImageComponentInfo(nvjpeg2kStream_t stream_handle,
            nvjpeg2kImageComponentInfo_t* component_info,
            uint32_t component_id);

**Parameters:**

.. list-table::
  :header-rows: 1
  :widths: 15 10 10 20

  * - Parameter
    - Input/Output
    - Memory
    - Description
  * - nvjpeg2kStream_t stream_handle
    - Input
    - Host
    - bitstream handle
  * - nvjpeg2kImageComponentInfo_t* component_info
    - Input/Output
    - Host
    - Pointer to nvjpeg2kImageInfo_t
  * - uint32_t component_id
    - Input
    - Host
    - Component index

**Returns:**

:code:`nvjpeg2kStatus_t` - An error code as specified in :ref:`nvjpeg2kapireturncodes-label`

.. _nvjpeg2kstreamgetresolutionsintile-label:

nvjpeg2kStreamGetResolutionsInTile()
*************************************

Retrieves the number of resolutions present in a tile. The number of resolutions is defined as: numResolutions = numWaveletDecompositionLevels + 1. Tiles in jpeg2000 are indexed in raster scan order. :ref:`nvjpeg2kStreamGetImageInfo<nvjpeg2kstreamgetimage-label>` retrieves the number of tiles present along both the x and y directions. 
For tile coordinates tile_x, tile_y: tile_id  = tile_y * num_tiles_x + tile_x, where tile_x and tile_y are in tile units.

**Signature:**

.. code-block:: cpp

    nvjpeg2kStatus_t nvjpeg2kStreamGetResolutionsInTile(
            nvjpeg2kStream_t stream_handle, 
            uint32_t tile_id,
            uint32_t* num_res);

**Parameters:**

.. list-table::
  :header-rows: 1
  :widths: 15 10 10 20

  * - Parameter
    - Input/Output
    - Memory
    - Description
  * - nvjpeg2kStream_t stream_handle
    - Input
    - Host
    - bitstream handle
  * - uint32_t tile_id
    - Input
    - Host
    - Raster scan based tile index
  * - uint32_t* num_res
    - Output
    - Host
    - Number of resolutions present in the tile

**Returns:**

:code:`nvjpeg2kStatus_t` - An error code as specified in :ref:`nvjpeg2kapireturncodes-label`

nvjpeg2kStreamGetTileComponentDim()
************************************

Retrieves the tile width and tile height for a tile component. This function is useful when the tile dimensions in
:ref:`nvjpeg2kimageinformation-label` are not a multiple of the image dimensions.

**Signature:**

.. code-block:: cpp

    nvjpeg2kStatus_t nvjpeg2kStreamGetTileComponentDim(
            nvjpeg2kStream_t stream_handle, 
            uint32_t component_id,
            uint32_t tile_id, 
            uint32_t* tile_width, 
            uint32_t* tile_height);


**Parameters:**

**Returns:**

:code:`nvjpeg2kStatus_t` - An error code as specified in :ref:`nvjpeg2kapireturncodes-label`

nvjpeg2kStreamGetResolutionComponentDim()
*******************************************
Retrieves the dimensions at a resolution level for a tile component. The formula is as follows:

:code:`res_scale = 1 << (num_resolutions - res_level - 1)` |br|
:code:`res_width   = (tile_width  + res_scale - 1) >> res_scale` |br|
:code:`res_height  = (tile_height + res_scale - 1) >> res_scale` |br|


**Signature:**

.. code-block:: cpp

    nvjpeg2kStatus_t nvjpeg2kStreamGetResolutionComponentDim(
            nvjpeg2kStream_t   stream_handle, 
            uint32_t component_id,
            uint32_t tile_id,
            uint32_t res_level,
            uint32_t* res_width,
            uint32_t* res_height);


**Returns:**

:code:`nvjpeg2kStatus_t` - An error code as specified in :ref:`nvjpeg2kapireturncodes-label`

nvjpeg2kStreamGetColorSpace()
*******************************
Retrieves color space information from a parsed JP2 file. For a jpeg2000 codestream (.j2k file), this function will retrieve 
:code:`NVJPEG2K_COLORSPACE_UNKNOWN` since color space information is not available.

**Signature:**

.. code-block:: cpp

    nvjpeg2kStatus_t nvjpeg2kStreamGetColorSpace(nvjpeg2kStream_t stream_handle,
            nvjpeg2kColorSpace_t* color_space);

**Parameters:**

.. list-table::
  :header-rows: 1
  :widths: 15 10 10 20

  * - Parameter
    - Input/Output
    - Memory
    - Description
  * - nvjpeg2kStream_t stream_handle
    - Input
    - Host
    - bitstream handle
  * - nvjpeg2kColorSpace_t* color_space
    - Input/Output
    - Host
    - Color space of the parsed image

**Returns:**

:code:`nvjpeg2kStatus_t` - An error code as specified in :ref:`nvjpeg2kapireturncodes-label`