Documentation
Disclaimer: The API is currently under development and might be subject to slight changes. The general idea is still standing, as described below. Follow the changes in this documentation to stay on top of the newest changes.
Content
Application Programming Interface
The BigWhoop library presents its API as C functions prefixed with bwc_*. The usage for compression and decompression are symmetrized in the sequence of required function calls to set up either direction of the BWC codec.
Compression
Implement the following steps for compressing a floating point data array:
bwc_codec *coder = bwc_alloc_coder(countDim1, countDim2 countDim3, countDim4, nPar, precision);
bwc_stream *stream = bwc_init_stream(orig_in, comp_out, comp);
bwc_create_compression(coder, stream, rate);
size_t compressed_size = bwc_compress(coder, stream);
bwc_free_codec(coder);
The first line allocates an instance coder that holds the settings and operations for compression. The first four function arguments describe the number of elements in each dimension of the original data set, which can have up to four dimensions. Data sets with less than four dimensions pass 1 for the unused dimensionality. The parameter nPar is a count for the number of independent parameters that can be stacked inside the data set. The function argument precision passes the precision of the data set that can take one of three values bwc_precision_half, bwc_precision_single, and bwc_precision_double. After allocation, the coder can be reused for multiple data sets that are described by the same dimensionality, number of parameters, and floating point precision.
The second line initializes the bwc_stream that handles the data set and the resulting compressed bitstream. The incoming pointers orig_in and comp_out must be managed by the user. This way, the BWC can be used on-the-fly for in-memory compression using readily existing pointers and buffers from the user applications. The argument comp is of type bwc_mode and classifies the stream to be input for compression.
The third and fourth lines combine coder and stream to compress the data set with the given rate.
Finally, the coder must be freed.
Advanced Settings
TBA
Decompression
Implement the following steps for decompressing an BWC-compressed data set:
bwc_codec *decoder = bwc_alloc_decoder();
bwc_stream *stream = bwc_init_stream(comp_in, decomp_out, decomp);
bwc_create_decompression(decoder, stream, layer);
bwc_decompress(decoder, stream);
bwc_free_codec(decoder);
Allocation of a bwc_codec for decompression, in the first line, is considerably simpler than for compression because the properties dimensionality, number of parameter, and precision of the original data set is encoded in the header of a compressed bwc_stream.
The second line passes the incoming, compressed stream as the pointer comp_in and provides a user defined buffer decomp_out for the decompressed output. The decomp flag signals the mode of the stream to be decompressed.
The third and fourth line parse and decompress the data choosing a given quality layer.
Finally, the decoder must be freed.