G3D::BinaryOutput Class Reference

Sequential or random access byte-order independent binary file access. More...

Public Member Functions
	BinaryOutput ()
	You must call setEndian() if you use this (memory) constructor. More...
	BinaryOutput (const String &filename, G3DEndian fileEndian)
	Doesn't actually open the file; commit() does that. More...
	~BinaryOutput ()
void	beginBits ()
	Call before a series of BinaryOutput::writeBits calls. More...
void	commit (bool flush=true)
	Write the bytes to disk. More...
void	commit (uint8 *)
	Write the bytes to memory (which must be of at least size() bytes). More...
void	compress (int level=9)
	Compresses the data in the buffer in place, preceeding it with a little-endian uint32 indicating the uncompressed size. More...
void	endBits ()
	Call after a series of BinaryOutput::writeBits calls. More...
G3DEndian	endian () const
const uint8 *	getCArray () const
	Returns a pointer to the internal memory buffer. More...
String	getFilename () const
int64	length () const
bool	ok () const
	True if no errors have been encountered. More...
int64	position () const
	Returns the current byte position in the file, where 0 is the beginning and getLength() - 1 is the end. More...
void	reset ()
	A memory BinaryOutput may be reset so that it can be written to again without allocating new memory. More...
void	setEndian (G3DEndian fileEndian)
void	setLength (int64 n)
	Sets the length of the file to n, padding with 0's past the current end. More...
void	setPosition (int64 p)
	Sets the position. More...
int64	size () const
void	skip (int n)
	Skips ahead n bytes. More...
void	writeBits (uint32 bitString, int numBits)
	Write numBits from bitString to the output stream. More...
void	writeBool8 (bool b)
void	writeBool8 (const bool *out, int n)
void	writeBool8 (const std::vector< bool > &out, int n)
void	writeBool8 (const Array< bool > &out, int n)
void	writeBytes (const void *b, size_t count)
void	writeColor3 (const Color3 &v)
void	writeColor4 (const Color4 &v)
void	writeFloat32 (float32 f)
void	writeFloat32 (const std::vector< float32 > &out, int n)
void	writeFloat32 (const float32 *out, int n)
void	writeFloat32 (const Array< float32 > &out, int n)
void	writeFloat64 (float64 f)
void	writeFloat64 (const float64 *out, int n)
void	writeFloat64 (const std::vector< float64 > &out, int n)
void	writeFloat64 (const Array< float64 > &out, int n)
void	writeInt16 (int16 i)
void	writeInt16 (const Array< int16 > &out, int n)
void	writeInt16 (const int16 *out, int n)
void	writeInt16 (const std::vector< int16 > &out, int n)
void	writeInt32 (int32 i)
void	writeInt32 (const int32 *out, int n)
void	writeInt32 (const std::vector< int32 > &out, int n)
void	writeInt32 (const Array< int32 > &out, int n)
void	writeInt64 (int64 i)
void	writeInt64 (const int64 *out, int n)
void	writeInt64 (const std::vector< int64 > &out, int n)
void	writeInt64 (const Array< int64 > &out, int n)
void	writeInt8 (int8 i)
	Writes a signed 8-bit integer to the current position. More...
void	writeInt8 (const Array< int8 > &out, int n)
void	writeInt8 (const int8 *out, int n)
void	writeInt8 (const std::vector< int8 > &out, int n)
void	writeString (const String &s)
	Write a string with nullptr termination. More...
void	writeString (const String &s, int len)
	Write a string that always consumes len bytes, truncating or padding as necessary. More...
void	writeString (const char *s)
void	writeString32 (const char *s)
void	writeString32 (const String &s)
	Write a nullptr-terminated string with a 32-bit length field in front of it. More...
void	writeStringEven (const String &s)
	Write a string, ensuring that the total length including nullptr is even. More...
void	writeStringEven (const char *s)
void	writeUInt16 (uint16 u)
void	writeUInt16 (const std::vector< uint16 > &out, int n)
void	writeUInt16 (const Array< uint16 > &out, int n)
void	writeUInt16 (const uint16 *out, int n)
void	writeUInt32 (uint32 u)
void	writeUInt32 (const std::vector< uint32 > &out, int n)
void	writeUInt32 (const uint32 *out, int n)
void	writeUInt32 (const Array< uint32 > &out, int n)
void	writeUInt64 (uint64 u)
void	writeUInt64 (const uint64 *out, int n)
void	writeUInt64 (const Array< uint64 > &out, int n)
void	writeUInt64 (const std::vector< uint64 > &out, int n)
void	writeUInt8 (uint8 i)
void	writeUInt8 (const uint8 *out, int n)
void	writeUInt8 (const std::vector< uint8 > &out, int n)
void	writeUInt8 (const Array< uint8 > &out, int n)
void	writeUNorm8 (unorm8 i)
void	writeVector2 (const Vector2 &v)
void	writeVector3 (const Vector3 &v)
void	writeVector4 (const Vector4 &v)

