OpenVDB  6.1.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 <AttributeArray.h>

Inherited by TypedAttributeArray< ValueType_, Codec_ >.

Classes

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

Public Types

enum  Flag {
  TRANSIENT = 0x1, HIDDEN = 0x2, OUTOFCORE = 0x4, 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)
 

Public Member Functions

 AttributeArray ()
 
virtual ~AttributeArray ()
 
 AttributeArray (const AttributeArray &rhs)
 
AttributeArrayoperator= (const AttributeArray &rhs)
 
 AttributeArray (AttributeArray &&)=default
 
AttributeArrayoperator= (AttributeArray &&)=default
 
virtual AttributeArray::Ptr copy () const =0
 
virtual AttributeArray::Ptr copyUncompressed () const =0
 
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 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...
 
virtual OPENVDB_DEPRECATED void set (const Index n, const AttributeArray &sourceArray, const Index sourceIndex)=0
 Set value at given index n from sourceIndex of another sourceArray. 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...
 
OPENVDB_DEPRECATED bool isCompressed () const
 
virtual OPENVDB_DEPRECATED bool compress ()=0
 
virtual OPENVDB_DEPRECATED bool decompress ()=0
 
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
 

Static Public Member Functions

static Ptr create (const NamePair &type, Index length, Index stride=1, bool constantStride=true)
 Create a new attribute array of the given (registered) type, length and stride. More...
 
static bool isRegistered (const NamePair &type)
 Return true if the given attribute type name is registered. More...
 
static void clearRegistry ()
 Clear the attribute type registry. More...
 

Protected Types

using AccessorBasePtr = std::shared_ptr< AccessorBase >
 

Protected Member Functions

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)
 Register a attribute type along with a factory function. More...
 
static void unregisterType (const NamePair &type)
 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
 
tbb::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)
using Ptr = std::shared_ptr<AttributeArray>

Member Enumeration Documentation

enum Flag
Enumerator
TRANSIENT 
HIDDEN 

by default not written to disk

OUTOFCORE 

hidden from UIs or iterators

CONSTANTSTRIDE 

data not yet loaded from disk (deprecated flag as of ABI=5)

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)
inline
AttributeArray ( AttributeArray &&  )
default

Member Function Documentation

static void clearRegistry ( )
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_ >.

virtual OPENVDB_DEPRECATED bool compress ( )
pure virtual
Deprecated:
Previously this compressed the attribute array, now it does nothing.

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

virtual AttributeArray::Ptr copy ( ) const
pure virtual

Return a copy of this attribute.

Note
This method is thread-safe.

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

virtual AttributeArray::Ptr copyUncompressed ( ) const
pure virtual

Return an uncompressed copy of this attribute (will return a copy if not compressed).

Note
This method is thread-safe.

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 
)
static

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

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 OPENVDB_DEPRECATED bool decompress ( )
pure virtual
Deprecated:
Previously this uncompressed the attribute array, now it does nothing.

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.

OPENVDB_DEPRECATED bool isCompressed ( ) const
inline
Deprecated:
Previously this returned true if the array was compressed, now it always returns false.
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)
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_ >.

bool operator!= ( const AttributeArray other) const
inline
AttributeArray& operator= ( const AttributeArray rhs)
inline
AttributeArray& operator= ( AttributeArray &&  )
default
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   
)
staticprotected

Register a attribute type along with a factory function.

virtual OPENVDB_DEPRECATED void set ( const Index  n,
const AttributeArray sourceArray,
const Index  sourceIndex 
)
pure virtual

Set value at given index n from sourceIndex of another sourceArray.

Deprecated:
From ABI 6 on, use copyValues() with source-target index pairs.

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

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)
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
tbb::atomic<Index32> mOutOfCore
protected
uint8_t mUsePagedRead = 0
protected

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