OpenVDB 11.0.0
Loading...
Searching...
No Matches
AttributeSet Class Reference

Ordered collection of uniquely-named attribute arrays. More...

#include <openvdb/points/AttributeSet.h>

Classes

class  Descriptor
 An immutable object that stores name, type and AttributeSet position for a constant collection of attribute arrays. More...
 
struct  Util
 

Public Types

enum  AttributePositionLabel : size_t { INVALID_POS = std::numeric_limits<size_t>::max() }
 
using Ptr = std::shared_ptr<AttributeSet>
 
using ConstPtr = std::shared_ptr<const AttributeSet>
 
using UniquePtr = std::unique_ptr<AttributeSet>
 
using DescriptorPtr = std::shared_ptr<Descriptor>
 
using DescriptorConstPtr = std::shared_ptr<const Descriptor>
 

Public Member Functions

 AttributeSet ()
 
 AttributeSet (const AttributeSet &attributeSet, Index arrayLength, const AttributeArray::ScopedRegistryLock *lock=nullptr)
 
 AttributeSet (const DescriptorPtr &descriptor, Index arrayLength=1, const AttributeArray::ScopedRegistryLock *lock=nullptr)
 
 AttributeSet (const AttributeSet &)
 Shallow copy constructor, the descriptor and attribute arrays will be shared.
 
AttributeSetoperator= (const AttributeSet &)=delete
 Disallow copy assignment, since it wouldn't be obvious whether the copy is deep or shallow.
 
Descriptordescriptor ()
 Return a reference to this attribute set's descriptor, which might be shared with other sets.
 
const Descriptordescriptor () const
 
DescriptorPtr descriptorPtr () const
 Return a pointer to this attribute set's descriptor, which might be shared with other sets.
 
size_t size () const
 Return the number of attributes in this set.
 
size_t memUsage () const
 Return the number of bytes of memory used by this attribute set.
 
size_t memUsageIfLoaded () const
 
size_t find (const std::string &name) const
 Return the position of the attribute array whose name is name, or INVALID_POS if no match is found.
 
size_t replace (const std::string &name, const AttributeArray::Ptr &)
 Replace the attribute array whose name is name.
 
size_t replace (size_t pos, const AttributeArray::Ptr &)
 Replace the attribute array stored at position pos in this container.
 
const AttributeArraygetConst (const std::string &name) const
 Return a pointer to the attribute array whose name is name or a null pointer if no match is found.
 
const AttributeArrayget (const std::string &name) const
 
AttributeArrayget (const std::string &name)
 
const AttributeArraygetConst (size_t pos) const
 Return a pointer to the attribute array stored at position pos in this set.
 
const AttributeArrayget (size_t pos) const
 
AttributeArrayget (size_t pos)
 
size_t groupOffset (const Name &groupName) const
 Return the group offset from the name or index of the group A group attribute array is a single byte (8-bit), each bit of which can denote a group. The group offset is the position of the bit that denotes the requested group if all group attribute arrays in the set (and only attribute arrays marked as group) were to be laid out linearly according to their order in the set.
 
size_t groupOffset (const Util::GroupIndex &index) const
 
Util::GroupIndex groupIndex (const Name &groupName) const
 Return the group index from the name of the group.
 
Util::GroupIndex groupIndex (const size_t offset) const
 
std::vector< size_t > groupAttributeIndices () const
 Return the indices of the attribute arrays which are group attribute arrays.
 
bool isShared (size_t pos) const
 Return true if the attribute array stored at position pos is shared.
 
void makeUnique (size_t pos)
 If the attribute array stored at position pos is shared, replace the array with a deep copy of itself that is not shared with anyone else.
 
AttributeArray::Ptr appendAttribute (const Name &name, const NamePair &type, const Index strideOrTotalSize=1, const bool constantStride=true, const Metadata *defaultValue=nullptr)
 Append attribute attribute (simple method)
 
AttributeArray::Ptr appendAttribute (const Descriptor &expected, DescriptorPtr &replacement, const size_t pos, const Index strideOrTotalSize=1, const bool constantStride=true, const Metadata *defaultValue=nullptr, const AttributeArray::ScopedRegistryLock *lock=nullptr)
 
