OpenVDB  12.0.0
Classes | Public Types | Public Member Functions | Static Public Member Functions | Protected Types | Protected Member Functions | Static Protected Member Functions | Protected Attributes | Friends | List of all members
AttributeArray Class Referenceabstract

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)
 
AttributeArrayoperator= (const AttributeArray &rhs)
 
 AttributeArray (AttributeArray &&)=delete
 
AttributeArrayoperator= (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 NamePairtype () 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< Index32mOutOfCore
 
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

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
fillif 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
outputTransientif 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
outputTransientif 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
outputTransientif true, write out transient attributes
pagedif 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
outputTransientif 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
uint8_t mUsePagedRead = 0
protected