API Reference

Decoding API Reference

Note

The APIs in this section are deprecated from v 0.3.0

nvTiffOpen()

Open a TIFF file and returns a pointer to a nvTiffFile_t object containing the file data.

Signature:

nvTiffFile_t NVTIFFAPI *nvTiffOpen(int dev,
                                   const char *fname,
                                   int hostMemType=NVTIFF_MEM_REG);

Parameters:

Parameter

Input/Output

Memory

Description

int dev

Input

device to use for CUDA calls

const char *fname

Input

Host

path to TIFF file to open.

int hostMemType=NVTIFF_MEM_REG

Input

specifies whether pinned or pageable memory should be used for the buffer allocated to read the content of the TIFF file “fname”. Possible values are NVTIFF_MEM_PIN or NVTIFF_MEM_REG. If pageable memory is used, then the file content is also copied in a device buffer before the function returns. In case of pinned memory instead, no Host2Device copy is performed.

nvTiffClose()

Closes an opened TIFF file read into a nvTiffFile_t object, freeing all the allocated memory (on both the host and the device).

Signature:

void nvTiffClose(nvTiffFile_t *tiffFile);

Parameters:

Parameter

Input/Output

Memory

Description

nvTiffFile_t *tiffFile

Input

Closes an opened TIFF file read into a nvTiffFile_t object

nvTiffH2DAsync()

Copies the file data read by nvTiffOpen() from the internal host buffer to the internal device buffer.

This function is fully asynchronous.

This function is useful when nvTiffOpen() is called withhostMemType=NVTIFF_MEM_PIN in order to overlap the copy of the data with something else before calling the decoding functions nvTiffDecode() or nvTiffDecodeRange(). Please note that in case the file buffer is allocated with pinned memory, if this function is not called, then the decode functions will directly read the pinned host buffer via zero-copy.

This function as no effect in case nvTiffOpen() is called with hostMemType=NVTIFF_MEM_REG.

Signature:

void NVTIFFAPI nvTiffH2DAsync(nvTiffFile_t *tiffFile,
                              cudaStream_t stream=0);

Parameters:

Parameter

Input/Output

Memory

Description

nvTiffFile_t *tiffFile

Input

nvtiff file

nvTiffDecode()

Perform the decoding of the image data on the GPU specified in “tiffFile” using a specified stream. Each image in the TIFF file is copied into the respective buffer pointed to by “imageOut_d”. This function is fully asynchronous.

Signature:

int nvTiffDecode(nvTiffFile_t *tiffFile,
                 unsigned char **imageOut_d,
                 cudaStream_t stream=0);

Parameters:

Parameter

Input/Output

Memory

Description

nvTiffFile_t *tiffFile

Input

The nvTiffFile_t object in which the TIFF file has been read.

unsigned char **imageOut_d

Output

Host

host array (of size tiffData->nSubFiles) of pointers to device buffers. Each device buffer is expected to have size at least: tiffData->subFiles[0].nrow * tiffData->subFiles[0].ncol * (tiffData->subFiles[0].bitsPerPixel/8)

cudaStream_t stream

Input

the stream to use for the kernel launches.

Returns:

NVTIFF_DECODE_SUCCESS - on success.

NVTIFF_DECODE_INVALID_CTX - if tiffFile is invalid.

nvTiffDecodeRange()

This function is similar to nvTiffDecode() with the difference that it allows to specify a range of images to be decoded (instead of decoding all images in the file).

Signature:

int nvTiffDecodeRange(nvTiffFile_t *tiffFile,
                      unsigned int subFileStart,
                      unsigned int subFileNum,
                      unsigned char **imageOut_d,
                      cudaStream_t stream=0);

Parameters:

Parameter

Input/Output

Memory

Description

nvTiffFile_t *tiffFile

Input

The nvTiffFile_t object in which the TIFF file has been read.

unsigned int subFileStart

Input

index of the first image to decode, in [0, tiffData->nSubFiles).

unsigned int subFileNum

Input

number of images to decode starting from “subFileStart”, in (0, tiffData->nSubFiles]

unsigned char **imageOut_d

Output

Host

host array (of size tiffData->nSubFiles) of pointers to device buffers. Each device buffer is expected to have size at least: tiffData->subFiles[0].nrow * tiffData->subFiles[0].ncol * (tiffData->subFiles[0].bitsPerPixel/8)

cudaStream_t stream

Input

the stream to use for the kernel launches.

Returns:

NVTIFF_DECODE_SUCCESS - on success.

