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;