Is this page helpful?

Native API#

This is the Native API reference for the NVIDIA® nvCOMP library.

Note

Disclaimer: Native APIs are experimental and are subject to change in the next nvCOMP releases.

Usage examples#

Bitcomp error-bounded lossy floating-point compression: examples/bitcomp_native_lossy.cu demonstrates the plan-based Native API (create plan → lossy FP32 compress → decompress → verify the delta/2 error bound). See Bitcomp Compression for guidance on modes and lossy compression.
GDeflate CPU compression and decompression: examples/gdeflate_cpu_compression.cu and examples/gdeflate_cpu_decompression.cu.

Bitcomp#

Typedefs

typedef uint16_t half#

typedef struct bitcompContext *bitcompHandle_t#

typedef enum bitcompResult_t bitcompResult_t

typedef enum bitcompDataType_t bitcompDataType_t

typedef enum bitcompAlgorithm_t bitcompAlgorithm_t

Enums

enum bitcompResult_t#

Values:

enumerator BITCOMP_SUCCESS#

enumerator BITCOMP_INVALID_PARAMETER#

enumerator BITCOMP_INVALID_COMPRESSED_DATA#

enumerator BITCOMP_INVALID_ALIGNMENT#

enumerator BITCOMP_INVALID_INPUT_LENGTH#

enumerator BITCOMP_CUDA_KERNEL_LAUNCH_ERROR#

enumerator BITCOMP_CUDA_API_ERROR#

enumerator BITCOMP_UNKNOWN_ERROR#

enum bitcompDataType_t#

Values:

enumerator BITCOMP_UNSIGNED_8BIT#

enumerator BITCOMP_SIGNED_8BIT#

enumerator BITCOMP_UNSIGNED_16BIT#

enumerator BITCOMP_SIGNED_16BIT#

enumerator BITCOMP_UNSIGNED_32BIT#

enumerator BITCOMP_SIGNED_32BIT#

enumerator BITCOMP_UNSIGNED_64BIT#

enumerator BITCOMP_SIGNED_64BIT#

enumerator BITCOMP_FP16_DATA#

enumerator BITCOMP_FP32_DATA#

enumerator BITCOMP_FP64_DATA#

enum bitcompAlgorithm_t#

Values:

enumerator BITCOMP_DEFAULT_ALGO#

enumerator BITCOMP_SPARSE_ALGO#

Functions

bitcompResult_t bitcompCreatePlan( bitcompHandle_t *handle, size_t n, bitcompDataType_t dataType, bitcompMode_t mode, bitcompAlgorithm_t algo, )#

Create a bitcomp plan for compression and decompression, lossy or lossless.

The lossless compression can be used on any data type, viewed as integral type. Choosing the right integral type will have an effect on the compression ratio.

Lossy compression: The lossy compression is only available for floating point data types, and is based on a quantization of the floating point values to integers. The floating point values are divided by the delta provided during the compression, and converted to integers. These integers are then compressed with a lossless encoder. The maximum error between the uncompressed data and the original data is <= delta/2. Values that would overflow during quantization (e.g. large input values and a very small delta), as well as NaN, +Inf, -Inf will be handled correctly by the compression. The integers can be either signed or unsigned.

The same plan can be used on several devices or on the host, but associating the plan with a stream, or turning on remote compression acceleration will make a plan device-specific. Using a plan concurrently on more than one device is not supported.

Parameters:

handle – [out] Handle created.
n – [in] size of the uncompressed data in bytes.
dataType – [in] Datatype of the uncompressed data.
mode – [in] Compression mode, lossless or lossy to signed / lossy to unsigned.
algo – [in] Which compression algorithm to use.

Returns:

Returns BITCOMP_SUCCESS if successful, or an error.

bitcompResult_t bitcompCreatePlanFromCompressedData( bitcompHandle_t *handle, const void *data, )#

Create a handle from existing compressed data.

Parameters:

handle – [out] Handle created.
data – [in] Pointer to the compressed data, from which all the handle parameters will be extracted.

Returns:

Returns BITCOMP_SUCCESS if successful, or an error.

bitcompResult_t bitcompDestroyPlan(bitcompHandle_t handle)#

Destroy an existing bitcomp handle.

Parameters:: handle – [in] Handle to destroy.
Returns:: Returns BITCOMP_SUCCESS if successful, or an error.

bitcompResult_t bitcompSetStream( bitcompHandle_t handle, cudaStream_t stream, )#

Associate a bitcomp handle to a stream. All the subsequent operations will be done in the stream.

