byteStream.h

Go to the documentation of this file.

/*********************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*********************************************************************************/
 
//! \file byteStream.h
//! \ingroup vreUtil
//! \brief Provides binary serialization and deserialization capabilities
//!
//! This file defines the DtStreamReader and DtStreamWriter classes that handle
//! reading and writing of various data types to and from byte streams. These
//! classes support primitives, strings, vectors, and VREngage-specific types.
 
#pragma once
 
#include "vreUtil/export.h"
#include "vreUtil/utilFunctions.h"
 
#include <vlpi/entityIdentifier.h>
#include <vlpi/entityType.h>
#include <vlpi/simulationAddress.h>
#include <matrix/vlVector.h>
#include <matrix/vlTaitBryan.h>
#include <matrix/vlQuaternion.h>
 
#include <string>
 
namespace makVre
{
 
 
//! \brief Calculates the size of a string when encoded in the byte stream format
//! \param str The string to calculate the encoded size for
//! \return The size in bytes that the string will occupy when encoded
int UTIL_DLL DtEncodedStringSize(const std::string& str);
 
//! \brief Reader class for decoding values from a byte array
//!
//! This class provides methods for reading various data types from a byte stream,
//! maintaining the current read position, and handling platform-specific byte ordering.
class UTIL_DLL DtStreamReader
{
public:
   //! \brief Constructor
   //! \param buffer Pointer to the buffer to read from
   //! \param length Length of the buffer in bytes
   //! \param makeCopy If true, make a copy of the buffer; if false, use the provided buffer directly
   DtStreamReader(char* buffer, int length, bool makeCopy = false);
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources, including the buffer if it was copied
   virtual ~DtStreamReader();
 
   //! \name Value Readers
   //! \brief Methods to read values from the byte stream
   //!
   //! These methods return a value and increment the current position in the byte stream
   //! based on the size of the value read.
   //! @{
 
   //! \brief Reads a boolean value
   //! \return The boolean value read from the stream
   bool readBool();
   //! \brief Reads a signed 8-bit integer
   //! \return The signed 8-bit integer read from the stream
   char readInt8();
 
   //! \brief Reads an unsigned 8-bit integer
   //! \return The unsigned 8-bit integer read from the stream
   unsigned char readUInt8();
 
   //! \brief Reads a signed 16-bit integer
   //! \return The signed 16-bit integer read from the stream
   short readInt16();
 
   //! \brief Reads an unsigned 16-bit integer
   //! \return The unsigned 16-bit integer read from the stream
   unsigned short readUInt16();
 
   //! \brief Reads a signed 32-bit integer
   //! \return The signed 32-bit integer read from the stream
   int readInt32();
 
   //! \brief Reads an unsigned 32-bit integer
   //! \return The unsigned 32-bit integer read from the stream
   unsigned int readUInt32();
 
   //! \brief Reads a signed 64-bit integer
   //! \return The signed 64-bit integer read from the stream
   Int64 readInt64();
 
   //! \brief Reads an unsigned 64-bit integer
   //! \return The unsigned 64-bit integer read from the stream
   UInt64 readUInt64();
 
   //! \brief Reads a 32-bit floating point value
   //! \return The 32-bit float read from the stream
   float readSingle();
 
   //! \brief Reads a 64-bit floating point value
   //! \return The 64-bit double read from the stream
   double readDouble();
   //! \brief Reads a string value
   //! \return The string read from the stream
   std::string readString();
 
   //! \brief Reads a 3D vector
   //! \return The vector read from the stream
   DtVector readVector();
 
   //! \brief Reads a Tait-Bryan angles representation
   //! \return The Tait-Bryan angles read from the stream
   DtTaitBryan readTaitBryan();
 
   //! \brief Reads a quaternion
   //! \return The quaternion read from the stream
   DtQuaternion readQuaternion();
 
   //! \brief Reads an entity identifier
   //! \return The entity identifier read from the stream
   DtEntityIdentifier readEntityId();
 
   //! \brief Reads an entity type
   //! \return The entity type read from the stream
   DtEntityType readEntityType();
 
   //! \brief Reads a simulation address
   //! \return The simulation address read from the stream
   DtSimulationAddress readSimulationAddress();
 
   //! \brief Reads a byte array of specified length
   //! \param length Number of bytes to read
   //! \return Pointer to the read bytes (caller must manage memory)
   char* readBytes(int length);
   //@}
 
protected:
   //! \brief Determines the size of a string from a variable length encoded integer
   //! \return The decoded string size
   int decodeStringSize();
 
   //! \brief Pointer to the buffer being read from
   char* myBuffer;
 
