#include <E57Format.h>

Public Member Functions
	SourceDestBuffer ()=delete

	SourceDestBuffer (ImageFile destImageFile, const ustring &pathName, int8_t *b, const size_t capacity, bool doConversion=false, bool doScaling=false, size_t stride=sizeof(int8_t))
	Designate buffers to transfer data to/from a CompressedVectorNode in a block. More...

	SourceDestBuffer (ImageFile destImageFile, const ustring &pathName, uint8_t *b, const size_t capacity, bool doConversion=false, bool doScaling=false, size_t stride=sizeof(uint8_t))
	Designate buffers to transfer data to/from a CompressedVectorNode in a block. More...

	SourceDestBuffer (ImageFile destImageFile, const ustring &pathName, int16_t *b, const size_t capacity, bool doConversion=false, bool doScaling=false, size_t stride=sizeof(int16_t))
	Designate buffers to transfer data to/from a CompressedVectorNode in a block. More...

	SourceDestBuffer (ImageFile destImageFile, const ustring &pathName, uint16_t *b, const size_t capacity, bool doConversion=false, bool doScaling=false, size_t stride=sizeof(uint16_t))
	Designate buffers to transfer data to/from a CompressedVectorNode in a block. More...

	SourceDestBuffer (ImageFile destImageFile, const ustring &pathName, int32_t *b, const size_t capacity, bool doConversion=false, bool doScaling=false, size_t stride=sizeof(int32_t))
	Designate buffers to transfer data to/from a CompressedVectorNode in a block. More...

	SourceDestBuffer (ImageFile destImageFile, const ustring &pathName, uint32_t *b, const size_t capacity, bool doConversion=false, bool doScaling=false, size_t stride=sizeof(uint32_t))
	Designate buffers to transfer data to/from a CompressedVectorNode in a block. More...

	SourceDestBuffer (ImageFile destImageFile, const ustring &pathName, int64_t *b, const size_t capacity, bool doConversion=false, bool doScaling=false, size_t stride=sizeof(int64_t))
	Designate buffers to transfer data to/from a CompressedVectorNode in a block. More...

	SourceDestBuffer (ImageFile destImageFile, const ustring &pathName, bool *b, const size_t capacity, bool doConversion=false, bool doScaling=false, size_t stride=sizeof(bool))
	Designate buffers to transfer data to/from a CompressedVectorNode in a block. More...

	SourceDestBuffer (ImageFile destImageFile, const ustring &pathName, float *b, const size_t capacity, bool doConversion=false, bool doScaling=false, size_t stride=sizeof(float))
	Designate buffers to transfer data to/from a CompressedVectorNode in a block. More...

	SourceDestBuffer (ImageFile destImageFile, const ustring &pathName, double *b, const size_t capacity, bool doConversion=false, bool doScaling=false, size_t stride=sizeof(double))
	Designate buffers to transfer data to/from a CompressedVectorNode in a block. More...

	SourceDestBuffer (ImageFile destImageFile, const ustring &pathName, std::vector< ustring > *b)

ustring	pathName () const
	Get path name in prototype that this SourceDestBuffer will transfer data to/from. More...

enum MemoryRepresentation	memoryRepresentation () const
	Get memory representation of the elements in this SourceDestBuffer. More...

size_t	capacity () const
	Get total capacity of buffer. More...

bool	doConversion () const
	Get whether conversions will be performed to match the memory type of buffer. More...

bool	doScaling () const
	Get whether scaling will be performed for ScaledIntegerNode transfers. More...

size_t	stride () const
	Get number of bytes between consecutive memory elements in buffer. More...

void	dump (int indent=0, std::ostream &os=std::cout) const
	Diagnostic function to print internal state of object to output stream in an indented format. More...

void	checkInvariant (bool doRecurse=true) const
	Check whether SourceDestBuffer class invariant is true. More...

Detailed Description

Definition at line 298 of file E57Format.h.

Constructor & Destructor Documentation

◆ SourceDestBuffer() [1/12]

e57::SourceDestBuffer::SourceDestBuffer ( )

