API Reference#

Type Declarations#

nvTIFF Encode API Return Status Codes#

The return codes of the nvTIFF Encode APIs are listed below:

#define NVTIFF_ENCODE_SUCCESS             (0)
#define NVTIFF_ENCODE_INVALID_CTX         (1)
#define NVTIFF_ENCODE_INVALID_STRIP_NUM   (2)
#define NVTIFF_ENCODE_COMP_OVERFLOW       (3)
#define NVTIFF_ENCODE_COMP_STRIP_TOO_LONG (4)

Description the Return Codes

Return Code	Description
NVTIFF_ENCODE_SUCCESS (0)	The API call has finished successfully. Note that many of the calls are asynchronous and some of the errors may be seen only after synchronization.
NVTIFF_ENCODE_INVALID_CTX (1)	Invalid CTX.
NVTIFF_ENCODE_INVALID_STRIP_NUM (2)	Invalid strip number
NVTIFF_ENCODE_COMP_OVERFLOW (3)	overflow during compression
NVTIFF_ENCODE_COMP_STRIP_TOO_LONG (4)	Too long strip

nvTIFF Write API Return Status Codes#

The return codes of the nvTIFF Write APIs are listed below:

#define NVTIFF_WRITE_SUCCESS                (0)
#define NVTIFF_WRITE_UNSUPP_PLANAR_CONF     (1)
#define NVTIFF_WRITE_UNSUPP_PHOTOMETRIC_INT (2)

Description the Return Codes

Return Code	Description
NVTIFF_WRITE_SUCCESS (0)	The API call has finished successfully. Note that many of the calls are asynchronous and some of the errors may be seen only after synchronization.
NVTIFF_WRITE_UNSUPP_PLANAR_CONF (1)	if the value of planarConf parameter is not equal to 1;.
NVTIFF_WRITE_UNSUPP_PHOTOMETRIC_INT (2)	if the value of photometricInt parameter is neither 1 nor 2;

Decode API Return Status Codes#

The return codes of the nvTiff Decode APIs are listed below:

typedef enum {
    NVTIFF_STATUS_SUCCESS = 0,
    NVTIFF_STATUS_NOT_INITIALIZED = 1,
    NVTIFF_STATUS_INVALID_PARAMETER = 2,
    NVTIFF_STATUS_BAD_TIFF = 3,
    NVTIFF_STATUS_TIFF_NOT_SUPPORTED = 4,
    NVTIFF_STATUS_ALLOCATOR_FAILURE = 5,
    NVTIFF_STATUS_EXECUTION_FAILED = 6,
    NVTIFF_STATUS_ARCH_MISMATCH = 7,
    NVTIFF_STATUS_INTERNAL_ERROR = 8,
    NVTIFF_STATUS_NVCOMP_NOT_FOUND = 9,
    NVTIFF_STATUS_NVJPEG_NOT_FOUND = 10,
    NVTIFF_STATUS_TAG_NOT_FOUND = 11,
    NVTIFF_STATUS_PARAMETER_OUT_OF_BOUNDS = 12,
    NVTIFF_STATUS_NVJPEG2K_NOT_FOUND = 13
} nvtiffStatus_t;

Description the Return Codes

Return Code	Description
NVTIFF_STATUS_SUCCESS (0)	The API call has finished successfully. Note that many of the calls are asynchronous and some of the errors may be seen only after synchronization.
NVTIFF_STATUS_NOT_INITIALIZED (1)	The library handle was not initialized.
NVTIFF_STATUS_INVALID_PARAMETER (2)	Wrong parameter was passed. For example, a null pointer as input data, or an invalid enum value
NVTIFF_STATUS_BAD_TIFF (3)	Cannot parse the TIFF stream. Likely due to a corruption that cannot be handled
NVTIFF_STATUS_TIFF_NOT_SUPPORTED (4)	Attempting to decode a TIFF stream that is not supported by the nvTIFF library.
NVTIFF_STATUS_ALLOCATOR_FAILURE (5)	The user-provided allocator functions, for either memory allocation or for releasing the memory, returned a non-zero code.
NVTIFF_STATUS_EXECUTION_FAILED (6)	Error during the execution of the device tasks.
NVTIFF_STATUS_ARCH_MISMATCH (7)	The device capabilities are not enough for the set of input parameters provided.
NVTIFF_STATUS_INTERNAL_ERROR (8)	Unknown error occured in the library.
NVTIFF_STATUS_NVCOMP_NOT_FOUND (9)	nvTiff is unable to load the nvcomp library.
NVTIFF_STATUS_NVJPEG_NOT_FOUND (10)	nvTiff is unable to load the nvjpeg library.
NVTIFF_STATUS_TAG_NOT_FOUND (11)	nvTiff is unable to find information about the provided tag.
NVTIFF_STATUS_PARAMETER_OUT_OF_BOUNDS (12)	Provided parameter is outside the range of possible values.
NVTIFF_STATUS_NVJPEG2K_NOT_FOUND (13)	nvTiff is unable to load the nvJPEG2000 library.

TIFF Tags#

typedef enum nvtiffTag {
  NVTIFF_TAG_UNKNOWN = -1,
  NVTIFF_TAG_MODEL_PIXEL_SCALE = 33550,
  NVTIFF_TAG_MODEL_TIE_POINT =   33922,
  NVTIFF_TAG_MODEL_TRANSFORMATION = 34264
} nvtiffTag_t;

nvtiffTag_t corresponds to various TIFF tags listed in the TIFF specification. Currently only GeoTIFF relevant tags are supported. User can refer to the TIFF specification for additional details.

TIFF Tag Data Type#

typedef enum nvtiffTagDataType {
    NVTIFF_TAG_TYPE_BYTE      =  1,
    NVTIFF_TAG_TYPE_ASCII     =  2,
    NVTIFF_TAG_TYPE_SHORT     =  3,
    NVTIFF_TAG_TYPE_LONG      =  4,
    NVTIFF_TAG_TYPE_RATIONAL  =  5,
    NVTIFF_TAG_TYPE_SBYTE     =  6,
    NVTIFF_TAG_TYPE_UNDEFINED =  7,
    NVTIFF_TAG_TYPE_SSHORT    =  8,
    NVTIFF_TAG_TYPE_SLONG     =  9,
    NVTIFF_TAG_TYPE_SRATIONAL = 10,
    NVTIFF_TAG_TYPE_FLOAT     = 11,
    NVTIFF_TAG_TYPE_DOUBLE    = 12,
    NVTIFF_TAG_TYPE_LONG8     = 16,
    NVTIFF_TAG_TYPE_SLONG8    = 17,
    NVTIFF_TAG_TYPE_IFD8      = 18,
} nvtiffTagDataType_t;