Parameters:

handle – [inout] Bitcomp handle
stream – [in] Stream to use.

Returns:

Returns BITCOMP_SUCCESS if successful, or an error.

bitcompResult_t bitcompAccelerateRemoteCompression( bitcompHandle_t handle, )#

Turn on compression acceleration when the compressed output is not in the global memory of the device running the compression (e.g. host pinned memory, or another device’s memory) This is optional and only affects the performance. NOTE: This makes the handle become device-specific. A plan that has this acceleration turned on should always be used on the same device.

Parameters:: handle – [inout] Bitcomp handle.
Returns:: Returns BITCOMP_SUCCESS if successful, or an error.

bitcompResult_t bitcompCompressLossy_fp16( const bitcompHandle_t handle, const half *input, void *output, half delta, )#

Compression for FP16 (half) data, running asynchronously on the device.

Parameters:

handle – [in] Bitcomp handle.
input – [in] Pointer to the uncompressed data. Must be accessible from the device.
output – [out] Pointer to the compressed data. Must be accessible from the device and 64-bit aligned.
delta – [in] Delta used for the integer quantization of the data. The maximum error between the uncompressed data and the original data should be <= delta/2. To ensure this, the delta value is rounded down to the nearest power of two (i.e. no mantissa).

Returns:

Returns BITCOMP_SUCCESS if successful, or an error.

bitcompResult_t bitcompCompressLossy_fp32( const bitcompHandle_t handle, const float *input, void *output, float delta, )#

Compression for 32-bit floating point data, running asynchronously on the device.

Parameters:

handle – [in] Bitcomp handle.
input – [in] Pointer to the uncompressed data. Must be accessible from the device.
output – [out] Pointer to the compressed data. Must be accessible from the device and 64-bit aligned.
delta – [in] Delta used for the integer quantization of the data. The maximum error between the uncompressed data and the original data should be <= delta/2. To ensure this, the delta value is rounded down to the nearest power of two (i.e. no mantissa).

Returns:

Returns BITCOMP_SUCCESS if successful, or an error.

bitcompResult_t bitcompCompressLossy_fp64( const bitcompHandle_t handle, const double *input, void *output, double delta, )#

Compression for 64-bit floating point data, running asynchronously on the device.

Parameters:

handle – [in] Bitcomp handle.
input – [in] Pointer to the uncompressed data. Must be accessible from the device.
output – [out] Pointer to the compressed data. Must be accessible from the device and 64-bit aligned.
delta – [in] Delta used for the integer quantization of the data. The maximum error between the uncompressed data and the original data should be <= delta/2. To ensure this, the delta value is rounded down to the nearest power of two (i.e. no mantissa).

Returns:

Returns BITCOMP_SUCCESS if successful, or an error.

bitcompResult_t bitcompCompressLossless( const bitcompHandle_t handle, const void *input, void *output, )#

bitcompResult_t bitcompUncompress( const bitcompHandle_t handle, const void *input, void *output, )#

Decompression, running asynchronously on the device.

Parameters:

handle – [in] Bitcomp handle.
input – [in] Pointer to the compressed data. Must be accessible from the device and 64-bit aligned.
output – [out] Pointer to where the uncompressed data will be written.

Returns:

Returns BITCOMP_SUCCESS if successful, or an error.

bitcompResult_t bitcompPartialUncompress( const bitcompHandle_t handle, const void *input, void *output, size_t start, size_t length, )#

Partial decompression, running asynchronously on the device.

Parameters:

handle – [in] Bitcomp handle.
input – [in] Pointer to the compressed data. Must be accessible from the device and 64-bit aligned.
output – [out] Pointer to where the partial uncompressed data will be written.
start – [in] Offset in bytes relative to the original uncompressed size where to start decompressing.
length – [in] Length in bytes of the partial decompression.

Returns:

Returns BITCOMP_SUCCESS if successful, or an error.

bitcompResult_t bitcompHostCompressLossy_fp16( const bitcompHandle_t handle, const half *input, void *output, half delta, )#

Lossy compression for FP16 (half) data, running on the host processor. This call is blocking. If a non-NULL stream was set in the handle, this call will synchronize the stream. before compressing the data. All arrays must be device accessible.

Parameters:

handle – [in] Bitcomp handle.
input – [in] Pointer to the uncompressed data. Must be accessible from the host.
output – [out] Pointer to the compressed data. Must be accessible from the host and 64-bit aligned.
delta – [in] Delta used for the integer quantization of the data. The maximum error between the uncompressed data and the original data should be <= delta/2. To ensure this, the delta value is rounded down to the nearest power of two (i.e. no mantissa).

