From b4fcb3daf8b4fe9d2ac7d269f6a83ea8befa3a7d Mon Sep 17 00:00:00 2001 From: Daviw Williams Date: Mon, 4 Mar 2013 15:17:19 +0100 Subject: [PATCH] Added API documentation regarding compression. --- .../include/PolyVoxCore/Compressor.h | 35 ++++++++++++++++++- .../include/PolyVoxCore/MinizCompressor.h | 15 +++++++- .../include/PolyVoxCore/RLECompressor.h | 12 +++++++ .../PolyVoxCore/source/MinizCompressor.cpp | 4 ++- 4 files changed, 63 insertions(+), 3 deletions(-) diff --git a/library/PolyVoxCore/include/PolyVoxCore/Compressor.h b/library/PolyVoxCore/include/PolyVoxCore/Compressor.h index 7006b2e8..510b7e20 100644 --- a/library/PolyVoxCore/include/PolyVoxCore/Compressor.h +++ b/library/PolyVoxCore/include/PolyVoxCore/Compressor.h @@ -35,6 +35,10 @@ namespace PolyVox * The main purpose of this is to allow the user to change the compression algorithm which is used by a LargeVolume, * based on the kind of voxel data it is storing. Users may also wish to use Compressor subclasses in more general * compression-related scenarios but this is not well tested. + * + * If you wish to implement your own compression algorithms for use in PolyVox then you should begin by subclassing this class. + * + * \sa MinizCompressor, RLECompressor */ class Compressor { @@ -49,14 +53,43 @@ namespace PolyVox /// If necessary you can use this as a destination buffer size, though it may be somewhat /// wasteful. It is not guarenteed that compression actually shrinks the data, so the /// worst-case value returned by this function may be bigger than the input size. - /// \param The size of the uncompressed input data + /// + /// \param uUncompressedInputSize The size of the uncompressed input data /// \return The largest possible size of the compressed output data. + /// virtual uint32_t getMaxCompressedSize(uint32_t uUncompressedInputSize) = 0; /// Compresses the data. + /// + /// Performs compression of the data pointed to by pSrcData and stores the result in pDstData. + /// The user is responsible for allocating both buffers and for making sure that the destination + /// buffer is large enough to hold the result. If you don't know how big the compressed data + /// will be (and you probably won't know this) then you can call getMaxCompressedSize() to get + /// an upper bound. The *actual* compressed size is then returned by this function and you can + /// use this to copy your compressed data to a more suitably size buffer. + /// + /// \param pSrcData A pointer to the data to be compressed. + /// \param uSrcLength The length of the data to be compressed. + /// \param pDstData A pointer to the memory where the result should be stored. + /// \param uDstLength The length of the destination buffer (compression will fail if this isn't big enough). + /// \return The size of the resulting compressed data. + /// virtual uint32_t compress(void* pSrcData, uint32_t uSrcLength, void* pDstData, uint32_t uDstLength) = 0; /// Decompresses the data. + /// + /// Performs decompression of the data pointed to by pSrcData and stores the result in pDstData. + /// The user is responsible for allocating both buffers and for making sure that the destination + /// buffer is large enough to hold the result. This means you need to know how large the resulting + /// data might be, so before you compress the data it may be worth storing this information somewhere. + /// The *actual* decompressed size is then returned by this function + /// + /// \param pSrcData A pointer to the data to be decompressed. + /// \param uSrcLength The length of the data to be decompressed. + /// \param pDstData A pointer to the memory where the result should be stored. + /// \param uDstLength The length of the destination buffer (decompression will fail if this isn't big enough). + /// \return The size of the resulting uncompressed data. + /// virtual uint32_t decompress(void* pSrcData, uint32_t uSrcLength, void* pDstData, uint32_t uDstLength) = 0; }; } diff --git a/library/PolyVoxCore/include/PolyVoxCore/MinizCompressor.h b/library/PolyVoxCore/include/PolyVoxCore/MinizCompressor.h index f6a5ed5c..fb2b2473 100644 --- a/library/PolyVoxCore/include/PolyVoxCore/MinizCompressor.h +++ b/library/PolyVoxCore/include/PolyVoxCore/MinizCompressor.h @@ -5,12 +5,25 @@ namespace PolyVox { + /** + * Performs compression of data using the miniz library. + * + * This compressor implements the DEFLATE (http://en.wikipedia.org/wiki/Deflate) compression algorithm via the pubic domain + * 'miniz' library (https://code.google.com/p/miniz/). This is a general purpose compression algorithm, and within PolyVox it + * is intended for situations in which the alternative RLECompressor is not appropriate. It is a good default choice if you + * are not sure which compressor is best for your needs. + * + * \sa RLECompressor + */ class MinizCompressor : public Compressor { public: + /// Constructor MinizCompressor(int iCompressionLevel = 6); // Miniz defines MZ_DEFAULT_LEVEL = 6 so we use the same here + /// Destructor ~MinizCompressor(); - + + // API documentation is in base class and gets inherited by Doxygen. uint32_t getMaxCompressedSize(uint32_t uUncompressedInputSize); uint32_t compress(void* pSrcData, uint32_t uSrcLength, void* pDstData, uint32_t uDstLength); uint32_t decompress(void* pSrcData, uint32_t uSrcLength, void* pDstData, uint32_t uDstLength); diff --git a/library/PolyVoxCore/include/PolyVoxCore/RLECompressor.h b/library/PolyVoxCore/include/PolyVoxCore/RLECompressor.h index 7e75742b..10b52b90 100644 --- a/library/PolyVoxCore/include/PolyVoxCore/RLECompressor.h +++ b/library/PolyVoxCore/include/PolyVoxCore/RLECompressor.h @@ -5,6 +5,15 @@ namespace PolyVox { + /** + * Performs compression of data using Run Length Encoding (RLE). + * + * This compressor is designed for voxel data which contains long runs of the same value. Minecraft-style terrain and other + * cubic-style terrains are likely to fall under this category, whereas density fields for Marching Cubes terrain will not. Please + * see the following article if you want more details of how RLE compression works: http://en.wikipedia.org/wiki/Run-length_encoding + * + * \sa MinizCompressor + */ template class RLECompressor : public Compressor { @@ -14,9 +23,12 @@ namespace PolyVox LengthType length; }; public: + /// Constructor RLECompressor(); + /// Destructor ~RLECompressor(); + // API documentation is in base class and gets inherited by Doxygen. uint32_t getMaxCompressedSize(uint32_t uUncompressedInputSize); uint32_t compress(void* pSrcData, uint32_t uSrcLength, void* pDstData, uint32_t uDstLength); uint32_t decompress(void* pSrcData, uint32_t uSrcLength, void* pDstData, uint32_t uDstLength); diff --git a/library/PolyVoxCore/source/MinizCompressor.cpp b/library/PolyVoxCore/source/MinizCompressor.cpp index af1af34b..4c17ae65 100644 --- a/library/PolyVoxCore/source/MinizCompressor.cpp +++ b/library/PolyVoxCore/source/MinizCompressor.cpp @@ -29,7 +29,9 @@ using namespace std; namespace PolyVox { - // Compression levels: 0-9 are the standard zlib-style levels, 10 is best possible compression (not zlib compatible, and may be very slow) + /// You can specify a compression level when constructing this compressor. This controls the tradeoff between speed and compression + /// rate. Levels 0-9 are the standard zlib-style levels, 10 is best possible compression (not zlib compatible, and may be very slow). + /// \param iCompressionLevel The desired compression level. MinizCompressor::MinizCompressor(int iCompressionLevel) :m_pDeflator(0) {