nvtiffTagDataType_t corresponds to the datatype for a TIFF tag.

GeoTIFF Keys#

typedef enum nvtiffGeoKeys
{
    // GeoTIFF Configuration Keys
    NVTIFF_GEOKEY_GT_MODEL_TYPE                = 1024,
    NVTIFF_GEOKEY_GT_RASTER_TYPE               = 1025,
    NVTIFF_GEOKEY_GT_CITATION                  = 1026,

    // Geodetic CRS Parameter Keys
    NVTIFF_GEOKEY_GEODETIC_CRS                 = 2048,
    NVTIFF_GEOKEY_GEODETIC_CITATION            = 2049,
    NVTIFF_GEOKEY_GEODETIC_DATUM               = 2050,
    NVTIFF_GEOKEY_PRIME_MERIDIAN               = 2051,
    NVTIFF_GEOKEY_GEOG_LINEAR_UNITS            = 2052,
    NVTIFF_GEOKEY_GEOG_LINEAR_UNIT_SIZE        = 2053,
    NVTIFF_GEOKEY_GEOG_ANGULAR_UNITS           = 2054,
    NVTIFF_GEOKEY_GEOG_ANGULAR_UNIT_SIZE       = 2055,
    NVTIFF_GEOKEY_ELLIPSOID                    = 2056,
    NVTIFF_GEOKEY_ELLIPSOID_SEMI_MAJOR_AXIS    = 2057,
    NVTIFF_GEOKEY_ELLIPSOID_SEMI_MINOR_AXIS    = 2058,
    NVTIFF_GEOKEY_ELLIPSOID_INV_FLATTENING     = 2059,
    NVTIFF_GEOKEY_GEOG_AZIMUTH_UNITS           = 2060,
    NVTIFF_GEOKEY_PRIME_MERIDIAN_LONG          = 2061,

    // Projected CRS Parameter Keys
    NVTIFF_GEOKEY_PROJECTED_CRS                = 3072,
    NVTIFF_GEOKEY_PROJECTED_CITATION           = 3073,
    NVTIFF_GEOKEY_PROJECTION                   = 3074,
    NVTIFF_GEOKEY_PROJ_METHOD                  = 3075,
    NVTIFF_GEOKEY_PROJ_LINEAR_UNITS            = 3076,
    NVTIFF_GEOKEY_PROJ_LINEAR_UNIT_SIZE        = 3077,
    NVTIFF_GEOKEY_PROJ_STD_PARALLEL1           = 3078,
    NVTIFF_GEOKEY_PROJ_STD_PARALLEL            = 3078,
    NVTIFF_GEOKEY_PROJ_STD_PARALLEL2           = 3079,
    NVTIFF_GEOKEY_PROJ_NAT_ORIGIN_LONG         = 3080,
    NVTIFF_GEOKEY_PROJ_ORIGIN_LONG             = 3080,
    NVTIFF_GEOKEY_PROJ_NAT_ORIGIN_LAT          = 3081,
    NVTIFF_GEOKEY_PROJ_ORIGIN_LAT              = 3081,
    NVTIFF_GEOKEY_PROJ_FALSE_EASTING           = 3082,
    NVTIFF_GEOKEY_PROJ_FALSE_NORTHING          = 3083,
    NVTIFF_GEOKEY_PROJ_FALSE_ORIGIN_LONG       = 3084,
    NVTIFF_GEOKEY_PROJ_FALSE_ORIGIN_LAT        = 3085,
    NVTIFF_GEOKEY_PROJ_FALSE_ORIGIN_EASTING    = 3086,
    NVTIFF_GEOKEY_PROJ_FALSE_ORIGIN_NORTHING   = 3087,
    NVTIFF_GEOKEY_PROJ_CENTER_LONG             = 3088,
    NVTIFF_GEOKEY_PROJ_CENTER_LAT              = 3089,
    NVTIFF_GEOKEY_PROJ_CENTER_EASTING          = 3090,
    NVTIFF_GEOKEY_PROJ_CENTER_NORTHING         = 3091,
    NVTIFF_GEOKEY_PROJ_SCALE_AT_NAT_ORIGIN     = 3092,
    NVTIFF_GEOKEY_PROJ_SCALE_AT_ORIGIN         = 3092,
    NVTIFF_GEOKEY_PROJ_SCALE_AT_CENTER         = 3093,
    NVTIFF_GEOKEY_PROJ_AZIMUTH_ANGLE           = 3094,
    NVTIFF_GEOKEY_PROJ_STRAIGHT_VERT_POLE_LONG = 3095,

    // Vertical CRS Parameter Keys (4096-5119)
    NVTIFF_GEOKEY_VERTICAL                     = 4096,
    NVTIFF_GEOKEY_VERTICAL_CITATION            = 4097,
    NVTIFF_GEOKEY_VERTICAL_DATUM               = 4098,
    NVTIFF_GEOKEY_VERTICAL_UNITS               = 4099,

    NVTIFF_GEOKEY_BASE                         = 32768,
    NVTIFF_GEOKEY_END                          = 65535
} nvtiffGeoKey_t;

nvtiffGeoKey_t corresponds to various geo keys listed in the GeoTIFF specification. User can refer to the GeoTIFF specification for additional details.

GeoTIFF Key Datatype#

typedef enum nvtiffGeoKeyDataType {
    NVTIFF_GEOKEY_TYPE_SHORT=1,
    NVTIFF_GEOKEY_TYPE_ASCII=2,
    NVTIFF_GEOKEY_TYPE_DOUBLE=3,
    NVTIFF_GEOKEY_TYPE_UNKNOWN=4
} nvtiffGeoKeyDataType_t;

nvtiffGeoKeyDataType_t corresponds to a datatype for a geo key.

Device Allocator Interface#

typedef int (*nvtiffDeviceMallocAsync)(void* ctx, void **ptr, size_t size, cudaStream_t stream);

