StormLib Documentation

To build StormLib using Visual Studio 2008:

1. Download the latest release.
2. Open StormLib_vs08.sln in Visual Studio 2008.
3. Use Build > Batch Build, select all builds of "StormLib", and choose Rebuild.
4. The resulting libraries will be located in .\bin\Win32 and .\bin\x64.

To build and install StormLib on Linux:

1. Clone the repository and checkout the latest release tag.
2. Use CMake to configure and build with shared libraries enabled.
3. Install using sudo.

To produce Debian (.deb) or RPM (.rpm) packages, use cpack from the build directory.

Compilation Note: When including StormLib in your project, ensure you link against storm, z, and bz2.

Header: #include <StormLib.h>

git clone https://github.com/ladislav-zezula/StormLib.git
cd StormLib && git checkout <latest-release-tag>
cmake -B build -D BUILD_SHARED_LIBS=ON
cmake --build build --config Release
sudo cmake --install build

To build StormLib using Visual Studio 2022:

1. Ensure you have the Visual Studio 2017 - Windows XP toolset installed.
2. Download the latest release.
3. Open StormLib.sln in Visual Studio.
4. Use Build > Batch Build, select all builds of "StormLib", and choose Rebuild.
5. The resulting libraries will be located in .\bin\Win32 and .\bin\x64.

Note: If you wish to use a newer toolset (e.g., v143), right-click the solution and select Retarget solution to pick your desired version.

You can build StormLib using CMake from a command prompt. Ensure you load the appropriate Visual Studio environment using vcvarsall.bat before running CMake commands.

For amd64 (64-bit)

"C:/Program Files/Microsoft Visual Studio/2022/Community/VC/Auxiliary/Build/vcvarsall.bat" x64
cmake -G "Visual Studio 17 2022" -B build_amd64 -D BUILD_SHARED_LIBS=ON
cmake --build build --config Release

For x86 (32-bit)

"C:/Program Files/Microsoft Visual Studio/2022/Community/VC/Auxiliary/Build/vcvarsall.bat" x86
cmake -G "Visual Studio 17 2022" -B build_x86 -D BUILD_SHARED_LIBS=ON

To use StormLib in a Windows project, include the main header and link the appropriate library file. The library filename follows the pattern StormLibXYZ.lib where:

• X (Build Type): D for Debug, R for Release
• Y (Character Set): A for ANSI, U for Unicode
• Z (CRT Linkage): S for Static CRT, D for Dynamic CRT

Example: StormLibRUD.lib would be a Release, Unicode build using a Dynamic CRT.

#include <StormLib.h>

Conan can automatically resolve and build dependencies like zlib, bzip2, and libtommath.

Important: You must set -DWITH_BUNDLED_LIBTOMCRYPT=ON because libtomcrypt is not yet available in the Conan Index.

For 32-bit Windows builds: Add -s:h arch=x86 to the conan install command.

conan install . -of build -s build_type=Release --build=missing
cmake -B build -DCMAKE_BUILD_TYPE=Release -DSTORM_USE_BUNDLED_LIBRARIES=OFF -DWITH_BUNDLED_LIBTOMCRYPT=ON -DCMAKE_TOOLCHAIN_FILE=build/conan_toolchain.cmake
cmake --build build --config Release

The following CMake options are available to customize the StormLib build:

Compresses raw audio samples into ADPCM format. The function writes a header containing a zero byte and the compression level, followed by the initial sample values for each channel. It then processes the input buffer, applying compression based on the provided CompressionLevel.

int CompressADPCM(
    void * pvOutBuffer,      // Buffer to store compressed data
    int cbOutBuffer,         // Size of the output buffer in bytes
    void * pvInBuffer,       // Buffer containing raw input samples
    int cbInBuffer,           // Size of the input buffer in bytes
    int ChannelCount,          // Number of audio channels
    int CompressionLevel      // Compression level (affects bit shift)
);

To decompress data, wrap your input buffer in a TInputStream and use the THuffmannTree::Decompress method. The TInputStream handles bit-level reading from a raw byte buffer.

1. Initialize TInputStream with your source buffer and its size.
2. Initialize THuffmannTree with bCompression set to false.
3. Call Decompress providing the destination buffer, destination size, and the input stream.

// Assuming buffers are already allocated
// void* inputBuffer, size_t inputSize, void* outputBuffer, size_t outputSize

TInputStream is(inputBuffer, inputSize);
THuffmannTree tree(false); // false for decompression

unsigned int decompressedBytes = tree.Decompress(outputBuffer, outputSize, &is);

Decompresses ADPCM compressed audio data back into raw samples. It expects the input buffer to contain a header (a zero byte and a bit shift/compression level byte) and the initial sample values for each channel. The function returns the total number of bytes written to the output buffer.

int DecompressADPCM(
    void * pvOutBuffer,      // Buffer to store decompressed samples
    int cbOutBuffer,         // Size of the output buffer in bytes
    void * pvInBuffer,       // Buffer containing compressed ADPCM data
    int cbInBuffer,           // Size of the input buffer in bytes
    int ChannelCount         // Number of audio channels
);

The TInputStream class provides methods to read data at the bit level from a byte buffer, which is essential for decompressing Huffman streams.

• TInputStream(void * pvInBuffer, size_t cbInBuffer): Constructor. Initializes the stream with the input buffer and its size.
• bool Get1Bit(unsigned int & BitValue): Reads a single bit and stores it in BitValue.
• bool Get8Bits(unsigned int & ByteValue): Reads 8 bits and stores them as a byte in ByteValue.
• bool Peek7Bits(unsigned int & Value): Peeks at the next 7 bits without advancing the stream position.
• void SkipBits(unsigned int BitCount): Advances the stream position by BitCount bits.

To compress data, wrap your destination buffer in a TOutputStream and use the THuffmannTree::Compress method. The TOutputStream handles bit-level writing and requires a Flush() call to finalize the stream.

1. Initialize TOutputStream with your destination buffer and its capacity.
2. Initialize THuffmannTree with bCompression set to true.
3. Call Compress providing the output stream, the source buffer, source size, and the DataType.
4. Call TOutputStream::Flush() to ensure all bits are written to the buffer.

// Assuming buffers are already allocated
// void* inputBuffer, int inputSize, void* outputBuffer, size_t outputSize

TOutputStream os(outputBuffer, outputSize);
THuffmannTree tree(true); // true for compression

unsigned int compressedBytes = tree.Compress(&os, inputBuffer, inputSize, DATA_TYPE_GENERAL);
os.Flush();