nvtiffDecode()
"""""""""""""""

Decodes image data on the GPU which is specified in :code:`tiff_stream`.
Each image in the TIFF file is copied into the respective buffer pointed to by "imageOut_d". This function is fully asynchronous.

When the photometric interpretation of an image is :code:`NVTIFF_PHOTOMETRIC_PALETTE` or :code:`NVTIFF_PHOTOMETRIC_YCBCR`, the decode output will be converted to RGB.

For images with multiple samples, the decode output will always be in planar contiguous format.

**Signature:**

.. code-block:: cpp

    nvtiffStatus_t nvtiffDecode(nvtiffStream_t tiff_stream, 
                        nvtiffDecoder_t nvtiff_decoder,
                        unsigned char **image_out,
                        cudaStream_t cuda_stream);


**Parameters:**

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

  * - Parameter
    - Input/Output
    - Memory
    - Description
  * - nvtiffStream_t tiff_stream
    - Input
    - Host
    - :code:`tiff_stream` handle in which the TIFF file has been read.
  * - nvtiffDecoder_t nvtiff_decoder
    - Input
    - Host
    - Decoder handle
  * - unsigned char \*\*imageOut_d
    - Output
    - Host
    - Host array (of size num_images in the TIFF file) of pointers to device buffers.Each device buffer should have a size of image_width * image height * bitdepth * samples_per_pixel
      When the photometric interpretation for an image is palette mode, the device buffer should have a size of image_width * image height * 3 * 2
  * - cudaStream_t cuda_stream
    - Input
    - Host
    - :code:`cuda_stream` where all the GPU work will be submitted

**Returns:**

:code:`nvtiffStatus_t` - An error code as specified in :ref:`nvtiffapireturncodesv2-label`



nvtiffDecodeRange()
"""""""""""""""""""

This function is similar to :code:`nvtiffDecode()`. It allows the user to specify a range of images to be decoded 
(instead of decoding all images in the file).

When the photometric interpretation of an image is :code:`NVTIFF_PHOTOMETRIC_PALETTE` or :code:`NVTIFF_PHOTOMETRIC_YCBCR`, the decode output will be converted to RGB.

For images with multiple samples, the decode output will always be in planar contiguous format.



**Signature:**

.. code-block:: cpp

    nvtiffStatus_t NVTIFFAPI nvtiffDecodeRange(nvtiffStream_t tiff_stream, 
                    nvtiffDecoder_t decoder,
                    unsigned int sub_file_start, 
                    unsigned int sub_file_num,
                    unsigned char **image_out,
                    cudaStream_t cuda_stream);


**Parameters:**

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

  * - Parameter
    - Input/Output
    - Memory
    - Description
  * - nvtiffStream_t tiff_stream
    - Input
    - Host
    -  :code:`tiff_stream` handle in which the TIFF file has been read.
  * - nvtiffDecoder_t nvtiff_decoder
    - Input
    - Host
    - Decoder handle
  * - unsigned int sub_file_start
    - Input
    - Host
    - Index of the first image to decode, in [0, tiff_info.num_sub_files).
  * - unsigned int sub_file_num
    - Input
    - Host
    - Number of images to decode starting from :code:`sub_file_start`, in (0, tiff_info.num_sub_files]
  * - unsigned char \*\*imageOut_d
    - Output
    - Host
    - Host array (of size num_images in the TIFF file) of pointers to device buffers.Each device buffer should have a size of image_width * image height * bitdepth * samples_per_pixel
      When the photometric interpretation for an image is palette mode, the device buffer should have a size of image_width * image height * 3 * 2
  * - cudaStream_t cuda_stream
    - Input
    - Host
    - :code:`cuda_stream` where all the GPU work will be submitted

**Returns:**

:code:`nvtiffStatus_t` - An error code as specified in :ref:`nvtiffapireturncodesv2-label`



.. _nvtiffdecodeimage-label:

nvtiffDecodeImage()
""""""""""""""""""""

Decodes a single image on the GPU which is specified in :code:`tiff_stream`. The function is asynchronous with respect to the host.
Additional control of the decode output is possible using an instance :code:`nvtiffDecodeParams_t`.

**Signature:**

.. code-block:: cpp

    nvtiffStatus_t nvtiffDecodeImage(nvtiffStream_t tiff_stream,
          nvtiffDecoder_t decoder, 
          nvtiffDecodeParams_t params,
          uint32_t image_id,
          void* image_out_d, 
          cudaStream_t cuda_stream);


**Parameters:**

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

  * - Parameter
    - Input/Output
    - Memory
    - Description
  * - nvtiffStream_t tiff_stream
    - Input
    - Host
    -  :code:`tiff_stream` handle in which the TIFF file has been read.
  * - nvtiffDecoder_t nvtiff_decoder
    - Input
    - Host
    - Decoder handle
  * - nvtiffDecodeParams_t params
    - Input
    - Host
    - Used to control the decoded output (like specifying ROI, output format).
  * - uint32_t image_id
    - Input
    - Host
    - Corresponds to the image index(IFDs) within a multi images TIFF file. Cannot exceed the total number of images in a TIFF file.
  * - void* image_out_d
    - Output
    - Device
    - Decode output buffer. For allocation size, see :ref:`nvtiffdecodeparamssetoutputformat-label`
  * - cudaStream_t cuda_stream
    - Input
    - Host
    - :code:`cuda_stream` where all the GPU work will be submitted


**Returns:**

:code:`nvtiffStatus_t` - An error code as specified in :ref:`nvtiffapireturncodesv2-label`



nvtiffDecodeCheckSupported()
""""""""""""""""""""""""""""

Helps determine whether any given image within a tiff file specified by :code:`tiff_stream` can be decoded by nvTIFF.
Returns :code:`NVTIFF_STATUS_SUCCESS`, if the image is supported

**Signature:**

.. code-block:: cpp

    nvtiffStatus_t nvtiffDecodeCheckSupported(nvtiffStream_t tiff_stream,
          nvtiffDecoder_t decoder, 
          nvtiffDecodeParams_t params, 
          uint32_t image_id);

**Parameters:**

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

  * - Parameter
    - Input/Output
    - Memory
    - Description
  * - nvtiffStream_t tiff_stream
    - Input
    - Host
    -  :code:`tiff_stream` handle in which the TIFF file has been read.
  * - nvtiffDecoder_t nvtiff_decoder
    - Input
    - Host
    - Decoder handle
  * - nvtiffDecodeParams_t params
    - Input
    - Host
    - Used to control the decoded output (like specifying ROI, output format).
  * - uint32_t image_id
    - Input
    - Host
    - Corresponds to the image index(IFDs) within a multi images TIFF file. Cannot exceed the total number of images in a TIFF file.


**Returns:**

:code:`nvtiffStatus_t` - An error code as specified in :ref:`nvtiffapireturncodesv2-label`