mitsuba/include/mitsuba/core/stream.h

/*
    This file is part of Mitsuba, a physically based rendering system.

    Copyright (c) 2007-2014 by Wenzel Jakob and others.

    Mitsuba is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License Version 3
    as published by the Free Software Foundation.

    Mitsuba is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program. If not, see <http://www.gnu.org/licenses/>.
*/

#pragma once
#if !defined(__MITSUBA_CORE_STREAM_H_)
#define __MITSUBA_CORE_STREAM_H_

#include <mitsuba/mitsuba.h>
#include <mitsuba/core/half.h>

MTS_NAMESPACE_BEGIN

/// \brief This exception is thrown after an incomplete IO read/write operation
class EOFException : public std::runtime_error {
public:
	inline EOFException(const std::string &str, size_t completed)
		: std::runtime_error(str), m_completed(completed) { }

	/// Return the number of bytes that successfully completed
	inline size_t getCompleted() const {
		return m_completed;
	}
private:
	size_t m_completed;
};

/** \brief Abstract seekable stream class
 *
 * Specifies all functions to be implemented by stream
 * subclasses and provides various convenience functions
 * layered on top of on them.
 *
 * All read<b>X</b>() and write<b>X</b>() methods support transparent
 * conversion based on the endianness of the underlying system and the
 * value passed to \ref setByteOrder(). Whenever \ref getHostByteOrder()
 * and \ref getByteOrder() disagree, the endianness is swapped.
 *
 * \sa FileStream, MemoryStream, SocketStream,
 *     ConsoleStream, SSHStream, ZStream
 * \ingroup libcore
 * \ingroup libpython
 */
class MTS_EXPORT_CORE Stream : public Object {
public:
	/// Defines the byte order to use in this Stream
	enum EByteOrder {
		EBigEndian = 0,                ///< PowerPC, SPARC, Motorola 68K
		ELittleEndian = 1,             ///< x86, x86_64
		ENetworkByteOrder = EBigEndian ///< Network byte order (an alias for big endian)
	};

	/**
	 * \brief Create a new stream.
	 *
	 * By default, it assumes the byte order of the
	 * underlying system, i.e. no endianness conversion
	 * is performed.
	 */
	Stream();

	/// Return a string representation
	virtual std::string toString() const;

	// ======================================================================
	/// @{ \name Endianness-related
	// ======================================================================

	/// Set the stream byte order
	void setByteOrder(EByteOrder byteOrder);

	/// Return the byte order of this stream
	inline EByteOrder getByteOrder() const { return m_byteOrder; }

	/// Return the byte order of the underlying machine
	inline static EByteOrder getHostByteOrder() { return m_hostByteOrder; }

	/// @}
	// ======================================================================

	// ======================================================================
	//! @{ \name Abstract methods that need to be implemented by subclasses
	// ======================================================================

	/**
	 * \brief Read a specified amount of data from the stream
	 *
	 * Throws an exception when the stream ended prematurely
	 */
	virtual void read(void *ptr, size_t size) = 0;

	/**
	 * \brief Write a specified amount of data into the stream
	 *
	 * Throws an exception when not all data could be written
	 */
	virtual void write(const void *ptr, size_t size) = 0;

	/// Seek to a position inside the stream
	virtual void seek(size_t pos) = 0;

	/// Truncate the stream to a given size
	virtual void truncate(size_t size) = 0;

	/// Get the current position inside the stream
	virtual size_t getPos() const = 0;

	/// Return the size of the stream
	virtual size_t getSize() const = 0;

	/// Flush the stream's buffers
	virtual void flush() = 0;

	/// Can we write to the stream?
	virtual bool canWrite() const = 0;

	/// Can we read from the stream?
	virtual bool canRead() const = 0;

	//! @}
	// ======================================================================

	// ======================================================================
	//! @{ \name Convenience functions with automatic endianness conversion
	// ======================================================================

	/// Skip the given number of bytes
	void skip(size_t amount);

	/// Write a null-terminated string to the stream
	void writeString(const std::string &value);

	/// Write a string followed by a newline
	void writeLine(const std::string &value);

