G3D::BinaryInput Class Reference

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

Public Member Functions
	BinaryInput (const std::string &filename, G3DEndian fileEndian, bool compressed=false)
	If the file cannot be opened, a zero length buffer is presented.
	BinaryInput (const uint8 *data, int64 dataLen, G3DEndian dataEndian, bool compressed=false, bool copyMemory=true)
	Creates input stream from an in memory source.
virtual	~BinaryInput ()
void	beginBits ()
	Prepares for bit reading via readBits.
void	endBits ()
	Ends bit-reading.
G3DEndian	endian () const
const uint8 *	getCArray ()
	Returns a pointer to the internal memory buffer.
std::string	getFilename () const
int64	getLength () const
	Returns the length of the file in bytes.
int64	getPosition () const
	Returns the current byte position in the file, where 0 is the beginning and getLength() - 1 is the end.
bool	hasMore () const
	Returns true if the position is not at the end of the file.
uint8	operator[] (int64 n)
	Performs bounds checks in debug mode.
uint32	readBits (int numBits)
	Can only be called between beginBits and endBits.
bool	readBool8 ()
void	readBool8 (bool *out, int64 n)
void	readBool8 (std::vector< bool > &out, int64 n)
void	readBool8 (Array< bool > &out, int64 n)
void	readBytes (void *bytes, int64 n)
Color3	readColor3 ()
Color4	readColor4 ()
std::string	readFixedLengthString (int numBytes)
	Read a string (which may contain NULLs) of exactly numBytes bytes, including the final terminator if there is one.
float32	readFloat32 ()
void	readFloat32 (float32 *out, int64 n)
void	readFloat32 (std::vector< float32 > &out, int64 n)
void	readFloat32 (Array< float32 > &out, int64 n)
float64	readFloat64 ()
void	readFloat64 (std::vector< float64 > &out, int64 n)
void	readFloat64 (float64 *out, int64 n)
void	readFloat64 (Array< float64 > &out, int64 n)
int16	readInt16 ()
void	readInt16 (int16 *out, int64 n)
void	readInt16 (std::vector< int16 > &out, int64 n)
void	readInt16 (Array< int16 > &out, int64 n)
int32	readInt32 ()
void	readInt32 (Array< int32 > &out, int64 n)
void	readInt32 (int32 *out, int64 n)
void	readInt32 (std::vector< int32 > &out, int64 n)
int64	readInt64 ()
void	readInt64 (int64 *out, int64 n)
void	readInt64 (Array< int64 > &out, int64 n)
void	readInt64 (std::vector< int64 > &out, int64 n)
int8	readInt8 ()
void	readInt8 (Array< int8 > &out, int64 n)
void	readInt8 (int8 *out, int64 n)
void	readInt8 (std::vector< int8 > &out, int64 n)
std::string	readString (int64 maxLength)
	Always consumes maxLength characters.
std::string	readString ()
	Reads a string until NULL or end of file.
std::string	readString32 ()
	Reads a uint32 and then calls readString(maxLength) with that value as the length.
std::string	readStringEven ()
	Reads until NULL or the end of the file is encountered.
std::string	readStringNewline ()
	Reads a string until NULL, newline ("&#92;r", "&#92;n", "&#92;r&#92;n", "&#92;n&#92;r") or the end of the file is encountered.
uint16	readUInt16 ()
void	readUInt16 (std::vector< uint16 > &out, int64 n)
void	readUInt16 (uint16 *out, int64 n)
void	readUInt16 (Array< uint16 > &out, int64 n)
uint32	readUInt32 ()
void	readUInt32 (std::vector< uint32 > &out, int64 n)
void	readUInt32 (Array< uint32 > &out, int64 n)
void	readUInt32 (uint32 *out, int64 n)
uint64	readUInt64 ()
void	readUInt64 (uint64 *out, int64 n)
void	readUInt64 (std::vector< uint64 > &out, int64 n)
void	readUInt64 (Array< uint64 > &out, int64 n)
uint8	readUInt8 ()
void	readUInt8 (Array< uint8 > &out, int64 n)
void	readUInt8 (std::vector< uint8 > &out, int64 n)
void	readUInt8 (uint8 *out, int64 n)
unorm8	readUNorm8 ()
Vector2	readVector2 ()
Vector3	readVector3 ()
Vector4	readVector4 ()
void	reset ()
	Goes back to the beginning of the file.
void	setEndian (G3DEndian endian)
	Change the endian-ness of the file.
void	setPosition (int64 p)
	Sets the position.
int64	size () const
void	skip (int64 n)
	Skips ahead n bytes.

Static Public Attributes
static const bool	NO_COPY
	false, constant to use with the copyMemory option

Detailed Description

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

Files compressed with zlib and beginning with an unsigned 32-bit int size are transparently decompressed when the compressed = true flag is specified to the constructor.

For every readX method there are also versions that operate on a whole Array, std::vector, or C-array. e.g. readFloat32(Array<float32>& array, n) These methods resize the array or std::vector to the appropriate size before reading. For a C-array, they require the pointer to reference a memory block at least large enough to hold n elements.