Returns:

Returns BITCOMP_SUCCESS if successful, or an error

bitcompResult_t bitcompHostCompressLossy_fp32( const bitcompHandle_t handle, const float *input, void *output, float delta, )#

Lossy compression for 32-bit floats, running on the host processor. This call is blocking. If a non-NULL stream was set in the handle, this call will synchronize the stream before compressing the data. All arrays must be device accessible.

Parameters:

handle – [in] Bitcomp handle.
input – [in] Pointer to the uncompressed data. Must be accessible from the host.
output – [out] Pointer to the compressed data. Must be accessible from the host and 64-bit aligned.
delta – [in] Delta used for the integer quantization of the data. The maximum error between the uncompressed data and the original data should be <= delta/2. To ensure this, the delta value is rounded down to the nearest power of two (i.e. no mantissa).

Returns:

Returns BITCOMP_SUCCESS if successful, or an error.

bitcompResult_t bitcompHostCompressLossy_fp64( const bitcompHandle_t handle, const double *input, void *output, double delta, )#

Lossy compression for 64-bit floats, running on the host processor. This call is blocking. If a non-NULL stream was set in the handle, this call will synchronize the stream before compressing the data. All arrays must be device accessible.

Parameters:

handle – [in] Bitcomp handle.
input – [in] Pointer to the uncompressed data. Must be accessible from the host.
output – [out] Pointer to the compressed data. Must be accessible from the host and 64-bit aligned.
delta – [in] Delta used for the integer quantization of the data. The maximum error between the uncompressed data and the original data should be <= delta/2. To ensure this, the delta value is rounded down to the nearest power of two (i.e. no mantissa).

Returns:

Returns BITCOMP_SUCCESS if successful, or an error.

bitcompResult_t bitcompHostCompressLossless( const bitcompHandle_t handle, const void *input, void *output, )#

Lossless compression (integral datatypes), running on the host processor. This call is blocking. If a non-NULL stream was set in the handle, this call will synchronize the stream before compressing the data. All arrays must be device accessible.

Parameters:

handle – [in] Bitcomp handle.
input – [in] Pointer to the uncompressed data. Must be accessible from the host.
output – [out] Pointer to the compressed data. Must be accessible from the host and 64-bit aligned.

Returns:

Returns BITCOMP_SUCCESS if successful, or an error.

bitcompResult_t bitcompHostUncompress( const bitcompHandle_t handle, const void *input, void *output, )#

Decompression, running on the host processor. This call is blocking. If a non-NULL stream was set in the handle, this call will synchronize the stream before decompressing the data. All arrays must be device accessible.

Parameters:

handle – [in] Bitcomp handle.
input – [in] Pointer to the compressed data. Must be accessible from the host and 64-bit aligned.
output – [out] Pointer to the uncompressed data. Must be accessible from the host.

Returns:

Returns BITCOMP_SUCCESS if successful, or an error.

bitcompResult_t bitcompHostPartialUncompress( const bitcompHandle_t handle, const void *input, void *output, size_t start, size_t length, )#

Partial decompression, running on the host processor. This call is blocking. If a non-NULL stream was set in the handle, this call will synchronize the stream before decompressing the data. All arrays must be device accessible.

Parameters:

handle – [in] Bitcomp handle.
input – [in] Pointer to the compressed data. Must be accessible from the host and 64-bit aligned.
output – [out] Pointer to where the partial uncompressed data will be written.
start – [in] Offset in bytes relative to the original uncompressed size where to start decompressing.
length – [in] Length in bytes of the partial decompression.

Returns:

Returns BITCOMP_SUCCESS if successful, or an error

size_t bitcompMaxBuflen(size_t nbytes)#

Query the maximum size (worst case scenario) that the compression could generate given an input size.

Parameters:: nbytes – [in] Size of the uncompressed data, in bytes.
Returns:: Returns the maximum size of the compressed data, in bytes.

bitcompResult_t bitcompGetCompressedSize( const void *compressedData, size_t *size, )#

Query the compressed size from a compressed buffer. The pointers don’t have to be device-accessible. This is a blocking call. The compression must have completed before calling this function.

Parameters:

compressedData – [in] Pointer to the compressed data.
size – [out] Size of the compressed data, in bytes.

Returns:

Returns BITCOMP_SUCCESS if successful, or an error.

