From 1a6841c92f78e18e489cb8bdca7caf6d7ddfa974 Mon Sep 17 00:00:00 2001 From: Kari Salminen Date: Fri, 13 Jun 2008 08:28:14 +0000 Subject: More documentation for CineUnpacker-class (Practically done documenting now). Also changed parameter and return value types to a more uniform style (uint16 -> uint, int -> uint where applicable etc). svn-id: r32688 --- engines/cine/unpack.cpp | 18 +++++++++--------- engines/cine/unpack.h | 48 +++++++++++++++++++++++++++++++++++++++--------- 2 files changed, 48 insertions(+), 18 deletions(-) diff --git a/engines/cine/unpack.cpp b/engines/cine/unpack.cpp index a27387a1e3..6c14b1980b 100644 --- a/engines/cine/unpack.cpp +++ b/engines/cine/unpack.cpp @@ -40,8 +40,8 @@ uint32 CineUnpacker::readSource() { return value; } -int CineUnpacker::rcr(int inputCarry) { - int outputCarry = (_chunk32b & 1); +uint CineUnpacker::rcr(bool inputCarry) { + uint outputCarry = (_chunk32b & 1); _chunk32b >>= 1; if (inputCarry) { _chunk32b |= 0x80000000; @@ -49,20 +49,20 @@ int CineUnpacker::rcr(int inputCarry) { return outputCarry; } -int CineUnpacker::nextBit() { - int carry = rcr(0); +uint CineUnpacker::nextBit() { + uint carry = rcr(false); // Normally if the chunk becomes zero then the carry is one as // the end of chunk marker is always the last to be shifted out. if (_chunk32b == 0) { _chunk32b = readSource(); _crc ^= _chunk32b; - carry = rcr(1); // Put the end of chunk marker in the most significant bit + carry = rcr(true); // Put the end of chunk marker in the most significant bit } return carry; } -uint16 CineUnpacker::getBits(byte numBits) { - uint16 c = 0; +uint CineUnpacker::getBits(uint numBits) { + uint c = 0; while (numBits--) { c <<= 1; c |= nextBit(); @@ -70,7 +70,7 @@ uint16 CineUnpacker::getBits(byte numBits) { return c; } -void CineUnpacker::unpackRawBytes(uint16 numBytes) { +void CineUnpacker::unpackRawBytes(uint numBytes) { if (_dst >= _dstEnd || _dst - numBytes + 1 < _dstBegin) { _error = true; return; // Destination pointer is out of bounds for this operation @@ -81,7 +81,7 @@ void CineUnpacker::unpackRawBytes(uint16 numBytes) { } } -void CineUnpacker::copyRelocatedBytes(uint16 offset, uint16 numBytes) { +void CineUnpacker::copyRelocatedBytes(uint offset, uint numBytes) { if (_dst + offset >= _dstEnd || _dst - numBytes + 1 < _dstBegin) { _error = true; return; // Destination pointer is out of bounds for this operation diff --git a/engines/cine/unpack.h b/engines/cine/unpack.h index 5bb7bfc8f9..e16cb594a9 100644 --- a/engines/cine/unpack.h +++ b/engines/cine/unpack.h @@ -39,38 +39,68 @@ namespace Cine { */ class CineUnpacker { public: - /** Returns true if unpacking was successful, otherwise false. */ + /** + * Unpacks packed data from the source buffer to the destination buffer. + * @warning Do NOT call this on data that is not packed. + * @note Source and destination buffer pointers can be the same as long as there's space for the unpacked data. + * @param src Pointer to the source buffer. + * @param srcLen Length of the source buffer. + * @param dst Pointer to the destination buffer. + * @param dstLen Length of the destination buffer. + * @return True if no errors were detected in the source data and unpacking was successful, otherwise false. + */ bool unpack(const byte *src, uint srcLen, byte *dst, uint dstLen); private: - /** Reads a single big endian 32-bit integer from the source and goes backwards 4 bytes. */ + /** + * Reads an unsigned big endian 32-bit integer from the source stream and goes backwards 4 bytes. + * @return If the operation is valid, an unsigned big endian 32-bit integer read from the source stream. + * @return If the operation is invalid, zero. + * @note Sets internal error state if the read operation would be out of source bounds. + */ uint32 readSource(); /** * Shifts the current internal 32-bit chunk to the right by one. * Puts input carry into internal chunk's topmost (i.e. leftmost) bit. - * Returns the least significant bit that was shifted out. + * @return The least significant bit that was shifted out from the chunk. + */ + uint rcr(bool inputCarry); + + /** + * Get the next bit from the source stream. + * @note Changes the bit position in the source stream. + * @return The next bit from the source stream. + */ + uint nextBit(); + + /** + * Get bits from the source stream. + * @note Changes the bit position in the source stream. + * @param numBits Number of bits to read from the source stream. + * @return Integer value consisting of the bits read from the source stream (In range [0, (2 ** numBits) - 1]). + * @return Later the bit was read from the source, the less significant it is in the return value. */ - int rcr(int inputCarry); - int nextBit(); - uint16 getBits(byte numBits); + uint getBits(uint numBits); /** * Copy raw bytes from the input stream and write them to the destination stream. * This is used when no adequately long match is found in the sliding window. + * @note Sets internal error state if the operation would be out of bounds. * @param numBytes Amount of bytes to copy from the input stream */ - void unpackRawBytes(uint16 numBytes); + void unpackRawBytes(uint numBytes); /** * Copy bytes from the sliding window in the destination buffer. * This is used when a match of two bytes or longer is found. + * @note Sets internal error state if the operation would be out of bounds. * @param offset Offset in the sliding window * @param numBytes Amount of bytes to copy */ - void copyRelocatedBytes(uint16 offset, uint16 numBytes); + void copyRelocatedBytes(uint offset, uint numBytes); private: uint32 _crc; //!< Error-detecting code (This should be zero after successful unpacking) - uint32 _chunk32b; //!< The current internal 32-bit chunk + uint32 _chunk32b; //!< The current internal 32-bit chunk of source data byte *_dst; //!< Pointer to the current position in the destination buffer const byte *_src; //!< Pointer to the current position in the source buffer -- cgit v1.2.3