--- libgig/trunk/src/RIFF.h 2007/03/18 07:13:06 1102 +++ libgig/trunk/src/RIFF.h 2008/02/10 16:07:22 1678 @@ -38,6 +38,7 @@ #include #include +#include #include #include @@ -55,14 +56,8 @@ #include #ifdef WIN32 -# include "../win32/libgig_private.h" // like config.h, automatically generated by Dev-C++ # include typedef unsigned int uint; - typedef unsigned char uint8_t; - typedef unsigned short uint16_t; - typedef unsigned int uint32_t; -# define PACKAGE "libgig" -# define VERSION VER_STRING // VER_STRING defined in libgig_private.h #endif // WIN32 #include @@ -82,7 +77,25 @@ #define RIFF_HEADER_SIZE 12 -/** RIFF specific classes and definitions */ +/** + * @brief RIFF specific classes and definitions + * + * The Resource Interchange File Format (RIFF) is a generic tree-structured + * meta-format which stores data in so called "chunks". It can be compared + * to XML, but in contrast to XML, RIFF is entirely binary encoded, that is + * not ASCII based. RIFF is used as basis for many file formats like AVI, + * WAV, DLS and of course the Gigasampler file format. ;-) + * + * RIFF chunks can be seen as containers for data. There are two distinct + * types of chunks: + * + * - @e ordinary @e chunks are the leafs of the data tree which encapsulate + * the actual data of the file (i.e. the sample data of a .wav file) + * + * - @e list @e chunks are the nodes of the data tree which hold an + * arbitrary amount of subchunks (can be both, list chunks and/or ordinary + * chunks) + */ namespace RIFF { /* just symbol prototyping */ @@ -114,7 +127,18 @@ stream_end = 3 } stream_whence_t; - /** Provides convenient methods to access data of RIFF chunks in general. */ + /** Alignment of data bytes in memory (system dependant). */ + typedef enum { + endian_little = 0, + endian_big = 1, + endian_native = 2 + } endian_t; + + /** @brief Ordinary RIFF Chunk + * + * Provides convenient methods to access data of ordinary RIFF chunks + * in general. + */ class Chunk { public: Chunk(File* pFile, unsigned long StartPos, List* Parent); @@ -205,7 +229,11 @@ friend class List; }; - /** Provides convenient methods to access data of RIFF list chunks and their subchunks. */ + /** @brief RIFF List Chunk + * + * Provides convenient methods to access data of RIFF list chunks and + * their subchunks. + */ class List : public Chunk { public: List(File* pFile, unsigned long StartPos, List* Parent); @@ -246,13 +274,19 @@ virtual void __resetPos(); ///< Sets List Chunk's read/write position to zero and causes all sub chunks to do the same. }; - /** Parses arbitrary RIFF files and provides together with it's base classes convenient methods to walk through the RIFF tree. */ + /** @brief RIFF File + * + * Handles arbitrary RIFF files and provides together with its base + * classes convenient methods to walk through, read and modify the + * file's RIFF tree. + */ class File : public List { public: File(uint32_t FileType); File(const String& path); stream_mode_t GetMode(); bool SetMode(stream_mode_t NewMode); + void SetByteOrder(endian_t Endian); String GetFileName(); virtual void Save(); virtual void Save(const String& path); @@ -277,7 +311,7 @@ friend class List; private: stream_mode_t Mode; - ChunkList ResizedChunks; ///< All chunks which have been resized (enlarged / shortened). + std::set ResizedChunks; ///< All chunks which have been resized (enlarged / shortened). unsigned long GetFileSize(); void ResizeFile(unsigned long ulNewSize); @@ -290,7 +324,9 @@ #endif }; - /** Will be thrown whenever an error occurs while parsing a RIFF file. */ + /** + * Will be thrown whenever an error occurs while handling a RIFF file. + */ class Exception { public: String Message;