typedef int (*nvtiffDeviceFreeAsync)(void* ctx, void *ptr, size_t size, cudaStream_t stream);

typedef struct {
    nvtiffDeviceMallocAsync device_malloc;
    nvtiffDeviceFreeAsync device_free;
    void *device_ctx;
} nvtiffDeviceAllocator_t;

Custom device allocator supports stream ordered allocation and user defined context information *device_ctx. When invoking the device allocators, nvTiff will pass *device_ctx as input to the device allocator.

Pinned Allocator Interface#

typedef int (*nvtiffPinnedMallocAsync)(void* ctx, void **ptr, size_t size, cudaStream_t stream);

typedef int (*nvtiffPinnedFreeAsync)(void* ctx, void *ptr, size_t size, cudaStream_t stream);

typedef struct {
    nvtiffPinnedMallocAsync pinned_malloc;
    nvtiffPinnedFreeAsync pinned_free;
    void *pinned_ctx;
} nvtiffPinnedAllocator_t;

Custom pinned allocator supports stream ordered allocation and user defined context information *pinned_ctx. When invoking the pinned allocators, nvTiff will pass *pinned_ctx as input to the pinned allocator.

Image Type#

typedef enum {
    NVTIFF_IMAGETYPE_REDUCED_IMAGE = 0b0001,
    NVTIFF_IMAGETYPE_PAGE          = 0b0010,
    NVTIFF_IMAGETYPE_MASK          = 0b0100,
    NVTIFF_IMAGETYPE_ENUM_FORCE_UINT32 =  0xFFFFFFFF,
} nvtiffImageType;
typedef uint32_t nvtiffImageType_t;

nvtiffImageType enum corresponds to the NewSubfiletype (254) tag defined in the TIFF specification.

Compression Type#

typedef enum nvtiffCompression {
    NVTIFF_COMPRESSION_UNKNOWN = 0,
    NVTIFF_COMPRESSION_NONE = 1,
    NVTIFF_COMPRESSION_LZW = 5,
    NVTIFF_COMPRESSION_JPEG = 7,
    NVTIFF_COMPRESSION_ADOBE_DEFLATE = 8,
    NVTIFF_COMPRESSION_DEFLATE = 32946,
    NVTIFF_COMPRESSION_APERIO_JP2000_YCC = 33003,
    NVTIFF_COMPRESSION_APERIO_JP2000_RGB = 33005,
    NVTIFF_COMPRESSION_JP2000 = 34712
} nvtiffCompression_t;

nvtiffCompression_t enum corresponds to the Compression (259) tag defined in the TIFF specification.

Photometric Interpretation#

typedef enum nvtiffPhotometricInt {
    NVTIFF_PHOTOMETRIC_UNKNOWN    = -1,
    NVTIFF_PHOTOMETRIC_MINISWHITE = 0,
    NVTIFF_PHOTOMETRIC_MINISBLACK = 1,
    NVTIFF_PHOTOMETRIC_RGB        = 2,
    NVTIFF_PHOTOMETRIC_PALETTE    = 3,
    NVTIFF_PHOTOMETRIC_MASK       = 4,
    NVTIFF_PHOTOMETRIC_SEPARATED  = 5,
    NVTIFF_PHOTOMETRIC_YCBCR      = 6,
}nvtiffPhotometricInt_t;

nvtiffPhotometricInt_t enum corresponds to the PhotometricInterpretation (262) tag defined in the TIFF specification.

Planar Configuration#

typedef enum nvtiffPlanarConfig {
  NVTIFF_PHOTOMETRIC_UNKNOWN    = -1,
  NVTIFF_PHOTOMETRIC_MINISWHITE = 0,
  NVTIFF_PHOTOMETRIC_MINISBLACK = 1,
  NVTIFF_PHOTOMETRIC_RGB        = 2,
  NVTIFF_PHOTOMETRIC_PALETTE    = 3,
  NVTIFF_PHOTOMETRIC_MASK       = 4,
  NVTIFF_PHOTOMETRIC_SEPARATED  = 5,
  NVTIFF_PHOTOMETRIC_YCBCR      = 6,
} nvtiffPlanarConfig_t;

nvtiffPlanarConfig_t enum corresponds to the PlanarConfiguration (284) tag defined in the TIFF specification.

Sample Format#

typedef enum nvtiffSampleFormat {
    NVTIFF_SAMPLEFORMAT_UNKNOWN = 0,
    NVTIFF_SAMPLEFORMAT_UINT    = 1,
    NVTIFF_SAMPLEFORMAT_INT        = 2,
    NVTIFF_SAMPLEFORMAT_IEEEFP    = 3,
    NVTIFF_SAMPLEFORMAT_VOID        = 4,
    NVTIFF_SAMPLEFORMAT_COMPLEXINT    = 5,
    NVTIFF_SAMPLEFORMAT_COMPLEXIEEEFP    = 6
} nvtiffSampleFormat_t;

nvtiffSampleFormat_t enum corresponds to the SampleFormat (339) tag defined in the TIFF specification.

TIFF File Information#

typedef struct nvtiffFileInfo {
    uint32_t num_images;
    uint32_t image_width;
    uint32_t image_height;
    nvtiffPhotometricInt_t photometric_int;
    nvtiffPlanarConfig_t planar_config;
    uint16_t samples_per_pixel;
    uint16_t bits_per_pixel; // SUM(bits_per_sample)
    uint16_t bits_per_sample[MAX_NUM_SAMPLES];
    nvtiffSampleFormat_t sample_format[MAX_NUM_SAMPLES];
} nvtiffFileInfo_t;

nvtiffFileInfo_t enum is used to retrieve some of the TIFF file metadata. This information can be used for allocating decode output buffers.

TIFF Image Information#

typedef struct nvtiffImageInfo {
    nvtiffImageType_t image_type;
    uint32_t image_width;
    uint32_t image_height;
    nvtiffCompression_t compression;
    nvtiffPhotometricInt_t photometric_int;
    nvtiffPlanarConfig_t planar_config;
    uint16_t samples_per_pixel;
    uint16_t bits_per_pixel; // SUM(bits_per_sample)
    uint16_t bits_per_sample[MAX_NUM_SAMPLES];
    nvtiffSampleFormat_t sample_format[MAX_NUM_SAMPLES];
} nvtiffImageInfo_t;