Detailed Description

Sequential or random access byte-order independent binary file access.

The compress() call can be used to compress with zlib.

Any method call can trigger an out of memory error (thrown as char*) when writing to "<memory>" instead of a file.

Compressed writing and seeking backwards is not supported for huge files (i.e., BinaryOutput may have to dump the contents to disk if they exceed available RAM).

Constructor & Destructor Documentation

BinaryOutput() [1/2]

G3D::BinaryOutput::BinaryOutput

(

)

You must call setEndian() if you use this (memory) constructor.

BinaryOutput() [2/2]

G3D::BinaryOutput::BinaryOutput	(	const String &	filename,
		G3DEndian	fileEndian
	)

Doesn't actually open the file; commit() does that.

Use "<memory>" as the filename if you're going to commit to memory.

~BinaryOutput()

G3D::BinaryOutput::~BinaryOutput

(

)

Member Function Documentation

beginBits()

void G3D::BinaryOutput::beginBits

(

)

Call before a series of BinaryOutput::writeBits calls.

Only writeBits can be called between beginBits and endBits without corrupting the stream.

commit() [1/2]

void G3D::BinaryOutput::commit

(

bool

flush = true

)

Write the bytes to disk.

It is ok to call this multiple times; it will just overwrite the previous file.

Parent directories are created as needed if they do not exist.

Not called from the destructor; you must call it yourself.

Parameters

flush

If true (default) the file is ready for reading when the method returns, otherwise the method returns immediately and writes the file in the background.

String exception will be thrown for file write failure.

commit() [2/2]

void G3D::BinaryOutput::commit

(

uint8 *

)

Write the bytes to memory (which must be of at least size() bytes).

compress()

void G3D::BinaryOutput::compress

(

int

level = 9

)

Compresses the data in the buffer in place, preceeding it with a little-endian uint32 indicating the uncompressed size.

Call immediately before commit().

Cannot be used for huge files (ones where the data was already written to disk)– will throw char*.

Parameters

level

Compression level. 0 = fast, low compression; 9 = slow, high compression

endBits()

void G3D::BinaryOutput::endBits

(

)

Call after a series of BinaryOutput::writeBits calls.

This will finish out with zeros the last byte into which bits were written.

endian()

G3DEndian G3D::BinaryOutput::endian ( ) const

inline

getCArray()

const uint8* G3D::BinaryOutput::getCArray ( ) const

inline

Returns a pointer to the internal memory buffer.

getFilename()

String G3D::BinaryOutput::getFilename ( ) const

inline

length()

int64 G3D::BinaryOutput::length ( ) const

inline

Referenced by size().

ok()

bool G3D::BinaryOutput::ok

(

)

const

True if no errors have been encountered.

position()

int64 G3D::BinaryOutput::position ( ) const

inline

Returns the current byte position in the file, where 0 is the beginning and getLength() - 1 is the end.

reset()

void G3D::BinaryOutput::reset

(

)

A memory BinaryOutput may be reset so that it can be written to again without allocating new memory.

The underlying array will not be deallocated, but the reset structure will act like a newly intialized one.

setEndian()

void G3D::BinaryOutput::setEndian

(

G3DEndian

fileEndian

)

setLength()

void G3D::BinaryOutput::setLength ( int64  n )

inline

Sets the length of the file to n, padding with 0's past the current end.

Does not change the position of the next byte to be written unless n < size().

Throws char* when resetting a huge file to be shorter than its current length.

Referenced by setPosition(), and skip().

setPosition()

void G3D::BinaryOutput::setPosition ( int64  p )

inline

Sets the position.

Can set past length, in which case the file is padded with zeros up to one byte before the next to be written.

May throw a char* exception when seeking backwards on a huge file.

size()

int64 G3D::BinaryOutput::size ( ) const

inline

Referenced by G3D::serializeMessage().

skip()

void G3D::BinaryOutput::skip ( int  n )

inline

Skips ahead n bytes.

writeBits()

void G3D::BinaryOutput::writeBits	(	uint32	bitString,
		int	numBits
	)

