Class ZstdCompress

• Defined in File libCZI_compress.h

Class Documentation

class ZstdCompress

The functions found here deal with zstd-compression (the compression-part in particular). Those functions are rather low-level, and the common theme is - given a source bitmap, create a blob (containing the compressed bitmap data) which is suitable to be placed in a subblock’s data. Several overloads are provided, for performance critical scenarios we provide functions which write directly into caller-provided memory, and there are versions which use caller-provided functions for internal allocations. The latter may be beneficial in high-performance scenarios where pre-allocation and buffer-reuse can be leveraged in order to avoid repeated heap-allocations.

Public Static Functions

static size_t CalculateMaxCompressedSizeZStd0(std::uint32_t sourceWidth, std::uint32_t sourceHeight, libCZI::PixelType sourcePixeltype)

Calculates the maximum size which might be required (for the output buffer) when calling into “CompressZStd0”. The guarantee here is : if calling into “CompressZStd0” with an output buffer of the size as determined here, the call will NEVER fail (for insufficient output buffer size). Note that this upper limit may be larger than the actual needed size by a huge factor (10 times or more), and it is of the order of the input size.

Parameters:

• sourceWidth – The width of the bitmap in pixels.

• sourceHeight – The height of the bitmap in pixels.

• sourcePixeltype – The pixeltype of the bitmap.

Returns:

The calculated maximum compressed size.

static bool CompressZStd0(std::uint32_t sourceWidth, std::uint32_t sourceHeight, std::uint32_t sourceStride, libCZI::PixelType sourcePixeltype, const void *source, const std::function<void*(size_t)> &allocateTempBuffer, const std::function<void(void*)> &freeTempBuffer, void *destination, size_t &sizeDestination, const ICompressParameters *parameters)

Compress the specified bitmap in “zstd0”-format. This method will compress the specified source-bitmap according to the “ZEN-zstd0-scheme” to a caller supplied block of memory. If successful, the used size of the memory block is returned, and the data is suitable to be put into a subblock. Details of the operation are:

• (under certain conditions) a temporary buffer is required, the size of this temporary buffer is width*size_of_pixel*height. This method allows to pass

  in functions for allocating/freeing this temp-buffer. For performance reasons, some type of buffer-pooling or reuse can be applied here.

• A pointer to an output buffer must be supplied, and its size is to be given. The required size of the output buffer is in general not known (and

  not knowable) beforehand. It is only possible to query an upper limit for the output-buffer (CalculateMaxCompressedSizeZStd1). If the output buffer size is insufficient, this method return ‘false’.

• On input, the parameter ‘sizeDestination’ gives the size of the output buffer; on return of the function, the value is overwritten with the actual

  used size (which is always less than the size on input).

• There are only two possible outcomes of this function - either the operation completed successfully and returns true, the data is put into the output buffer and

  the argument ‘sizeDestination’ gives the used size in the output buffer. Or, false is returned, meaning that the output buffer size is found to be insufficient - however, note that the required size is not given, so ‘sizeDestination’ is unchanged in this case (and there is no indication about how big an output buffer is required).

• All other error conditions (like e. g. invalid arguments) result in an exception being thrown.

Parameters:

• sourceWidth – Width of the source bitmap in pixels.

• sourceHeight – Height of the source bitmap in pixels.

• sourceStride – The stride of the source bitmap in bytes.

• sourcePixeltype – The pixeltype of the source bitmap.

• source – Pointer to the source bitmap.

• allocateTempBuffer – This functor is called when it is necessary to allocate a temporary buffer. The argument specifies the size in bytes for the buffer. This argument must not be null. If this functor returns null, then this method exception is left with an exception(of type runtime_error).

• freeTempBuffer – This functor is called when the temporary buffer is to be released. It is guaranteed that this free-functor is called for every temp-buffer-allocation before this method returns. This argument must not be null.

• destination – [inout] The pointer to the output buffer.

• sizeDestination – [inout] On input, this gives the size of the destination buffer in bytes. On return of this method (and provided the return value is ‘true’), this gives the actual used size (which is always less or equal to the value on input).

• parameters – Property bag containing parameters controlling the operation. This argument can be null, in which case default parameters are used.

Returns:

True if it succeeds, and in this case the argument ‘sizeDestination’ will contain the size actual used in the output buffer. False is returned in the case that the output buffer size was insufficient.

