Base class for storing attribute data. More...

#include <openvdb/points/AttributeArray.h>

Inherited by TypedAttributeArray< ValueType_, Codec_ >.

Classes
struct	Accessor

struct	AccessorBase
	Accessor base class for AttributeArray storage where type is not available. More...

class	ScopedRegistryLock

Public Types
enum	Flag { TRANSIENT = 0x1, HIDDEN = 0x2, CONSTANTSTRIDE = 0x8, STREAMING = 0x10, PARTIALREAD = 0x20 }

enum	SerializationFlag { WRITESTRIDED = 0x1, WRITEUNIFORM = 0x2, WRITEMEMCOMPRESS = 0x4, WRITEPAGED = 0x8 }

using	Ptr = std::shared_ptr< AttributeArray >

using	ConstPtr = std::shared_ptr< const AttributeArray >

using	FactoryMethod = Ptr()(Index, Index, bool, const Metadata )

Public Member Functions
	AttributeArray ()

virtual	~AttributeArray ()

	AttributeArray (const AttributeArray &rhs)

AttributeArray &	operator= (const AttributeArray &rhs)

	AttributeArray (AttributeArray &&)=delete

AttributeArray &	operator= (AttributeArray &&)=delete

virtual AttributeArray::Ptr	copy () const =0
	Return a copy of this attribute. More...

virtual Index	size () const =0

virtual Index	stride () const =0

virtual Index	dataSize () const =0

virtual Name	valueType () const =0
	Return the name of the value type of a single element in this array (e.g., "float" or "vec3d"). More...

virtual Name	codecType () const =0
	Return the name of the codec used by this array (e.g., "trnc" or "fxpt"). More...

virtual Index	valueTypeSize () const =0

virtual Index	storageTypeSize () const =0

virtual bool	valueTypeIsFloatingPoint () const =0
	Return `true` if the value type is floating point. More...

virtual bool	valueTypeIsClass () const =0
	Return `true` if the value type is a class (ie vector, matrix or quaternion return true) More...

virtual bool	valueTypeIsVector () const =0
	Return `true` if the value type is a vector. More...

virtual bool	valueTypeIsQuaternion () const =0
	Return `true` if the value type is a quaternion. More...

virtual bool	valueTypeIsMatrix () const =0
	Return `true` if the value type is a matrix. More...

virtual size_t	memUsage () const =0
	Return the number of bytes of memory used by this attribute. More...

virtual size_t	memUsageIfLoaded () const =0

virtual const NamePair &	type () const =0
	Return the name of this attribute's type. More...

template<typename AttributeArrayType >
bool	isType () const
	Return `true` if this attribute is of the same type as the template parameter. More...

template<typename ValueType >
bool	hasValueType () const
	Return `true` if this attribute has a value type the same as the template parameter. More...

template<typename IterT >
void	copyValuesUnsafe (const AttributeArray &sourceArray, const IterT &iter)
	Copy values into this array from a source array to a target array as referenced by an iterator. More...

template<typename IterT >
void	copyValues (const AttributeArray &sourceArray, const IterT &iter, bool compact=true)
	Like copyValuesUnsafe(), but if compact is true, attempt to collapse this array. More...

virtual bool	isUniform () const =0
	Return `true` if this array is stored as a single uniform value. More...

virtual void	expand (bool fill=true)=0
	If this array is uniform, replace it with an array of length size(). More...

virtual void	collapse ()=0
	Replace the existing array with a uniform zero value. More...

virtual bool	compact ()=0
	Compact the existing array to become uniform if all values are identical. More...

void	setHidden (bool state)
	Specify whether this attribute should be hidden (e.g., from UI or iterators). More...

bool	isHidden () const
	Return `true` if this attribute is hidden (e.g., from UI or iterators). More...

void	setTransient (bool state)
	Specify whether this attribute should only exist in memory and not be serialized during stream output. More...

bool	isTransient () const
	Return `true` if this attribute is not serialized during stream output. More...

void	setStreaming (bool state)
	Specify whether this attribute is to be streamed off disk, in which case, the attributes are collapsed after being first loaded leaving them in a destroyed state. More...

bool	isStreaming () const
	Return `true` if this attribute is in streaming mode. More...

bool	hasConstantStride () const
	Return `true` if this attribute has a constant stride. More...

uint8_t	flags () const
	Retrieve the attribute array flags. More...