nvtiffImageInfo_t contains some additional metadata of an image stored in a TIFF file.

TIFF Geometry Type#

typedef enum nvtiffImageGeometryType {
    NVTIFF_IMAGE_STRIPED = 0,
    NVTIFF_IMAGE_TILED = 1,
} nvtiffImageGeometryType_t;

nvtiffImageGeometryType_t specifies whether a tiff file uses strips or tiles

TIFF Geometry Information#

typedef struct nvtiffImageGeometry {
    nvtiffImageGeometryType_t type;
    uint32_t image_depth;
    uint32_t strile_width;            // strile_width = image_width for strips
    uint32_t strile_height;
    uint32_t strile_depth;            // strile_depth = image_depth for strips
    uint32_t num_striles_per_plane;
    uint32_t num_striles;
} nvtiffImageGeometry_t;

Stores image geometry along with strip/tile dimensions. When the geometry type is NVTIFF_IMAGE_STRIPED, strile_width is to image width.

Decode Output Format#

typedef enum nvtiffOutputFormat {
    NVTIFF_OUTPUT_UNCHANGED_I    = 0,   // Interleaved channels
    NVTIFF_OUTPUT_RGB_I_UINT8    = 1,   // Interleaved RGB with 8 bits per channel
    NVTIFF_OUTPUT_RGB_I_UINT16   = 2,   // Interleaved RGB with 16 bits per channel
} nvtiffOutputFormat_t;

nvtiffOutputFormat_t is used to specify the decode output format.

Decoder Handle#

struct nvtiffDecoder;
typedef struct nvtiffDecoder* nvtiffDecoder_t;

nvtiffDecoder_t stores intermediate decode buffers used in decoding.

Bitstream/File Handle#

struct nvtiffStream;
typedef struct nvtiffStream* nvtiffStream_t;

nvtiffStream_t is used for parsing a tiff file. Tiff metadata can be extracted using APIs defined in Parser API Reference.

Decode Parameters Handle#

struct nvtiffDecodeParams;
typedef struct nvtiffDecodeParams* nvtiffDecodeParams_t;

nvtiffDecodeParams_t is used to specify decode output parameters such as region of interest to decode, output format.

Encoder Handle#

struct nvtiffEncoder;
typedef struct nvtiffEncoder* nvtiffEncoder_t;

nvtiffEncoder_t stores intermediate buffers used in encoding.

Encode Parameters Handle#

struct nvtiffEncodeParams;
typedef struct nvtiffEncodeParams* nvtiffEncodeParams_t;

nvtiffEncodeParams_t is used to specify encode input parameters such as image and pixel information, compression method, and GeoTIFF tags and keys.

API Reference#

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 Decode 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 Decode 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 Decode 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 Decode 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 Decode API Return Status Codes

nvtiffDecodeParamsCreate()#

Creates an instance of the decode output parameters handle.

Signature:

nvtiffStatus_t nvtiffDecodeParamsCreate(nvtiffDecodeParams_t *decode_params);

Parameters:

Parameter	Input/Output	Memory	Description
nvtiffDecodeParams_t *decode_params	Input/Output	Host	Decode output parameters handle

Returns:

nvtiffStatus_t - An error code as specified in nvtiffapireturncodes-label

nvtiffDecodeParamsDestroy()#

Releases the decode output parameters handle.

Signature:

nvtiffStatus_t nvtiffDecodeParamsDestroy(nvtiffDecodeParams_t decode_params);

Parameters:

Parameter	Input/Output	Memory	Description
nvtiffDecodeParams_t decode_params	Input	Host	Decode output parameters handle

Returns:

nvtiffStatus_t - An error code as specified in nvtiffapireturncodes-label

nvtiffEncoderCreate()#

Creates and initializes a TIFF encoder instance.

Signature:

nvtiffStatus_t nvtiffEncoderCreate(nvtiffEncoder_t* encoder,
    nvtiffDeviceAllocator_t* deviceAllocator,
    nvtiffPinnedAllocator_t* pinnedAllocator,
    cudaStream_t stream)

Parameters:

Parameter	Input/Output	Memory	Description
nvtiffEncoder_t* encoder	Output	Host	Pointer to encoder handle
nvtiffDeviceAllocator_t* deviceAllocator	Input	Host	Custom device memory allocator (can be NULL to use default which are cudaMalloc/cudaFree)
nvtiffPinnedAllocator_t* pinnedAllocator	Input	Host	Custom pinned memory allocator (can be NULL to use default which are cudaHostAlloc/cudaFreeHost)
cudaStream_t stream	Input	Host	CUDA stream

Returns:

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

nvtiffEncoderDestroy()#

Destroys a TIFF encoder instance and frees associated resources.

Signature:

nvtiffStatus_t nvtiffEncoderDestroy(nvtiffEncoder_t encoder,
    cudaStream_t stream)

Parameters:

Parameter	Input/Output	Memory	Description
nvtiffEncoder_t encoder	Input	Host	Encoder handle to destroy
cudaStream_t stream	Input	Host	CUDA stream

Returns:

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

nvtiffEncodeParamsCreate()#

Creates and initializes encode parameters object.

Signature:

nvtiffStatus_t nvtiffEncodeParamsCreate(nvtiffEncodeParams_t* params)

Parameters:

Parameter	Input/Output	Memory	Description
nvtiffEncodeParams_t* params	Output	Host	Pointer to encode parameters handle

Returns:

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

nvtiffEncodeParamsDestroy()#

Destroys encode parameters object and frees associated resources.

Signature:

nvtiffStatus_t nvtiffEncodeParamsDestroy(nvtiffEncodeParams_t params,
    cudaStream_t stream)

Parameters:

Parameter	Input/Output	Memory	Description
nvtiffEncodeParams_t params	Input	Host	Encode parameters handle
cudaStream_t stream	Input	Host	CUDA stream

Returns:

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

Parser API Reference#

The APIs in this section are used to parse a TIFF file and retrieve meta data. Meta data such as image dimensions, samples per pixel may be used to allocate output buffers on device memory.

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 Decode API Return Status Codes

nvtiffStreamParse()#

Parses a tiff file which is loaded to host memory and stores the meta data in nvtiffStream_t.

Signature:

nvtiffStatus_t nvtiffStreamParse(const uint8_t *buffer,
      size_t buffer_size,
      nvtiffStream_t tiff_stream);

Parameters:

Parameter	Input/Output	Memory	Description
const uint8_t *buffer	Input	Host	Buffer containing tiff file
size_t buffer_size	Input	Host	tiff file size
nvtiffStream_t tiff_stream	Input/Output	Host	tiff stream handle

Returns:

nvtiffStatus_t - An error code as specified in Decode 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 Decode API Return Status Codes

nvtiffStreamGetFileInfo()#

Retrieves the image information defined in TIFF File Information.

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 Decode API Return Status Codes

nvtiffStreamGetNumImages()#

Retrieves the number of images stored in a TIFF file.

Signature:

nvtiffStatus_t nvtiffStreamGetNumImages(nvtiffStream_t tiff_stream,
        uint32_t *num_images)

Parameters:

Parameter	Input/Output	Memory	Description
nvtiffStream_t tiff_stream	Input	Host	tiff stream handle
uint32_t *num_images	Output	Host	Pointer to buffer containing number of images

Returns:

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

nvtiffStreamGetImageInfo()#

Retrieves the image information of a given image stored in a TIFF file. Refer to TIFF Image Information for details on what information is retrieved.

Signature:

nvtiffStatus_t nvtiffStreamGetImageInfo(nvtiffStream_t tiff_stream,
        uint32_t image_id,
        nvtiffImageInfo_t *image_info)

Parameters:

Parameter	Input/Output	Memory	Description
nvtiffStream_t tiff_stream	Input	Host	tiff stream handle
uint32_t image_id	Input	Host	Image index
nvtiffImageInfo_t *image_info	Output	Host	Pointer to nvtiffImageInfo_t

Returns:

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

nvtiffStreamGetImageGeometry()#

Retrieves image geometry related information. Geometry includes information whether the images use strips or tiles and their corresponding dimensions.

Signature:

nvtiffStatus_t nvtiffStreamGetImageGeometry(nvtiffStream_t tiff_stream,
      uint32_t image_id,
      nvtiffImageGeometry_t* geometry);

Parameters:

Parameter	Input/Output	Memory	Description
nvtiffStream_t tiff_stream	Input	Host	tiff stream handle
uint32_t image_id	Input	Host	Image index
nvtiffImageGeometry_t* geometry	Input/Output	Host	Pointer to nvtiffImageGeometry_t

Returns:

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

nvtiffStreamGetGeoKeyInfo()#

Retrieves the information about a geo key defined in GeoTIFF Keys. This information is useful in retrieving the values associated with the geo key.

Signature:

nvtiffStatus_t nvtiffStreamGetGeoKeyInfo(nvtiffStream_t tiff_stream,
        nvtiffGeoKey_t key,
        uint32_t *size,
        uint32_t *count,
        nvtiffGeoKeyDataType_t* type)

Parameters:

Parameter	Input/Output	Memory	Description
nvtiffStream_t tiff_stream	Input	Host	tiff stream handle
nvtiffGeoKey_t key	Input	Host	GeoTIFF key
uint32_t *size	Output	Host	Pointer to size of each value (in bytes) stored in key
uint32_t *count	Output	Host	Pointer to number of values stored in key
nvtiffGeoKeyDataType_t *type	Output	Host	Pointer to datatype of values stored in key

Returns:

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

nvtiffStreamGetNumberOfGeoKeys()#

Retrieves the list of geokeys present in a TIFF file and their count. This information is later useful in retrieving the values associated with each geo key.

Signature:

nvtiffStatus_t nvtiffStreamGetNumberOfGeoKeys(nvtiffStream_t tiff_stream,
        nvtiffGeoKey_t* key,
        uint32_t *num_keys)

Parameters:

Parameter	Input/Output	Memory	Description
nvtiffStream_t tiff_stream	Input	Host	tiff stream handle
nvtiffGeoKey_t *key	Output	Host	Pointer to user allocated buffer for storing all geokeys in TIFF file (can be `nullptr`, in which case only `num_keys` is returned)
uint32_t *num_keys	Output	Host	Pointer to number of geokeys stored in TIFF file

Returns:

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

nvtiffStreamGetTagInfo()#

Retrieves the information about a TIFF tag defined in TIFF Tags. This information is later useful in retrieving the values associated with the TIFF tag.

Signature:

nvtiffStatus_t nvtiffStreamGetTagInfo(nvtiffStream_t tiff_stream,
        uint32_t image_id,
        nvtiffTag_t tiff_tag,
        nvtiffTagDataType_t *tag_type,
        uint32_t *size,
        uint32_t *count);

Parameters:

Parameter	Input/Output	Memory	Description
nvtiffStream_t tiff_stream	Input	Host	tiff stream handle
uint32_t image_id	Input	Host	image index
nvtiffTag_t tiff_tag	Input	Host	tiff tag
nvtiffTagDataType_t *tag_type,	Output	Host	Pointer to buffer containing the datatype of `tiff_tag`. See TIFF Tag Data Type for which datatypes are supported.
uint32_t *size	Output	Host	Pointer to buffer containing size of individual values in `tiff_tag`
uint32_t *count	Output	Host	Pointer to buffer containing number of values in `tiff_tag`

Returns:

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

nvtiffStreamGetTagValue()#

Retrieves the values stored in a TIFF tag.

Signature:

nvtiffStatus_t nvtiffStreamGetTagValue(nvtiffStream_t tiff_stream,
        uint32_t image_id,
        nvtiffTag_t tiff_tag,
        void *tag_value,
        uint32_t count);

Parameters:

Parameter	Input/Output	Memory	Description
nvtiffStream_t tiff_stream	Input	Host	tiff stream handle
uint32_t image_id	Input	Host	image index
nvtiffTag_t tiff_tag	Input	Host	tiff tag
void *tag_value	Output	Host	Pointer to buffer containing values associated with `tiff_tag`
uint32_t *count	Output	Host	Pointer to buffer containing number of values in `tiff_tag`

Returns:

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

nvtiffStreamGetTagInfoGeneric()#

Retrieves TIFF tag information such as - tag type, size per element, and count for a sub image within a tiff file. If the tag is not found for sub image, NVTIFF_STATUS_TAG_NOT_FOUND is returned.

Signature:

nvtiffStatus_t nvtiffStreamGetTagInfoGeneric(nvtiffStream_t tiff_stream,
        uint32_t image_id,
        uint16_t tiff_tag,
        nvtiffTagDataType_t *tag_type,
        uint32_t *size,
        uint32_t *count);

Parameters:

Parameter	Input/Output	Memory	Description
nvtiffStream_t tiff_stream	Input	Host	tiff stream handle
uint32_t image_id	Input	Host	image index, cannot be greater than the total no of images in a tiff file.
uint16_t tiff_tag	Input	Host	TIFF tag of interest
nvtiffTagDataType_t * tag_type,	Output	Host	Retrieves the datatype of `tiff_tag`. See TIFF Tag Data Type for which datatypes are supported.
uint32_t * size	Output	Host	Retrieves the size per element, When tag type is NVTIFF_TAG_TYPE_ASCII, the string is NULL terminated.
uint32_t * count	Output	Host	Retrieves the number of elements associated with the tag

Returns:

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

nvtiffStreamGetTagValueGeneric()#

Retrieves the values stored in a TIFF tag for sub image. If the tag is not found for sub image, NVTIFF_STATUS_TAG_NOT_FOUND is returned.

Signature:

nvtiffStatus_t nvtiffStreamGetTagValueGeneric(nvtiffStream_t tiff_stream,
        uint32_t image_id,
        uint16_t tiff_tag,
        void *tag_value,
        uint32_t count);

Parameters:

Parameter	Input/Output	Memory	Description
nvtiffStream_t tiff_stream	Input	Host	tiff stream handle
uint32_t image_id	Input	Host	image index, cannot be greater than the total no of images in a tiff file.
uint16_t tiff_tag	Input	Host	tiff tag
void * tag_value	Output	Host	Output buffer used to retrieve the tag value
uint32_t count	Output	Host	Number of elements to retrieve.

Returns:

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

nvtiffStreamGetGeoKey()#

Retrieves the values associated with a given geo key stored in a TIFF file.

Signature:

nvtiffStatus_t nvtiffStreamGetGeoKey(nvtiffStream_t tiff_stream,
        nvtiffGeoKey_t key,
        void *val,
        uint32_t count);

Parameters:

Parameter	Input/Output	Memory	Description
nvtiffStream_t tiff_stream	Input	Host	tiff stream handle
nvtiffGeoKey_t key	Input	Host	geo key for which information is retrieved
void *val	Output	Host	Pointer to user allocated buffer for storing values associated with `key`
uint32_t count	Input	Host	Number of values copied (for geo key of type `NVTIFF_GEOKEY_TYPE_ASCII`, this is ignored. For geo key of type `NVTIFF_GEOKEY_TYPE_SHORT`, `count=1` is implied)

Returns:

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

nvtiffStreamGetGeoKeyASCII()#

Retrieves the values associated with geo key having ASCII values.

Signature:

nvtiffStatus_t NVTIFFAPI nvtiffStreamGetGeoKeyASCII(nvtiffStream_t tiff_stream,
        nvtiffGeoKey_t key,
        char* szStr,
        uint32_t szStrMaxLen)

Parameters:

Parameter	Input/Output	Memory	Description
nvtiffStream_t tiff_stream	Input	Host	tiff stream handle
nvtiffGeoKey_t key	Input	Host	geo key for which information is retrieved
char *szStr	Output	Host	Pointer to user allocated buffer containing key values
uint32_t szStrMaxLen	Input	Host	Size of the user allocated buffer `szStr`

Returns:

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

nvtiffStreamGetGeoKeySHORT()#

Retrieves the values associated with geo key having SHORT values.

Signature:

nvtiffStatus_t NVTIFFAPI nvtiffStreamGetGeoKeySHORT(nvtiffStream_t tiff_stream,
        nvtiffGeoKey_t key,
        unsigned short *val,
        uint32_t index,
        uint32_t count)

Parameters:

Parameter	Input/Output	Memory	Description
nvtiffStream_t tiff_stream	Input	Host	tiff stream handle
nvtiffGeoKey_t key	Input	Host	geo key for which information is retrieved
unsigned short *val	Output	Host	Pointer to user allocated buffer containing key values
uint32_t count	Input	Host	Number of values which are required to be copied to `val`
uint32_t index	Input	Host	Index of the starting value to be copied to `val`

Returns:

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

nvtiffStreamGetGeoKeyDOUBLE()#

Retrieves the values associated with geo key having DOUBLE values.

Signature:

nvtiffStatus_t NVTIFFAPI nvtiffStreamGetGeoKeyDOUBLE(nvtiffStream_t tiff_stream,
        nvtiffGeoKey_t key,
        double *val,
        uint32_t index,
        uint32_t count)

Parameters:

Parameter	Input/Output	Memory	Description
nvtiffStream_t tiff_stream	Input	Host	tiff stream handle
nvtiffGeoKey_t key	Input	Host	geo key for which information is retrieved
double *val	Output	Host	Pointer to user allocated buffer containing key values
uint32_t count	Input	Host	Number of values which are required to be copied to `val`
uint32_t index	Input	Host	Index of the starting value to be copied to `val`

Returns:

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

Decode API 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.

When the photometric interpretation of an image is NVTIFF_PHOTOMETRIC_PALETTE or 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:

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 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	`cuda_stream` where all the GPU work will be submitted

Returns:

nvtiffStatus_t - An error code as specified in Decode 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).

When the photometric interpretation of an image is NVTIFF_PHOTOMETRIC_PALETTE or 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:

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 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	`cuda_stream` where all the GPU work will be submitted

Returns:

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

nvtiffDecodeImage()#

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

Signature:

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:

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
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 nvtiffDecodeParamsSetOutputFormat()
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 Decode API Return Status Codes

nvtiffDecodeCheckSupported()#

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

Signature:

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

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

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

Decode Parameters API Reference#

The APIs under this category are used to initialize the decoding parameters as part of the nvtiffDecodeParams_t handle. Once initialized, the handle can be passed as an input to nvtiffDecodeImage()

nvtiffDecodeParamsSetOutputFormat()#

Used to set the decode output format. See Decode Output Format for details. The default value is NVTIFF_OUTPUT_UNCHANGED_I.

Note

