Ogre::StreamSerialiser Class Reference
[Resources]

Utility class providing helper methods for reading / writing structured data held in a DataStream. More...

#include <OgreStreamSerialiser.h>

Inheritance diagram for Ogre::StreamSerialiser:

Classes
struct	Chunk
	Definition of a chunk of data in a file. More...
Public Types
enum	Endian { ENDIAN_AUTO, ENDIAN_BIG, ENDIAN_LITTLE }
	The endianness of files. More...
enum	RealStorageFormat { REAL_FLOAT, REAL_DOUBLE }
	The storage format of Real values. More...
Public Member Functions
	StreamSerialiser (const DataStreamPtr &stream, Endian endianMode=ENDIAN_AUTO, bool autoHeader=true, RealStorageFormat realFormat=REAL_FLOAT)
	Constructor.
virtual	~StreamSerialiser ()
virtual Endian	getEndian () const
	Get the endian mode.
size_t	getCurrentChunkDepth () const
	Report the current depth of the chunk nesting, whether reading or writing.
uint32	getCurrentChunkID () const
	Get the ID of the chunk that's currently being read/written, if any.
size_t	getOffsetFromChunkStart () const
	Get the current byte position relative to the start of the data section of the last chunk that was read or written.
virtual const Chunk *	readChunkBegin ()
	Reads the start of the next chunk in the file.
virtual const Chunk *	readChunkBegin (uint32 id, uint16 maxVersion, const String &msg=StringUtil::BLANK)
	Reads the start of the next chunk so long as it's of a given ID and version.
virtual void	undoReadChunk (uint32 id)
	Call this to 'rewind' the stream to just before the start of the current chunk.
virtual uint32	peekNextChunkID ()
	Call this to 'peek' at the next chunk ID without permanently moving the stream pointer.
virtual void	readChunkEnd (uint32 id)
	Finish the reading of a chunk.
virtual bool	isEndOfChunk (uint32 id)
	Return whether the current data pointer is at the end of the current chunk.
virtual bool	eof () const
	Reports whether the stream is at the end of file.
virtual const Chunk *	getCurrentChunk () const
	Get the definition of the current chunk being read (if any).
virtual void	writeChunkBegin (uint32 id, uint16 version=1)
	Begin writing a new chunk.
virtual void	writeChunkEnd (uint32 id)
	End writing a chunk.
virtual void	writeData (const void *buf, size_t size, size_t count)
	Write arbitrary data to a stream.
template<typename T >
void	write (const T *pT, size_t count=1)
	Catch-all method to write primitive types.
virtual void	write (const Real *val, size_t count=1)
virtual void	write (const Vector2 *vec, size_t count=1)
virtual void	write (const Vector3 *vec, size_t count=1)
virtual void	write (const Vector4 *vec, size_t count=1)
virtual void	write (const Quaternion *q, size_t count=1)
virtual void	write (const Matrix3 *m, size_t count=1)
virtual void	write (const Matrix4 *m, size_t count=1)
virtual void	write (const String *string)
virtual void	write (const AxisAlignedBox *aabb, size_t count=1)
virtual void	write (const Sphere *sphere, size_t count=1)
virtual void	write (const Plane *plane, size_t count=1)
virtual void	write (const Ray *ray, size_t count=1)
virtual void	write (const Radian *angle, size_t count=1)
virtual void	write (const Node *node, size_t count=1)
virtual void	write (const bool *boolean, size_t count=1)
virtual void	readData (void *buf, size_t size, size_t count)
	Read arbitrary data from a stream.
template<typename T >
void	read (T *pT, size_t count=1)
	Catch-all method to read primitive types.
virtual void	read (Real *val, size_t count=1)
virtual void	read (Vector2 *vec, size_t count=1)
	read a Vector3
virtual void	read (Vector3 *vec, size_t count=1)
virtual void	read (Vector4 *vec, size_t count=1)
virtual void	read (Quaternion *q, size_t count=1)
virtual void	read (Matrix3 *m, size_t count=1)
virtual void	read (Matrix4 *m, size_t count=1)
virtual void	read (String *string)
virtual void	read (AxisAlignedBox *aabb, size_t count=1)
virtual void	read (Sphere *sphere, size_t count=1)
virtual void	read (Plane *plane, size_t count=1)
virtual void	read (Ray *ray, size_t count=1)
virtual void	read (Radian *angle, size_t count=1)
virtual void	read (Node *node, size_t count=1)
virtual void	read (bool *val, size_t count=1)
void *	operator new (size_t sz, const char file, int line, const char func)
	operator new, with debug line info