delete

◆ SourceDestBuffer() [2/12]

SourceDestBuffer::SourceDestBuffer	(	ImageFile	destImageFile,
		const ustring &	pathName,
		int8_t *	b,
		const size_t	capacity,
		bool	doConversion = `false`,
		bool	doScaling = `false`,
		size_t	stride = `sizeof( int8_t )`
	)

Designate buffers to transfer data to/from a CompressedVectorNode in a block.

Parameters

[in]	destImageFile	The ImageFile where the new node will eventually be stored.
[in]	pathName	The pathname of the field in CompressedVectorNode that will transfer data to/from.
[in]	b	The caller allocated memory buffer.
[in]	capacity	The total number of memory elements in buffer b.
[in]	doConversion	Will a conversion be attempted between memory and ImageFile representations.
[in]	doScaling	In a ScaledInteger field, do memory elements hold scaled values, if false they hold raw values.
[in]	stride	The number of bytes between memory elements. If zero, defaults to sizeof memory element.

This overloaded form of the SourceDestBuffer constructor declares a buffer b to be the source/destination of a transfer of values stored in a CompressedVectorNode.

The pathName will be used to identify a Node in the prototype that will get/receive data from this buffer. The pathName may be an absolute path name (e.g. "/cartesianX") or a path name relative to the root of the prototype (i.e. the absolute path name without the leading "/", for example: "cartesianX").

The type of b is used to determine the MemoryRepresentation of the SourceDestBuffer. The buffer b may be used for multiple block transfers. See discussions of operation of SourceDestBuffer attributes in SourceDestBuffer::memoryRepresentation, SourceDestBuffer::capacity, SourceDestBuffer::doConversion, and SourceDestBuffer::doScaling, and SourceDestBuffer::stride.

The API user is responsible for ensuring that the lifetime of the b memory buffer exceeds the time that it is used in transfers (i.e. the E57 Foundation Implementation cannot detect that the buffer been destroyed).

The capacity must match the capacity of all other SourceDestBuffers that will participate in a transfer with a CompressedVectorNode.

Precondition: The destImageFile must be open (i.e. destImageFile.isOpen() must be true).; The stride must be >= sizeof(*b)

Returns: A smart SourceDestBuffer handle referencing the underlying object.

Exceptions

E57_ERROR_BAD_API_ARGUMENT
E57_ERROR_BAD_PATH_NAME
E57_ERROR_BAD_BUFFER
E57_ERROR_IMAGEFILE_NOT_OPEN
E57_ERROR_INTERNAL	All objects in undocumented state

See also: ImageFile::reader, ImageFile::writer, CompressedVectorReader::read(std::vector<SourceDestBuffer>&), CompressedVectorWriter::write(std::vector<SourceDestBuffer>&)

Definition at line 1860 of file E57Format.cpp.

References stride().

◆ SourceDestBuffer() [3/12]

SourceDestBuffer::SourceDestBuffer	(	ImageFile	destImageFile,
		const ustring &	pathName,
		uint8_t *	b,
		const size_t	capacity,
		bool	doConversion = `false`,
		bool	doScaling = `false`,
		size_t	stride = `sizeof( uint8_t )`
	)

Designate buffers to transfer data to/from a CompressedVectorNode in a block.

Definition at line 1871 of file E57Format.cpp.

References stride().

◆ SourceDestBuffer() [4/12]

SourceDestBuffer::SourceDestBuffer	(	ImageFile	destImageFile,
		const ustring &	pathName,
		int16_t *	b,
		const size_t	capacity,
		bool	doConversion = `false`,
		bool	doScaling = `false`,
		size_t	stride = `sizeof( int16_t )`
	)

Designate buffers to transfer data to/from a CompressedVectorNode in a block.

Definition at line 1882 of file E57Format.cpp.

References stride().

◆ SourceDestBuffer() [5/12]

SourceDestBuffer::SourceDestBuffer	(	ImageFile	destImageFile,
		const ustring &	pathName,
		uint16_t *	b,
		const size_t	capacity,
		bool	doConversion = `false`,
		bool	doScaling = `false`,
		size_t	stride = `sizeof( uint16_t )`
	)

