Support Forum       G3D Web Page     
Public Member Functions | Static Public Attributes | List of all members
G3D::BinaryInput Class Reference


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

Public Member Functions

 BinaryInput (const String &filename, G3DEndian fileEndian, bool compressed=false)
 If the file cannot be opened, a zero length buffer is presented. More...
 
 BinaryInput (const uint8 *data, int64 dataLen, G3DEndian dataEndian, bool compressed=false, bool copyMemory=true)
 
Creates input stream from an in memory source. More...
 
virtual ~BinaryInput ()
 
void beginBits ()
 Prepares for bit reading via readBits. More...
 
void endBits ()
 Ends bit-reading. More...
 
G3DEndian endian () const
 
const uint8getCArray ()
 
Returns a pointer to the internal memory buffer. More...
 
String getFilename () const
 
int64 getLength () const
 
Returns the length of the file in bytes. More...
 
int64 getPosition () const
 
Returns the current byte position in the file, where 0 is the beginning and getLength() - 1 is the end. More...
 
bool hasMore () const
 Returns true if the position is not at the end of the file. More...
 
uint8 operator[] (int64 n)
 
Performs bounds checks in debug mode. More...
 
uint32 readBits (int numBits)
 Can only be called between beginBits and endBits. More...
 
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 ()
 
String readFixedLengthString (int numBytes)
 Read a string (which may contain NULLs) of exactly numBytes bytes, including the final terminator if there is one. More...
 
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)
 
String readString (int64 maxLength)
 
Always consumes maxLength characters. More...
 
String readString ()
 
Reads a string until nullptr or end of file. More...
 
String readString32 ()
 Reads a uint32 and then calls readString(maxLength) with that value as the length. More...
 
String readStringEven ()
 
Reads until nullptr or the end of the file is encountered. More...
 
String readStringNewline ()
 
Reads a string until nullptr, newline ("&#92;r", "&#92;n", "&#92;r&#92;n", "&#92;n&#92;r") or the end of the file is encountered. More...
 
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. More...
 
void setEndian (G3DEndian endian)
 Change the endian-ness of the file. More...
 
void setPosition (int64 p)
 
Sets the position. More...
 
int64 size () const
 
void skip (int64 n)
 
Skips ahead n bytes. More...
 

Static Public Attributes

static const bool NO_COPY
 false, constant to use with the copyMemory option More...
 

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, 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

◆ BinaryInput() [1/2]

G3D::BinaryInput::BinaryInput ( const 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
compressedSet 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.

◆ BinaryInput() [2/2]

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:

   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)

◆ ~BinaryInput()

virtual G3D::BinaryInput::~BinaryInput ( )
virtual

Member Function Documentation

◆ beginBits()

void G3D::BinaryInput::beginBits ( )

Prepares for bit reading via readBits.

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

◆ endBits()

void G3D::BinaryInput::endBits ( )

Ends bit-reading.

◆ endian()

G3DEndian G3D::BinaryInput::endian ( ) const
inline

◆ getCArray()

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


Returns a pointer to the internal memory buffer.

May throw an exception for huge files.

◆ getFilename()

String G3D::BinaryInput::getFilename ( ) const
inline

◆ getLength()

int64 G3D::BinaryInput::getLength ( ) const
inline


Returns the length of the file in bytes.

Referenced by size().

◆ getPosition()

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.

◆ hasMore()

bool G3D::BinaryInput::hasMore ( ) const
inline

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

◆ operator[]()

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)

◆ readBits()

uint32 G3D::BinaryInput::readBits ( int  numBits)

Can only be called between beginBits and endBits.

◆ readBool8() [1/4]

bool G3D::BinaryInput::readBool8 ( )
inline

Referenced by G3D::deserialize().

◆ readBool8() [2/4]

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

◆ readBool8() [3/4]

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

◆ readBool8() [4/4]

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

◆ readBytes()

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

◆ readColor3()

Color3 G3D::BinaryInput::readColor3 ( )

◆ readColor4()

Color4 G3D::BinaryInput::readColor4 ( )