virtual void	read (std::istream &)=0
	Read attribute metadata and buffers from a stream. More...

virtual void	write (std::ostream &, bool outputTransient) const =0

virtual void	write (std::ostream &) const =0
	Write attribute metadata and buffers to a stream, don't write transient attributes. More...

virtual void	readMetadata (std::istream &)=0
	Read attribute metadata from a stream. More...

virtual void	writeMetadata (std::ostream &, bool outputTransient, bool paged) const =0

virtual void	readBuffers (std::istream &)=0
	Read attribute buffers from a stream. More...

virtual void	writeBuffers (std::ostream &, bool outputTransient) const =0

virtual void	readPagedBuffers (compression::PagedInputStream &)=0
	Read attribute buffers from a paged stream. More...

virtual void	writePagedBuffers (compression::PagedOutputStream &, bool outputTransient) const =0

virtual void	loadData () const =0
	Ensures all data is in-core. More...

virtual bool	isDataLoaded () const =0
	Return `true` if all data has been loaded. More...

bool	operator== (const AttributeArray &other) const

bool	operator!= (const AttributeArray &other) const

const char *	constDataAsByteArray () const
	Indirect virtual function to retrieve the data buffer cast to a char byte array. More...

Static Public Member Functions
static Ptr	create (const NamePair &type, Index length, Index stride=1, bool constantStride=true, const Metadata metadata=nullptr, const ScopedRegistryLock lock=nullptr)

static bool	isRegistered (const NamePair &type, const ScopedRegistryLock *lock=nullptr)
	Return `true` if the given attribute type name is registered. More...

static void	clearRegistry (const ScopedRegistryLock *lock=nullptr)
	Clear the attribute type registry. More...

Protected Types
using	AccessorBasePtr = std::shared_ptr< AccessorBase >

Protected Member Functions
	AttributeArray (const AttributeArray &rhs, const tbb::spin_mutex::scoped_lock &)

void	setConstantStride (bool state)
	Specify whether this attribute has a constant stride or not. More...

virtual AccessorBasePtr	getAccessor () const =0
	Obtain an Accessor that stores getter and setter functors. More...

Static Protected Member Functions
static void	registerType (const NamePair &type, FactoryMethod, const ScopedRegistryLock *lock=nullptr)
	Register a attribute type along with a factory function. More...

static void	unregisterType (const NamePair &type, const ScopedRegistryLock *lock=nullptr)
	Remove a attribute type from the registry. More...

Protected Attributes
bool	mIsUniform = true

tbb::spin_mutex	mMutex

uint8_t	mFlags = 0

uint8_t	mUsePagedRead = 0

std::atomic< Index32 >	mOutOfCore

union {
compression::PageHandle::Ptr mPageHandle

size_t mCompressedBytes

};
	used for out-of-core, paged reading More...

Friends
template<typename ValueType , typename CodecType >
class	AttributeHandle

class	::TestAttributeArray

Detailed Description

Base class for storing attribute data.

Member Typedef Documentation

using AccessorBasePtr = std::shared_ptr<AccessorBase>

protected

using ConstPtr = std::shared_ptr<const AttributeArray>

using FactoryMethod = Ptr (*)(Index, Index, bool, const Metadata*)

using Ptr = std::shared_ptr<AttributeArray>

Member Enumeration Documentation

enum Flag

Enumerator
TRANSIENT
HIDDEN	by default not written to disk
CONSTANTSTRIDE	hidden from UIs or iterators
STREAMING	stride size does not vary in the array
PARTIALREAD	streaming mode collapses attributes when first accessed

enum SerializationFlag

Enumerator
WRITESTRIDED
WRITEUNIFORM	data is marked as strided when written
WRITEMEMCOMPRESS	data is marked as uniform when written
WRITEPAGED	data is marked as compressed in-memory when written (deprecated flag as of ABI=6)

Constructor & Destructor Documentation

AttributeArray ( )

inline

virtual ~AttributeArray ( )

inlinevirtual

AttributeArray ( const AttributeArray & rhs )

AttributeArray ( AttributeArray && )

delete

AttributeArray	(	const AttributeArray &	rhs,
		const tbb::spin_mutex::scoped_lock &
	)

protected

Member Function Documentation

static void clearRegistry ( const ScopedRegistryLock * lock = nullptr )

static

Clear the attribute type registry.

virtual Name codecType ( ) const

pure virtual