NVTIFF_DECODE_INVALID_CTX - if tiffFile is invalid.

NVTIFF_DECODE_INVALID_RANGE - if (subFileStart, subFileNum) specify and invalid range of images.

Helper API Reference

nvtiffStreamCreate()

Creates an instance of the bitstream handle.

Signature:

nvtiffStatus_t nvtiffStreamCreate(nvtiffStream_t *tiff_stream);

Parameters:

Parameter

Input/Output

Memory

Description

nvtiffStream_t *tiff_stream

Input/Output

Host

nvtiff bitstream handle

Returns:

nvtiffStatus_t - An error code as specified in Version 2 API Return Status Codes

nvtiffStreamDestroy()

Releases the bitstream handle.

Signature:

nvtiffStatus_t nvtiffStreamDestroy(nvtiffStream_t stream_handle);

Parameters:

Parameter

Input/Output

Memory

Description

nvtiffStream_t stream_handle

Input

Host

nvtiff bitstream handle

Returns:

nvtiffStatus_t - An error code as specified in Version 2 API Return Status Codes

nvtiffDecoderCreateSimple()

Creates an instance of the decoder handle with default memory allocators.

Signature:

Parameters:

Parameter

Input/Output

Memory

Description

nvtiffDecoder_t *decoder

Input/Output

Host

nvtiff decoder handle

cudaStream_t cuda_stream

Input

Host

Used for asynchronous CUDA API calls

Returns:

nvtiffStatus_t - An error code as specified in Version 2 API Return Status Codes

nvtiffDecoderCreate

Creates an instance of the decoder handle.

Signature:

nvtiffStatus_t nvtiffDecoderCreate(nvtiffDecoder_t *decoder,
    nvtiffDeviceAllocator_t *device_allocator,
    nvtiffPinnedAllocator_t *pinned_allocator,
    cudaStream_t cuda_stream);

Parameters:

Parameter

Input/Output

Memory

Description

nvtiffDecoder_t *decoder

Input/Output

Host

nvtiff decoder handle

nvtiffDeviceAllocator_t *device_allocator

Input

Host

User provided device memory allocator. If set to NULL, the library will fallback to cudaMalloc/cudaFree.

nvtiffPinnedAllocator_t *pinned_allocator

Input

Host

User provided pinned memory allocator. If set to NULL, the library will fallback to cudaHostAlloc/cudaFreeHost.

cudaStream_t cuda_stream

Input

Host

Used for asynchronous CUDA API calls

Returns:

nvtiffStatus_t - An error code as specified in Version 2 API Return Status Codes

nvtiffDecoderDestroy()

Releases the decoder handle.

Signature:

nvtiffStatus_t nvtiffDecoderDestroy(nvtiffDecoder_t decoder,
    cudaStream_t cuda_stream);

Parameters:

Parameter

Input/Output

Memory

Description

nvtiffDecoder_t decoder

Input

Host

nvtiff decoder handle

cudaStream_t cuda_stream

Input

Host

Used for asynchronous CUDA API calls

Returns:

nvtiffStatus_t - An error code as specified in Version 2 API Return Status Codes

Parser API Reference

nvtiffStreamParseFromFile()

Parses the tiff file and stores the meta data in nvtiffStream_t .

Signature:

nvtiffStatus_t nvtiffStreamParseFromFile(const char *fname,
        nvtiffStream_t tiff_stream)

Parameters:

Parameter

Input/Output

Memory

Description

const char *fname

Input

Host

tiff file name on disk

nvtiffStream_t tiff_stream

Input/Output

Host

tiff stream handle

Returns:

nvtiffStatus_t - An error code as specified in Version 2 API Return Status Codes

nvtiffStreamPrint()

Prints to standard output, the tiff file meta data stored in nvtiffStream_t.

Signature:

nvtiffStatus_t nvtiffStreamPrint(nvtiffStream_t tiff_stream)

Parameters:

Parameter

Input/Output

Memory

Description

nvtiffStream_t tiff_stream

Input

Host

tiff stream handle

Returns:

nvtiffStatus_t - An error code as specified in Version 2 API Return Status Codes

nvtiffStreamGetFileInfo()

Retrieves the image information defined in nvtiffFileInfo_t. This information is useful in allocating output buffers on device memory.

Signature:

nvtiffStatus_t nvtiffStreamGetFileInfo(nvtiffStream_t tiff_stream,
        nvtiffFileInfo_t *file_info)

Parameters:

Parameter