   //! \brief Current position in the buffer
   char* myReadHead;
 
   //! \brief Total length of the buffer
   int myLength;
 
   //! \brief Flag indicating if the buffer should be deleted on destruction
   bool myShouldDelete;
};
 
//! \brief Writer class for encoding values into a byte array
//!
//! This class provides methods for writing various data types to a byte stream,
//! maintaining the current write position, and handling platform-specific byte ordering.
class UTIL_DLL DtStreamWriter
{
public:
   //! \brief Constructor that creates an internal buffer
   //! \param length Size of internal buffer to create (in bytes)
   //! \note Care must be taken to allocate enough space
   DtStreamWriter(int length = 0);
 
   //! \brief Constructor that uses an existing buffer
   //! \param buffer Pointer to the buffer to write to
   //! \param length Length of the buffer in bytes
   //! \note Care must be taken to ensure the buffer has enough space
   DtStreamWriter(char* buffer, int length);
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources, including the buffer if it was created internally
   virtual ~DtStreamWriter();
 
   //! \name Buffer Access
   //! \brief Methods to access the internal buffer
   //! @{
 
   //! \brief Gets a pointer to the internal buffer
   //! \return Pointer to the buffer
   char* buffer();
 
   //! \brief Gets the current length of data in the buffer
   //! \return Current length in bytes
   int length();
   //@}
 
   //! \name Value Writers
   //! \brief Methods to write values to the byte stream
   //!
   //! These methods write a value and increment the current position in the byte stream
   //! based on the size of the value written.
   //! @{
 
   //! \brief Writes a boolean value
   //! \param b The boolean value to write
   void writeBool(bool b);
   //! \brief Writes a signed 8-bit integer
   //! \param num The signed 8-bit integer to write
   void writeInt8(char num);
 
   //! \brief Writes an unsigned 8-bit integer
   //! \param num The unsigned 8-bit integer to write
   void writeUInt8(unsigned char num);
 
   //! \brief Writes a signed 16-bit integer
   //! \param num The signed 16-bit integer to write
   void writeInt16(short num);
 
   //! \brief Writes an unsigned 16-bit integer
   //! \param num The unsigned 16-bit integer to write
   void writeUInt16(unsigned short num);
 
   //! \brief Writes a signed 32-bit integer
   //! \param num The signed 32-bit integer to write
   void writeInt32(int num);
 
   //! \brief Writes an unsigned 32-bit integer
   //! \param num The unsigned 32-bit integer to write
   void writeUInt32(unsigned int num);
 
   //! \brief Writes a signed 64-bit integer
   //! \param num The signed 64-bit integer to write
   void writeInt64(Int64 num);
 
   //! \brief Writes an unsigned 64-bit integer
   //! \param num The unsigned 64-bit integer to write
   void writeUInt64(UInt64 num);
 
   //! \brief Writes a 32-bit floating point value
   //! \param num The 32-bit float to write
   void writeSingle(float num);
 
   //! \brief Writes a 64-bit floating point value
   //! \param num The 64-bit double to write
   void writeDouble(double num);
   //! \brief Writes a string value
   //! \param str The string to write
   void writeString(const std::string& str);
 
   //! \brief Writes a 3D vector
   //! \param vec The vector to write
   void writeVector(const DtVector& vec);
 
   //! \brief Writes a Tait-Bryan angles representation
   //! \param tb The Tait-Bryan angles to write
   void writeTaitBryan(const DtTaitBryan& tb);
 
   //! \brief Writes a quaternion
   //! \param q The quaternion to write
   void writeQuaternion(const DtQuaternion& q);
 
   //! \brief Writes an entity identifier
   //! \param id The entity identifier to write
   void writeEntityId(const DtEntityIdentifier& id);
 
   //! \brief Writes a simulation address
   //! \param addr The simulation address to write
   void writeSimulationAddress(const DtSimulationAddress& addr);
 
   //! \brief Writes an entity type
   //! \param type The entity type to write
   void writeEntityType(const DtEntityType& type);
 
   //! \brief Writes a byte array
   //! \param bytes Pointer to the bytes to write
   //! \param length Number of bytes to write
   void writeBytes(char* bytes, int length);
   //@}
 
protected:
   //! \brief Encodes the size of a string as a variable length integer
   //! \param size The size to encode
   void encodeStringSize(int size);
 
   //! \brief Pointer to the buffer being written to
   char* myBuffer;
 
   //! \brief Current position in the buffer
   char* myWriteHead;
 
   //! \brief Total length of the buffer
   int myLength;
 
   //! \brief Flag indicating if the buffer should be deleted on destruction
   bool myShouldDelete;
};
 
 
} // namespace makVre