void *	operator new (size_t sz)
void *	operator new (size_t sz, void *ptr)
	placement operator new
void *	operator new[] (size_t sz, const char file, int line, const char func)
	array operator new, with debug line info
void *	operator new[] (size_t sz)
void	operator delete (void *ptr)
void	operator delete (void ptr, void )
void	operator delete (void ptr, const char , int, const char *)
void	operator delete[] (void *ptr)
void	operator delete[] (void ptr, const char , int, const char *)
Static Public Member Functions
static uint32	makeIdentifier (const String &code)
	Pack a 4-character code into a 32-bit identifier.
Protected Types
typedef deque< Chunk * >::type	ChunkStack
Protected Member Functions
virtual Chunk *	readChunkImpl ()
virtual void	writeChunkImpl (uint32 id, uint16 version)
virtual void	readHeader ()
virtual void	writeHeader ()
virtual uint32	calculateChecksum (Chunk *c)
virtual void	checkStream (bool failOnEof=false, bool validateReadable=false, bool validateWriteable=false) const
virtual void	flipEndian (void *pData, size_t size, size_t count)
virtual void	flipEndian (void *pData, size_t size)
virtual void	determineEndianness ()
virtual Chunk *	popChunk (uint id)
virtual void	writeFloatsAsDoubles (const float *val, size_t count)
virtual void	writeDoublesAsFloats (const double *val, size_t count)
virtual void	readFloatsAsDoubles (double *val, size_t count)
virtual void	readDoublesAsFloats (float *val, size_t count)
template<typename T , typename U >
void	writeConverted (const T *src, U typeToWrite, size_t count)
template<typename T , typename U >
void	readConverted (T *dst, U typeToRead, size_t count)
Protected Attributes
DataStreamPtr	mStream
Endian	mEndian
bool	mFlipEndian
bool	mReadWriteHeader
RealStorageFormat	mRealFormat
ChunkStack	mChunkStack
	Current list of open chunks.
Static Protected Attributes
static uint32	HEADER_ID
static uint32	REVERSE_HEADER_ID
static uint32	CHUNK_HEADER_SIZE

Detailed Description

Utility class providing helper methods for reading / writing structured data held in a DataStream.

Remarks:: The structure of a file read / written by this class is a series of 'chunks'. A chunk-based format has the advantage of being extensible later, and it's robust, in that a reader can skip chunks that they are not able (or willing) to process.

: Chunks are contained serially in the file, but they can also be nested in order both to provide context, and to group chunks together for potential skipping.

The data format of a chunk is as follows:

Chunk ID (32-bit uint). This can be any number unique in a context, except the numbers 0x0000, 0x0001 and 0x1000, which are reserved for Ogre's use
Chunk version (16-bit uint). Chunks can change over time so this version number reflects that
Length (32-bit uint). The length of the chunk data section, including nested chunks. Note that this length excludes this header, but includes the header of any nested chunks.
Checksum (32-bit uint). Checksum value generated from the above - basically lets us check this is a valid chunk.
Chunk data The 'Chunk data' section will contain chunk-specific data, which may include other nested chunks.

Definition at line 66 of file OgreStreamSerialiser.h.

Member Typedef Documentation

typedef deque<Chunk*>::type Ogre::StreamSerialiser::ChunkStack [protected]

Definition at line 327 of file OgreStreamSerialiser.h.

Member Enumeration Documentation

enum Ogre::StreamSerialiser::Endian

The endianness of files.

Enumerator:

ENDIAN_AUTO	Automatically determine endianness.
ENDIAN_BIG	Use big endian (0x1000 is serialised as 0x10 0x00).
ENDIAN_LITTLE	Use little endian (0x1000 is serialised as 0x00 0x10).

Definition at line 70 of file OgreStreamSerialiser.h.

enum Ogre::StreamSerialiser::RealStorageFormat

The storage format of Real values.

Enumerator:

REAL_FLOAT	Real is stored as float, reducing precision if you're using OGRE_DOUBLE_PRECISION.
REAL_DOUBLE	Real as stored as double, not useful unless you're using OGRE_DOUBLE_PRECISION.

Definition at line 81 of file OgreStreamSerialiser.h.

Constructor & Destructor Documentation

Ogre::StreamSerialiser::StreamSerialiser	(	const DataStreamPtr &	stream,
		Endian	endianMode = `ENDIAN_AUTO`,
		bool	autoHeader = `true`,
		RealStorageFormat	realFormat = `REAL_FLOAT`
	)

