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