Return the name of the codec used by this array (e.g., "trnc" or "fxpt").

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

virtual void collapse ( )

pure virtual

Replace the existing array with a uniform zero value.

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

virtual bool compact ( )

pure virtual

Compact the existing array to become uniform if all values are identical.

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

const char* constDataAsByteArray ( ) const

inline

Indirect virtual function to retrieve the data buffer cast to a char byte array.

virtual AttributeArray::Ptr copy ( ) const

pure virtual

Return a copy of this attribute.

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

void copyValues	(	const AttributeArray &	sourceArray,
		const IterT &	iter,
		bool	compact = `true`
	)

Like copyValuesUnsafe(), but if compact is true, attempt to collapse this array.

Note: This method is not thread-safe, it must be guaranteed that this array is not concurrently modified by another thread and that the source array is also not modified.

void copyValuesUnsafe	(	const AttributeArray &	sourceArray,
		const IterT &	iter
	)

Copy values into this array from a source array to a target array as referenced by an iterator.

Iterators must adhere to the ForwardIterator interface described in the example below:

struct MyIterator
{
    // returns true if the iterator is referencing valid copying indices
    operator bool() const;
    // increments the iterator
    MyIterator& operator++();
    // returns the source index that the iterator is referencing for copying
    Index sourceIndex() const;
    // returns the target index that the iterator is referencing for copying
    Index targetIndex() const;
};

Note: It is assumed that the strided storage sizes match, the arrays are both in-core, and both value types are floating-point or both integer.; It is possible to use this method to write to a uniform target array if the iterator does not have non-zero target indices.; This method is not thread-safe, it must be guaranteed that this array is not concurrently modified by another thread and that the source array is also not modified.

static Ptr create	(	const NamePair &	type,
		Index	length,
		Index	stride = `1`,
		bool	constantStride = `true`,
		const Metadata *	metadata = `nullptr`,
		const ScopedRegistryLock *	lock = `nullptr`
	)

static

Create a new attribute array of the given (registered) type, length and stride.

If lock is non-null, the AttributeArray registry mutex has already been locked

virtual Index dataSize ( ) const

pure virtual

Return the total number of data elements in this array.

Note: This counts each data element in a strided array

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

virtual void expand ( bool fill = true )

pure virtual

If this array is uniform, replace it with an array of length size().

Parameters

fill	if true, assign the uniform value to each element of the array.

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

uint8_t flags ( ) const

inline

Retrieve the attribute array flags.

virtual AccessorBasePtr getAccessor ( ) const

protectedpure virtual

Obtain an Accessor that stores getter and setter functors.

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

bool hasConstantStride ( ) const

inline

Return true if this attribute has a constant stride.

bool hasValueType ( ) const

inline

Return true if this attribute has a value type the same as the template parameter.

virtual bool isDataLoaded ( ) const

pure virtual

Return true if all data has been loaded.

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

bool isHidden ( ) const

inline

Return true if this attribute is hidden (e.g., from UI or iterators).

static bool isRegistered	(	const NamePair &	type,
		const ScopedRegistryLock *	lock = `nullptr`
	)

static

Return true if the given attribute type name is registered.

bool isStreaming ( ) const

inline

Return true if this attribute is in streaming mode.

bool isTransient ( ) const

inline

Return true if this attribute is not serialized during stream output.

bool isType ( ) const

inline

Return true if this attribute is of the same type as the template parameter.

virtual bool isUniform ( ) const

pure virtual

Return true if this array is stored as a single uniform value.

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

virtual void loadData ( ) const

pure virtual

Ensures all data is in-core.

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

virtual size_t memUsage ( ) const

pure virtual

Return the number of bytes of memory used by this attribute.

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

virtual size_t memUsageIfLoaded ( ) const

pure virtual

Return the number of bytes of memory used by this attribute array once it has been deserialized (this may be different to memUsage() if delay-loading is in use). Note that this method does NOT consider the fact that a uniform attribute could be expanded and only deals with delay-loading.

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

bool operator!= ( const AttributeArray & other ) const

inline

AttributeArray& operator= ( const AttributeArray & rhs )

AttributeArray& operator= ( AttributeArray && )

delete

bool operator== ( const AttributeArray & other ) const

Check the compressed bytes and flags. If they are equal, perform a deeper comparison check necessary on the inherited types (TypedAttributeArray) Requires non operator implementation due to inheritance

virtual void read ( std::istream & )