Constructor.

Parameters:

	stream	The stream on which you will read / write data.
	endianMode	The endian mode in which to read / writedata. If left at the default, when writing the endian mode will be the native platform mode, and when reading it's expected that the first chunk encountered will be the header chunk, which will determine the endian mode.
	autoHeader	If true, the first write or read to this stream will automatically read / write the header too. This is required if you set endianMode to ENDIAN_AUTO, but if you manually set the endian mode, then you can skip writing / reading the header if you wish, if for example this stream is midway through a file which has already included header information.
	realFormat	Set the format you want to write reals in. Only useful for files that you're writing (since when reading this is picked up from the file), and can only be changed if autoHeader is true, since real format is stored in the header. Defaults to float unless you're using OGRE_DOUBLE_PRECISION.

virtual Ogre::StreamSerialiser::~StreamSerialiser ( ) [virtual]

Member Function Documentation

virtual uint32 Ogre::StreamSerialiser::calculateChecksum ( Chunk * c ) [protected, virtual]

virtual void Ogre::StreamSerialiser::checkStream	(	bool	failOnEof = `false`,
		bool	validateReadable = `false`,
		bool	validateWriteable = `false`
	)			const `[protected, virtual]`

virtual void Ogre::StreamSerialiser::determineEndianness ( ) [protected, virtual]

virtual bool Ogre::StreamSerialiser::eof ( ) const [virtual]

Reports whether the stream is at the end of file.

virtual void Ogre::StreamSerialiser::flipEndian	(	void *	pData,
		size_t	size
	)			`[protected, virtual]`

virtual void Ogre::StreamSerialiser::flipEndian	(	void *	pData,
		size_t	size,
		size_t	count
	)			`[protected, virtual]`

virtual const Chunk* Ogre::StreamSerialiser::getCurrentChunk ( ) const [virtual]

Get the definition of the current chunk being read (if any).

size_t Ogre::StreamSerialiser::getCurrentChunkDepth ( ) const

Report the current depth of the chunk nesting, whether reading or writing.

Remarks:: Returns how many levels of nested chunks are currently being processed, either writing or reading. In order to tidily finish, you must call read/writeChunkEnd this many times.

Definition at line 153 of file OgreStreamSerialiser.h.

uint32 Ogre::StreamSerialiser::getCurrentChunkID ( ) const

Get the ID of the chunk that's currently being read/written, if any.

Returns:: The id of the current chunk being read / written (at the tightest level of nesting), or zero if no chunk is being processed.

virtual Endian Ogre::StreamSerialiser::getEndian ( ) const [virtual]

Get the endian mode.

Remarks:: If the result is ENDIAN_AUTO, this mode will change when the first piece of data is read / written.

Definition at line 137 of file OgreStreamSerialiser.h.

size_t Ogre::StreamSerialiser::getOffsetFromChunkStart ( ) const

Get the current byte position relative to the start of the data section of the last chunk that was read or written.

Returns:: the offset. Note that a return value of 0 means that either the position is at the start of the chunk data section (ie right after the header), or that no chunk is currently active. Use getCurrentChunkID or getCurrentChunkDepth to determine if a chunk is active.

virtual bool Ogre::StreamSerialiser::isEndOfChunk ( uint32 id ) [virtual]

Return whether the current data pointer is at the end of the current chunk.

Parameters:

id

The id of the chunk that you were reading (for validation purposes)

static uint32 Ogre::StreamSerialiser::makeIdentifier ( const String & code ) [static]

Pack a 4-character code into a 32-bit identifier.

Remarks:: You can use this to generate id's for your chunks based on friendlier 4-character codes rather than assigning numerical IDs, if you like.

Parameters:

code

String to pack - must be 4 characters.

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete	(	void *	ptr,
		const char *	,
		int	,
		const char *
	)			`[inherited]`

Definition at line 107 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete	(	void *	ptr,
		void *
	)			`[inherited]`

Definition at line 101 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete ( void * ptr ) [inherited]

Definition at line 95 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete[]	(	void *	ptr,
		const char *	,
		int	,
		const char *
	)			`[inherited]`

Definition at line 118 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete[] ( void * ptr ) [inherited]

Definition at line 112 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new	(	size_t	sz,
		void *	ptr
	)			`[inherited]`

placement operator new

Definition at line 78 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new ( size_t sz ) [inherited]

Definition at line 72 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new	(	size_t	sz,
		const char *	file,
		int	line,
		const char *	func
	)			`[inherited]`