Write numBits from bitString to the output stream.

Bits are numbered from low to high.

Can only be called between beginBits and endBits. Bits written are semantically little-endian, regardless of the actual endian-ness of the system. That is, writeBits(0xABCD, 16) writes 0xCD to the first byte and 0xAB to the second byte. However, if used with BinaryInput::readBits, the ordering is transparent to the caller.

writeBool8() [1/4]

void G3D::BinaryOutput::writeBool8 ( bool  b )

inline

Referenced by G3D::serialize().

writeBool8() [2/4]

void G3D::BinaryOutput::writeBool8	(	const bool *	out,
		int	n
	)

writeBool8() [3/4]

void G3D::BinaryOutput::writeBool8	(	const std::vector< bool > &	out,
		int	n
	)

writeBool8() [4/4]

void G3D::BinaryOutput::writeBool8	(	const Array< bool > &	out,
		int	n
	)

writeBytes()

void G3D::BinaryOutput::writeBytes ( const void *  b, size_t  count  )

inline

Referenced by writeString().

writeColor3()

void G3D::BinaryOutput::writeColor3

(

const Color3 &

v

)

writeColor4()

void G3D::BinaryOutput::writeColor4

(

const Color4 &

v

)

writeFloat32() [1/4]

void G3D::BinaryOutput::writeFloat32 ( float32  f )

inline

Referenced by G3D::serialize(), G3D::BumpMap::Settings::serialize(), G3D::PointKDTree< T, PositionFunc, HashFunc, EqualsFunc >::Node::serializeStructure(), and G3D::KDTree< T, BoundsFunc, HashFunc, EqualsFunc >::Node::serializeStructure().

writeFloat32() [2/4]

void G3D::BinaryOutput::writeFloat32	(	const float32 *	out,
		int	n
	)

writeFloat32() [3/4]

void G3D::BinaryOutput::writeFloat32	(	const std::vector< float32 > &	out,
		int	n
	)

writeFloat32() [4/4]

void G3D::BinaryOutput::writeFloat32	(	const Array< float32 > &	out,
		int	n
	)

writeFloat64() [1/4]

void G3D::BinaryOutput::writeFloat64 ( float64  f )

inline

Referenced by G3D::serialize().

writeFloat64() [2/4]

void G3D::BinaryOutput::writeFloat64	(	const float64 *	out,
		int	n
	)

writeFloat64() [3/4]

void G3D::BinaryOutput::writeFloat64	(	const Array< float64 > &	out,
		int	n
	)

writeFloat64() [4/4]

void G3D::BinaryOutput::writeFloat64	(	const std::vector< float64 > &	out,
		int	n
	)

writeInt16() [1/4]

void G3D::BinaryOutput::writeInt16 ( int16  i )

inline

writeInt16() [2/4]

void G3D::BinaryOutput::writeInt16	(	const int16 *	out,
		int	n
	)

writeInt16() [3/4]

void G3D::BinaryOutput::writeInt16	(	const std::vector< int16 > &	out,
		int	n
	)

writeInt16() [4/4]

void G3D::BinaryOutput::writeInt16	(	const Array< int16 > &	out,
		int	n
	)

writeInt32() [1/4]

void G3D::BinaryOutput::writeInt32 ( int32  i )

inline

Referenced by G3D::serialize(), G3D::BumpMap::Settings::serialize(), G3D::GKeySym::serialize(), and G3D::GKey::serialize().

writeInt32() [2/4]

void G3D::BinaryOutput::writeInt32	(	const Array< int32 > &	out,
		int	n
	)

writeInt32() [3/4]

void G3D::BinaryOutput::writeInt32	(	const int32 *	out,
		int	n
	)

writeInt32() [4/4]

void G3D::BinaryOutput::writeInt32	(	const std::vector< int32 > &	out,
		int	n
	)

writeInt64() [1/4]

void G3D::BinaryOutput::writeInt64 ( int64  i )

inline

writeInt64() [2/4]

void G3D::BinaryOutput::writeInt64	(	const int64 *	out,
		int	n
	)

writeInt64() [3/4]

void G3D::BinaryOutput::writeInt64	(	const std::vector< int64 > &	out,
		int	n
	)

writeInt64() [4/4]

void G3D::BinaryOutput::writeInt64	(	const Array< int64 > &	out,
		int	n
	)

writeInt8() [1/4]

void G3D::BinaryOutput::writeInt8 ( int8  i )

inline

Writes a signed 8-bit integer to the current position.

Referenced by writeBool8().

writeInt8() [2/4]