Most classes define serialize/deserialize methods that use BinaryInput, BinaryOutput, TextInput, and TextOutput. There are text serializer functions for primitive types (e.g. int, std::string, float, double) but not binary serializers– you must call the BinaryInput::readInt32 or other appropriate function. This is because it would be very hard to debug the error sequence: serialize(1.0, bo); ... float f; deserialize(f, bi); in which a double is serialized and then deserialized as a float.

Constructor & Destructor Documentation

G3D::BinaryInput::BinaryInput	(	const std::string &	filename,
		G3DEndian	fileEndian,
		bool	compressed = false
	)

If the file cannot be opened, a zero length buffer is presented.

Automatically opens files that are inside zipfiles.

Parameters

compressed

Set to true if and only if the file was compressed using BinaryOutput's zlib compression. This has nothing to do with whether the input is in a zipfile.

G3D::BinaryInput::BinaryInput	(	const uint8 *	data,
		int64	dataLen,
		G3DEndian	dataEndian,
		bool	compressed = false,
		bool	copyMemory = true
	)

Creates input stream from an in memory source.

 Unless you specify copyMemory = false, the data is copied
 from the pointer, so you may deallocate it as soon as the
 object is constructed.  It is an error to specify copyMemory = false
 and compressed = true.

 To decompress part of a file, you can follow the following paradigm:

 <PRE>
    BinaryInput master(...);

read from master to point where compressed data exists.

    BinaryInput subset(master.getCArray() + master.getPosition(), 
                       master.length() - master.getPosition(),
                       master.endian(), true, true);

Now read from subset (it is ok for master to go out of scope)

virtual G3D::BinaryInput::~BinaryInput ( )

virtual

Member Function Documentation

void G3D::BinaryInput::beginBits

(

)

Prepares for bit reading via readBits.

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

void G3D::BinaryInput::endBits

(

)

Ends bit-reading.

G3DEndian G3D::BinaryInput::endian ( ) const

inline

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

inline

Returns a pointer to the internal memory buffer.

May throw an exception for huge files.

std::string G3D::BinaryInput::getFilename ( ) const

inline

int64 G3D::BinaryInput::getLength ( ) const

inline

Returns the length of the file in bytes.

Referenced by size().

int64 G3D::BinaryInput::getPosition ( ) const

inline

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

bool G3D::BinaryInput::hasMore ( ) const

inline

Returns true if the position is not at the end of the file.

uint8 G3D::BinaryInput::operator[] ( int64  n )

inline

Performs bounds checks in debug mode.

[] are relative to the start of the file, not the current position. Seeks to the new position before reading (and leaves that as the current position)

uint32 G3D::BinaryInput::readBits

(

int

numBits

)

Can only be called between beginBits and endBits.

bool G3D::BinaryInput::readBool8 ( )

inline

Referenced by G3D::deserialize(), and G3D::Component< Color3, Image3 >::speedDeserialize().

void G3D::BinaryInput::readBool8	(	bool *	out,
		int64	n
	)

void G3D::BinaryInput::readBool8	(	std::vector< bool > &	out,
		int64	n
	)

void G3D::BinaryInput::readBool8	(	Array< bool > &	out,
		int64	n
	)

void G3D::BinaryInput::readBytes	(	void *	bytes,
		int64	n
	)

Color3 G3D::BinaryInput::readColor3

(

)

Color4 G3D::BinaryInput::readColor4

(

)

std::string G3D::BinaryInput::readFixedLengthString

(

int

numBytes

)

Read a string (which may contain NULLs) of exactly numBytes bytes, including the final terminator if there is one.

If there is a NULL in the string before the end, then only the part up to the first NULL is returned although all bytes are read.

float32 G3D::BinaryInput::readFloat32 ( )

inline

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

void G3D::BinaryInput::readFloat32	(	float32 *	out,
		int64	n
	)

void G3D::BinaryInput::readFloat32	(	std::vector< float32 > &	out,
		int64	n
	)

void G3D::BinaryInput::readFloat32	(	Array< float32 > &	out,
		int64	n
	)

float64 G3D::BinaryInput::readFloat64 ( )

inline

Referenced by G3D::deserialize().

void G3D::BinaryInput::readFloat64	(	float64 *	out,
		int64	n
	)

void G3D::BinaryInput::readFloat64	(	std::vector< float64 > &	out,
		int64	n
	)

void G3D::BinaryInput::readFloat64	(	Array< float64 > &	out,
		int64	n
	)

int16 G3D::BinaryInput::readInt16 ( )

inline

void G3D::BinaryInput::readInt16	(	int16 *	out,
		int64	n
	)

void G3D::BinaryInput::readInt16	(	std::vector< int16 > &	out,
		int64	n
	)

void G3D::BinaryInput::readInt16	(	Array< int16 > &	out,
		int64	n
	)

int32 G3D::BinaryInput::readInt32 ( )

inline

Referenced by G3D::deserialize(), G3D::BumpMap::Settings::deserialize(), G3D::GKeySym::deserialize(), G3D::GKey::deserialize(), and G3D::Component< Color3, Image3 >::speedDeserialize().