operator new, with debug line info

Definition at line 67 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new[] ( size_t sz ) [inherited]

Definition at line 90 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new[]	(	size_t	sz,
		const char *	file,
		int	line,
		const char *	func
	)			`[inherited]`

array operator new, with debug line info

Definition at line 85 of file OgreMemoryAllocatedObject.h.

virtual uint32 Ogre::StreamSerialiser::peekNextChunkID ( ) [virtual]

Call this to 'peek' at the next chunk ID without permanently moving the stream pointer.

virtual Chunk* Ogre::StreamSerialiser::popChunk ( uint id ) [protected, virtual]

virtual void Ogre::StreamSerialiser::read	(	bool *	val,
		size_t	count = `1`
	)			`[virtual]`

virtual void Ogre::StreamSerialiser::read	(	Node *	node,
		size_t	count = `1`
	)			`[virtual]`

virtual void Ogre::StreamSerialiser::read	(	Radian *	angle,
		size_t	count = `1`
	)			`[virtual]`

virtual void Ogre::StreamSerialiser::read	(	Ray *	ray,
		size_t	count = `1`
	)			`[virtual]`

virtual void Ogre::StreamSerialiser::read	(	Plane *	plane,
		size_t	count = `1`
	)			`[virtual]`

virtual void Ogre::StreamSerialiser::read	(	Sphere *	sphere,
		size_t	count = `1`
	)			`[virtual]`

virtual void Ogre::StreamSerialiser::read	(	AxisAlignedBox *	aabb,
		size_t	count = `1`
	)			`[virtual]`

virtual void Ogre::StreamSerialiser::read ( String * string ) [virtual]

virtual void Ogre::StreamSerialiser::read	(	Matrix4 *	m,
		size_t	count = `1`
	)			`[virtual]`

virtual void Ogre::StreamSerialiser::read	(	Matrix3 *	m,
		size_t	count = `1`
	)			`[virtual]`

virtual void Ogre::StreamSerialiser::read	(	Quaternion *	q,
		size_t	count = `1`
	)			`[virtual]`

virtual void Ogre::StreamSerialiser::read	(	Vector4 *	vec,
		size_t	count = `1`
	)			`[virtual]`

virtual void Ogre::StreamSerialiser::read	(	Vector3 *	vec,
		size_t	count = `1`
	)			`[virtual]`

virtual void Ogre::StreamSerialiser::read	(	Vector2 *	vec,
		size_t	count = `1`
	)			`[virtual]`

read a Vector3

virtual void Ogre::StreamSerialiser::read	(	Real *	val,
		size_t	count = `1`
	)			`[virtual]`

template<typename T >

void Ogre::StreamSerialiser::read	(	T *	pT,
		size_t	count = `1`
	)

Catch-all method to read primitive types.

Definition at line 297 of file OgreStreamSerialiser.h.

virtual const Chunk* Ogre::StreamSerialiser::readChunkBegin	(	uint32	id,
		uint16	maxVersion,
		const String &	msg = `StringUtil::BLANK`
	)			`[virtual]`

Reads the start of the next chunk so long as it's of a given ID and version.

Remarks:: This method operates like readChunkBegin, except it checks the ID and version.

Parameters:

	id	The ID you're expecting. If the next chunk isn't of this ID, then the chunk read is undone and the method returns null.
	maxVersion	The maximum version you're able to process. If the ID is correct but the version exceeds what is passed in here, the chunk is skipped over, the problem logged and null is returned.
	msg	Descriptive text added to the log if versions are not compatible

Returns:: The chunk if it passes the validation.

virtual const Chunk* Ogre::StreamSerialiser::readChunkBegin ( ) [virtual]

Reads the start of the next chunk in the file.

Remarks:: Files are serialised in a chunk-based manner, meaning that each section of data is prepended by a chunk header. After reading this chunk header, the next set of data is available directly afterwards.

Note:: When you have finished with this chunk, you should call readChunkEnd. This will perform a bit of validation and clear the chunk from the stack.

Returns:: The Chunk that comes next

virtual void Ogre::StreamSerialiser::readChunkEnd ( uint32 id ) [virtual]

Finish the reading of a chunk.

Remarks:: You can call this method at any point after calling readChunkBegin, even if you didn't read all the rest of the data in the chunk. If you did not read to the end of a chunk, this method will automatically skip over the remainder of the chunk and position the stream just after it.

Parameters:

id

The id of the chunk that you were reading (for validation purposes)

virtual Chunk* Ogre::StreamSerialiser::readChunkImpl ( ) [protected, virtual]