static std::shared_ptr<IMemoryBlock> CompressZStd0Alloc(std::uint32_t sourceWidth, std::uint32_t sourceHeight, std::uint32_t sourceStride, libCZI::PixelType sourcePixeltype, const void *source, const std::function<void*(size_t)> &allocateTempBuffer, const std::function<void(void*)> &freeTempBuffer, const ICompressParameters *parameters)

Compress the specified bitmap in “zstd0”-format. This method will compress the specified source-bitmap according to the “ZEN-zstd0-scheme” to newly allocated memory, and return a blob of memory containing the data suitable to be put into a subblock. Details of the operation are:

• (under certain conditions) a temporary buffer is required, the size of this temporary buffer is width*size_of_pixel*height. This method allows to pass

  in functions for allocating/freeing this temp-buffer. For performance reasons, some type of buffer-pooling or reuse can be applied here.

• A pointer to an output buffer must be supplied, and its size is to be given. The required size of the output buffer is in general not known (and

  not knowable) beforehand. It is only possible to query an upper limit for the output-buffer (CalculateMaxCompressedSizeZStd1). If the output buffer size is insufficient, this method return ‘false’.

• On input, the parameter ‘sizeDestination’ gives the size of the output buffer; on return of the function, the value is overwritten with the actual

  used size (which is always less than the size on input).

• All error conditions (like e. g. invalid arguments) result in an exception being thrown.

Parameters:

• sourceWidth – Width of the source bitmap in pixels.

• sourceHeight – Height of the source bitmap in pixels.

• sourceStride – The stride of the source bitmap in bytes.

• sourcePixeltype – The pixeltype of the source bitmap.

• source – Pointer to the source bitmap.

• allocateTempBuffer – This functor is called when it is necessary to allocate a temporary buffer. The argument specifies the size in bytes for the buffer. This argument must not be null. If this functor returns null, then this method exception is left with an exception(of type runtime_error).

• freeTempBuffer – This functor is called when the temporary buffer is to be released. It is guaranteed that this free-functor is called for every temp-buffer-allocation before this method returns. This argument must not be null.

• parameters – Property bag containing parameters controlling the operation. This argument can be null, in which case default parameters are used.

Returns:

A shared pointer to an object representing and owning a block of memory.

static bool CompressZStd0(std::uint32_t sourceWidth, std::uint32_t sourceHeight, std::uint32_t sourceStride, libCZI::PixelType sourcePixeltype, const void *source, void *destination, size_t &sizeDestination, const ICompressParameters *parameters)

Compress the specified bitmap in “zstd0”-format. This method will compress the specified source-bitmap according to the “ZEN-zstd0-scheme” to a caller supplied block of memory. If successful, the used size of the memory block is returned, and the data is suitable to be put into a subblock. Details of the operation are:

• (under certain conditions) a temporary buffer is required, and this memory is then allocated internally (and freed) from the standard heap.

• A pointer to an output buffer must be supplied, and its size is to be given. The required size of the output buffer is in general not known (and

  not knowable) beforehand. It is only possible to query an upper limit for the output-buffer (CalculateMaxCompressedSizeZStd1). If the output buffer size is insufficient, this method return ‘false’.

• On input, the parameter ‘sizeDestination’ gives the size of the output buffer; on return of the function, the value is overwritten with the actual

  used size (which is always less than the size on input).

• There are only two possible outcomes of this function - either the operation completed successfully and returns true, the data is put into the output buffer and

  the argument ‘sizeDestination’ gives the used size in the output buffer. Or, false is returned, meaning that the output buffer size is found to be insufficient - however, note that the required size is not given, so ‘sizeDestination’ is unchanged in this case (and there is no indication about how big an output buffer is required).

• All other error conditions (like e. g. invalid arguments) result in an exception being thrown.

Parameters:

• sourceWidth – Width of the source bitmap in pixels.

• sourceHeight – Height of the source bitmap in pixels.

• sourceStride – The stride of the source bitmap in bytes.

• sourcePixeltype – The pixeltype of the source bitmap.

• source – Pointer to the source bitmap.

• destination – [inout] The pointer to the output buffer.

• sizeDestination – [inout] On input, this gives the size of the destination buffer in bytes. On return of this method (and provided the return value is ‘true’), this gives the actual used size (which is always less or equal to the value on input).