When the photometric interpretation is NVTIFF_PHOTOMETRIC_YCBCR and compression is NVTIFF_COMPRESSION_JPEG, output format must be set to either NVTIFF_OUTPUT_RGB_I_UINT8 or NVTIFF_OUTPUT_RGB_I_UINT16.

Note

When the photometric interpretation is NVTIFF_PHOTOMETRIC_MASK, only NVTIFF_OUTPUT_UNCHANGED_I can be used.

When setting the output format to NVTIFF_OUTPUT_UNCHANGED_I-

the size in bytes of the decode output buffer when bits_per_pixel is a multiple 8, should be image_width * image_height * (bits_per_pixel/8)

the size in bytes of the decode output buffer when bits_per_pixel is less than 8, should be (image_width * bits_per_pixel + 7)/8 * image_height

When setting the output to NVTIFF_OUTPUT_RGB_I_UINT8-

the size in bytes of the decode output buffer should be image_width * image_height * 3 * sizeof(uint8_t)

When setting the output to NVTIFF_OUTPUT_RGB_I_UINT16-

the size in bytes of the decode output buffer should be image_width * image_height * 3 * sizeof(uint16_t)

Signature:

nvtiffStatus_t nvtiffDecodeParamsSetOutputFormat(nvtiffDecodeParams_t decode_params,
    nvtiffOutputFormat_t format);

Parameters:

Parameter	Input/Output	Memory	Description
nvtiffDecodeParams_t decode_params	Input/Output	Host	Decode output parameters handle.
nvtiffOutputFormat_t format	Input	Host	Output format value. Defaults to `NVTIFF_OUTPUT_UNCHANGED_I`.

Returns:

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

nvtiffDecodeParamsSetROI()#

Used to set the region of interest for decoding. The entire image is decoded by default.

offset_x and offset_y should be greater than or equal to 0, and cannot exceed image width and height respectively.

offset_x + roi_width and offset_y + roi_height cannot exceed image width and image height respectively.

When image bitdepth is 1, offset_x and roi_width should be a multiple of 8

Signature:

nvjpeg2kStatus_t nvtiffDecodeParamsSetROI(nvtiffDecodeParams_t decode_params,
        int32_t offset_x,
        int32_t offset_y,
        int32_t roi_width,
        int32_t roi_height)

Parameters:

Parameter	Input/Output	Memory	Description
nvtiffDecodeParams_t decode_params	Input/Output	Host	Decode output parameter handle
int32_t offset_x	Input	Host	Image offset along the horizontal direction relative to the top left corner.
int32_t offset_y	Input	Host	Image offset along the vertical direction relative to the top left corner.
int32_t roi_width	Input	Host	Image width relative to offset_x
int32_t roi_height	Input	Host	Image height relative to offset_y

Returns:

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

Encode 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	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)nImagesstripAllocSize 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;

Encode Parameters API Reference#

nvtiffEncodeParamsSetImageInfo()#

Sets image information for encoding.

Signature:

nvtiffStatus_t nvtiffEncodeParamsSetImageInfo(nvtiffEncodeParams_t params,
    const nvtiffImageInfo_t* info)

Parameters:

Parameter	Input/Output	Memory	Description
nvtiffEncodeParams_t params	Input	Host	Encode parameters handle
const nvtiffImageInfo_t* info	Input	Host	Pointer to image information structure

Returns:

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

nvtiffEncodeParamsSetInputs()#

Sets input image pointers for encoding.

Signature:

nvtiffStatus_t nvtiffEncodeParamsSetInputs(nvtiffEncodeParams_t params,
    uint8_t** images_d,
    uint32_t nImages)

Parameters:

Parameter	Input/Output	Memory	Description
nvtiffEncodeParams_t params	Input	Host	Encode parameters handle
uint8_t** images_d	Input	Host	Host array of size nImages of pointers to device buffers
uint32_t nImages	Input	Host	Number of input images

Returns:

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

nvtiffEncodeParamsSetGeoKey()#

Sets a GeoTIFF key with arbitrary type and value.

Signature:

nvtiffStatus_t nvtiffEncodeParamsSetGeoKey(nvtiffEncodeParams_t params,
    nvtiffGeoKey_t key,
    nvtiffGeoKeyDataType_t type,
    void* value,
    uint32_t valueSize,
    uint32_t count)

Parameters:

Parameter	Input/Output	Memory	Description
nvtiffEncodeParams_t params	Input	Host	Encode parameters handle
nvtiffGeoKey_t key	Input	Host	GeoTIFF key to set
nvtiffGeoKeyDataType_t type	Input	Host	Data type of the key value
void* value	Input	Host	Pointer to key value
uint32_t valueSize	Input	Host	Size of individual value in bytes
uint32_t count	Input	Host	Number of values

Returns:

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

nvtiffEncodeParamsSetTag()#

Sets a TIFF tag with specified type and value.

Signature:

nvtiffStatus_t nvtiffEncodeParamsSetTag(nvtiffEncodeParams_t params,
    uint16_t tag,
    nvtiffTagDataType type,
    void* value,
    uint32_t count)

Parameters:

Parameter	Input/Output	Memory	Description
nvtiffEncodeParams_t params	Input	Host	Encode parameters handle
uint16_t tag	Input	Host	TIFF tag to set
nvtiffTagDataType type	Input	Host	Data type of tag value
void* value	Input	Host	Pointer to tag value
uint32_t count	Input	Host	Number of values

Returns:

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

nvtiffEncodeParamsSetGeoKeySHORT()#

Sets a GeoTIFF key with SHORT value type.

Signature:

nvtiffStatus_t nvtiffEncodeParamsSetGeoKeySHORT(nvtiffEncodeParams_t params,
    nvtiffGeoKey_t key,
    uint16_t value,
    uint32_t count)

Parameters:

Parameter	Input/Output	Memory	Description
nvtiffEncodeParams_t params	Input	Host	Encode parameters handle
nvtiffGeoKey_t key	Input	Host	GeoTIFF key to set
uint16_t value	Input	Host	SHORT value to set
uint32_t count	Input	Host	Number of values

Returns:

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

nvtiffEncodeParamsSetGeoKeyDOUBLE()#

Sets a GeoTIFF key with DOUBLE value type.

Signature:

nvtiffStatus_t nvtiffEncodeParamsSetGeoKeyDOUBLE(nvtiffEncodeParams_t params,
    nvtiffGeoKey_t key,
    double value,
    uint32_t count)

Parameters:

Parameter	Input/Output	Memory	Description
nvtiffEncodeParams_t params	Input	Host	Encode parameters handle
nvtiffGeoKey_t key	Input	Host	GeoTIFF key to set
double value	Input	Host	DOUBLE value to set
uint32_t count	Input	Host	Number of values

Returns:

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

nvtiffEncodeParamsSetGeoKeyASCII()#

Sets a GeoTIFF key with ASCII value type.

Signature:

nvtiffStatus_t nvtiffEncodeParamsSetGeoKeyASCII(nvtiffEncodeParams_t params,
    nvtiffGeoKey_t key,
    const char* value,
    uint32_t valueSize)

Parameters:

Parameter	Input/Output	Memory	Description
nvtiffEncodeParams_t params	Input	Host	Encode parameters handle
nvtiffGeoKey_t key	Input	Host	GeoTIFF key to set
const char* value	Input	Host	ASCII string value
uint32_t valueSize	Input	Host	Size of ASCII string including null terminator

Returns:

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

Encode API v2 Reference#

nvtiffEncode()#

Performs asynchronous TIFF encoding of one or more images. We assume parameters have been set using the nvtiffEncodeParamsSetImageInfo and nvtiffEncodeParamsSetInputs functions. If the input images have different dimensions or encode parameters, multiple nvtiffEncodeParams_t objects can be used (that’s why this function takes an array of encode parameters). However, as of the current version (0.5), we only support one encode params object (nParams==1).

If the provided compression method (LZW by default) results in a bitstream larger than the raw input image data, we automatically disable compression.

Signature:

nvtiffStatus_t nvtiffEncode(nvtiffEncoder_t encoder,
    nvtiffEncodeParams_t* params,
    uint32_t nParams,
    cudaStream_t stream)

Parameters:

Parameter	Input/Output	Memory	Description
nvtiffEncoder_t encoder	Input	Host	Encoder handle
nvtiffEncodeParams_t* params	Input	Host	Array of nParams encode parameters
uint32_t nParams	Input	Host	Number of encode parameters in params array. Must be 1 for now.
cudaStream_t stream	Input	Host	CUDA stream

Returns:

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

nvtiffEncodeFinalize()#

Finalizes asynchronous TIFF encoding operation started by nvtiffEncode. This function must be called before the encoded bitstream can be written to host memory or file with nvtiffWriteTiffBuffer or nvtiffWriteTiffFile. The nvtiffWrite* functions perform stream synchronization to make sure the bitstreams are ready, so there is no need for explicit stream synchronization from the user after calling this function.

Signature:

nvtiffStatus_t nvtiffEncodeFinalize(nvtiffEncoder_t encoder,
    nvtiffEncodeParams_t* params,
    uint32_t nParams,
    cudaStream_t stream)

Parameters:

Parameter	Input/Output	Memory	Description
nvtiffEncoder_t encoder	Input	Host	Encoder handle
nvtiffEncodeParams_t* params	Input	Host	Array of nParams encode parameters
uint32_t nParams	Input	Host	Number of encode parameters in params array. Must be 1 for now.
cudaStream_t stream	Input	Host	CUDA stream

Returns:

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

nvtiffGetBitstreamSize()#

Calculates the size of the TIFF metadata and/or compressed bitstream. This function is useful for the user to allocate external buffers to store the encoded TIFF data with nvtiffWriteTiffBuffer. Either of those two output parameters (metadataSize or bitstreamSize) can be NULL, in which case we only calculate the other parameter. metadataSize can be calculated as soon as all parameters are set (even before calling nvtiffEncode), but bitstreamSize can only be calculated after nvtiffEncodeFinalize is called.

Signature:

nvtiffStatus_t nvtiffGetBitstreamSize(nvtiffEncoder_t encoder,
    nvtiffEncodeParams_t* params,
    uint32_t nParams,
    size_t* metadataSize,
    size_t* bitstreamSize)

Parameters:

Parameter	Input/Output	Memory	Description
nvtiffEncoder_t encoder	Input	Host	Encoder handle
nvtiffEncodeParams_t* params	Input	Host	Array of nParams encode parameters
uint32_t nParams	Input	Host	Number of encode parameters in params array. Must be 1 for now.
size_t* metadataSize	Output	Host	Size of TIFF metadata in bytes (can be NULL)
size_t* bitstreamSize	Output	Host	Size of compressed data in bytes (can be NULL)

Returns:

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

nvtiffWriteTiffBuffer()#

Writes complete TIFF data including metadata to a host memory buffer. This function performs stream synchronization internally to make sure the bitstream is ready before writing.

Signature:

nvtiffStatus_t nvtiffWriteTiffBuffer(nvtiffEncoder_t encoder,
    nvtiffEncodeParams_t* params,
    uint32_t nParams,
    uint8_t* buffer,
    size_t size,
    cudaStream_t stream)

Parameters:

Parameter	Input/Output	Memory	Description
nvtiffEncoder_t encoder	Input	Host	Encoder handle
nvtiffEncodeParams_t* params	Input	Host	Array of nParams encode parameters
uint32_t nParams	Input	Host	Number of encode parameters in the params array. Must be 1 for now.
uint8_t* buffer	Output	Host	Buffer to write TIFF data to
size_t size	Input	Host	Size of output buffer in bytes
cudaStream_t stream	Input	Host	CUDA stream

Returns:

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

nvtiffWriteTiffFile()#

Writes complete TIFF data including metadata to a file. This function performs stream synchronization internally to make sure the bitstream is ready before writing.

Signature:

nvtiffStatus_t nvtiffWriteTiffFile(nvtiffEncoder_t encoder,
    nvtiffEncodeParams_t* params,
    uint32_t nParams,
    const char* fname,
    cudaStream_t stream)

Parameters:

Parameter	Input/Output	Memory	Description
nvtiffEncoder_t encoder	Input	Host	Encoder handle
nvtiffEncodeParams_t* params	Input	Host	Array of nParams encode parameters
uint32_t nParams	Input	Host	Number of encode parameters in params array. Must be 1 for now.
const char* fname	Input	Host	Output file
cudaStream_t stream	Input	Host	CUDA stream

Returns:

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