	/// Write a signed short (16 bit) to the stream
	void writeShort(short value);

	/// Write an array of signed shorts (16 bit) to the stream
	void writeShortArray(const short *values, size_t size);

	/// Write an array of known size of signed shorts (16 bit) to the stream
	template <size_t N>
	inline void writeShortArray(const short (&values)[N]) {
		writeShortArray(&values[0], N);
	}

	/// Write an unsigned short (16 bit) to the stream
	void writeUShort(unsigned short value);

	/// Write an array of unsigned shorts (16 bit) to the stream
	void writeUShortArray(const unsigned short *values, size_t size);

	/// Write an array of known size of unsigned shorts (16 bit) to the stream
	template <size_t N>
	inline void writeUShortArray(const unsigned short (&values)[N]) {
		writeUShortArray(&values[0], N);
	}

	/// Write a signed int (32 bit) to the stream
	void writeInt(int value);

	/// Write an array of signed ints (32 bit) to the stream
	void writeIntArray(const int *values, size_t size);

	/// Write an array of known size of signed ints (32 bit) to the stream
	template <size_t N>
	inline void writeIntArray(const int (&values)[N]) {
		writeIntArray(&values[0], N);
	}

	/// Write an unsigned int (32 bit) to the stream
	void writeUInt(unsigned int value);

	/// Write an array of unsigned ints (32 bit) to the stream
	void writeUIntArray(const unsigned int *values, size_t size);

	/// Write an array of known size of unsigned ints (32 bit) to the stream
	template <size_t N>
	inline void writeUIntArray(const unsigned int (&values)[N]) {
		writeUIntArray(&values[0], N);
	}

	/// Write a signed int (64 bit) to the stream
	void writeLong(int64_t value);

	/// Write an array of signed ints (64 bit) to the stream
	void writeLongArray(const int64_t *values, size_t size);

	/// Write an array of known size of signed ints (64 bit) to the stream
	template <size_t N>
	inline void writeLongArray(const int64_t (&values)[N]) {
		writeLongArray(&values[0], N);
	}

	/// Write an unsigned int (64 bit) to the stream
	void writeULong(uint64_t value);

	/// Write a size value to the stream
	void writeSize(size_t value) { writeULong((uint64_t) value); }

	/// Write an array of unsigned ints (64 bit) to the stream
	void writeULongArray(const uint64_t *values, size_t size);

	/// Write an array of known size of unsigned ints (64 bit) to the stream
	template <size_t N>
	inline void writeULongArray(const uint64_t (&values)[N]) {
		writeULongArray(&values[0], N);
	}

	/// Write a signed character (8 bit) to the stream
	void writeChar(char value);

	/// Write an unsigned character (8 bit) to the stream
	void writeUChar(unsigned char value);

	/// Write a boolean (8 bit) to the stream
	inline void writeBool(bool value) { writeUChar(value); }

	/// Write a half-precision floating point number (16 bit) to the stream
	void writeHalf(half value);

	/// Write a half-precision floating point array (16 bit) to the stream
	void writeHalfArray(const half *data, size_t size);

	/// Write a known size half-precision floating point array (16 bit) to the stream
	template <size_t N>
	inline void writeHalfArray(const half (&values)[N]) {
		writeHalfArray(&values[0], N);
	}

	/// Write a single-precision floating point number (32 bit) to the stream
	void writeSingle(float value);

	/// Write a single-precision floating point array (32 bit) to the stream
	void writeSingleArray(const float *data, size_t size);

	/// Write a known size single-precision floating point array (32 bit) to the stream
	template <size_t N>
	inline void writeSingleArray(const float (&values)[N]) {
		writeSingleArray(&values[0], N);
	}

	/// Write a double-precision floating point number (64 bit) to the stream
	void writeDouble(double value);

	/// Write a double-precision floating point array (64 bit) to the stream
	void writeDoubleArray(const double *data, size_t size);

	/// Write a known size double-precision floating point array (64 bit) to the stream
	template <size_t N>
	inline void writeDoubleArray(const double (&values)[N]) {
		writeDoubleArray(&values[0], N);
	}