bitcompResult_t bitcompGetCompressedSizeAsync( const void *compressedData, size_t *size, cudaStream_t stream, )#

Query the compressed size from a compressed buffer, asynchronously. Both pointers must be device-accessible.

Parameters:

compressedData – [in] Pointer to the compressed data.
size – [out] Size of the compressed data, in bytes.
stream – [in] Stream for asynchronous operation.

Returns:

Returns BITCOMP_SUCCESS if successful, or an error.

bitcompResult_t bitcompGetUncompressedSize( const void *compressedData, size_t *size, )#

Query the uncompressed size from a compressed buffer.

Parameters:

compressedData – [in] Pointer to the compressed data buffer, The pointer doesn’t have to be device-accessible.
size – [out] Size of the uncompressed data, in bytes.

Returns:

Returns BITCOMP_SUCCESS if successful, or an error.

bitcompResult_t bitcompGetUncompressedSizeFromHandle( const bitcompHandle_t handle, size_t *bytes, )#

Query the uncompressed size from a handle.

Parameters:

handle – [in] handle.
bytes – [out] Size in bytes of the uncompressed data.

Returns:

Returns BITCOMP_SUCCESS if successful, or an error.

bitcompResult_t bitcompGetDataTypeFromHandle( const bitcompHandle_t handle, bitcompDataType_t *dataType, )#

Query the uncompressed datatype from a handle.

Parameters:

handle – [in] handle.
dataType – [out] Data type of the uncompressed data.

Returns:

Returns BITCOMP_SUCCESS if successful, or an error.

bitcompResult_t bitcompGetCompressedInfo( const void *compressedData, size_t *compressedDataSize, size_t *uncompressedSize, bitcompDataType_t *dataType, bitcompMode_t *mode, bitcompAlgorithm_t *algo, )#

: Query compressed data information.

Parameters:

compressedData – [in] Compressed data pointer. Doesn’t have to be device-accessible.
compressedDataSize – [inout] Takes size of the compressed buffer. Stores actual size of the compressed data If the size of the compressed buffer is smaller than the actual size of the compressed data, BITCOMP_INVALID_PARAMETER will be returned.
uncompressedSize – [out] The size of the uncompressed data in bytes.
dataType – [out] The type of the compressed data.
mode – [out] Compression mode (lossy or lossless).
algo – [out] Bitcomp algorithm used (default, or sparse).

Returns:

Returns BITCOMP_SUCCESS if successful, or an error.

GDeflate CPU#

namespace gdeflate#

Functions

void compressCPUGetMaxOutputChunkSize( size_t max_uncompressed_chunk_bytes, size_t *max_compressed_chunk_bytes, )#

Get the maximum size that a chunk of size at most max_uncompressed_chunk_bytes could compress to. That is, the minimum amount of output memory required to be given compressCPU for each chunk.

Throws:

nvcomp::NVCompException – on error.

Parameters:

max_uncompressed_chunk_bytes – [in] The maximum size of a chunk before compression.
max_compressed_chunk_bytes – [out] The maximum possible compressed size of the chunk.

void compressCPU( const void *const *in_ptr, const size_t *in_bytes, const size_t max_uncompressed_chunk_bytes, size_t batch_size, void *const *out_ptr, size_t *out_bytes, int level = 12, )#

Perform compression on the CPU.

Throws:

nvcomp::NVCompException – on error.

Parameters:

in_ptr – [in] Pointers on the CPU, to uncompressed batched items.
in_bytes – [in] The size of each uncompressed batch item on the CPU.
max_uncompressed_chunk_bytes – [in] The maximum size of an uncompressed chunk in bytes.
batch_size – [in] The number of batch items.
out_ptr – [out] Pointers on the CPU, to the output location for each compressed batch item (output).
out_bytes – [out] The compressed size of each chunk on the CPU (output).
level – [in] The selected compression level (between 0 and 12, both inclusive).

void decompressCPU( const void *const *in_ptr, const size_t *in_bytes, size_t batch_size, void *const *out_ptr, size_t *out_buffer_bytes, size_t *out_bytes, )#

Perform decompression on the CPU.

Throws:

nvcomp::NVCompException – on error.

Parameters:

in_ptr – [in] Pointers on the CPU, to the compressed chunks.
in_bytes – [in] The size of each compressed batch item on the CPU in bytes.
batch_size – [in] The number of batch items.
out_ptr – [out] Pointers on the CPU, indicating where to decompress each chunk (output).
out_buffer_bytes – [in] The size of each output chunk buffer in bytes.
out_bytes – [out] The size of each decompressed batch item on the CPU in bytes. (output).