AttributeArray::Ptr removeAttribute (const Name &name)
 Remove and return an attribute array by name.
 
AttributeArray::Ptr removeAttribute (const size_t pos)
 Remove and return an attribute array by index.
 
AttributeArray::Ptr removeAttributeUnsafe (const size_t pos)
 Remove and return an attribute array by index (unsafe method)
 
void dropAttributes (const std::vector< size_t > &pos)
 
void dropAttributes (const std::vector< size_t > &pos, const Descriptor &expected, DescriptorPtr &replacement)
 
void renameAttributes (const Descriptor &expected, const DescriptorPtr &replacement)
 
void reorderAttributes (const DescriptorPtr &replacement)
 
void resetDescriptor (const DescriptorPtr &replacement, const bool allowMismatchingDescriptors=false)
 
void read (std::istream &)
 Read the entire set from a stream.
 
void write (std::ostream &, bool outputTransient=false) const
 
void readDescriptor (std::istream &)
 This will read the attribute descriptor from a stream.
 
void writeDescriptor (std::ostream &, bool outputTransient=false) const
 
void readMetadata (std::istream &)
 This will read the attribute metadata from a stream.
 
void writeMetadata (std::ostream &, bool outputTransient=false, bool paged=false) const
 
void readAttributes (std::istream &)
 This will read the attribute data from a stream.
 
void writeAttributes (std::ostream &, bool outputTransient=false) const
 
bool operator== (const AttributeSet &other) const
 
bool operator!= (const AttributeSet &other) const
 

Detailed Description

Ordered collection of uniquely-named attribute arrays.

Member Typedef Documentation

◆ ConstPtr

using ConstPtr = std::shared_ptr<const AttributeSet>

◆ DescriptorConstPtr

using DescriptorConstPtr = std::shared_ptr<const Descriptor>

◆ DescriptorPtr

using DescriptorPtr = std::shared_ptr<Descriptor>

◆ Ptr

using Ptr = std::shared_ptr<AttributeSet>

◆ UniquePtr

using UniquePtr = std::unique_ptr<AttributeSet>

Member Enumeration Documentation

◆ AttributePositionLabel

enum AttributePositionLabel : size_t
Enumerator
INVALID_POS 

Constructor & Destructor Documentation

◆ AttributeSet() [1/4]

◆ AttributeSet() [2/4]

AttributeSet ( const AttributeSet & attributeSet,
Index arrayLength,
const AttributeArray::ScopedRegistryLock * lock = nullptr )

Construct a new AttributeSet from the given AttributeSet.

Parameters
attributeSetthe old attribute set
arrayLengththe desired length of the arrays in the new AttributeSet
lockan optional scoped registry lock to avoid contention
Note
This constructor is typically used to resize an existing AttributeSet as it transfers attribute metadata such as hidden and transient flags

◆ AttributeSet() [3/4]

AttributeSet ( const DescriptorPtr & descriptor,
Index arrayLength = 1,
const AttributeArray::ScopedRegistryLock * lock = nullptr )

Construct a new AttributeSet from the given Descriptor.

Parameters
descriptorstored in the new AttributeSet and used in construction
arrayLengththe desired length of the arrays in the new AttributeSet
lockan optional scoped registry lock to avoid contention
Note
Descriptors do not store attribute metadata such as hidden and transient flags which live on the AttributeArrays, so for constructing from an existing AttributeSet use the AttributeSet(const AttributeSet&, Index) constructor instead

◆ AttributeSet() [4/4]

Shallow copy constructor, the descriptor and attribute arrays will be shared.

Member Function Documentation

◆ appendAttribute() [1/2]

AttributeArray::Ptr appendAttribute ( const Descriptor & expected,
DescriptorPtr & replacement,
const size_t pos,
const Index strideOrTotalSize = 1,
const bool constantStride = true,
const Metadata * defaultValue = nullptr,
const AttributeArray::ScopedRegistryLock * lock = nullptr )

Append attribute attribute (descriptor-sharing) Requires current descriptor to match expected On append, current descriptor is replaced with replacement Provide a lock object to avoid contention from appending in parallel

◆ appendAttribute() [2/2]

AttributeArray::Ptr appendAttribute ( const Name & name,
const NamePair & type,
const Index strideOrTotalSize = 1,
const bool constantStride = true,
const Metadata * defaultValue = nullptr )

Append attribute attribute (simple method)

◆ descriptor() [1/2]

Descriptor & descriptor ( )
inline

Return a reference to this attribute set's descriptor, which might be shared with other sets.

◆ descriptor() [2/2]

const Descriptor & descriptor ( ) const
inline

◆ descriptorPtr()

DescriptorPtr descriptorPtr ( ) const
inline

Return a pointer to this attribute set's descriptor, which might be shared with other sets.

◆ dropAttributes() [1/2]

void dropAttributes ( const std::vector< size_t > & pos)

Drop attributes with pos indices (simple method) Creates a new descriptor for this attribute set

◆ dropAttributes() [2/2]

void dropAttributes ( const std::vector< size_t > & pos,
const Descriptor & expected,
DescriptorPtr & replacement )

Drop attributes with pos indices (descriptor-sharing method) Requires current descriptor to match expected On drop, current descriptor is replaced with replacement

◆ find()

size_t find ( const std::string & name) const

Return the position of the attribute array whose name is name, or INVALID_POS if no match is found.

◆ get() [1/4]

AttributeArray * get ( const std::string & name)

◆ get() [2/4]

const AttributeArray * get ( const std::string & name) const

◆ get() [3/4]

AttributeArray * get ( size_t pos)

◆ get() [4/4]

const AttributeArray * get ( size_t pos) const

◆ getConst() [1/2]

const AttributeArray * getConst ( const std::string & name) const

Return a pointer to the attribute array whose name is name or a null pointer if no match is found.

◆ getConst() [2/2]

const AttributeArray * getConst ( size_t pos) const

Return a pointer to the attribute array stored at position pos in this set.

◆ groupAttributeIndices()

std::vector< size_t > groupAttributeIndices ( ) const

Return the indices of the attribute arrays which are group attribute arrays.

◆ groupIndex() [1/2]

Util::GroupIndex groupIndex ( const Name & groupName) const

Return the group index from the name of the group.

◆ groupIndex() [2/2]

Util::GroupIndex groupIndex ( const size_t offset) const

Return the group index from the offset of the group

Note
see offset description for groupOffset()

◆ groupOffset() [1/2]

size_t groupOffset ( const Name & groupName) const

Return the group offset from the name or index of the group A group attribute array is a single byte (8-bit), each bit of which can denote a group. The group offset is the position of the bit that denotes the requested group if all group attribute arrays in the set (and only attribute arrays marked as group) were to be laid out linearly according to their order in the set.

◆ groupOffset() [2/2]

size_t groupOffset ( const Util::GroupIndex & index) const

◆ isShared()

bool isShared ( size_t pos) const

Return true if the attribute array stored at position pos is shared.

◆ makeUnique()

void makeUnique ( size_t pos)

If the attribute array stored at position pos is shared, replace the array with a deep copy of itself that is not shared with anyone else.

◆ memUsage()

size_t memUsage ( ) const

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

◆ memUsageIfLoaded()

size_t memUsageIfLoaded ( ) const

Return the number of bytes of memory used by this attribute set once it has been deserialized (this may be different to memUsage() if delay-loading is in use).

◆ operator!=()

bool operator!= ( const AttributeSet & other) const
inline

◆ operator=()

AttributeSet & operator= ( const AttributeSet & )
delete

Disallow copy assignment, since it wouldn't be obvious whether the copy is deep or shallow.

◆ operator==()

bool operator== ( const AttributeSet & other) const

Compare the descriptors and attribute arrays on the attribute sets Exit early if the descriptors do not match

◆ read()

void read ( std::istream & )

Read the entire set from a stream.

◆ readAttributes()

void readAttributes ( std::istream & )

This will read the attribute data from a stream.

◆ readDescriptor()

void readDescriptor ( std::istream & )

This will read the attribute descriptor from a stream.

◆ readMetadata()

void readMetadata ( std::istream & )

This will read the attribute metadata from a stream.

◆ removeAttribute() [1/2]

AttributeArray::Ptr removeAttribute ( const Name & name)

Remove and return an attribute array by name.

Parameters
namethe name of the attribute array to release

Detaches the attribute array from this attribute set and returns it, if name is invalid, returns an empty shared pointer. This also updates the descriptor to remove the reference to the attribute array.

Note
AttributeArrays are stored as shared pointers, so they are not guaranteed to be unique. Check the reference count before blindly re-using in a new AttributeSet.

◆ removeAttribute() [2/2]

AttributeArray::Ptr removeAttribute ( const size_t pos)

Remove and return an attribute array by index.

Parameters
posthe position index of the attribute to release

Detaches the attribute array from this attribute set and returns it, if pos is invalid, returns an empty shared pointer. This also updates the descriptor to remove the reference to the attribute array.

Note
AttributeArrays are stored as shared pointers, so they are not guaranteed to be unique. Check the reference count before blindly re-using in a new AttributeSet.

◆ removeAttributeUnsafe()

AttributeArray::Ptr removeAttributeUnsafe ( const size_t pos)

Remove and return an attribute array by index (unsafe method)

Parameters
posthe position index of the attribute to release

Detaches the attribute array from this attribute set and returns it, if pos is invalid, returns an empty shared pointer. In cases where the AttributeSet is due to be destroyed, a small performance advantage can be gained by leaving the attribute array as a nullptr and not updating the descriptor. However, this leaves the AttributeSet in an invalid state making it unsafe to call any methods that implicitly derefence the attribute array.

Note
AttributeArrays are stored as shared pointers, so they are not guaranteed to be unique. Check the reference count before blindly re-using in a new AttributeSet.
Warning
Only use this method if you're an expert and know the risks of not updating the array of attributes or the descriptor.

◆ renameAttributes()

void renameAttributes ( const Descriptor & expected,
const DescriptorPtr & replacement )

Re-name attributes in set to match a provided descriptor Replaces own descriptor with replacement

◆ reorderAttributes()

void reorderAttributes ( const DescriptorPtr & replacement)

Re order attribute set to match a provided descriptor Replaces own descriptor with replacement

◆ replace() [1/2]

size_t replace ( const std::string & name,
const AttributeArray::Ptr &  )

Replace the attribute array whose name is name.

Returns
The position of the updated attribute array or INVALID_POS if the given name does not exist or if the replacement failed because the new array type does not comply with the descriptor.

◆ replace() [2/2]

size_t replace ( size_t pos,
const AttributeArray::Ptr &  )

Replace the attribute array stored at position pos in this container.

Returns
The position of the updated attribute array or INVALID_POS if replacement failed because the new array type does not comply with the descriptor.

◆ resetDescriptor()

void resetDescriptor ( const DescriptorPtr & replacement,
const bool allowMismatchingDescriptors = false )

Replace the current descriptor with a replacement Note the provided Descriptor must be identical to the replacement unless allowMismatchingDescriptors is true (default is false)

◆ size()

size_t size ( ) const
inline

Return the number of attributes in this set.

◆ write()

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

Write the entire set to a stream.

Parameters
outputTransientif true, write out transient attributes

◆ writeAttributes()

void writeAttributes ( std::ostream & ,
bool outputTransient = false ) const

This will write the attribute data to a stream.

Parameters
outputTransientif true, write out transient attributes

◆ writeDescriptor()

void writeDescriptor ( std::ostream & ,
bool outputTransient = false ) const

This will write the attribute descriptor to a stream.

Parameters
outputTransientif true, write out transient attributes

◆ writeMetadata()

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

This will write the attribute metadata to a stream.

Parameters
outputTransientif true, write out transient attributes
pagedif true, data is written out in pages