OpenVDB 11.0.0

Loading...
Searching...
No Matches
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>`

Inheritance diagram for AttributeArray:

## 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.
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").
virtual Name | codecType () const =0
| Return the name of the codec used by this array (e.g., "trnc" or "fxpt").
virtual Index | valueTypeSize () const =0
virtual Index | storageTypeSize () const =0
virtual bool | valueTypeIsFloatingPoint () const =0
| Return `true` if the value type is floating point.
virtual bool | valueTypeIsClass () const =0
| Return `true` if the value type is a class (ie vector, matrix or quaternion return true)
virtual bool | valueTypeIsVector () const =0
| Return `true` if the value type is a vector.
virtual bool | valueTypeIsQuaternion () const =0
| Return `true` if the value type is a quaternion.
virtual bool | valueTypeIsMatrix () const =0
| Return `true` if the value type is a matrix.
virtual size_t | memUsage () const =0
| Return the number of bytes of memory used by this attribute.
virtual size_t | memUsageIfLoaded () const =0
virtual const NamePair & | type () const =0
| Return the name of this attribute's type.
template<typename AttributeArrayType >
bool | isType () const
| Return `true` if this attribute is of the same type as the template parameter.
template<typename ValueType >
bool | hasValueType () const
| Return `true` if this attribute has a value type the same as the template parameter.
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.
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.
virtual bool | isUniform () const =0
| Return `true` if this array is stored as a single uniform value.
virtual void | expand (bool fill=true)=0
| If this array is uniform, replace it with an array of length size().
virtual void | collapse ()=0
| Replace the existing array with a uniform zero value.
virtual bool | compact ()=0
| Compact the existing array to become uniform if all values are identical.
void | setHidden (bool state)
| Specify whether this attribute should be hidden (e.g., from UI or iterators).
bool | isHidden () const
| Return `true` if this attribute is hidden (e.g., from UI or iterators).
void | setTransient (bool state)
| Specify whether this attribute should only exist in memory and not be serialized during stream output.
bool | isTransient () const
| Return `true` if this attribute is not serialized during stream output.
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.
bool | isStreaming () const
| Return `true` if this attribute is in streaming mode.
bool | hasConstantStride () const
| Return `true` if this attribute has a constant stride.
uint8_t | flags () const
| Retrieve the attribute array flags.
virtual void | read (std::istream &)=0
| Read attribute metadata and buffers from a stream.
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.
virtual void | readMetadata (std::istream &)=0
| Read attribute metadata from a stream.
virtual void | writeMetadata (std::ostream &, bool outputTransient, bool paged) const =0
virtual void | readBuffers (std::istream &)=0
| Read attribute buffers from a stream.
virtual void | writeBuffers (std::ostream &, bool outputTransient) const =0
virtual void | readPagedBuffers (compression::PagedInputStream &)=0
| Read attribute buffers from a paged stream.
virtual void | writePagedBuffers (compression::PagedOutputStream &, bool outputTransient) const =0
virtual void | loadData () const =0
| Ensures all data is in-core.
virtual bool | isDataLoaded () const =0
| Return `true` if all data has been loaded.
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.

## 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.
static void | clearRegistry (const ScopedRegistryLock *lock=nullptr)
| Clear the attribute type registry.

## 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.
virtual AccessorBasePtr | getAccessor () const =0
| Obtain an Accessor that stores getter and setter functors.

## Static Protected Member Functions
static void | registerType (const NamePair &type, FactoryMethod, const ScopedRegistryLock *lock=nullptr)
| Register a attribute type along with a factory function.
static void | unregisterType (const NamePair &type, const ScopedRegistryLock *lock=nullptr)
| Remove a attribute type from the registry.

## 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

## Friends
template<typename ValueType , typename CodecType >
class | AttributeHandle
class | ::TestAttributeArray

## Detailed Description

Base class for storing attribute data.

## Member Typedef Documentation

## ◆ AccessorBasePtr

using AccessorBasePtr = std::shared_ptr<AccessorBase>
| protected

## ◆ ConstPtr

using ConstPtr = std::shared_ptr<const AttributeArray>

## ◆ FactoryMethod

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

## ◆ Ptr

using Ptr = std::shared_ptr<AttributeArray>

## Member Enumeration Documentation

## ◆ Flag

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

## ◆ SerializationFlag

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() [1/4]

AttributeArray | ( |  | ) |
| inline

## ◆ ~AttributeArray()

virtual ~AttributeArray | ( |  | ) |
| inline virtual

## ◆ AttributeArray() [2/4]

AttributeArray | ( | const AttributeArray & | rhs | ) |

## ◆ AttributeArray() [3/4]

AttributeArray | ( | AttributeArray && |  | ) |
| delete

## ◆ AttributeArray() [4/4]

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

## Member Function Documentation

## ◆ clearRegistry()

static void clearRegistry | ( | const ScopedRegistryLock * | lock = `nullptr` | ) |
| static

Clear the attribute type registry.

## ◆ codecType()

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_ >.

## ◆ collapse()

virtual void collapse | ( |  | ) |
| pure virtual

Replace the existing array with a uniform zero value.

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

## ◆ compact()

virtual bool compact | ( |  | ) |
| pure virtual

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

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

## ◆ constDataAsByteArray()

const char * constDataAsByteArray | ( |  | ) | const
| inline

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

## ◆ copy()

virtual AttributeArray::Ptr copy | ( |  | ) | const
| pure virtual

Return a copy of this attribute.

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

## ◆ copyValues()

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.

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.

## ◆ copyValuesUnsafe()

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.

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;
};
openvdb::v11_0::Index
Index32 Index
Definition Types.h:54

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.

## ◆ create()

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

## ◆ dataSize()

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_ >.

## ◆ expand()

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_ >.

## ◆ flags()

uint8_t flags | ( |  | ) | const
| inline

Retrieve the attribute array flags.

## ◆ getAccessor()

virtual AccessorBasePtr getAccessor | ( |  | ) | const
| protected pure virtual

Obtain an Accessor that stores getter and setter functors.

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

## ◆ hasConstantStride()

bool hasConstantStride | ( |  | ) | const
| inline

Return `true` if this attribute has a constant stride.

## ◆ hasValueType()

template<typename ValueType >

bool hasValueType | ( |  | ) | const
| inline

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

## ◆ isDataLoaded()

virtual bool isDataLoaded | ( |  | ) | const
| pure virtual

Return `true` if all data has been loaded.

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

## ◆ isHidden()

bool isHidden | ( |  | ) | const
| inline

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

## ◆ isRegistered()

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

Return `true` if the given attribute type name is registered.

## ◆ isStreaming()

bool isStreaming | ( |  | ) | const
| inline

Return `true` if this attribute is in streaming mode.

## ◆ isTransient()

bool isTransient | ( |  | ) | const
| inline

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

## ◆ isType()

template<typename AttributeArrayType >

bool isType | ( |  | ) | const
| inline

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

## ◆ isUniform()

virtual bool isUniform | ( |  | ) | const
| pure virtual

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

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

## ◆ loadData()

virtual void loadData | ( |  | ) | const
| pure virtual

Ensures all data is in-core.

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

## ◆ memUsage()

virtual size_t memUsage | ( |  | ) | const
| pure virtual

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

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

## ◆ memUsageIfLoaded()

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_ >.

## ◆ operator!=()

bool operator!= | ( | const AttributeArray & | other | ) | const
| inline

## ◆ operator=() [1/2]

AttributeArray & operator= | ( | AttributeArray && |  | ) |
| delete

## ◆ operator=() [2/2]

AttributeArray & operator= | ( | const AttributeArray & | rhs | ) |

## ◆ operator==()

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

## ◆ read()

virtual void read | ( | std::istream & |  | ) |
| pure virtual

Read attribute metadata and buffers from a stream.

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

## ◆ readBuffers()

virtual void readBuffers | ( | std::istream & |  | ) |
| pure virtual

Read attribute buffers from a stream.

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

## ◆ readMetadata()

virtual void readMetadata | ( | std::istream & |  | ) |
| pure virtual

Read attribute metadata from a stream.

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

## ◆ readPagedBuffers()

virtual void readPagedBuffers | ( | compression::PagedInputStream & |  | ) |
| pure virtual

Read attribute buffers from a paged stream.

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

## ◆ registerType()

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

Register a attribute type along with a factory function.

## ◆ setConstantStride()

void setConstantStride | ( | bool | state | ) |
| protected

Specify whether this attribute has a constant stride or not.

## ◆ setHidden()

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.

## ◆ setStreaming()

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.

## ◆ setTransient()

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.

## ◆ size()

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_ >.

## ◆ storageTypeSize()

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_ >.

## ◆ stride()

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_ >.

## ◆ type()

virtual const NamePair & type | ( |  | ) | const
| pure virtual

Return the name of this attribute's type.

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

## ◆ unregisterType()

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

Remove a attribute type from the registry.

## ◆ valueType()

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_ >.

## ◆ valueTypeIsClass()

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_ >.

## ◆ valueTypeIsFloatingPoint()

virtual bool valueTypeIsFloatingPoint | ( |  | ) | const
| pure virtual

Return `true` if the value type is floating point.

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

## ◆ valueTypeIsMatrix()

virtual bool valueTypeIsMatrix | ( |  | ) | const
| pure virtual

Return `true` if the value type is a matrix.

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

## ◆ valueTypeIsQuaternion()

virtual bool valueTypeIsQuaternion | ( |  | ) | const
| pure virtual

Return `true` if the value type is a quaternion.

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

## ◆ valueTypeIsVector()

virtual bool valueTypeIsVector | ( |  | ) | const
| pure virtual

Return `true` if the value type is a vector.

Implemented in TypedAttributeArray< ValueType_, Codec_ >.

## ◆ valueTypeSize()

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_ >.

## ◆ write() [1/2]

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_ >.

## ◆ write() [2/2]

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_ >.

## ◆ writeBuffers()

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_ >.

## ◆ writeMetadata()

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_ >.

## ◆ writePagedBuffers()

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 Symbol Documentation

## ◆ ::TestAttributeArray

friend class ::TestAttributeArray
| friend

## ◆ AttributeHandle

template<typename ValueType , typename CodecType >

friend class AttributeHandle
| friend

## Member Data Documentation

## ◆ [union]

union { ... }

used for out-of-core, paged reading

## ◆ mCompressedBytes

size_t mCompressedBytes

## ◆ mFlags

uint8_t mFlags = 0
| protected

## ◆ mIsUniform

bool mIsUniform = true
| protected

## ◆ mMutex

tbb::spin_mutex mMutex
| mutable protected

## ◆ mOutOfCore

std::atomic<Index32> mOutOfCore
| protected

## ◆ mPageHandle

compression::PageHandle::Ptr mPageHandle

## ◆ mUsePagedRead

uint8_t mUsePagedRead = 0
| protected