Input/Output

Memory

Description

nvtiffStream_t tiff_stream

Input

Host

tiff stream handle

nvtiffFileInfo_t *file_info

Input/Output

Host

pointer to nvtiffFileInfo_t

Returns:

nvtiffStatus_t - An error code as specified in Version 2 API Return Status Codes

Decoding API V2 Reference

nvtiffDecode()

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

Signature:

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

Parameters:

Parameter

Input/Output

Memory

Description

nvtiffStream_t tiff_stream

Input

Host

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

cudaStream_t cuda_stream

Input

Host

cuda_stream where all the GPU work will be submitted

Returns:

nvtiffStatus_t - An error code as specified in Version 2 API Return Status Codes

nvtiffDecodeRange()

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

Signature:

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:

Parameter

Input/Output

Memory

Description

nvtiffStream_t tiff_stream

Input

Host

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

cudaStream_t cuda_stream

Input

Host

cuda_stream where all the GPU work will be submitted

Returns:

nvtiffStatus_t - An error code as specified in Version 2 API Return Status Codes

Encoding API Reference

nvTiffEncodeCtxCreate()

This function encoding context based on the specified parameters that can be used to perform a parallel LZW compression of images.

Signature:

nvTiffEncodeCtx_t nvTiffEncodeCtxCreate(int dev,
                                        unsigned int imagesMax,
                                        unsigned int stripsPerImageMax,
                                        size_t memLimit=0);

Parameters:

Parameter

Input/Output

Memory

Description

int dev

Input

Device to use for CUDA calls and kernel launches

unsigned int imagesMax

Input

maximum number of images that will be encoded using the returned context

unsigned int stripsPerImageMax

Input

maximum number of strips that the images that will be encoded using the returned context will be partitioned into

size_t memLimit

Input

maximum amount of device memory that can be used to allocate the internal buffers required by the strip compression kernel

Returns:

SUCCESS - on success returns a pointer to nvTiffEncodeCtx_t

NULL - otherwise.

nvTiffEncodeCtxDestroy()

Destroys context ctx freeing all the allocated memory on both the host and the device.

Signature:

void nvTiffEncodeCtxDestroy(nvTiffEncodeCtx_t *ctx);

Parameters:

Parameter

Input/Output

Memory

Description

nvTiffEncodeCtx_t *ctx

Input

Destroys context ctx freeing all the allocated memory on both the host and the device.

nvTiffEncode()

Perform the encoding of multiple images using the resources specified by the encoding context. Each image is divided into strips formed by groups of consecutive rows and then each strip is compressed using LZW independently.

This function is fully asynchronous.

Signature:

int NVTIFFAPI nvTiffEncode(nvTiffEncodeCtx_t *ctx,
                           unsigned int nrow,
                           unsigned int ncol,
                           unsigned int pixelSize,
                           unsigned int rowsPerStrip,
                           unsigned int nImages,
                           unsigned char **images_d,
                           unsigned long long stripAllocSize,
                           unsigned long long *stripSize_d,
                           unsigned long long *stripOffs_d,
                           unsigned char      *stripData_d,
                           cudaStream_t stream=0);

Parameters:

Parameter

Input/Output

Memory

Description

nvTiffEncodeCtx_t *ctx

Input

the nvTiffEncodeCtx_t returned by nvTiffEncodeCtxCreate();

unsigned int nrow

Input

number of rows of the images to compress;

unsigned int ncol

Input

number of columns of the images to compress;

unsigned int pixelSize

Input

pixel size, in bytes, for the images to compress;

unsigned int rowsPerStrip

Input

number of rows to be compressed together in a single strip;

unsigned int nImages

Input

number of images to compress;

unsigned char **images_d

Input

Host

host array of size nImages of pointers to device buffers

unsigned long long stripAllocSize

Input

the estimated maximum size for compressed strips;

unsigned int *stripSize_d

Output

Device

device array of size at least ceil(nrow/rowsPerStrip)*nImages

unsigned int *stripOffs_d

Output

Device

device array of size at least ceil(nrow/rowsPerStrip)*nImages

unsigned long long *stripData_d

Output

Device

device array of size at least ceil(nrow/rowsPerStrip)*nImages*stripAllocSize in which the compressed strips are returned

stream

Input

the stream to use for the kernel launches

Returns:

NVTIFF_ENCODE_SUCCESS - on success, the compressed strips can be accessed after the subsequent call to nvTiffEncodeFinalize(), see below;