Designate buffers to transfer data to/from a CompressedVectorNode in a block.

Definition at line 1893 of file E57Format.cpp.

References stride().

◆ SourceDestBuffer() [6/12]

SourceDestBuffer::SourceDestBuffer	(	ImageFile	destImageFile,
		const ustring &	pathName,
		int32_t *	b,
		const size_t	capacity,
		bool	doConversion = `false`,
		bool	doScaling = `false`,
		size_t	stride = `sizeof( int32_t )`
	)

Designate buffers to transfer data to/from a CompressedVectorNode in a block.

Definition at line 1904 of file E57Format.cpp.

References stride().

◆ SourceDestBuffer() [7/12]

SourceDestBuffer::SourceDestBuffer	(	ImageFile	destImageFile,
		const ustring &	pathName,
		uint32_t *	b,
		const size_t	capacity,
		bool	doConversion = `false`,
		bool	doScaling = `false`,
		size_t	stride = `sizeof( uint32_t )`
	)

Designate buffers to transfer data to/from a CompressedVectorNode in a block.

Definition at line 1915 of file E57Format.cpp.

References stride().

◆ SourceDestBuffer() [8/12]

SourceDestBuffer::SourceDestBuffer	(	ImageFile	destImageFile,
		const ustring &	pathName,
		int64_t *	b,
		const size_t	capacity,
		bool	doConversion = `false`,
		bool	doScaling = `false`,
		size_t	stride = `sizeof( int64_t )`
	)

Designate buffers to transfer data to/from a CompressedVectorNode in a block.

Definition at line 1926 of file E57Format.cpp.

References stride().

◆ SourceDestBuffer() [9/12]

SourceDestBuffer::SourceDestBuffer	(	ImageFile	destImageFile,
		const ustring &	pathName,
		bool *	b,
		const size_t	capacity,
		bool	doConversion = `false`,
		bool	doScaling = `false`,
		size_t	stride = `sizeof( bool )`
	)

Designate buffers to transfer data to/from a CompressedVectorNode in a block.

Definition at line 1937 of file E57Format.cpp.

References stride().

◆ SourceDestBuffer() [10/12]

SourceDestBuffer::SourceDestBuffer	(	ImageFile	destImageFile,
		const ustring &	pathName,
		float *	b,
		const size_t	capacity,
		bool	doConversion = `false`,
		bool	doScaling = `false`,
		size_t	stride = `sizeof( float )`
	)

Designate buffers to transfer data to/from a CompressedVectorNode in a block.

Definition at line 1948 of file E57Format.cpp.

References stride().

◆ SourceDestBuffer() [11/12]

SourceDestBuffer::SourceDestBuffer	(	ImageFile	destImageFile,
		const ustring &	pathName,
		double *	b,
		const size_t	capacity,
		bool	doConversion = `false`,
		bool	doScaling = `false`,
		size_t	stride = `sizeof( double )`
	)

Designate buffers to transfer data to/from a CompressedVectorNode in a block.

Definition at line 1959 of file E57Format.cpp.

References stride().

◆ SourceDestBuffer() [12/12]

e57::SourceDestBuffer::SourceDestBuffer	(	ImageFile	destImageFile,
		const ustring &	pathName,
		std::vector< ustring > *	b
	)

Member Function Documentation

◆ capacity()

size_t SourceDestBuffer::capacity ( ) const

Get total capacity of buffer.

The API programmer is responsible for correctly specifying the length of a buffer. This function returns that declared length. If the length is incorrect (in particular, too long) memory may be corrupted or erroneous values written.

Postcondition: No visible state is modified.

Returns: Total capacity of buffer.

Exceptions

E57_ERROR_INTERNAL All objects in undocumented state

Definition at line 2070 of file E57Format.cpp.

Referenced by e57::DecodeChannel::isOutputBlocked().

◆ checkInvariant()

