source: OGRE/trunk/ogrenew/OgreMain/include/OgreDataStream.h @ 692

Revision 692, 15.4 KB checked in by mattausch, 19 years ago (diff)

adding ogre 1.2 and dependencies

RevLine 
[692]1/*
2-----------------------------------------------------------------------------
3This source file is part of OGRE
4(Object-oriented Graphics Rendering Engine)
5For the latest info, see http://www.ogre3d.org/
6
7Copyright (c) 2000-2005 The OGRE Team
8Also see acknowledgements in Readme.html
9
10This program is free software; you can redistribute it and/or modify it under
11the terms of the GNU Lesser General Public License as published by the Free Software
12Foundation; either version 2 of the License, or (at your option) any later
13version.
14
15This program is distributed in the hope that it will be useful, but WITHOUT
16ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
17FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
18
19You should have received a copy of the GNU Lesser General Public License along with
20this program; if not, write to the Free Software Foundation, Inc., 59 Temple
21Place - Suite 330, Boston, MA 02111-1307, USA, or go to
22http://www.gnu.org/copyleft/lesser.txt.
23-----------------------------------------------------------------------------
24*/
25#ifndef __DataStream_H__
26#define __DataStream_H__
27
28#include "OgrePrerequisites.h"
29#include "OgreString.h"
30#include "OgreSharedPtr.h"
31#include <istream>
32
33namespace Ogre {
34
35        /** General purpose class used for encapsulating the reading of data.
36        @remarks
37                This class performs basically the same tasks as std::basic_istream,
38                except that it does not have any formatting capabilities, and is
39                designed to be subclassed to receive data from multiple sources,
40                including libraries which have no compatiblity with the STL's
41                stream interfaces. As such, this is an abstraction of a set of
42                wrapper classes which pretend to be standard stream classes but
43                can actually be implemented quite differently.
44        @par
45                Generally, if a plugin or application provides an ArchiveFactory,
46                it should also provide a DataStream subclass which will be used
47                to stream data out of that Archive implementation, unless it can
48                use one of the common implementations included.
49        @note
50                Ogre makes no guarantees about thread safety, for performance reasons.
51                If you wish to access stream data asynchronously then you should
52                organise your own mutexes to avoid race conditions.
53        */
54        class _OgreExport DataStream
55        {
56        protected:
57                /// The name (e.g. resource name) that can be used to identify the source fot his data (optional)
58                String mName;           
59        /// Size of the data in the stream (may be 0 if size cannot be determined)
60        size_t mSize;
61        #define OGRE_STREAM_TEMP_SIZE 128
62        /// Temporary buffer area used for formatted read
63        char mTmpArea[OGRE_STREAM_TEMP_SIZE];
64        public:
65                /// Constructor for creating unnamed streams
66        DataStream() : mSize(0) {}
67                /// Constructor for creating named streams
68                DataStream(const String& name) : mName(name), mSize(0) {}
69                /// Returns the name of the stream, if it has one.
70                const String& getName(void) { return mName; }
71        virtual ~DataStream() {}
72                // Streaming operators
73        template<typename T> DataStream& operator>>(T& val);
74                /** Read the requisite number of bytes from the stream,
75                        stopping at the end of the file.
76                @param buf Reference to a buffer pointer
77                @param count Number of bytes to read
78                @returns The number of bytes read
79                */
80                virtual size_t read(void* buf, size_t count) = 0;
81                /** Get a single line from the stream.
82                @remarks
83                        The delimiter character is not included in the data
84                        returned, and it is skipped over so the next read will occur
85                        after it. The buffer contents will include a
86                        terminating character.
87                @param buf Reference to a buffer pointer
88                @param maxCount The maximum length of data to be read, excluding the terminating character
89                @param delim The delimiter to stop at
90                @returns The number of bytes read, excluding the terminating character
91                */
92                virtual size_t readLine(char* buf, size_t maxCount, const String& delim = "\n") = 0;
93               
94            /** Returns a String containing the next line of data, optionally
95                    trimmed for whitespace.
96            @remarks
97                    This is a convenience method for text streams only, allowing you to
98                    retrieve a String object containing the next line of data. The data
99                    is read up to the next newline character and the result trimmed if
100                    required.
101            @param
102                    trimAfter If true, the line is trimmed for whitespace (as in
103                    String.trim(true,true))
104            */
105            virtual String getLine( bool trimAfter = true );
106
107            /** Returns a String containing the entire stream.
108            @remarks
109                    This is a convenience method for text streams only, allowing you to
110                    retrieve a String object containing all the data in the stream.
111            */
112            virtual String getAsString(void);
113
114                /** Skip a single line from the stream.
115                @param delim The delimiter(s) to stop at
116                @returns The number of bytes skipped
117                */
118                virtual size_t skipLine(const String& delim = "\n") = 0;
119
120                /** Skip a defined number of bytes. This can also be a negative value, in which case
121                the file pointer rewinds a defined number of bytes. */
122                virtual void skip(long count) = 0;
123       
124                /** Repositions the read point to a specified byte.
125            */
126            virtual void seek( size_t pos ) = 0;
127               
128                /** Returns the current byte offset from beginning */
129            virtual size_t tell(void) const = 0;
130
131                /** Returns true if the stream has reached the end.
132            */
133            virtual bool eof(void) const = 0;
134
135                /** Returns the total size of the data to be read from the stream,
136                        or 0 if this is indeterminate for this stream.
137                */
138        size_t size(void) const { return mSize; }
139
140        /** Close the stream; this makes further operations invalid. */
141        virtual void close(void) = 0;
142               
143
144        };
145
146        /** Shared pointer to allow data streams to be passed around without
147                worrying about deallocation
148        */
149        typedef SharedPtr<DataStream> DataStreamPtr;
150
151        /// List of DataStream items
152        typedef std::list<DataStreamPtr> DataStreamList;
153        /// Shared pointer to list of DataStream items
154        typedef SharedPtr<DataStreamList> DataStreamListPtr;
155
156        /** Common subclass of DataStream for handling data from chunks of memory.
157        */
158        class _OgreExport MemoryDataStream : public DataStream
159        {
160        protected:
161        /// Pointer to the start of the data area
162            uchar* mData;
163        /// Pointer to the current position in the memory
164            uchar* mPos;
165        /// Pointer to the end of the memory
166            uchar* mEnd;
167        /// Do we delete the memory on close
168                bool mFreeOnClose;                     
169        public:
170               
171                /** Wrap an existing memory chunk in a stream.
172                @param pMem Pointer to the exising memory
173                @param size The size of the memory chunk in bytes
174                @param freeOnClose If true, the memory associated will be destroyed
175                        when the stream is destroyed.
176                */
177                MemoryDataStream(void* pMem, size_t size, bool freeOnClose = false);
178               
179                /** Wrap an existing memory chunk in a named stream.
180                @param name The name to give the stream
181                @param pMem Pointer to the exising memory
182                @param size The size of the memory chunk in bytes
183                @param freeOnClose If true, the memory associated will be destroyed
184                        when the stream is destroyed.
185                */
186                MemoryDataStream(const String& name, void* pMem, size_t size,
187                                bool freeOnClose = false);
188
189                /** Create a stream which pre-buffers the contents of another stream.
190                @remarks
191                        This constructor can be used to intentionally read in the entire
192                        contents of another stream, copying them to the internal buffer
193                        and thus making them available in memory as a single unit.
194                @param sourceStream Another DataStream which will provide the source
195                        of data
196                @param freeOnClose If true, the memory associated will be destroyed
197                        when the stream is destroyed.
198                */
199                MemoryDataStream(DataStream& sourceStream,
200                                bool freeOnClose = true);
201               
202                /** Create a stream which pre-buffers the contents of another stream.
203                @remarks
204                        This constructor can be used to intentionally read in the entire
205                        contents of another stream, copying them to the internal buffer
206                        and thus making them available in memory as a single unit.
207                @param sourceStream Weak reference to another DataStream which will provide the source
208                        of data
209                @param freeOnClose If true, the memory associated will be destroyed
210                        when the stream is destroyed.
211                */
212                MemoryDataStream(DataStreamPtr& sourceStream,
213                                bool freeOnClose = true);
214
215                /** Create a named stream which pre-buffers the contents of
216                        another stream.
217                @remarks
218                        This constructor can be used to intentionally read in the entire
219                        contents of another stream, copying them to the internal buffer
220                        and thus making them available in memory as a single unit.
221                @param name The name to give the stream
222                @param sourceStream Another DataStream which will provide the source
223                        of data
224                @param freeOnClose If true, the memory associated will be destroyed
225                        when the stream is destroyed.
226                */
227                MemoryDataStream(const String& name, DataStream& sourceStream,
228                                bool freeOnClose = true);
229
230        /** Create a named stream which pre-buffers the contents of
231        another stream.
232        @remarks
233        This constructor can be used to intentionally read in the entire
234        contents of another stream, copying them to the internal buffer
235        and thus making them available in memory as a single unit.
236        @param name The name to give the stream
237        @param sourceStream Another DataStream which will provide the source
238        of data
239        @param freeOnClose If true, the memory associated will be destroyed
240        when the stream is destroyed.
241        */
242        MemoryDataStream(const String& name, const DataStreamPtr& sourceStream,
243            bool freeOnClose = true);
244
245        /** Create a stream with a brand new empty memory chunk.
246                @param size The size of the memory chunk to create in bytes
247                @param freeOnClose If true, the memory associated will be destroyed
248                        when the stream is destroyed.
249                */
250                MemoryDataStream(size_t size, bool freeOnClose = true);
251                /** Create a named stream with a brand new empty memory chunk.
252                @param name The name to give the stream
253                @param size The size of the memory chunk to create in bytes
254                @param freeOnClose If true, the memory associated will be destroyed
255                        when the stream is destroyed.
256                */
257                MemoryDataStream(const String& name, size_t size,
258                                bool freeOnClose = true);
259
260                ~MemoryDataStream();
261
262                /** Get a pointer to the start of the memory block this stream holds. */
263                uchar* getPtr(void) { return mData; }
264               
265                /** Get a pointer to the current position in the memory block this stream holds. */
266                uchar* getCurrentPtr(void) { return mPos; }
267               
268                /** @copydoc DataStream::read
269                */
270                size_t read(void* buf, size_t count);
271                /** @copydoc DataStream::readLine
272                */
273                size_t readLine(char* buf, size_t maxCount, const String& delim = "\n");
274               
275                /** @copydoc DataStream::skipLine
276                */
277                size_t skipLine(const String& delim = "\n");
278
279                /** @copydoc DataStream::skip
280                */
281                void skip(long count);
282       
283                /** @copydoc DataStream::seek
284                */
285            void seek( size_t pos );
286               
287                /** @copydoc DataStream::tell
288                */
289            size_t tell(void) const;
290
291                /** @copydoc DataStream::eof
292                */
293            bool eof(void) const;
294
295        /** @copydoc DataStream::close
296        */
297        void close(void);
298
299                /** Sets whether or not to free the encapsulated memory on close. */
300                void setFreeOnClose(bool free) { mFreeOnClose = free; }
301        };
302
303    /** Shared pointer to allow memory data streams to be passed around without
304    worrying about deallocation
305    */
306    typedef SharedPtr<MemoryDataStream> MemoryDataStreamPtr;
307
308    /** Common subclass of DataStream for handling data from
309                std::basic_istream.
310        */
311        class _OgreExport FileStreamDataStream : public DataStream
312        {
313        protected:
314                /// Reference to source stream
315                std::ifstream* mpStream;
316        bool mFreeOnClose;                     
317        public:
318                /** Construct stream from an STL stream
319        @param s Pointer to source stream
320        @param freeOnClose Whether to delete the underlying stream on
321            destruction of this class
322        */
323                FileStreamDataStream(std::ifstream* s,
324            bool freeOnClose = true);
325                /** Construct named stream from an STL stream
326        @param name The name to give this stream
327        @param s Pointer to source stream
328        @param freeOnClose Whether to delete the underlying stream on
329            destruction of this class
330        */
331                FileStreamDataStream(const String& name,
332            std::ifstream* s,
333            bool freeOnClose = true);
334
335                /** Construct named stream from an STL stream, and tell it the size
336        @remarks
337            This variant tells the class the size of the stream too, which
338            means this class does not need to seek to the end of the stream
339            to determine the size up-front. This can be beneficial if you have
340            metadata about the contents of the stream already.
341        @param name The name to give this stream
342        @param s Pointer to source stream
343        @param size Size of the stream contents in bytes
344        @param freeOnClose Whether to delete the underlying stream on
345            destruction of this class
346        */
347                FileStreamDataStream(const String& name,
348            std::ifstream* s,
349            size_t size,
350            bool freeOnClose = true);
351
352        ~FileStreamDataStream();
353
354                /** @copydoc DataStream::read
355                */
356                size_t read(void* buf, size_t count);
357                /** @copydoc DataStream::readLine
358                */
359        size_t readLine(char* buf, size_t maxCount, const String& delim = "\n");
360               
361                /** @copydoc DataStream::skipLine
362                */
363                size_t skipLine(const String& delim = "\n");
364
365                /** @copydoc DataStream::skip
366                */
367                void skip(long count);
368       
369                /** @copydoc DataStream::seek
370                */
371            void seek( size_t pos );
372
373                /** @copydoc DataStream::tell
374                */
375                size_t tell(void) const;
376
377                /** @copydoc DataStream::eof
378                */
379            bool eof(void) const;
380
381        /** @copydoc DataStream::close
382        */
383        void close(void);
384               
385               
386        };
387
388        /** Common subclass of DataStream for handling data from C-style file
389                handles.
390    @remarks
391        Use of this class is generally discouraged; if you want to wrap file
392        access in a DataStream, you should definitely be using the C++ friendly
393        FileStreamDataStream. However, since there are quite a few applications
394        and libraries still wedded to the old FILE handle access, this stream
395        wrapper provides some backwards compatibility.
396        */
397        class _OgreExport FileHandleDataStream : public DataStream
398        {
399        protected:
400                FILE* mFileHandle;
401        public:
402                /// Create stream from a C file handle
403                FileHandleDataStream(FILE* handle);
404                /// Create named stream from a C file handle
405                FileHandleDataStream(const String& name, FILE* handle);
406        ~FileHandleDataStream();
407
408                /** @copydoc DataStream::read
409                */
410                size_t read(void* buf, size_t count);
411                /** @copydoc DataStream::readLine
412                */
413                size_t readLine(char* buf, size_t maxCount, const String& delim = "\n");
414               
415                /** @copydoc DataStream::skipLine
416                */
417                size_t skipLine(const String& delim = "\n");
418
419                /** @copydoc DataStream::skip
420                */
421                void skip(long count);
422       
423                /** @copydoc DataStream::seek
424                */
425            void seek( size_t pos );
426
427                /** @copydoc DataStream::tell
428                */
429                size_t tell(void) const;
430
431                /** @copydoc DataStream::eof
432                */
433            bool eof(void) const;
434
435        /** @copydoc DataStream::close
436        */
437        void close(void);
438
439        };
440}
441#endif
442
Note: See TracBrowser for help on using the repository browser.