• parameters – Property bag containing parameters controlling the operation. This argument can be null, in which case default parameters are used.

Returns:

True if it succeeds, and in this case the argument ‘sizeDestination’ will contain the size actual used in the output buffer. False is returned in the case that the output buffer size was insufficient.

static std::shared_ptr<IMemoryBlock> CompressZStd0Alloc(std::uint32_t sourceWidth, std::uint32_t sourceHeight, std::uint32_t sourceStride, libCZI::PixelType sourcePixeltype, const void *source, const ICompressParameters *parameters)

Compress the specified bitmap in “zstd0”-format. This method will compress the specified source-bitmap according to the “ZEN-zstd0-scheme” to a caller supplied block of memory. If successful, the used size of the memory block is returned, and the data is suitable to be put into a subblock. Details of the operation are:

• (under certain conditions) a temporary buffer is required, and this memory is then allocated internally (and freed) from the standard heap.

• A pointer to an output buffer must be supplied, and its size is to be given. The required size of the output buffer is in general not known (and

  not knowable) beforehand. It is only possible to query an upper limit for the output-buffer (CalculateMaxCompressedSizeZStd1). If the output buffer size is insufficient, this method return ‘false’.

• On input, the parameter ‘sizeDestination’ gives the size of the output buffer; on return of the function, the value is overwritten with the actual

  used size (which is always less than the size on input).

• There are only two possible outcomes of this function - either the operation completed successfully and returns true, the data is put into the output buffer and

  the argument ‘sizeDestination’ gives the used size in the output buffer. Or, false is returned, meaning that the output buffer size is found to be insufficient - however, note that the required size is not given, so ‘sizeDestination’ is unchanged in this case (and there is no indication about how big an output buffer is required).

• All other error conditions (like e. g. invalid arguments) result in an exception being thrown.

Parameters:

• sourceWidth – Width of the source bitmap in pixels.

• sourceHeight – Height of the source bitmap in pixels.

• sourceStride – The stride of the source bitmap in bytes.

• sourcePixeltype – The pixeltype of the source bitmap.

• source – Pointer to the source bitmap.

• parameters – Property bag containing parameters controlling the operation. This argument can be null, in which case default parameters are used.

Returns:

True if it succeeds, and in this case the argument ‘sizeDestination’ will contain the size actual used in the output buffer. False is returned in the case that the output buffer size was insufficient.

static size_t CalculateMaxCompressedSizeZStd1(std::uint32_t sourceWidth, std::uint32_t sourceHeight, libCZI::PixelType sourcePixeltype)

Calculates the maximum size which might be required (for the output buffer) when calling into “CompressZStd0”. The guarantee here is : if calling into “CompressZStd0” with a output buffer of the size as determined here, the call will NEVER fail (for insufficient output buffer size). Note that this upper limit may be larger than the actual needed size by a huge factor (10 times or more), and it is of the order of the input size.

Parameters:

• sourceWidth – The width of the bitmap in pixels.

• sourceHeight – The height of the bitmap in pixels.

• sourcePixeltype – The pixeltype of the bitmap.

Returns:

The calculated maximum compressed size.

static bool CompressZStd1(std::uint32_t sourceWidth, std::uint32_t sourceHeight, std::uint32_t sourceStride, libCZI::PixelType sourcePixeltype, const void *source, const std::function<void*(size_t)> &allocateTempBuffer, const std::function<void(void*)> &freeTempBuffer, void *destination, size_t &sizeDestination, const ICompressParameters *parameters)

Compress the specified bitmap in “zstd1”-format. This method will compress the specified source-bitmap according to the “ZEN-zstd1-scheme” to a caller supplied block of memory. If successful, the used size of the memory block is returned, and the data is suitable to be put into a subblock. Details of the operation are:

• (under certain conditions) a temporary buffer is required, the size of this temporary buffer is width*size_of_pixel*height. This method allows to pass

  in functions for allocating/freeing this temp-buffer. For performance reasons, some type of buffer-pooling or reuse can be applied here.

• A pointer to an output buffer must be supplied, and its size is to be given. The required size of the output buffer is in general not known (and

  not knowable) beforehand. It is only possible to query an upper limit for the output-buffer (CalculateMaxCompressedSizeZStd1). If the output buffer size is insufficient, this method return ‘false’.