void SourceDestBuffer::checkInvariant ( bool doRecurse = true ) const

Check whether SourceDestBuffer class invariant is true.

Definition at line 881 of file E57Format.cpp.

References e57::E57_BOOL, e57::E57_ERROR_INVARIANCE_VIOLATION, E57_EXCEPTION1, e57::E57_INT16, e57::E57_INT32, e57::E57_INT64, e57::E57_INT8, e57::E57_REAL32, e57::E57_REAL64, e57::E57_UINT16, e57::E57_UINT32, e57::E57_UINT8, e57::E57_USTRING, memoryRepresentation(), and stride().

◆ doConversion()

bool SourceDestBuffer::doConversion ( ) const

Get whether conversions will be performed to match the memory type of buffer.

The API user must explicitly request conversion between basic representation groups in memory and on the disk. The four basic representation groups are: integer, boolean, floating point, and string. There is no distinction between integer and boolean groups on the disk (they both use IntegerNode). A explicit request for conversion between single and double precision floating point representations is not required.

The most useful conversion is between integer and floating point representation groups. Conversion from integer to floating point representations cannot result in an overflow, and is usually loss-less (except for extremely large integers). Conversion from floating point to integer representations can result in an overflow, and can be lossy.

Conversion between any of the integer, boolean, and floating point representation groups is supported. No conversion from the string to any other representation group is possible. Missing or unsupported conversions are detected when the first transfer is attempted (i.e. not when the CompressedVectorReader or CompressedVectorWriter is created).

Postcondition: No visible state is modified.

Returns: true if conversions will be performed to match the memory type of buffer.

Exceptions

E57_ERROR_IMAGEFILE_NOT_OPEN
E57_ERROR_INTERNAL	All objects in undocumented state

Definition at line 2104 of file E57Format.cpp.

◆ doScaling()

bool SourceDestBuffer::doScaling ( ) const

Get whether scaling will be performed for ScaledIntegerNode transfers.

The doScaling option only applies to ScaledIntegerNodes stored in a CompressedVectorNode on the disk (it is ignored if a ScaledIntegerNode is not involved).

As a convenience, an E57 Foundation Implementation can perform scaling of data so that the API user can manipulate scaledValues rather than rawValues. For a reader, the scaling process is: scaledValue = (rawValue * scale) + offset. For a writer, the scaling process is reversed: rawValue = (scaledValue - offset) / scale. The result performing a scaling in a reader (or "unscaling" in a writer) is always a floating point number. This floating point number may have to be converted to be compatible with the destination representation. If the destination representation is not floating point, there is a risk of violating declared min/max bounds. Because of this risk, it is recommended that scaling only be requested for reading scaledValues from ScaledIntegerNodes into floating point numbers in memory.

It is also possible (and perhaps safest of all) to never request that scaling be performed, and always deal with rawValues outside the API. Note this does not mean that ScaledIntegerNodes should be avoided. ScaledIntgerNodes are essential for encoding numeric data with fractional parts in CompressedVectorNodes. Because the ASTM E57 format recommends that SI units without prefix be used (i.e. meters, not milli-meters or micro-furlongs), almost every measured value will have a fractional part.

Postcondition: No visible state is modified.

Returns: true if scaling will be performed for ScaledInteger transfers.

Exceptions

E57_ERROR_INTERNAL All objects in undocumented state

See also: ScaledIntegerNode

Definition at line 2141 of file E57Format.cpp.

◆ dump()

void SourceDestBuffer::dump	(	int	indent = `0`,
		std::ostream &	os = `std::cout`
	)		const

Diagnostic function to print internal state of object to output stream in an indented format.

Parameters

[in]	indent	Number of spaces to indent all the printed lines of this object.
[in]	os	Output stream to print on.

All objects in the E57 Foundation API (with exception of E57Exception) support a dump() function. These functions print out to the console a detailed listing of the internal state of objects. The content of these printouts is not documented, and is really of interest only to implementation developers/maintainers or the really adventurous users. In implementations of the API other than the Reference Implementation, the dump() functions may produce no output (although the functions should still be defined). The output format may change from version to version.