void G3D::BinaryInput::readInt32	(	int32 *	out,
		int64	n
	)

void G3D::BinaryInput::readInt32	(	std::vector< int32 > &	out,
		int64	n
	)

void G3D::BinaryInput::readInt32	(	Array< int32 > &	out,
		int64	n
	)

int64 G3D::BinaryInput::readInt64 ( )

inline

void G3D::BinaryInput::readInt64	(	int64 *	out,
		int64	n
	)

void G3D::BinaryInput::readInt64	(	std::vector< int64 > &	out,
		int64	n
	)

void G3D::BinaryInput::readInt64	(	Array< int64 > &	out,
		int64	n
	)

int8 G3D::BinaryInput::readInt8 ( )

inline

Referenced by readBool8().

void G3D::BinaryInput::readInt8	(	int8 *	out,
		int64	n
	)

void G3D::BinaryInput::readInt8	(	std::vector< int8 > &	out,
		int64	n
	)

void G3D::BinaryInput::readInt8	(	Array< int8 > &	out,
		int64	n
	)

std::string G3D::BinaryInput::readString

(

int64

maxLength

)

Always consumes maxLength characters.

Reads a string until NULL or maxLength characters. Does not require NULL termination.

std::string G3D::BinaryInput::readString

(

)

Reads a string until NULL or end of file.

std::string G3D::BinaryInput::readString32

(

)

Reads a uint32 and then calls readString(maxLength) with that value as the length.

Referenced by G3D::deserialize().

std::string G3D::BinaryInput::readStringEven

(

)

Reads until NULL or the end of the file is encountered.

If the string has odd length (including NULL), reads another byte. This is a common format for 16-bit alignment in files.

std::string G3D::BinaryInput::readStringNewline

(

)

Reads a string until NULL, newline ("&#92;r", "&#92;n", "&#92;r&#92;n", "&#92;n&#92;r") or the end of the file is encountered.

Consumes the newline.

uint16 G3D::BinaryInput::readUInt16 ( )

inline

Referenced by G3D::GKeySym::deserialize(), and readInt16().

void G3D::BinaryInput::readUInt16	(	uint16 *	out,
		int64	n
	)

void G3D::BinaryInput::readUInt16	(	std::vector< uint16 > &	out,
		int64	n
	)

void G3D::BinaryInput::readUInt16	(	Array< uint16 > &	out,
		int64	n
	)

uint32 G3D::BinaryInput::readUInt32 ( )

inline

Referenced by G3D::deserialize(), readFloat32(), and readInt32().

void G3D::BinaryInput::readUInt32	(	uint32 *	out,
		int64	n
	)

void G3D::BinaryInput::readUInt32	(	Array< uint32 > &	out,
		int64	n
	)

void G3D::BinaryInput::readUInt32	(	std::vector< uint32 > &	out,
		int64	n
	)

uint64 G3D::BinaryInput::readUInt64

(

)

Referenced by readFloat64(), and readInt64().

void G3D::BinaryInput::readUInt64	(	Array< uint64 > &	out,
		int64	n
	)

void G3D::BinaryInput::readUInt64	(	std::vector< uint64 > &	out,
		int64	n
	)

void G3D::BinaryInput::readUInt64	(	uint64 *	out,
		int64	n
	)

uint8 G3D::BinaryInput::readUInt8 ( )

inline

Referenced by G3D::GKeySym::deserialize(), G3D::PointKDTree< T, PositionFunc, HashFunc, EqualsFunc >::Node::deserializeStructure(), G3D::KDTree< T, BoundsFunc, HashFunc, EqualsFunc >::Node::deserializeStructure(), operator[](), and readUNorm8().

void G3D::BinaryInput::readUInt8	(	uint8 *	out,
		int64	n
	)

void G3D::BinaryInput::readUInt8	(	std::vector< uint8 > &	out,
		int64	n
	)

void G3D::BinaryInput::readUInt8	(	Array< uint8 > &	out,
		int64	n
	)

unorm8 G3D::BinaryInput::readUNorm8 ( )

inline

Vector2 G3D::BinaryInput::readVector2

(

)

Vector3 G3D::BinaryInput::readVector3

(

)

Vector4 G3D::BinaryInput::readVector4

(

)

void G3D::BinaryInput::reset ( )

inline

Goes back to the beginning of the file.

void G3D::BinaryInput::setEndian

(

G3DEndian

endian

)

Change the endian-ness of the file.

This only changes the interpretation of the file for future read calls; the underlying data is unmodified.

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

inline

Sets the position.

Cannot set past length. May throw a char* when seeking backwards more than 10 MB on a huge file.

Referenced by operator[](), reset(), and skip().

int64 G3D::BinaryInput::size ( ) const

inline

void G3D::BinaryInput::skip ( int64  n )

inline

Skips ahead n bytes.

Member Data Documentation

const bool G3D::BinaryInput::NO_COPY

static

false, constant to use with the copyMemory option

Referenced by G3D::ReliableConduit::receive(), and G3D::LightweightConduit::receive().