• On input, the parameter ‘sizeDestination’ gives the size of the output buffer; on return of the function, the value is overwritten with the actual

  used size (which is always less than the size on input).

• There are only two possible outcomes of this function - either the operation completed successfully and returns true, the data is put into the output buffer and

  the argument ‘sizeDestination’ gives the used size in the output buffer. Or, false is returned, meaning that the output buffer size is found to be insufficient - however, note that the required size is not given, so ‘sizeDestination’ is unchanged in this case (and there is no indication about how big an output buffer is required).

• All other error conditions (like e. g. invalid arguments) result in an exception being thrown.

Parameters:

• sourceWidth – Width of the source bitmap in pixels.

• sourceHeight – Height of the source bitmap in pixels.

• sourceStride – The stride of the source bitmap in bytes.

• sourcePixeltype – The pixeltype of the source bitmap.

• source – Pointer to the source bitmap.

• allocateTempBuffer – This functor is called when it is necessary to allocate a temporary buffer. The argument specifies the size in bytes for the buffer. This argument must not be null. If this functor returns null, then this method exception is left with an exception (of type runtime_error).

• freeTempBuffer – This functor is called when the temporary buffer is to be released. It is guaranteed that this free-functor is called for every temp-buffer-allocation before this method returns. This argument must not be null.

• destination – [inout] The pointer to the output buffer.

• sizeDestination – [inout] On input, this gives the size of the destination buffer in bytes. On return of this method (and provided the return value is ‘true’), this gives the actual used size (which is always less or equal to the value on input).

• parameters – Property bag containing parameters controlling the operation. This argument can be null, in which case default parameters are used.

Returns:

True if it succeeds, and in this case the argument ‘sizeDestination’ will contain the size actual used in the output buffer. False is returned in the case that the output buffer size was insufficient.

static std::shared_ptr<IMemoryBlock> CompressZStd1Alloc(std::uint32_t sourceWidth, std::uint32_t sourceHeight, std::uint32_t sourceStride, libCZI::PixelType sourcePixeltype, const void *source, const std::function<void*(size_t)> &allocateTempBuffer, const std::function<void(void*)> &freeTempBuffer, const ICompressParameters *parameters)

Compress the specified bitmap in “zstd1”-format. This method will compress the specified source-bitmap according to the “ZEN-zstd1-scheme” to newly allocated memory, and return a blob of memory containing the data suitable to be put into a subblock. Details of the operation are: Details of the operation are:

• (under certain conditions) a temporary buffer is required, the size of this temporary buffer is width*size_of_pixel*height. This method allows to pass

  in functions for allocating/freeing this temp-buffer. For performance reasons, some type of buffer-pooling or reuse can be applied here.

• A pointer to an output buffer must be supplied, and its size is to be given. The required size of the output buffer is in general not known (and

  not knowable) beforehand. It is only possible to query an upper limit for the output-buffer (CalculateMaxCompressedSizeZStd1). If the output buffer size is insufficient, this method return ‘false’.

• On input, the parameter ‘sizeDestination’ gives the size of the output buffer; on return of the function, the value is overwritten with the actual

  used size (which is always less than the size on input).

• There are only two possible outcomes of this function - either the operation completed successfully and returns true, the data is put into the output buffer and

  the argument ‘sizeDestination’ gives the used size in the output buffer. Or, false is returned, meaning that the output buffer size is found to be insufficient - however, note that the required size is not given, so ‘sizeDestination’ is unchanged in this case (and there is no indication about how big an output buffer is required).

• All error conditions (like e. g. invalid arguments) result in an exception being thrown.

Parameters:

• sourceWidth – Width of the source bitmap in pixels.

• sourceHeight – Height of the source bitmap in pixels.

• sourceStride – The stride of the source bitmap in bytes.

• sourcePixeltype – The pixeltype of the source bitmap.

• source – Pointer to the source bitmap.

• allocateTempBuffer – This functor is called when it is necessary to allocate a temporary buffer. The argument specifies the size in bytes for the buffer. This argument must not be null. If this functor returns null, then this method exception is left with an exception (of type runtime_error).

• freeTempBuffer – This functor is called when the temporary buffer is to be released. It is guaranteed that this free-functor is called for every temp-buffer-allocation before this method returns. This argument must not be null.

• parameters – Property bag containing parameters controlling the operation. This argument can be null, in which case default parameters are used.

Returns:

A shared pointer to an object representing and owning a block of memory.

static bool CompressZStd1(std::uint32_t sourceWidth, std::uint32_t sourceHeight, std::uint32_t sourceStride, libCZI::PixelType sourcePixeltype, const void *source, void *destination, size_t &sizeDestination, const ICompressParameters *parameters)

Compress the specified bitmap in “zstd1”-format. This method will compress the specified source-bitmap according to the “ZEN-zstd1-scheme” to a caller supplied block of memory. If successful, the used size of the memory block is returned, and the data is suitable to be put into a subblock. Details of the operation are:

• (under certain conditions) a temporary buffer is required, and this memory is then allocated internally (and freed) from the standard heap.

• A pointer to an output buffer must be supplied, and its size is to be given. The required size of the output buffer is in general not known (and

  not knowable) beforehand. It is only possible to query an upper limit for the output-buffer (CalculateMaxCompressedSizeZStd1). If the output buffer size is insufficient, this method return ‘false’.

• On input, the parameter ‘sizeDestination’ gives the size of the output buffer; on return of the function, the value is overwritten with the actual

  used size (which is always less than the size on input).

• There are only two possible outcomes of this function - either the operation completed successfully and returns true, the data is put into the output buffer and

  the argument ‘sizeDestination’ gives the used size in the output buffer. Or, false is returned, meaning that the output buffer size is found to be insufficient - however, note that the required size is not given, so ‘sizeDestination’ is unchanged in this case (and there is no indication about how big an output buffer is required).

• All other error conditions (like e. g. invalid arguments) result in an exception being thrown.

Parameters:

• sourceWidth – Width of the source bitmap in pixels.

• sourceHeight – Height of the source bitmap in pixels.

• sourceStride – The stride of the source bitmap in bytes.

• sourcePixeltype – The pixeltype of the source bitmap.

• source – Pointer to the source bitmap.

• destination – [inout] The pointer to the output buffer.

• sizeDestination – [inout] On input, this gives the size of the destination buffer in bytes. On return of this method (and provided the return value is ‘true’), this gives the actual used size (which is always less or equal to the value on input).

• parameters – Property bag containing parameters controlling the operation. This argument can be null, in which case default parameters are used.

Returns:

True if it succeeds, and in this case the argument ‘sizeDestination’ will contain the size actual used in the output buffer. False is returned in the case that the output buffer size was insufficient.

static std::shared_ptr<IMemoryBlock> CompressZStd1Alloc(std::uint32_t sourceWidth, std::uint32_t sourceHeight, std::uint32_t sourceStride, libCZI::PixelType sourcePixeltype, const void *source, const ICompressParameters *parameters)

Compress the specified bitmap in “zstd1”-format. This method will compress the specified source-bitmap according to the “ZEN-zstd1-scheme” to newly allocated memory, and return a blob of memory containing the data suitable to be put into a subblock. Details of the operation are: Details of the operation are:

• (under certain conditions) a temporary buffer is required, and this memory is then allocated internally (and freed) from the standard heap.

• A pointer to an output buffer must be supplied, and its size is to be given. The required size of the output buffer is in general not known (and

  not knowable) beforehand. It is only possible to query an upper limit for the output-buffer (CalculateMaxCompressedSizeZStd1). If the output buffer size is insufficient, this method return ‘false’.

• On input, the parameter ‘sizeDestination’ gives the size of the output buffer; on return of the function, the value is overwritten with the actual

  used size (which is always less than the size on input).

• There are only two possible outcomes of this function - either the operation completed successfully and returns true, the data is put into the output buffer and

  the argument ‘sizeDestination’ gives the used size in the output buffer. Or, false is returned, meaning that the output buffer size is found to be insufficient - however, note that the required size is not given, so ‘sizeDestination’ is unchanged in this case (and there is no indication about how big an output buffer is required).

• All error conditions (like e. g. invalid arguments) result in an exception being thrown.

Parameters:

• sourceWidth – Width of the source bitmap in pixels.

• sourceHeight – Height of the source bitmap in pixels.

• sourceStride – The stride of the source bitmap in bytes.

• sourcePixeltype – The pixel type of the source bitmap.

• source – Pointer to the source bitmap.

• parameters – Property bag containing parameters controlling the operation. This argument can be null, in which case default parameters are used.

Returns:

A shared pointer to an object representing and owning a block of memory.