Postcondition: No visible object state is modified.

Exceptions

No	E57Exceptions

Definition at line 2167 of file E57Format.cpp.

Referenced by e57::DecodeChannel::dump().

◆ memoryRepresentation()

MemoryRepresentation SourceDestBuffer::memoryRepresentation ( ) const

Get memory representation of the elements in this SourceDestBuffer.

The memory representation is deduced from which overloaded SourceDestBuffer constructor was used. The memory representation is independent of the type and minimum/maximum bounds of the node in the prototype that the SourceDestBuffer will transfer to/from. However, some combinations will result in an error if doConversion is not requested (e.g. E57_INT16 and FloatNode).

Some combinations risk an error occurring during a write, if a value is too large (e.g. writing a E57_INT16 memory representation to an IntegerNode with minimum=-1024 maximum=1023). Some combinations risk an error occurring during a read, if a value is too large (e.g. reading an IntegerNode with minimum=-1024 maximum=1023 int an E57_INT8 memory representation). Some combinations are never possible (e.g. E57_INT16 and StringNode).

Postcondition: No visible state is modified.

Returns: Memory representation of the elements in buffer.

Exceptions

E57_ERROR_INTERNAL All objects in undocumented state

See also: MemoryRepresentation, NodeType

Definition at line 2055 of file E57Format.cpp.

Referenced by checkInvariant().

◆ pathName()

ustring SourceDestBuffer::pathName ( ) const

Get path name in prototype that this SourceDestBuffer will transfer data to/from.

The prototype of a CompressedVectorNode describes the fields that are in each record. This function returns the path name of the node in the prototype tree that this SourceDestBuffer will write/read. The correctness of this path name is checked when this SourceDestBuffer is associated with a CompressedVectorNode (either in CompressedVectorNode::writer, CompressedVectorWriter::write(std::vector<SourceDestBuffer>&, unsigned), CompressedVectorNode::reader, CompressedVectorReader::read(std::vector<SourceDestBuffer>&)).

Postcondition: No visible state is modified.

Returns: Path name in prototype that this SourceDestBuffer will transfer data to/from.

Exceptions

E57_ERROR_INTERNAL All objects in undocumented state

See also: CompressedVector, CompressedVectorNode::prototype

Definition at line 2030 of file E57Format.cpp.

Referenced by e57::Encoder::EncoderFactory().

◆ stride()

size_t SourceDestBuffer::stride ( ) const

Get number of bytes between consecutive memory elements in buffer.

Elements in a memory buffer do not have to be consecutive. They can also be spaced at regular intervals. This allows a value to be picked out of an array of C++ structures (the stride would be the size of the structure). In the case that the element values are stored consecutively in memory, the stride equals the size of the memory representation of the element.

Postcondition: No visible state is modified.

Returns: Number of bytes between consecutive memory elements in buffer

Definition at line 2158 of file E57Format.cpp.

Referenced by checkInvariant(), and SourceDestBuffer().

The documentation for this class was generated from the following files:

/root/ACloudViewer/plugins/core/IO/qE57IO/extern/libE57Format/include/E57Format.h
/root/ACloudViewer/plugins/core/IO/qE57IO/extern/libE57Format/src/E57Format.cpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ SourceDestBuffer() [1/12]

◆ SourceDestBuffer() [2/12]

◆ SourceDestBuffer() [3/12]

◆ SourceDestBuffer() [4/12]

◆ SourceDestBuffer() [5/12]

◆ SourceDestBuffer() [6/12]

◆ SourceDestBuffer() [7/12]

◆ SourceDestBuffer() [8/12]

◆ SourceDestBuffer() [9/12]

◆ SourceDestBuffer() [10/12]

◆ SourceDestBuffer() [11/12]

◆ SourceDestBuffer() [12/12]

Member Function Documentation

◆ capacity()

◆ checkInvariant()

◆ doConversion()

◆ doScaling()

◆ dump()

◆ memoryRepresentation()

◆ pathName()

◆ stride()