pure virtual

Read attribute metadata and buffers from a stream.

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

virtual void readBuffers ( std::istream & )

pure virtual

Read attribute buffers from a stream.

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

virtual void readMetadata ( std::istream & )

pure virtual

Read attribute metadata from a stream.

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

virtual void readPagedBuffers ( compression::PagedInputStream & )

pure virtual

Read attribute buffers from a paged stream.

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

static void registerType	(	const NamePair &	type,
		FactoryMethod	,
		const ScopedRegistryLock *	lock = `nullptr`
	)

staticprotected

Register a attribute type along with a factory function.

void setConstantStride ( bool state )

protected

Specify whether this attribute has a constant stride or not.

void setHidden ( bool state )

Specify whether this attribute should be hidden (e.g., from UI or iterators).

This is useful if the attribute is used for blind data or as scratch space for a calculation.

Note: Attributes are not hidden by default.

void setStreaming ( bool state )

Specify whether this attribute is to be streamed off disk, in which case, the attributes are collapsed after being first loaded leaving them in a destroyed state.

Note: This operation is not thread-safe.

void setTransient ( bool state )

Specify whether this attribute should only exist in memory and not be serialized during stream output.

Note: Attributes are not transient by default.

virtual Index size ( ) const

pure virtual

Return the number of elements in this array.

Note: This does not count each data element in a strided array

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

virtual Index storageTypeSize ( ) const

pure virtual

Return the size in bytes of the storage type of a single element of this array.

Note: If the Codec is a NullCodec, valueSize() == storageSize()

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

virtual Index stride ( ) const

pure virtual

Return the stride of this array.

Note: a return value of zero means a non-constant stride

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

virtual const NamePair& type ( ) const

pure virtual

Return the name of this attribute's type.

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

static void unregisterType	(	const NamePair &	type,
		const ScopedRegistryLock *	lock = `nullptr`
	)

staticprotected

Remove a attribute type from the registry.

virtual Name valueType ( ) const

pure virtual

Return the name of the value type of a single element in this array (e.g., "float" or "vec3d").

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

virtual bool valueTypeIsClass ( ) const

pure virtual

Return true if the value type is a class (ie vector, matrix or quaternion return true)

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

virtual bool valueTypeIsFloatingPoint ( ) const

pure virtual

Return true if the value type is floating point.

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

virtual bool valueTypeIsMatrix ( ) const

pure virtual

Return true if the value type is a matrix.

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

virtual bool valueTypeIsQuaternion ( ) const

pure virtual

Return true if the value type is a quaternion.

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

virtual bool valueTypeIsVector ( ) const

pure virtual

Return true if the value type is a vector.

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

virtual Index valueTypeSize ( ) const

pure virtual

Return the size in bytes of the value type of a single element in this array. (e.g. "float" -> 4 bytes, "vec3d" -> 24 bytes").

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

virtual void write	(	std::ostream &	,
		bool	outputTransient
	)		const

pure virtual

Write attribute metadata and buffers to a stream.

Parameters

outputTransient if true, write out transient attributes

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

virtual void write ( std::ostream & ) const

pure virtual

Write attribute metadata and buffers to a stream, don't write transient attributes.

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

virtual void writeBuffers	(	std::ostream &	,
		bool	outputTransient
	)		const

pure virtual

Write attribute buffers to a stream.

Parameters

outputTransient if true, write out transient attributes

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

virtual void writeMetadata	(	std::ostream &	,
		bool	outputTransient,
		bool	paged
	)		const

pure virtual

Write attribute metadata to a stream.

Parameters

outputTransient	if true, write out transient attributes
paged	if true, data is written out in pages

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

virtual void writePagedBuffers	(	compression::PagedOutputStream &	,
		bool	outputTransient
	)		const

pure virtual

Write attribute buffers to a paged stream.

Parameters

outputTransient if true, write out transient attributes

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

Friends And Related Function Documentation

friend class ::TestAttributeArray

friend

friend class AttributeHandle

friend

Member Data Documentation

union { ... }

used for out-of-core, paged reading

size_t mCompressedBytes

uint8_t mFlags = 0

protected

bool mIsUniform = true

protected

tbb::spin_mutex mMutex

mutableprotected

std::atomic<Index32> mOutOfCore

protected

compression::PageHandle::Ptr mPageHandle

uint8_t mUsePagedRead = 0

protected

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Types

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation