SourceDestBuffer Class Reference

A memory buffer to transfer data to/from a CompressedVectorNode in a block. More...

List of all members.

Public Member Functions
	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.
	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.
	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.
	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.
	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.
	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.
	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.
	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.
	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.
	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.
	SourceDestBuffer (ImageFile destImageFile, const ustring pathName, std::vector< ustring > *b)
	Designate vector of strings to transfer data to/from a CompressedVector as a block.
ustring	pathName () const
	Get path name in prototype that this SourceDestBuffer will transfer data to/from.
enum MemoryRepresentation	memoryRepresentation () const
	Get memory representation of the elements in this SourceDestBuffer.
size_t	capacity () const
	Get total capacity of buffer.
bool	doConversion () const
	Get whether conversions will be performed to match the memory type of buffer.
bool	doScaling () const
	Get whether scaling will be performed for ScaledIntegerNode transfers.
size_t	stride () const
	Get number of bytes between consecutive memory elements in buffer.
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.
void	checkInvariant (bool doRecurse=true)
	Check whether SourceDestBuffer class invariant is true.

---

Detailed Description

A memory buffer to transfer data to/from a CompressedVectorNode in a block.

The SourceDestBuffer is an encapsulation of a buffer in memory that will transfer data to/from a field in a CompressedVectorNode. The API user is responsible for creating the actual memory buffer, describing it correctly to the API, making sure it exists during the transfer period, and destroying it after the transfer is complete. Additionally, the SourceDestBuffer has information that specifies the connection to the CompressedVectorNode field (i.e. the field's path name in the prototype).

The type of buffer element may be an assortment of built-in C++ memory types. There are all combinations of signed/unsigned and 8/16/32/64 bit integers (except unsigned 64bit integer, which is not supported in the ASTM standard), bool, float, double, as well as a vector of variable length unicode strings. The compiler selects the appropriate constructor automatically based on the type of the buffer array. However, the API user is responsible for reporting the correct length and stride options (otherwise unspecified behavior can occur).

The connection of the SourceDestBuffer to a CompressedVectorNode field is established by specifying the pathName. There are several options to this connection: doConversion and doScaling, which are described in the constructor documentation.

Class Invariant

A class invariant is a list of statements about an object that are always true before and after any operation on the object. An invariant is useful for testing correct operation of an implementation. Statements in an invariant can involve only externally visible state, or can refer to internal implementation-specific state that is not visible to the API user. The following C++ code checks externally visible state for consistency and throws an exception if the invariant is violated:

void SourceDestBuffer::checkInvariant(bool /*doRecurse*/) {
    // Stride must be >= a memory type dependent value
    size_t min_stride = 0;
    switch (memoryRepresentation()) {
        case E57_INT8:      min_stride = 1; break;
        case E57_UINT8:     min_stride = 1; break;
        case E57_INT16:     min_stride = 2; break;
        case E57_UINT16:    min_stride = 2; break;
        case E57_INT32:     min_stride = 4; break;
        case E57_UINT32:    min_stride = 4; break;
        case E57_INT64:     min_stride = 8; break;
        case E57_BOOL:      min_stride = 1; break;
        case E57_REAL32:    min_stride = 4; break;
        case E57_REAL64:    min_stride = 8; break;
        case E57_USTRING:   min_stride = sizeof(ustring); break;
        default:
            throw E57_EXCEPTION1(E57_ERROR_INVARIANCE_VIOLATION);
    }
    if (stride() < min_stride)
        throw E57_EXCEPTION1(E57_ERROR_INVARIANCE_VIOLATION);
} // end SourceDestBuffer::checkInvariant

See also:

Node