	/// Write a floating point number (configured precision) to the stream
	inline void writeFloat(Float value) {
#ifdef SINGLE_PRECISION
		writeSingle(value);
#else
		writeDouble(value);
#endif
	}

	/// Write an array of floating point values (configured precision) to the stream
	inline void writeFloatArray(const Float *data, size_t size) {
#ifdef SINGLE_PRECISION
		writeSingleArray(data, size);
#else
		writeDoubleArray(data, size);
#endif
	}

	/// Write a known size array of floating point values (configured precision) to the stream
	template <size_t N>
	inline void writeFloatArray(const Float (&values)[N]) {
		writeFloatArray(&values[0], N);
	}

	/// Return whether we are at the end of the stream
	bool isEOF() const;

	/// Read a line from the stream and return it as a string
	std::string readLine();

	/// Read a null-terminated string from the stream
	std::string readString();

	/// Read a signed short (16 bit) from the stream
	short readShort();

	/// Read an array of signed shorts (16 bit) from the stream
	void readShortArray(short *dest, size_t size);

	/// Read an array of known size of signed shorts (16 bit) from the stream
	template <size_t N>
	inline void readShortArray(short (&values)[N]) {
		readShortArray(&values[0], N);
	}

	/// Read an unsigned short (16 bit) from the stream
	unsigned short readUShort();

	/// Read an array of unsigned shorts (16 bit) from the stream
	void readUShortArray(unsigned short *dest, size_t size);

	/// Read an array of known size of unsigned shorts (16 bit) from the stream
	template <size_t N>
	inline void readUShortArray(short (&values)[N]) {
		readUShortArray(&values[0], N);
	}

	/// Read a signed int (32 bit) from the stream
	int readInt();

	/// Read an array of signed ints (32 bit) from the stream
	void readIntArray(int *dst, size_t size);

	/// Read an array of known size of signed ints (32 bit) from the stream
	template <size_t N>
	inline void readIntArray(int (&values)[N]) {
		readIntArray(&values[0], N);
	}

	/// Read an unsigned int (32 bit) from the stream
	unsigned int readUInt();

	/// Read an array of unsigned ints (32 bit) from the stream
	void readUIntArray(unsigned int *dest, size_t size);

	/// Read an array of known size of unsigned ints (32 bit) from the stream
	template <size_t N>
	inline void readUIntArray(int (&values)[N]) {
		readUIntArray(&values[0], N);
	}

	/// Read a signed int (64 bit) from the stream
	int64_t readLong();

	/// Read an array of signed ints (64 bit) from the stream
	void readLongArray(int64_t *dst, size_t size);

	/// Read an array of known size of signed ints (64 bit) from the stream
	template <size_t N>
	inline void readLongArray(int64_t (&values)[N]) {
		readLongArray(&values[0], N);
	}

	/// Read an unsigned int (64 bit) from the stream
	uint64_t readULong();

	/// Read a size value from the stream
	size_t readSize() { return (size_t) readULong(); }

	/// Read an array of unsigned ints (64 bit) from the stream
	void readULongArray(uint64_t *dst, size_t size);

	/// Read an array of known size of unsigned ints (64 bit) from the stream
	template <size_t N>
	inline void readULongArray(uint64_t (&values)[N]) {
		readULongArray(&values[0], N);
	}

	/// Read a signed character (8 bit) from the stream
	char readChar();

	/// Read an unsigned character (8 bit) from the stream
	unsigned char readUChar();

	/// Read a boolean (8 bit) from the stream
	inline bool readBool() { return static_cast<bool> (readUChar()); }

	/// Read a half-precision floating point number (16 bit) from the stream
	half readHalf();

	/// Read a half-precision floating point array (16 bit) from the stream
	void readHalfArray(half *data, size_t size);

	/// Read a known-size half-precision floating point array (16 bit) from the stream
	template <size_t N>
	inline void readHalfArray(half (&values)[N]) {
		readHalfArray(&values[0], N);
	}

	/// Read a single-precision floating point number (32 bit) from the stream
	float readSingle();

	/// Read a single-precision floating point array (32 bit) from the stream
	void readSingleArray(float *data, size_t size);

	/// Read a known-size single-precision floating point array (32 bit) from the stream
	template <size_t N>
	inline void readSingleArray(float (&values)[N]) {
		readSingleArray(&values[0], N);
	}

	/// Read a double-precision floating point number (64 bit) from the stream
	double readDouble();

	/// Read a double-precision floating point array (64 bit) from the stream
	void readDoubleArray(double *data, size_t size);

	/// Read a known-size double-precision floating point array (64 bit) from the stream
	template <size_t N>
	inline void readDoubleArray(double (&values)[N]) {
		readDoubleArray(&values[0], N);
	}

	/// Write a floating point number (configured precision) to the stream
	inline Float readFloat() {
#ifdef SINGLE_PRECISION
		return readSingle();
#else
		return readDouble();
#endif
	}

	/// Write an array of floating point values (configured precision) to the stream
	inline void readFloatArray(Float *data, size_t size) {
#ifdef SINGLE_PRECISION
		readSingleArray(data, size);
#else
		readDoubleArray(data, size);
#endif
	}

	/// Read a known-size array of floating point values (configured precision) to the stream
	template <size_t N>
	inline void readFloatArray(Float (&values)[N]) {
		readFloatArray(&values[0], N);
	}

	/**
	 * \brief Copy content from this stream into another stream
	 * \param stream Destination stream
	 * \param numBytes
	 * 		The number of bytes to copy. When -1 is specified,
	 * 		copying proceeds until the end of the source stream.
	 */
	void copyTo(Stream *stream, int64_t numBytes = -1);

	/**
	 * \brief Read an element from the stream (uses partial template
	 * specialization to select a method appropriate to the data type)
	 */
	template <typename T> T readElement();

	/**
	 * \brief Write an element to the stream (uses partial template
	 * specialization to select a method appropriate to the data type)
	 */
	template <typename T> void writeElement(T value);

	/**
	 * \brief Read an array from the stream (uses partial template
	 * specialization to select a method appropriate to the data type)
	 */
	template <typename T> void readArray(T *array, size_t count);

	/**
	 * \brief Read a known-size array from the stream (uses partial template
	 * specialization to select a method appropriate to the data type)
	 */
	template <typename T, size_t N> inline void readArray(T (&arr)[N]) {
		readArray(&arr[0], N);
	}

	/**
	 * \brief Write an array to the stream (uses partial template
	 * specialization to select a method appropriate to the data type)
	 */
	template <typename T> void writeArray(const T *array, size_t count);

	/**
	 * \brief Write a known-size array to the stream (uses partial template
	 * specialization to select a method appropriate to the data type)
	 */
	template <typename T, size_t N> inline void writeArray(const T (&arr)[N]) {
		writeArray(&arr[0], N);
	}

	//! @}

	MTS_DECLARE_CLASS()
protected:
	/// Virtual destructor
	virtual ~Stream() { }
private:
	static EByteOrder m_hostByteOrder;
	EByteOrder m_byteOrder;
};


template <typename T> inline T Stream::readElement() {
	Log(EError, "Stream::readElement<T>: not implemented!");
}

template <typename T> inline void Stream::writeElement(T value) {
	Log(EError, "Stream::writeElement<T>: not implemented!");
}

template <typename T> inline void Stream::readArray(T *array, size_t count) {
	Log(EError, "Stream::readArray<T>: not implemented!");
}

template <typename T> inline void Stream::writeArray(const T *array, size_t count) {
	Log(EError, "Stream::writeArray<T>: not implemented!");
}

/// \cond
template <> inline half Stream::readElement() { return readHalf(); }
template <> inline float Stream::readElement() { return readSingle(); }
template <> inline double Stream::readElement() { return readDouble(); }
template <> inline char Stream::readElement() { return readChar(); }
template <> inline unsigned char Stream::readElement() { return readUChar(); }
template <> inline bool Stream::readElement() { return readBool(); }
template <> inline int16_t Stream::readElement() { return readShort(); }
template <> inline uint16_t Stream::readElement() { return readUShort(); }
template <> inline int32_t Stream::readElement() { return readInt(); }
template <> inline uint32_t Stream::readElement() { return readUInt(); }
template <> inline int64_t Stream::readElement() { return readLong(); }
template <> inline uint64_t Stream::readElement() { return readULong(); }
template <> inline std::string Stream::readElement() { return readString(); }