◆ readFixedLengthString()

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 nullptr in the string before the end, then only the part up to the first nullptr is returned although all bytes are read.

◆ readFloat32() [1/4]

float32 G3D::BinaryInput::readFloat32 ( )
inline

◆ readFloat32() [2/4]

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

◆ readFloat32() [3/4]

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

◆ readFloat32() [4/4]

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

◆ readFloat64() [1/4]

float64 G3D::BinaryInput::readFloat64 ( )
inline

Referenced by G3D::deserialize().

◆ readFloat64() [2/4]

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

◆ readFloat64() [3/4]

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

◆ readFloat64() [4/4]

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

◆ readInt16() [1/4]

int16 G3D::BinaryInput::readInt16 ( )
inline

◆ readInt16() [2/4]

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

◆ readInt16() [3/4]

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

◆ readInt16() [4/4]

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

◆ readInt32() [1/4]

int32 G3D::BinaryInput::readInt32 ( )
inline

◆ readInt32() [2/4]

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

◆ readInt32() [3/4]

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

◆ readInt32() [4/4]

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

◆ readInt64() [1/4]

int64 G3D::BinaryInput::readInt64 ( )
inline

◆ readInt64() [2/4]

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

◆ readInt64() [3/4]

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

◆ readInt64() [4/4]

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

◆ readInt8() [1/4]

int8 G3D::BinaryInput::readInt8 ( )
inline

Referenced by readBool8().

◆ readInt8() [2/4]

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

◆ readInt8() [3/4]

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

◆ readInt8() [4/4]

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

◆ readString() [1/2]

String G3D::BinaryInput::readString ( int64  maxLength)


Always consumes maxLength characters.

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

◆ readString() [2/2]

String G3D::BinaryInput::readString ( )


Reads a string until nullptr or end of file.

◆ readString32()

String G3D::BinaryInput::readString32 ( )

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

Referenced by G3D::deserialize().

◆ readStringEven()

String G3D::BinaryInput::readStringEven ( )


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

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

◆ readStringNewline()

String G3D::BinaryInput::readStringNewline ( )


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

Consumes the newline.

◆ readUInt16() [1/4]

uint16 G3D::BinaryInput::readUInt16 ( )
inline

◆ readUInt16() [2/4]

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

◆ readUInt16() [3/4]

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

◆ readUInt16() [4/4]

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

◆ readUInt32() [1/4]

uint32 G3D::BinaryInput::readUInt32 ( )
inline

◆ readUInt32() [2/4]

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

◆ readUInt32() [3/4]

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

◆ readUInt32() [4/4]

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

◆ readUInt64() [1/4]

uint64 G3D::BinaryInput::readUInt64 ( )

Referenced by readFloat64(), and readInt64().

◆ readUInt64() [2/4]

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

◆ readUInt64() [3/4]

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

◆ readUInt64() [4/4]

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

◆ readUInt8() [1/4]

uint8 G3D::BinaryInput::readUInt8 ( )
inline

◆ readUInt8() [2/4]

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

◆ readUInt8() [3/4]

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

◆ readUInt8() [4/4]

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

◆ readUNorm8()

unorm8 G3D::BinaryInput::readUNorm8 ( )
inline

◆ readVector2()

Vector2 G3D::BinaryInput::readVector2 ( )

◆ readVector3()

Vector3 G3D::BinaryInput::readVector3 ( )

◆ readVector4()

Vector4 G3D::BinaryInput::readVector4 ( )

◆ reset()

void G3D::BinaryInput::reset ( )
inline


Goes back to the beginning of the file.

◆ setEndian()

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.

◆ setPosition()

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().

◆ size()

int64 G3D::BinaryInput::size ( ) const
inline

◆ skip()

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


Skips ahead n bytes.

Member Data Documentation

◆ NO_COPY

const bool G3D::BinaryInput::NO_COPY
static

false, constant to use with the copyMemory option

Referenced by G3D::receive().


documentation generated on Wed Nov 24 2021 08:01:53 using doxygen 1.8.15