Variables

static constexpr size_t nvcompGdeflateCPUCompressionMaxAllowedChunkSize = 1u << 16#: The maximum supported uncompressed chunk size in bytes for the Gdeflate CPU compressor.

static constexpr int nvcompGdeflateCPUMinCompressionLevel = 0#: The minimum and maximum compression level allowed for the Gdeflate CPU compressor.

static constexpr int nvcompGdeflateCPUMaxCompressionLevel = 12#

static constexpr size_t nvcompGdeflateCPURequiredCompressionAlignment = 1#: The most restrictive of the minimum alignment requirements for void-type memory buffers used for input and output, passed to compression functions.

Note

In all cases, typed memory buffers must still be aligned to their type’s size, e.g., 4 bytes for int.

static constexpr size_t nvcompGdeflateCPURequiredDecompressionAlignment = 1#: The most restrictive of the minimum alignment requirements for void-type memory buffers used for input and output, passed to decompression functions.

Note

In all cases, typed memory buffers must still be aligned to their type’s size, e.g., 4 bytes for int.

Streaming Gzip#

Functions

nvcompStatus_t nvcompGzipStreamingDecompressGetTempSize( size_t *temp_bytes, )#

Compute the number of bytes to allocate for the decompression workspace.

Parameters:: temp_bytes – [out] Number of bytes needed for scratch space.
Returns:: nvcompSuccess if successful, and an error code otherwise.

nvcompStatus_t nvcompGzipStreamingDecompress( std::istream &input_stream, std::ostream &output_stream, const size_t temp_bytes, void *const device_temp_ptr, cudaStream_t stream, )#

Perform synchronous decompression streaming from stream to stream.

Note

Does not support multi-member gzip streams, i.e., streams containing more than one concatenated gzip member.

Parameters:

input_stream – [in] Input stream with the compressed buffer.
output_stream – [in] Output stream to write the uncompressed buffer.
temp_bytes – [in] Size of internal buffer for scratch space.
device_temp_ptr – [in] Pointer to device memory allocated to store scratch data.
stream – [in] The CUDA stream to operate on.

Returns:

nvcompSuccess if successfully decompressed, and an error code otherwise.

nvcompStatus_t nvcompGzipStreamingGetDecompressSize( std::istream &input_stream, const size_t temp_bytes, void *const device_temp_ptr, size_t *decomp_size, cudaStream_t stream, )#

Determine the total uncompressed size of a gzip stream.

The stream is decompressed in full and the output is discarded, so this costs as much as nvcompGzipStreamingDecompress.

Note

Does not support multi-member gzip streams, i.e., streams containing more than one concatenated gzip member.

Parameters:

input_stream – [in] Input stream with the compressed buffer.
temp_bytes – [in] Size of internal buffer for scratch space.
device_temp_ptr – [in] Pointer to device memory allocated to store scratch data.
decomp_size – [out] Pointer to host-accessible memory allocated to store the total number of uncompressed bytes.
stream – [in] The CUDA stream to operate on.

Returns:

nvcompSuccess if the size was determined, and an error code otherwise.

nvcompStatus_t nvcompGzipStreamingCompressGetTempSize( nvcompBatchedGzipCompressOpts_t opts, size_t *temp_bytes, )#

Compute the number of device bytes to allocate for the compression workspace.

Parameters:

opts – [in] Compression options (see nvcompBatchedGzipCompressOpts_t) applied to every window.
temp_bytes – [out] Number of device bytes needed for scratch space.

Returns:

nvcompSuccess if successful, and an error code otherwise.

nvcompStatus_t nvcompGzipStreamingCompress( std::istream &input_stream, std::ostream &output_stream, const size_t temp_bytes, void *const device_temp_ptr, nvcompBatchedGzipCompressOpts_t opts, cudaStream_t stream, )#

Perform synchronous compression streaming from stream to stream.

Parameters:

input_stream – [in] Input stream with the uncompressed buffer.
output_stream – [in] Output stream to write the compressed (gzip) buffer.
temp_bytes – [in] Size of the device scratch space (>= nvcompGzipStreamingCompressGetTempSize).
device_temp_ptr – [in] Pointer to device memory allocated to store scratch data.
opts – [in] Compression options (see nvcompBatchedGzipCompressOpts_t) applied to every window.
stream – [in] The CUDA stream to operate on.

Returns:

nvcompSuccess if successfully compressed, and an error code otherwise.