template<typename T , typename U >

void Ogre::StreamSerialiser::readConverted	(	T *	dst,
		U	typeToRead,
		size_t	count
	)			`[protected]`

Definition at line 366 of file OgreStreamSerialiser.h.

References Ogre::MEMCATEGORY_GENERAL, OGRE_ALLOC_T, and OGRE_FREE.

virtual void Ogre::StreamSerialiser::readData	(	void *	buf,
		size_t	size,
		size_t	count
	)			`[virtual]`

Read arbitrary data from a stream.

Parameters:

	buf	Pointer to bytes
	size	The size of each element to read; each will be endian-flipped if necessary
	count	The number of elements to read

virtual void Ogre::StreamSerialiser::readDoublesAsFloats	(	float *	val,
		size_t	count
	)			`[protected, virtual]`

virtual void Ogre::StreamSerialiser::readFloatsAsDoubles	(	double *	val,
		size_t	count
	)			`[protected, virtual]`

virtual void Ogre::StreamSerialiser::readHeader ( ) [protected, virtual]

virtual void Ogre::StreamSerialiser::undoReadChunk ( uint32 id ) [virtual]

Call this to 'rewind' the stream to just before the start of the current chunk.

Remarks:: The most common case of wanting to use this is if you'd calledReadChunkBegin(), but the chunk you read wasn't one you wanted to process, and rather than skipping over it (which readChunkEnd() would do), you want to backtrack and give something else an opportunity to read it.

Parameters:

id

The id of the chunk that you were reading (for validation purposes)

virtual void Ogre::StreamSerialiser::write	(	const bool *	boolean,
		size_t	count = `1`
	)			`[virtual]`

virtual void Ogre::StreamSerialiser::write	(	const Node *	node,
		size_t	count = `1`
	)			`[virtual]`

virtual void Ogre::StreamSerialiser::write	(	const Radian *	angle,
		size_t	count = `1`
	)			`[virtual]`

virtual void Ogre::StreamSerialiser::write	(	const Ray *	ray,
		size_t	count = `1`
	)			`[virtual]`

virtual void Ogre::StreamSerialiser::write	(	const Plane *	plane,
		size_t	count = `1`
	)			`[virtual]`

virtual void Ogre::StreamSerialiser::write	(	const Sphere *	sphere,
		size_t	count = `1`
	)			`[virtual]`

virtual void Ogre::StreamSerialiser::write	(	const AxisAlignedBox *	aabb,
		size_t	count = `1`
	)			`[virtual]`

virtual void Ogre::StreamSerialiser::write ( const String * string ) [virtual]

virtual void Ogre::StreamSerialiser::write	(	const Matrix4 *	m,
		size_t	count = `1`
	)			`[virtual]`

virtual void Ogre::StreamSerialiser::write	(	const Matrix3 *	m,
		size_t	count = `1`
	)			`[virtual]`

virtual void Ogre::StreamSerialiser::write	(	const Quaternion *	q,
		size_t	count = `1`
	)			`[virtual]`

virtual void Ogre::StreamSerialiser::write	(	const Vector4 *	vec,
		size_t	count = `1`
	)			`[virtual]`

virtual void Ogre::StreamSerialiser::write	(	const Vector3 *	vec,
		size_t	count = `1`
	)			`[virtual]`

virtual void Ogre::StreamSerialiser::write	(	const Vector2 *	vec,
		size_t	count = `1`
	)			`[virtual]`

virtual void Ogre::StreamSerialiser::write	(	const Real *	val,
		size_t	count = `1`
	)			`[virtual]`

template<typename T >

void Ogre::StreamSerialiser::write	(	const T *	pT,
		size_t	count = `1`
	)

Catch-all method to write primitive types.

Definition at line 263 of file OgreStreamSerialiser.h.

virtual void Ogre::StreamSerialiser::writeChunkBegin	(	uint32	id,
		uint16	version = `1`
	)			`[virtual]`

Begin writing a new chunk.

Remarks:: This starts the process of writing a new chunk to the stream. This will write the chunk header for you, and store a pointer so that the class can automatically go back and fill in the size for you later should you need it to. If you have already begun a chunk without ending it, then this method will start a nested chunk within it. Once written, you can then start writing chunk-specific data into your stream.

Note:: If this is the first chunk in the file

Parameters:

	id	The identifier of the new chunk. Any value that's unique in the file context is valid, except for the numbers 0x0001 and 0x1000 which are reserved for internal header identification use.
	version	The version of the chunk you're writing