void G3D::BinaryOutput::writeInt8	(	const int8 *	out,
		int	n
	)

writeInt8() [3/4]

void G3D::BinaryOutput::writeInt8	(	const std::vector< int8 > &	out,
		int	n
	)

writeInt8() [4/4]

void G3D::BinaryOutput::writeInt8	(	const Array< int8 > &	out,
		int	n
	)

writeString() [1/3]

void G3D::BinaryOutput::writeString ( const String &  s )

inline

Write a string with nullptr termination.

Referenced by writeString().

writeString() [2/3]

void G3D::BinaryOutput::writeString ( const String &  s, int  len  )

inline

Write a string that always consumes len bytes, truncating or padding as necessary.

writeString() [3/3]

void G3D::BinaryOutput::writeString

(

const char *

s

)

writeString32() [1/2]

void G3D::BinaryOutput::writeString32

(

const char *

s

)

Referenced by G3D::serialize(), and writeString32().

writeString32() [2/2]

void G3D::BinaryOutput::writeString32 ( const String &  s )

inline

Write a nullptr-terminated string with a 32-bit length field in front of it.

The nullptr character is included in the length count.

writeStringEven() [1/2]

void G3D::BinaryOutput::writeStringEven ( const String &  s )

inline

Write a string, ensuring that the total length including nullptr is even.

writeStringEven() [2/2]

void G3D::BinaryOutput::writeStringEven

(

const char *

s

)

writeUInt16() [1/4]

void G3D::BinaryOutput::writeUInt16

(

uint16

u

)

Referenced by G3D::GKeySym::serialize(), and writeInt16().

writeUInt16() [2/4]

void G3D::BinaryOutput::writeUInt16	(	const Array< uint16 > &	out,
		int	n
	)

writeUInt16() [3/4]

void G3D::BinaryOutput::writeUInt16	(	const uint16 *	out,
		int	n
	)

writeUInt16() [4/4]

void G3D::BinaryOutput::writeUInt16	(	const std::vector< uint16 > &	out,
		int	n
	)

writeUInt32() [1/4]

void G3D::BinaryOutput::writeUInt32

(

uint32

u

)

Referenced by G3D::serialize(), G3D::serializeMessage(), writeFloat32(), and writeInt32().

writeUInt32() [2/4]

void G3D::BinaryOutput::writeUInt32	(	const uint32 *	out,
		int	n
	)

writeUInt32() [3/4]

void G3D::BinaryOutput::writeUInt32	(	const Array< uint32 > &	out,
		int	n
	)

writeUInt32() [4/4]

void G3D::BinaryOutput::writeUInt32	(	const std::vector< uint32 > &	out,
		int	n
	)

writeUInt64() [1/4]

void G3D::BinaryOutput::writeUInt64

(

uint64

u

)

Referenced by writeFloat64(), and writeInt64().

writeUInt64() [2/4]

void G3D::BinaryOutput::writeUInt64	(	const uint64 *	out,
		int	n
	)

writeUInt64() [3/4]

void G3D::BinaryOutput::writeUInt64	(	const std::vector< uint64 > &	out,
		int	n
	)

writeUInt64() [4/4]

void G3D::BinaryOutput::writeUInt64	(	const Array< uint64 > &	out,
		int	n
	)

writeUInt8() [1/4]

void G3D::BinaryOutput::writeUInt8 ( uint8  i )

inline

Referenced by G3D::GKeySym::serialize(), G3D::PointKDTree< T, PositionFunc, HashFunc, EqualsFunc >::Node::serializeStructure(), G3D::KDTree< T, BoundsFunc, HashFunc, EqualsFunc >::Node::serializeStructure(), writeString(), and writeUNorm8().

writeUInt8() [2/4]

void G3D::BinaryOutput::writeUInt8	(	const uint8 *	out,
		int	n
	)

writeUInt8() [3/4]

void G3D::BinaryOutput::writeUInt8	(	const std::vector< uint8 > &	out,
		int	n
	)

writeUInt8() [4/4]

void G3D::BinaryOutput::writeUInt8	(	const Array< uint8 > &	out,
		int	n
	)

writeUNorm8()

void G3D::BinaryOutput::writeUNorm8 ( unorm8  i )

inline

writeVector2()

void G3D::BinaryOutput::writeVector2

(

const Vector2 &

v

)

writeVector3()

void G3D::BinaryOutput::writeVector3

(

const Vector3 &

v

)

writeVector4()

void G3D::BinaryOutput::writeVector4

(

const Vector4 &

v

)