template <> inline void Stream::writeElement(half val) { return writeHalf(val); }
template <> inline void Stream::writeElement(float val) { return writeSingle(val); }
template <> inline void Stream::writeElement(double val) { return writeDouble(val); }
template <> inline void Stream::writeElement(char val) { return writeChar(val); }
template <> inline void Stream::writeElement(unsigned char val) { return writeUChar(val); }
template <> inline void Stream::writeElement(bool val) { return writeBool(val); }
template <> inline void Stream::writeElement(int16_t val) { return writeShort(val); }
template <> inline void Stream::writeElement(uint16_t val) { return writeUShort(val); }
template <> inline void Stream::writeElement(int32_t val) { return writeInt(val); }
template <> inline void Stream::writeElement(uint32_t val) { return writeUInt(val); }
template <> inline void Stream::writeElement(int64_t val) { return writeLong(val); }
template <> inline void Stream::writeElement(uint64_t val) { return writeULong(val); }
template <> inline void Stream::writeElement(const std::string &val) { return writeString(val); }

template <> inline void Stream::readArray(half *array, size_t count) { return readHalfArray(array, count); }
template <> inline void Stream::readArray(float *array, size_t count) { return readSingleArray(array, count); }
template <> inline void Stream::readArray(double *array, size_t count) { return readDoubleArray(array, count); }
template <> inline void Stream::readArray(char *array, size_t count) { return read((uint8_t *) array, count); }
template <> inline void Stream::readArray(unsigned char *array, size_t count) { return read((uint8_t *) array, count); }
template <> inline void Stream::readArray(bool *array, size_t count) { return read((uint8_t *) array, count); }
template <> inline void Stream::readArray(int16_t *array, size_t count) { return readShortArray(array, count); }
template <> inline void Stream::readArray(uint16_t *array, size_t count) { return readUShortArray(array, count); }
template <> inline void Stream::readArray(int32_t *array, size_t count) { return readIntArray(array, count); }
template <> inline void Stream::readArray(uint32_t *array, size_t count) { return readUIntArray(array, count); }
template <> inline void Stream::readArray(int64_t *array, size_t count) { return readLongArray(array, count); }
template <> inline void Stream::readArray(uint64_t *array, size_t count) { return readULongArray(array, count); }

template <> inline void Stream::writeArray(const half *array, size_t count) { return writeHalfArray(array, count); }
template <> inline void Stream::writeArray(const float *array, size_t count) { return writeSingleArray(array, count); }
template <> inline void Stream::writeArray(const double *array, size_t count) { return writeDoubleArray(array, count); }
template <> inline void Stream::writeArray(const char *array, size_t count) { return write((uint8_t *) array, count); }
template <> inline void Stream::writeArray(const unsigned char *array, size_t count) { return write((uint8_t *) array, count); }
template <> inline void Stream::writeArray(const bool *array, size_t count) { return write((uint8_t *) array, count); }
template <> inline void Stream::writeArray(const int16_t *array, size_t count) { return writeShortArray(array, count); }
template <> inline void Stream::writeArray(const uint16_t *array, size_t count) { return writeUShortArray(array, count); }
template <> inline void Stream::writeArray(const int32_t *array, size_t count) { return writeIntArray(array, count); }
template <> inline void Stream::writeArray(const uint32_t *array, size_t count) { return writeUIntArray(array, count); }
template <> inline void Stream::writeArray(const int64_t *array, size_t count) { return writeLongArray(array, count); }
template <> inline void Stream::writeArray(const uint64_t *array, size_t count) { return writeULongArray(array, count); }

extern MTS_EXPORT_CORE std::ostream &operator<<(std::ostream &os, const Stream::EByteOrder &value);

/// \endcond

MTS_NAMESPACE_END

#endif /* __MITSUBA_CORE_STREAM_H_ */