/[svn]/libgig/trunk/src/RIFF.h
ViewVC logotype

Contents of /libgig/trunk/src/RIFF.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 4093 - (show annotations) (download) (as text)
Mon Feb 12 12:26:06 2024 UTC (11 days, 5 hours ago) by schoenebeck
File MIME type: text/x-c++hdr
File size: 18953 byte(s)
* Move system dependent type and macro definitions into a shared header
  file sysdef.h (fixes compilation error with MSVC).

* Bumped version (4.4.0.svn2).

1 /***************************************************************************
2 * *
3 * libgig - C++ cross-platform Gigasampler format file access library *
4 * *
5 * Copyright (C) 2003-2024 by Christian Schoenebeck *
6 * <cuse@users.sourceforge.net> *
7 * *
8 * This library is free software; you can redistribute it and/or modify *
9 * it under the terms of the GNU General Public License as published by *
10 * the Free Software Foundation; either version 2 of the License, or *
11 * (at your option) any later version. *
12 * *
13 * This library is distributed in the hope that it will be useful, *
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of *
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
16 * GNU General Public License for more details. *
17 * *
18 * You should have received a copy of the GNU General Public License *
19 * along with this library; if not, write to the Free Software *
20 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, *
21 * MA 02111-1307 USA *
22 ***************************************************************************/
23
24 #ifndef __RIFF_H__
25 #define __RIFF_H__
26
27 #include <string>
28 #include <list>
29 #include <map>
30 #include <set>
31 #include <vector>
32 #include <iostream>
33 #include <stdarg.h>
34 #include <thread>
35 #include <mutex>
36 #include <stdio.h>
37
38 #include "sysdef.h"
39
40 #if WORDS_BIGENDIAN
41 # define CHUNK_ID_RIFF 0x52494646
42 # define CHUNK_ID_RIFX 0x52494658
43 # define CHUNK_ID_LIST 0x4C495354
44
45 # define LIST_TYPE_INFO 0x494E464F
46 # define CHUNK_ID_ICMT 0x49434D54
47 # define CHUNK_ID_ICOP 0x49434F50
48 # define CHUNK_ID_ICRD 0x49435244
49 # define CHUNK_ID_IENG 0x49454E47
50 # define CHUNK_ID_INAM 0x494E414D
51 # define CHUNK_ID_IPRD 0x49505244
52 # define CHUNK_ID_ISFT 0x49534654
53
54 # define CHUNK_ID_SMPL 0x736D706C
55
56 #else // little endian
57 # define CHUNK_ID_RIFF 0x46464952
58 # define CHUNK_ID_RIFX 0x58464952
59 # define CHUNK_ID_LIST 0x5453494C
60
61 # define LIST_TYPE_INFO 0x4F464E49
62 # define CHUNK_ID_ICMT 0x544D4349
63 # define CHUNK_ID_ICOP 0x504F4349
64 # define CHUNK_ID_ICRD 0x44524349
65 # define CHUNK_ID_IENG 0x474E4549
66 # define CHUNK_ID_INAM 0x4D414E49
67 # define CHUNK_ID_IPRD 0x44525049
68 # define CHUNK_ID_ISFT 0x54465349
69
70 # define CHUNK_ID_SMPL 0x6C706D73
71
72 #endif // WORDS_BIGENDIAN
73
74 #define CHUNK_HEADER_SIZE(fileOffsetSize) (4 + fileOffsetSize)
75 #define LIST_HEADER_SIZE(fileOffsetSize) (8 + fileOffsetSize)
76 #define RIFF_HEADER_SIZE(fileOffsetSize) (8 + fileOffsetSize)
77
78 /**
79 * @brief RIFF specific classes and definitions
80 *
81 * The Resource Interchange File Format (RIFF) is a generic tree-structured
82 * meta-format which stores data in so called "chunks". It can be compared
83 * to XML, but in contrast to XML, RIFF is entirely binary encoded, that is
84 * not ASCII based. RIFF is used as basis for many file formats like AVI,
85 * WAV, DLS and of course the Gigasampler file format. ;-)
86 *
87 * RIFF chunks can be seen as containers for data. There are two distinct
88 * types of chunks:
89 *
90 * - @e ordinary @e chunks are the leafs of the data tree which encapsulate
91 * the actual data of the file (i.e. the sample data of a .wav file)
92 *
93 * - @e list @e chunks are the nodes of the data tree which hold an
94 * arbitrary amount of subchunks (can be both, list chunks and/or ordinary
95 * chunks)
96 */
97 namespace RIFF {
98
99 /* just symbol prototyping */
100 class Chunk;
101 class List;
102 class File;
103
104 typedef std::string String;
105
106 /** Type used by libgig for handling file positioning during file I/O tasks. */
107 typedef uint64_t file_offset_t;
108
109 /** Whether file stream is open in read or in read/write mode. */
110 enum stream_mode_t {
111 stream_mode_read = 0,
112 stream_mode_read_write = 1,
113 stream_mode_closed = 2
114 };
115
116 /** Current state of the file stream. */
117 enum stream_state_t {
118 stream_ready = 0,
119 stream_end_reached = 1,
120 stream_closed = 2
121 };
122
123 /** File stream position dependent to these relations. */
124 enum stream_whence_t {
125 stream_start = 0,
126 stream_curpos = 1,
127 stream_backward = 2,
128 stream_end = 3
129 };
130
131 /** Alignment of data bytes in memory (system dependant). */
132 enum endian_t {
133 endian_little = 0,
134 endian_big = 1,
135 endian_native = 2
136 };
137
138 /** General RIFF chunk structure of a RIFF file. */
139 enum layout_t {
140 layout_standard = 0, ///< Standard RIFF file layout: First chunk in file is a List chunk which contains all other chunks and there are no chunks outside the scope of that very first (List) chunk.
141 layout_flat = 1 ///< Not a "real" RIFF file: First chunk in file is an ordinary data chunk, not a List chunk, and there might be other chunks after that first chunk.
142 };
143
144 /** Size of RIFF file offsets used in all RIFF chunks' headers. @see File::GetFileOffsetSize() */
145 enum offset_size_t {
146 offset_size_auto = 0, ///< Use 32 bit offsets for files smaller than 4 GB, use 64 bit offsets for files equal or larger than 4 GB.
147 offset_size_32bit = 4, ///< Always use 32 bit offsets (even for files larger than 4 GB).
148 offset_size_64bit = 8 ///< Always use 64 bit offsets (even for files smaller than 4 GB).
149 };
150
151 /**
152 * @brief Used for indicating the progress of a certain task.
153 *
154 * The function pointer argument has to be supplied with a valid
155 * function of the given signature which will then be called on
156 * progress changes. An equivalent progress_t structure will be passed
157 * back as argument to the callback function on each progress change.
158 * The factor field of the supplied progress_t structure will then
159 * reflect the current progress as value between 0.0 and 1.0. You might
160 * want to use the custom field for data needed in your callback
161 * function.
162 */
163 struct progress_t {
164 void (*callback)(progress_t*); ///< Callback function pointer which has to be assigned to a function for progress notification.
165 float factor; ///< Reflects current progress as value between 0.0 and 1.0.
166 void* custom; ///< This pointer can be used for arbitrary data.
167 float __range_min; ///< Only for internal usage, do not modify!
168 float __range_max; ///< Only for internal usage, do not modify!
169 progress_t();
170 std::vector<progress_t> subdivide(int iSubtasks);
171 std::vector<progress_t> subdivide(std::vector<float> vSubTaskPortions);
172 };
173
174 /** @brief Ordinary RIFF Chunk
175 *
176 * Provides convenient methods to access data of ordinary RIFF chunks
177 * in general.
178 */
179 class Chunk {
180 public:
181 Chunk(File* pFile, file_offset_t StartPos, List* Parent);
182 String GetChunkIDString() const;
183 uint32_t GetChunkID() const { return ChunkID; } ///< Chunk ID in unsigned integer representation.
184 File* GetFile() const { return pFile; } ///< Returns pointer to the chunk's File object.
185 List* GetParent() const { return pParent; } ///< Returns pointer to the chunk's parent list chunk.
186 file_offset_t GetSize() const { return ullCurrentChunkSize; } ///< Chunk size in bytes (without header, thus the chunk data body)
187 file_offset_t GetNewSize() const { return ullNewChunkSize; } ///< New chunk size if it was modified with Resize(), otherwise value returned will be equal to GetSize().
188 file_offset_t GetPos() const;
189 file_offset_t GetFilePos() const;
190 file_offset_t SetPos(file_offset_t Where, stream_whence_t Whence = stream_start);
191 file_offset_t RemainingBytes() const;
192 stream_state_t GetState() const;
193 file_offset_t Read(void* pData, file_offset_t WordCount, file_offset_t WordSize);
194 file_offset_t ReadInt8(int8_t* pData, file_offset_t WordCount = 1);
195 file_offset_t ReadUint8(uint8_t* pData, file_offset_t WordCount = 1);
196 file_offset_t ReadInt16(int16_t* pData, file_offset_t WordCount = 1);
197 file_offset_t ReadUint16(uint16_t* pData, file_offset_t WordCount = 1);
198 file_offset_t ReadInt32(int32_t* pData, file_offset_t WordCount = 1);
199 file_offset_t ReadUint32(uint32_t* pData, file_offset_t WordCount = 1);
200 int8_t ReadInt8();
201 uint8_t ReadUint8();
202 int16_t ReadInt16();
203 uint16_t ReadUint16();
204 int32_t ReadInt32();
205 uint32_t ReadUint32();
206 void ReadString(String& s, int size);
207 file_offset_t Write(void* pData, file_offset_t WordCount, file_offset_t WordSize);
208 file_offset_t WriteInt8(int8_t* pData, file_offset_t WordCount = 1);
209 file_offset_t WriteUint8(uint8_t* pData, file_offset_t WordCount = 1);
210 file_offset_t WriteInt16(int16_t* pData, file_offset_t WordCount = 1);
211 file_offset_t WriteUint16(uint16_t* pData, file_offset_t WordCount = 1);
212 file_offset_t WriteInt32(int32_t* pData, file_offset_t WordCount = 1);
213 file_offset_t WriteUint32(uint32_t* pData, file_offset_t WordCount = 1);
214 void* LoadChunkData();
215 void ReleaseChunkData();
216 void Resize(file_offset_t NewSize);
217 virtual ~Chunk();
218 protected:
219 uint32_t ChunkID;
220 file_offset_t ullCurrentChunkSize; /* in bytes */
221 file_offset_t ullNewChunkSize; /* in bytes (if chunk was scheduled to be resized) */
222 List* pParent;
223 File* pFile;
224 file_offset_t ullStartPos; /* actual position in file where chunk data (without header) starts */
225 uint8_t* pChunkData;
226 file_offset_t ullChunkDataSize;
227 struct ChunkPos { /* current read/write position as # of bytes from ulStartPos */
228 file_offset_t ullPos; /* used if File::IsIOPerThread() is false (default) */
229 mutable std::map<std::thread::id,file_offset_t> byThread; /* used if File::IsIOPerThread() is true */
230 mutable std::mutex mutex; /* for protecting concurrent changes on byThread map itself */
231 } chunkPos;
232
233 Chunk(File* pFile);
234 Chunk(File* pFile, List* pParent, uint32_t uiChunkID, file_offset_t ullBodySize);
235 void ReadHeader(file_offset_t filePos);
236 void WriteHeader(file_offset_t filePos);
237 file_offset_t ReadSceptical(void* pData, file_offset_t WordCount, file_offset_t WordSize);
238 inline static String convertToString(uint32_t word) {
239 String result;
240 for (int i = 0; i < 4; i++) {
241 uint8_t byte = *((uint8_t*)(&word) + i);
242 char c = byte;
243 result += c;
244 }
245 return result;
246 }
247 virtual file_offset_t RequiredPhysicalSize(int fileOffsetSize);
248 virtual file_offset_t WriteChunk(file_offset_t ullWritePos, file_offset_t ullCurrentDataOffset, progress_t* pProgress = NULL);
249 virtual void __resetPos(); ///< Sets Chunk's read/write position to zero.
250
251 friend class List;
252 private:
253 file_offset_t& GetPosUnsafeRef();
254 };
255
256 /** @brief RIFF List Chunk
257 *
258 * Provides convenient methods to access data of RIFF list chunks and
259 * their subchunks.
260 */
261 class List : public Chunk {
262 public:
263 List(File* pFile, file_offset_t StartPos, List* Parent);
264 String GetListTypeString() const;
265 uint32_t GetListType() const { return ListType; } ///< Returns unsigned integer representation of the list's ID
266 Chunk* GetSubChunkAt(size_t pos);
267 Chunk* GetSubChunk(uint32_t ChunkID);
268 List* GetSubListAt(size_t pos);
269 List* GetSubList(uint32_t ListType);
270 Chunk* GetFirstSubChunk() LIBGIG_DEPRECATED_API("Use GetSubChunkAt() instead.");
271 Chunk* GetNextSubChunk() LIBGIG_DEPRECATED_API("Use GetSubChunkAt() instead.");
272 List* GetFirstSubList() LIBGIG_DEPRECATED_API("Use GetSubListAt() instead.");
273 List* GetNextSubList() LIBGIG_DEPRECATED_API("Use GetSubListAt() instead.");
274 size_t CountSubChunks();
275 size_t CountSubChunks(uint32_t ChunkID);
276 size_t CountSubLists();
277 size_t CountSubLists(uint32_t ListType);
278 Chunk* AddSubChunk(uint32_t uiChunkID, file_offset_t ullBodySize);
279 List* AddSubList(uint32_t uiListType);
280 void DeleteSubChunk(Chunk* pSubChunk);
281 void MoveSubChunk(Chunk* pSrc, Chunk* pDst); // read API doc comments !!!
282 void MoveSubChunk(Chunk* pSrc, List* pNewParent);
283 virtual ~List();
284 protected:
285 typedef std::map<uint32_t, RIFF::Chunk*> ChunkMap;
286 typedef std::vector<Chunk*> ChunkList;
287 typedef std::set<Chunk*> ChunkSet;
288
289 uint32_t ListType;
290 ChunkList* pSubChunks;
291 ChunkMap* pSubChunksMap;
292 ChunkList::iterator ChunksIterator;
293 ChunkList::iterator ListIterator;
294
295 List(File* pFile);
296 List(File* pFile, List* pParent, uint32_t uiListID);
297 void ReadHeader(file_offset_t filePos);
298 void WriteHeader(file_offset_t filePos);
299 void LoadSubChunks(progress_t* pProgress = NULL);
300 void LoadSubChunksRecursively(progress_t* pProgress = NULL);
301 virtual file_offset_t RequiredPhysicalSize(int fileOffsetSize);
302 virtual file_offset_t WriteChunk(file_offset_t ullWritePos, file_offset_t ullCurrentDataOffset, progress_t* pProgress = NULL);
303 virtual void __resetPos(); ///< Sets List Chunk's read/write position to zero and causes all sub chunks to do the same.
304 void DeleteChunkList();
305 };
306
307 /** @brief RIFF File
308 *
309 * Handles arbitrary RIFF files and provides together with its base
310 * classes convenient methods to walk through, read and modify the
311 * file's RIFF tree.
312 */
313 class File : public List {
314 public:
315 /**
316 * OS dependent type serving as file handle / descriptor for OS
317 * dependent file I/O operations.
318 */
319 #if POSIX
320 typedef int Handle;
321 #elif defined(WIN32)
322 typedef HANDLE Handle;
323 #else
324 typedef FILE* Handle;
325 #endif
326
327 File(uint32_t FileType);
328 File(const String& path);
329 File(const String& path, uint32_t FileType, endian_t Endian, layout_t layout, offset_size_t fileOffsetSize = offset_size_auto);
330 stream_mode_t GetMode() const;
331 bool SetMode(stream_mode_t NewMode);
332 void SetByteOrder(endian_t Endian);
333 String GetFileName() const;
334 void SetFileName(const String& path);
335 Handle FileHandle() const;
336 bool IsNew() const;
337 layout_t GetLayout() const;
338 file_offset_t GetCurrentFileSize() const;
339 file_offset_t GetRequiredFileSize();
340 file_offset_t GetRequiredFileSize(offset_size_t fileOffsetSize);
341 int GetFileOffsetSize() const;
342 int GetRequiredFileOffsetSize();
343 bool IsIOPerThread() const;
344 void SetIOPerThread(bool enable);
345
346 virtual void Save(progress_t* pProgress = NULL);
347 virtual void Save(const String& path, progress_t* pProgress = NULL);
348 virtual ~File();
349 protected:
350 struct HandlePair {
351 Handle hRead; ///< handle / descriptor for reading from file
352 Handle hWrite; ///< handle / descriptor for writing to (some) file
353 stream_mode_t Mode; ///< State of handles (ro, rw, closed).
354 };
355 struct IO : HandlePair {
356 bool isPerThread; ///< Whether SetIOPerThread(true) was called.
357 mutable std::map<std::thread::id,HandlePair> byThread; ///< Optional: Individual file handle pair for each thread separately.
358 mutable std::mutex mutex; ///< For protecting concurrent changes on the @c byThread map itself and replacing handles.
359 } io;
360 String Filename;
361 bool bEndianNative;
362 bool bIsNewFile;
363 layout_t Layout; ///< An ordinary RIFF file is always set to layout_standard.
364 offset_size_t FileOffsetPreference;
365 int FileOffsetSize; ///< Size of file offsets (in bytes) when this file was opened (or saved the last time).
366
367 Handle FileWriteHandle() const;
368 HandlePair FileHandlePair() const;
369
370 friend class Chunk;
371 friend class List;
372 private:
373 void __openExistingFile(const String& path, uint32_t* FileType = NULL);
374 void ResizeFile(file_offset_t ullNewSize);
375 #if POSIX
376 file_offset_t __GetFileSize(int hFile) const;
377 #elif defined(WIN32)
378 file_offset_t __GetFileSize(HANDLE hFile) const;
379 #else
380 file_offset_t __GetFileSize(FILE* hFile) const;
381 #endif
382 int FileOffsetSizeFor(file_offset_t fileSize) const;
383 void Cleanup();
384 HandlePair& FileHandlePairUnsafeRef();
385 bool SetModeInternal(stream_mode_t NewMode, bool* pResetPos);
386 };
387
388 /**
389 * Will be thrown whenever an error occurs while handling a RIFF file.
390 */
391 class Exception {
392 public:
393 String Message;
394
395 Exception(String format, ...);
396 Exception(String format, va_list arg);
397 void PrintMessage();
398 virtual ~Exception() {}
399
400 protected:
401 Exception();
402 static String assemble(String format, va_list arg);
403 };
404
405 String libraryName();
406 String libraryVersion();
407
408 } // namespace RIFF
409 #endif // __RIFF_H__

  ViewVC Help
Powered by ViewVC