NVTIFF_ENCODE_INVALID_CTX - ctx is invalid.

NVTIFF_ENCODE_INVALID_STRIP_NUM - if the specified nrow, rowsPerStrip and nImages amount to a number of strips to be compressed greater than those specified by the parameters imagesMax and stripsPerImageMax specified at the creation of the context ctx;

CUTIFF_ENCODE_INVALID_IMAGE_NUM: if the specified nImages is greater than the parameter imagesMax specified at the creation of the context ctx;

nvTiffEncodeFinalize()

This function completes the compression process initiated by nvTiffEncode(). Since nvTiffEncode() is asynchronous, the state about its runtime operations is checked via this finalization call. Please note that this function is NOT fully asynchronous. On entry, it synchronizes on the stream specified as a parameter and, if the all the operations initiated by the previous cuTiffEncode() call terminated with success, then it launches a kernel, asynchronously, to finalize the data arrays passed to cuTiffEncode() (stripSize_d, stripOffs_d and stripData_d). Because of that, before accessing those arrays it is necessary to synchronize on the passed stream.

Signature:

int  nvTiffEncodeFinalize(nvTiffEncodeCtx_t *ctx,
                          cudaStream_t stream=0);

Parameters:

Parameter

Input/Output

Memory

Description

nvTiffEncodeCtx_t *ctx

Input

the nvTiffEncodeCtx_t passed to nvTiffEncode();

stream

Input

the stream to use for the kernel launches

Returns:

NVTIFF_ENCODE_SUCCESS - on success; the strips sizes, offsets and data can be accessed in the array stripSize_d, stripOffs_d, stripData_d passed to nvTiffEncode() after all the operations enqueued on stream are concluded;

NVTIFF_ENCODE_INVALID_CTX - ctx is invalid.

NVTIFF_ENCODE_COMP_STRIP_TOO_LONG - currently the compression procedure supports strips with a compressed size up to 48KB; if one strip would be compressed into a larger size then this error is returned

NVTIFF_ENCODE_COMP_OVERFLOW - this error is returned in case one or more strips compress to a size grater than the value of the parameter stripAllocSize passed to nvTiffEncode()

nvTiffWriteFile()

This is a convenience function to write compressed images to a single TIFF file. Library users may want to implement their own function to use additional/custom TIFF tags.

Signature:

int nvTiffWriteFile(const char *fname,
                    int tiffVer,
                    unsigned int nImages,
                    unsigned int nrow,
                    unsigned int ncol,
                    unsigned int rowsPerStrip,
                    unsigned short samplesPerPixel,
                    unsigned short *bitsPerSample,
                    unsigned int photometricInt,
                    unsigned int planarConf,
                    unsigned long long *stripSize,
                    unsigned long long *stripOffs,
                    unsigned char      *stripData);

Parameters:

Parameter

Input/Output

Memory

Description

const char *fname

Input

Host

the name of the output TIFF file;

int tiffVer

Input

specifies whether to use regular Tiff or a BigTiff file format; for regular Tiff use VER_REG_TIFF; for BigTiff use VER_BIG_TIFF;

unsigned int nImages

Input

number of images to write into the file

unsigned int nrow

Input

number of rows of every image

unsigned int ncol

Input

number of columns of every image;

unsigned int rowsPerStrip

Input

number of rows that form a Tiff strip

unsigned short samplesPerPixel

Input

number of components per pixel

unsigned short bitsPerSample

Input

array of length samplesPerPixel specifying the number of bits per component;

unsigned int photometricInt

Input

color space of the image data; supported values: 1 or 2;

unsigned int planarConf

Input

how the components of each pixel are stored; supported values: 1 (chunky format);

unsigned long long *stripSize

Input

Host

host array of size ceil(nrow/rowsPerStrip)*nImages containing the length of the compressed strips;

unsigned long long *stripOffs

Input

Host

host array of size ceil(nrow/rowsPerStrip)*nImages containing the starting offset of the compressed strips inside the stripData buffer;

unsigned char *stripData

Input

Host

host array containing the ceil(nrow/rowsPerStrip)*nImages compressed strips; strips are expected to be stored one after the other starting from the first image to the last, from the top to bottom;

Returns:

NVTIFF_WRITE_SUCCESS - on success

NVTIFF_WRITE_UNSUPP_PLANAR_CONF - if the value of planarConf parameter is not equal to 1;.

NVTIFF_WRITE_UNSUPP_PHOTOMETRIC_INT - if the value of photometricInt parameter is neither 1 nor 2;