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;