Attributes (C++)

group FnAttribute

API that allows to manipulate Katana Attributes.

Attributes are the basic data storage classes used by Katana’s scenegraph. Data types are int, float, double, string, and each attribute contains a map of time samples, with each sample being an array of the base data type. Group attributes contain a list of named child attributes.

This API should used in every plug-in that reads/manipulates Katana attributes.

All attributes, once constructed, are immutable. Attributes can be (and often are) referenced in many locations. Their lifetime is managed internally by ref-counted smart pointers.

The API provides several utility classes to build attributes in more friendly way (DataBuilder, and its attribute type specific typedefs: IntBuilder, FloatBuilder, DoubleBuilder and StringBuilder).

Functions

bool Bootstrap(const std::string &katanaPath)

Bootstraps the API without having to link against the internal libraries that implement the Attributes host. This can be useful when implementing an executable that needs to use the Attributes API via the plug-in system, without having to bootstrap Geolib or link against any internal library.

Returns true if the bootstrap succeeds.

void Initialize(const FnAttributeHostSuite*): Initializes the API with the given Attribute Host suite.

Attribute Base Class

class Attribute

The base class of all Attributes.

Subclassed by Foundry::Katana::DataAttribute, Foundry::Katana::GroupAttribute, Foundry::Katana::NullAttribute

Public Functions

inline Attribute(): Create empty attribute class (isValid() == false).

inline ~Attribute()

inline bool isValid() const: Returns true if this attribute is valid.

inline uint64_t getSize() const

Returns the total memory in bytes that was allocated when the attribute was created.

For GroupAttribute, this value includes, apart from the allocated size of the group internals, also the size of all its children. If an attribute is included more than once in the group, the size of said attribute will be added just as many times as it appears.

Releasing the last reference to the attribute will potentially free as much data as returned by this function.

Note

Katana may optimize the storage of certain attributes by caching small, frequently-used values internally. In these cases, it will not be possible to release the last reference.

Returns:: The total allocated memory of the attribute in bytes.

inline FnKatAttributeType getType() const: Returns the Type of Attribute

std::string getXML() const: Returns an xml representation of the attribute.

void getBinary(std::vector<char> *buffer) const: Returns an binary representation of the attribute.

bool writeAttributeStream(void *stream, FnAttributeWriteStreamFunc func, FnKatStreamType streamType) const

Writes an Attribute to the stream provided. Returns true for success, false for failure.

Parameters:

stream – Opaque pointer to stream object.
func – Function to write bytes to stream object.
streamType – How to write the stream either as XML or binary.

inline Hash getHash() const

inline Attribute(const Attribute &rhs)

inline Attribute &operator=(const Attribute &rhs)

inline Attribute(Attribute &&rhs)

inline Attribute &operator=(Attribute &&rhs)

Public Static Functions

static Attribute parseXML(const char *xml): Returns an Attribute from an XML representation.

static Attribute parseBinary(const char *buffer, size_t size): Returns an Attribute from a binary representation.

static Attribute readAttributeStream(void *stream, FnAttributeReadStreamFunc func, FnKatStreamType streamType)

Returns an Attribute read from the stream provided.

Parameters:

stream – Opaque pointer to stream object.
func – Function to read bytes from stream object.
streamType – How to read the stream either as XML or binary.

Friends

friend bool operator==(const Attribute &lhs, const Attribute &rhs)

friend bool operator!=(const Attribute &lhs, const Attribute &rhs)

Null Attributes

class NullAttribute : public Foundry::Katana::Attribute 

A class representing a null value.

Public Functions

inline NullAttribute()

inline NullAttribute(const Attribute &rhs)

inline NullAttribute &operator=(const Attribute &rhs)

inline NullAttribute(Attribute &&rhs)

inline NullAttribute &operator=(Attribute &&rhs)

Public Static Functions

static inline FnKatAttributeType getKatAttributeType()

Data Attributes

class DataAttribute : public Foundry::Katana::Attribute 

The base class of attributes containing data, possibly at multiple samples in time.

The data are organised in tuples of a fixed size of 1 or greater per attribute. DataAttribute implements common, data-agnostic functionality, such as querying them number and orientation of values and time samples.

DataAttributes enforce some limits on the amount of data they can store. These are as follows:

value count (per sample): [0, 2^63) time count: [0, 2^13) tuple size: [0, 2^16)

An invalid attribute will be returned should you attempt to create an attribute with values outside of these limits.

Subclassed by Foundry::Katana::DoubleAttribute, Foundry::Katana::FloatAttribute, Foundry::Katana::IntAttribute, Foundry::Katana::StringAttribute

Public Functions

inline DataAttribute(): Create empty attribute class (isValid() == false).

inline int64_t getTupleSize() const: Return the number of data values per tuple for this attribute.

inline int64_t getNumberOfValues() const: Return the total number of data values for this attribute. This will be equal to getNumberOfTuples() * getTupleSize()

inline int64_t getNumberOfTuples() const: Return the number of tuples in this attribute.

inline int64_t getNumberOfTimeSamples() const: Return the number of time samples at which data is recorded in this attribute.

inline float getSampleTime(int64_t index) const: Returns a float value containing the time at a particular index for this attribute. If the index is not valid 0.0 is returned.

inline bool getBoundingSampleTimes(float *ltime, float *rtime, float sampletime) const: For the specified sampletime, return the two bounding samples. (left bounds, right bounds). If the sampletime exactly falls on a single sample, ltime == rtime (this is also the case at extrema, or for attrs with only a single sample. For attrs with 0 samples, the return value is false (signifying failure) For attrs >0 samples, return value is true

inline DataAttribute(const Attribute &rhs)

inline DataAttribute &operator=(const Attribute &rhs)

inline DataAttribute(Attribute &&rhs)

inline DataAttribute &operator=(Attribute &&rhs)

class IntAttribute : public Foundry::Katana::DataAttribute 

A class representing a data attribute containing integers.

Public Types

typedef int32_t value_type

typedef IntConstVectorBase internal_array_type

typedef IntConstVector array_type

typedef SampleAccessor<value_type> accessor_type

typedef SampleAccessorBase<value_type> internal_accessor_type

typedef Sample<value_type> sample_type

Public Functions

inline IntAttribute(): Create empty attribute class (isValid() == false).

inline IntAttribute(value_type value)

Creates an integer attribute containing one value.

Parameters:: value – The integer value for the new attribute

inline IntAttribute(const value_type *values, int64_t valueCount, int64_t tupleSize, void *context = NULL, FnAttributeFreeOwnedDataFunc freeOwnedDataFunc = NULL)

Creates an integer attribute containing a number of values, grouped into tuples of a given size.

Specifying values for context and freeOwnedDataFunc will cause the constructor to take ownership of the memory pointed to by values. It is the responsibility of freeOwnedDataFunc to deallocate this memory when called.

Parameters:

values – An array of integers containing the values
valueCount – The total number of values. Must be a multiple of tupleSize
tupleSize – The size of tuples to group values into.
context – User supplied data passed to freeOwnedDataFunc.
freeOwnedDataFunc – Pointer to function that will be called when values’ memory is to be returned to the operating system.

inline IntAttribute(const float *times, int64_t timeCount, const value_type **values, int64_t valueCount, int64_t tupleSize, void *context = NULL, FnAttributeFreeOwnedDataFunc freeOwnedDataFunc = NULL)

Creates an integer attribute containing several timed samples, each containing a number of values, grouped into tuples of a given size.

Specifying values for context and freeOwnedDataFunc will cause the constructor to take ownership of the memory pointed to by values. It is the responsibility of freeOwnedDataFunc to deallocate this memory when called.

Note: when using the ‘zero copy’ version of this constructor copies of the pointers in times and values will be taken, only management of the memory pointed to by values will be transferred to the attribute.

Parameters:

times – An array of floats, giving the times of the samples.
timeCount – The number of samples for which there is data
values – An array of pointers to integer arrays containing values. There must be timeCount arrays, each of which has valueCount values.
valueCount – The total number of values in each sample. Must be a multiple of tupleSize
tupleSize – The size of tuples to group values into.
context – User supplied data passed to freeOwnedDataFunc.
freeOwnedDataFunc – Pointer to function that will be called when values’ memory is to be returned to the operating system.

inline accessor_type getSamples() const &: Returns a SampleAccessor object that provides a read-only view into all time samples of the Attribute.

Note

Any pointers or references obtained from the SampleAccessor are invalidated if the SampleAccessor is destructed.

inline array_type getNearestSample(float time) const &: Returns a ConstVector object that provides a read-only view into values of the sample nearest to the given time.

Note

Any pointers or references obtained from the ConstVector are invalidated if the ConstVector is destructed.

inline value_type getValue(const value_type defValue = 0, bool throwOnError = true) const

Returns first value from the time sample nearest 0.0. This is a convenience for the extremely common case of an attribute that stores a single sample of a single value at time 0.0. By default, throws std::runtime_error if there are no time samples or no values available.

Parameters:

defValue – The value to return if an error occurs and throwOnError is false.
throwOnError – When error occurs, if true, throw std::runtime_error. If false, return defValue.

template<typename T, size_t N> inline T getValuesAs(const T &defValue = T(), bool throwOnError = true) const

Convenience function that creates an object of type T by passing the first N values from time sample nearest t=0.0.

Example:

Matrix44<int> m44i = myAttr.getValuesAs<Matrix44<int>, 16>();

Note

The C++98 implementation supports constructors that take at most 16 arguments.

Template Parameters:

T – The type of object to construct.
N – The number of values to pass to T’s constructor.

Parameters:

defValue – The value to return if throwOnError is false and the attribute has either no time samples, or less than N values per sample.
throwOnError – Whether to throw an exception if the attribute has no time samples or has less than N values per sample.

Throws:

std::runtime_error – if an error occurs and throwOnError is true.

Returns:

An object of type T, constructed with the first N values from the attribute’s primary time sample.

inline IntAttribute(const Attribute &rhs)

inline IntAttribute &operator=(const Attribute &rhs)

inline IntAttribute(Attribute &&rhs)

inline IntAttribute &operator=(Attribute &&rhs)

Public Static Functions

static inline FnKatAttributeType getKatAttributeType(): Returns the intended type of this Attribute, without needing a valid handle.

class FloatAttribute : public Foundry::Katana::DataAttribute 

A class representing a data attribute containing single-precision floats.

Public Types

typedef float value_type

typedef FloatConstVectorBase internal_array_type

typedef FloatConstVector array_type

typedef SampleAccessor<value_type> accessor_type

typedef SampleAccessorBase<value_type> internal_accessor_type

typedef Sample<value_type> sample_type

Public Functions

inline FloatAttribute(): Create empty attribute class (isValid() == false).

inline FloatAttribute(value_type value)

Creates a float attribute containing one value.

Parameters:: value – The float value for the new attribute

inline FloatAttribute(const value_type *values, int64_t valueCount, int64_t tupleSize, void *context = NULL, FnAttributeFreeOwnedDataFunc freeOwnedDataFunc = NULL)

Creates a float attribute containing a number of values, grouped into tuples of a given size.

Parameters:

values – An array of floats containing the values
valueCount – The total number of values. Must be a multiple of tupleSize
tupleSize – The size of tuples to group values into.
context – User supplied data passed to freeOwnedDataFunc.
freeOwnedDataFunc – Pointer to function that will be called when values’ memory is to be returned to the operating system.

inline FloatAttribute(const float *times, int64_t timeCount, const value_type **values, int64_t valueCount, int64_t tupleSize, void *context = NULL, FnAttributeFreeOwnedDataFunc freeOwnedDataFunc = NULL)

Creates a float attribute containing several timed samples, each containing a number of values, grouped into tuples of a given size.

Specifying values for context and freeOwnedDataFunc will cause the constructor to take ownership of the memory pointed to by values. It is the responsibility of freeOwnedDataFunc to deallocate this memory when called.

Note: when using the ‘zero copy’ version of this constructor copies of the pointers in times and values will be taken, only management of the memory pointed to by values will be transferred to the attribute.

Parameters:

times – An array of floats, giving the times of the samples.
timeCount – The number of samples for which there is data
values – An array of pointers to float arrays containing values. There must be timeCount arrays, each of which has valueCount values.
valueCount – The total number of values in each sample. Must be a multiple of tupleSize
tupleSize – The size of tuples to group values into.
context – User supplied data passed to freeOwnedDataFunc.
freeOwnedDataFunc – Pointer to function that will be called when values’ memory is to be returned to the operating system.

inline accessor_type getSamples() const &: Returns a SampleAccessor object that provides a read-only view into all time samples of the Attribute.

Note

Any pointers or references obtained from the SampleAccessor are invalidated if the SampleAccessor is destructed.

inline array_type getNearestSample(float time) const &: Returns a ConstVector object that provides a read-only view into values of the sample nearest to the given time.

Note

Any pointers or references obtained from the ConstVector are invalidated if the ConstVector is destructed.

void fillInterpSample(value_type *array, int64_t valueCount, float sampleTime, const value_type defValue = 0.f, bool throwOnError = true) const: Fills the interpolated values for an exact time. If the time falls between two samples, the values of the samples are interpolated to make the result. If you wish to interpolate all values in the attr, valueCount should equal attr.getNumberOfValues()

inline value_type getValue(const value_type defValue = 0.f, bool throwOnError = true) const

Returns first value from the time sample nearest 0.0. This is a convenience for the extremely common case of an attribute that stores a single sample of a single value at time 0.0. By default, throws std::runtime_error if there are no time samples or no values available.

Parameters:

defValue – The value to return if an error occurs and throwOnError is false.
throwOnError – When error occurs, if true, throw std::runtime_error. If false, return defValue.

template<typename T, size_t N> inline T getValuesAs(const T &defValue = T(), bool throwOnError = true) const

Convenience function that creates an object of type T by passing the first N values from time sample nearest t=0.0.

Example:

Matrix44<float> m44f = myAttr.getValuesAs<Matrix44<float>, 16>();

Note

The C++98 implementation supports constructors that take at most 16 arguments.

Template Parameters:

T – The type of object to construct.
N – The number of values to pass to T’s constructor.

Parameters:

defValue – The value to return if throwOnError is false and the attribute has either no time samples, or less than N values per sample.
throwOnError – Whether to throw an exception if the attribute has no time samples or has less than N values per sample.

Throws:

std::runtime_error – if an error occurs and throwOnError is true.

Returns:

An object of type T, constructed with the first N values from the attribute’s primary time sample.

inline FloatAttribute(const Attribute &rhs)

inline FloatAttribute &operator=(const Attribute &rhs)

inline FloatAttribute(Attribute &&rhs)

inline FloatAttribute &operator=(Attribute &&rhs)

Public Static Functions

static inline FnKatAttributeType getKatAttributeType(): Returns the intended type of this Attribute, without needing a valid handle.

class DoubleAttribute : public Foundry::Katana::DataAttribute 

A class representing a data attribute containing double-precision floats.

Public Types

typedef double value_type

typedef DoubleConstVectorBase internal_array_type

typedef DoubleConstVector array_type

typedef SampleAccessor<value_type> accessor_type

typedef SampleAccessorBase<value_type> internal_accessor_type

typedef Sample<value_type> sample_type

Public Functions

inline DoubleAttribute(): Create empty attribute class (isValid() == false).

inline DoubleAttribute(value_type value)

Creates a double attribute containing one value.

Parameters:: value – The double value for the new attribute

inline DoubleAttribute(const value_type *values, int64_t valueCount, int64_t tupleSize, void *context = NULL, FnAttributeFreeOwnedDataFunc freeOwnedDataFunc = NULL)

Creates a double attribute containing a number of values, grouped into tuples of a given size.

Parameters:

values – An array of doubles containing the values
valueCount – The total number of values. Must be a multiple of tupleSize
tupleSize – The size of tuples to group values into.
context – User supplied data passed to freeOwnedDataFunc.
freeOwnedDataFunc – Pointer to function that will be called when values’ memory is to be returned to the operating system.

inline DoubleAttribute(const float *times, int64_t timeCount, const value_type **values, int64_t valueCount, int64_t tupleSize, void *context = NULL, FnAttributeFreeOwnedDataFunc freeOwnedDataFunc = NULL)

Creates a double attribute containing several timed samples, each containing a number of values, grouped into tuples of a given size.

Specifying values for context and freeOwnedDataFunc will cause the constructor to take ownership of the memory pointed to by values. It is the responsibility of freeOwnedDataFunc to deallocate this memory when called.

Note: when using the ‘zero copy’ version of this constructor copies of the pointers in times and values will be taken, only management of the memory pointed to by values will be transferred to the attribute.

Parameters:

times – An array of floats, giving the times of the samples.
timeCount – The number of samples for which there is data
values – An array of pointers to double arrays containing values. There must be timeCount arrays, each of which has valueCount values.
valueCount – The total number of values in each sample. Must be a multiple of tupleSize
tupleSize – The size of tuples to group values into.
context – User supplied data passed to freeOwnedDataFunc.
freeOwnedDataFunc – Pointer to function that will be called when values’ memory is to be returned to the operating system.

inline accessor_type getSamples() const &: Returns a SampleAccessor object that provides a read-only view into all time samples of the Attribute.

Note

Any pointers or references obtained from the SampleAccessor are invalidated if the SampleAccessor is destructed.

inline array_type getNearestSample(float time) const &: Returns a ConstVector object that provides a read-only view into values of the sample nearest to the given time.

Note

Any pointers or references obtained from the ConstVector are invalidated if the ConstVector is destructed.

void fillInterpSample(value_type *array, int64_t valueCount, float sampleTime, const value_type defValue = 0.0, bool throwOnError = true) const: Fills the interpolated values for an exact time. If the time falls between two samples, the values of the samples are interpolated to make the result. If you wish to interpolate all values in the attr, valueCount should equal attr.getNumberOfValues()

inline value_type getValue(const value_type defValue = 0.0, bool throwOnError = true) const

Returns first value from the time sample nearest 0.0. This is a convenience for the extremely common case of an attribute that stores a single sample of a single value at time 0.0. By default, throws std::runtime_error if there are no time samples or no values available.

Parameters:

defValue – The value to return if an error occurs and throwOnError is false.
throwOnError – When error occurs, if true, throw std::runtime_error. If false, return defValue.

template<typename T, size_t N> inline T getValuesAs(const T &defValue = T(), bool throwOnError = true) const

Convenience function that creates an object of type T by passing the first N values from time sample nearest t=0.0.

Example:

Matrix44<double> m44d = myAttr.getValuesAs<Matrix44<double>, 16>();

Note

The C++98 implementation supports constructors that take at most 16 arguments.

Template Parameters:

T – The type of object to construct.
N – The number of values to pass to T’s constructor.

Parameters:

defValue – The value to return if throwOnError is false and the attribute has either no time samples, or less than N values per sample.
throwOnError – Whether to throw an exception if the attribute has no time samples or has less than N values per sample.

Throws:

std::runtime_error – if an error occurs and throwOnError is true.

Returns:

An object of type T, constructed with the first N values from the attribute’s primary time sample.

inline DoubleAttribute(const Attribute &rhs)

inline DoubleAttribute &operator=(const Attribute &rhs)

inline DoubleAttribute(Attribute &&rhs)

inline DoubleAttribute &operator=(Attribute &&rhs)

Public Static Functions

static inline FnKatAttributeType getKatAttributeType(): Returns the intended type of this Attribute, without needing a valid handle.

class StringAttribute : public Foundry::Katana::DataAttribute 

A class representing a data attribute containing strings.

Public Types

typedef std::string value_type

typedef StringConstVectorBase internal_array_type

typedef StringConstVector array_type

typedef SampleAccessor<const char*> accessor_type

typedef SampleAccessorBase<const char*> internal_accessor_type

typedef Sample<const char*> sample_type

Public Functions

inline StringAttribute(): Create empty attribute class (isValid() == false).

inline StringAttribute(const std::string &value)

Creates a string attribute containing one value.

Parameters:: value – The value for the new attribute, in the form of a std::string.

inline StringAttribute(const char *value)

Creates a string attribute containing one value.

Parameters:: value – The value for the new attribute, in the form of a C string.

StringAttribute(const value_type *values, int64_t valueCount, int64_t tupleSize)

Creates a string attribute containing a number of values, grouped into tuples of a given size.

Parameters:

values – An array of std::strings containing the values
valueCount – The total number of values. Must be a multiple of tupleSize
tupleSize – The size of tuples to group values into.

StringAttribute(const std::vector<std::string> &stringvec, int64_t tupleSize = 1)

Creates a string attribute containing a number of values, grouped into tuples of a given size.

Parameters:

stringvec – A vector of std::string containing the values
tupleSize – The size of tuples to group values into.

inline StringAttribute(const char **values, int64_t valueCount, int64_t tupleSize)

Creates a string attribute containing a number of values, grouped into tuples of a given size.

Parameters:

values – An array of C strings containing the values
valueCount – The total number of values. Must be a multiple of tupleSize
tupleSize – The size of tuples to group values into.

inline StringAttribute(const float *times, int64_t timeCount, const char ***values, int64_t valueCount, int64_t tupleSize, void *context = NULL, FnAttributeFreeOwnedDataFunc freeOwnedDataFunc = NULL)

Creates a string attribute containing several timed samples, each containing a number of values, grouped into tuples of a given size.

Specifying values for context and freeOwnedDataFunc will cause the constructor to take ownership of the memory pointed to by values. It is the responsibility of freeOwnedDataFunc to deallocate this memory when called.

Note: when using the ‘zero copy’ version of this constructor copies of the pointers in times and values will be taken, only management of the memory pointed to by values will be transferred to the attribute.

Parameters:

times – An array of floats, giving the times of the samples.
timeCount – The number of samples for which there is data
values – An array of pointers to C string arrays containing values. There must be timeCount arrays, each of which has valueCount values.
valueCount – The total number of values in each sample. Must be a multiple of tupleSize
tupleSize – The size of tuples to group values into.
context – User supplied data passed to freeOwnedDataFunc.
freeOwnedDataFunc – Pointer to function that will be called when values’ memory is to be returned to the operating system.

inline accessor_type getSamples() const &: Returns a SampleAccessor object that provides a read-only view into all time samples of the Attribute.

Note

Any pointers or references obtained from the SampleAccessor are invalidated if the SampleAccessor is destructed.

inline array_type getNearestSample(float time) const &: Returns a ConstVector object that provides a read-only view into values of the sample nearest to the given time.

Note

Any pointers or references obtained from the ConstVector are invalidated if the ConstVector is destructed.

inline value_type getValue(const value_type &defValue = value_type(), bool throwOnError = true) const

Returns first value from the time sample nearest 0.0. This is a convenience for the extremely common case of an attribute that stores a single sample of a single value at time 0.0. By default, throws std::runtime_error if there are no time samples or no values available.

Parameters:

defValue – The value to return if an error occurs and throwOnError is false.
throwOnError – When error occurs, if true, throw std::runtime_error. If false, return defValue.

template<typename T, size_t N> inline T getValuesAs(const T &defValue = T(), bool throwOnError = true) const

Convenience function that creates an object of type T by passing the first N values from time sample nearest t=0.0.

Note

The C++98 implementation supports constructors that take at most 16 arguments.

Template Parameters:

T – The type of object to construct.
N – The number of values to pass to T’s constructor.

Parameters:

defValue – The value to return if throwOnError is false and the attribute has either no time samples, or less than N values per sample.
throwOnError – Whether to throw an exception if the attribute has no time samples or has less than N values per sample.

Throws:

std::runtime_error – if an error occurs and throwOnError is true.

Returns:

An object of type T, constructed with the first N values from the attribute’s primary time sample.

inline const char *getValueCStr(const char *defValue = "", bool throwOnError = true) const &

Returns first value from the time sample nearest 0.0. This is a convenience for the extremely common case of an attribute that stores a single sample of a single value at time 0.0. By default, throws std::runtime_error if there are no time samples or no values available.

Warning

The pointer returned by this function may be invalidated if *this is destroyed.

Parameters:

defValue – The value to return if an error occurs and throwOnError is false.
throwOnError – When error occurs, if true, throw std::runtime_error. If false, return defValue.

inline bool operator==(const char *str) const

inline bool operator!=(const char *str) const

inline bool operator==(const std::string &str) const

inline bool operator!=(const std::string &str) const

inline StringAttribute(const Attribute &rhs)

inline StringAttribute &operator=(const Attribute &rhs)

inline StringAttribute(Attribute &&rhs)

inline StringAttribute &operator=(Attribute &&rhs)

Public Static Functions

static inline FnKatAttributeType getKatAttributeType(): Returns the intended type of this Attribute, without needing a valid handle.

Group Attributes

class GroupAttribute : public Foundry::Katana::Attribute 

A class representing a group attribute, used for hierarchically encapsulating other attributes.

Public Types

typedef std::pair<std::string, Attribute> NamedAttr_Type

typedef std::vector<NamedAttr_Type> NamedAttrVector_Type

Public Functions

inline GroupAttribute(): Create empty attribute class (isValid() == false).

inline explicit GroupAttribute(const bool groupInherit)

inline GroupAttribute(const std::string &name1, const Attribute &attr1, const bool groupInherit)

inline GroupAttribute(const char *name1, const Attribute &attr1, const bool groupInherit)

inline GroupAttribute(const std::string &name1, const Attribute &attr1, const std::string &name2, const Attribute &attr2, const bool groupInherit)

inline GroupAttribute(const char *name1, const Attribute &attr1, const char *name2, const Attribute &attr2, const bool groupInherit)

inline GroupAttribute(const std::string &name1, const Attribute &attr1, const std::string &name2, const Attribute &attr2, const std::string &name3, const Attribute &attr3, const bool groupInherit)

inline GroupAttribute(const char *name1, const Attribute &attr1, const char *name2, const Attribute &attr2, const char *name3, const Attribute &attr3, const bool groupInherit)

inline GroupAttribute(const std::string &name1, const Attribute &attr1, const std::string &name2, const Attribute &attr2, const std::string &name3, const Attribute &attr3, const std::string &name4, const Attribute &attr4, const bool groupInherit)

inline GroupAttribute(const char *name1, const Attribute &attr1, const char *name2, const Attribute &attr2, const char *name3, const Attribute &attr3, const char *name4, const Attribute &attr4, const bool groupInherit)

inline GroupAttribute(const std::string &name1, const Attribute &attr1, const std::string &name2, const Attribute &attr2, const std::string &name3, const Attribute &attr3, const std::string &name4, const Attribute &attr4, const std::string &name5, const Attribute &attr5, const bool groupInherit)

inline GroupAttribute(const char *name1, const Attribute &attr1, const char *name2, const Attribute &attr2, const char *name3, const Attribute &attr3, const char *name4, const Attribute &attr4, const char *name5, const Attribute &attr5, const bool groupInherit)

GroupAttribute(const NamedAttrVector_Type &children, const bool inheritChildren)

inline int64_t getNumberOfChildren() const: Returns the number of child attributes under the group attribute.

inline std::string getChildName(int64_t index) const

Returns the name of child at index under a group attribute. This is returned as a std::string. If index is out of range, an empty string is returned.

Parameters:: index – The index of the child name to return.

inline const char *getChildNameCStr(int64_t index) const &

Returns the name of child at index under a group attribute. This is returned as a const char *.

Parameters:: index – The index of the child name to return.

inline const char *getChildNameCStr(int64_t index, int32_t &namelen) const &

Returns the name of child at index under a group attribute. This is returned as a const char *. The length is also returned.

Parameters:

index – The index of the child name to return.
namelen – Output parameter where the name length is returned.

inline FnPlatform::StringView getChildNameStringView(int64_t index) const &

Returns the name of child at index under a group attribute. This is returned as a FnPlatform::StringView, containing the data and length.

Parameters:: index – The index of the child name to return.

inline Attribute getChildByIndex(int64_t index) const

Returns a child attribute by index within a group attribute. If index is out of range, an invalid Attribute object is returned (returnValue.isValid() == false).

Parameters:: index – The index of the child attribute to return.

inline Attribute getChildByName(FnPlatform::StringView name) const

Looks up a child attribute by name, returning it If named child does not exist, an invalid Attribute object is returned (returnValue.isValid() == false).

Parameters:: name – The name of attribute to look up.

inline Attribute getChildByName(const char *name, int32_t length) const

Looks up a child attribute by name, returning it If named child does not exist, an invalid Attribute object is returned (returnValue.isValid() == false).

Parameters:

name – The name of attribute to look up.
length – The length of the string to look up.

inline bool getGroupInherit() const

void fillChildVector(NamedAttrVector_Type *children) const

inline GroupAttribute(const Attribute &rhs)

inline GroupAttribute &operator=(const Attribute &rhs)

inline GroupAttribute(Attribute &&rhs)

inline GroupAttribute &operator=(Attribute &&rhs)

Public Static Functions

static inline FnKatAttributeType getKatAttributeType(): Returns the intended type of this Attribute, without needing a valid handle.

DataBuilder

template<class ATTR> class DataBuilder

Helper class used for creating attributes.

Data is pushed into the DataBuilder, when populated with all the required data the builder build() can be called to generate a new Attribute.

The API provides several convenience typedefs of this class for the different Attribute types, which remove the template from DataBuilder: IntBuilder, FloatBuilder, DoubleBuilder, StringBuilder

Public Functions

inline DataBuilder(int64_t tupleSize = 1): Creates an empty DataBuilder with a given tuple size

DataBuilder(ATTR attr): Copies the data from the attribute attr into the DataBuilder

void reserve(int64_t timeSampleDataCount, float timeSample = 0.f): Reserves timeSampleDataCount entries in the given timesample data

int64_t getTupleSize() const: Gets the current size tuple size of the builder

std::vector<float> getTimeSamples() const: Get the current time samples in the builder

std::vector<typename ATTR::value_type> &get(const float timeSample = 0.f): Get a vector at the given data sample

void set(const std::vector<typename ATTR::value_type> &timeSampleData, const float timeSample = 0.f): Copies timeSampleData into the builder at the given time sample

void del(const float timeSample = 0.f): Removes the time sample data from the builder

void push_back(typename ATTR::value_type data, float timeSample = 0.f): Push back a single data element onto a given timesample

void update(ATTR &attr): Copies the attribute data into the builder

ATTR build(): Create an attribute from the current data in the builder

GroupBuilder

class GroupBuilder

A factory class for constructing GroupAttribute objects.

Typical usage involves creating a GroupBuilder, adding attributes to it with the set() method, and, when finished, retrieving a newly constructed GroupAttribute using the GroupBuilder's build() method.

As a convenience, GroupBuilder has support for creating arbitrarily nested GroupAttribute structures by passing a dot-delimited string to set(), which is referred to as a “path”. Note that this implies that the ‘.’ character is not a valid attribute name!

Example:

GroupBuilder gb;
gb.set("my.nested.attribute", IntAttribute(2));
gb.set("myTopLevelAttribute", StringAttribute("taco"));
gb.set("myOtherTopLevelAttribute", FloatAttribute(4.0f));

GroupAttribute groupAttribute = gb.build();

// Following the call to build(), |gb| is empty and |groupAttribute| has
// the following structure:
//
// {
//   "my": {
//     "nested": {
//       "attribute": IntAttribute(2)
//      }
//   },
//   "myTopLevelAttribute": StringAttribute("taco"),
//   "myOtherTopLevelAttribute": FloatAttribute(4.0f)
// }

Warning

There is currently no way to inspect the contents of the builder, other than by calling build() and inspecting the generated GroupAttribute. Note that by default build() clears the contents of the builder; to override this behaviour pass GroupBuilder::BuildAndRetain to build().

Public Types

enum BuilderMode

An enumeration of available modes in which GroupBuilder objects can build their resulting GroupAttribute objects.

The builder mode is set when constructing a GroupBuilder object.

Values:

enumerator BuilderModeNormal: The “normal” build mode, which allows the full suite of GroupBuilder functionality. This is the default.

enumerator BuilderModeStrict

An advanced option that enables a more restrictive but higher performance mode of operation.

When working in this mode:

callers must not pass dot-delimited paths to the set() method
callers must not make multiple calls to set() using the same path
deletions are disallowed: the del() method becomes a no-op.

enum BuilderBuildMode

An enumeration of flags to control the behaviour of the build() method.

Values:

enumerator BuildAndFlush: Specifies that the builder’s contents are cleared following a call to build(). This is the default.

enumerator BuildAndRetain: Specifies that the builder’s contents are retained following a call to build().

Public Functions

inline GroupBuilder()

Creates a new, empty GroupBuilder object.

Remark

The builder is created with GroupBuilder::BuilderModeNormal.

inline GroupBuilder(BuilderMode builderMode): Creates a new, empty GroupBuilder that uses the specified BuilderMode .

inline ~GroupBuilder()

inline void reset()

inline bool isValid() const

inline GroupBuilder &set(FnPlatform::StringView path, const Attribute &attr, bool groupInherit = true)

Sets the value for the attribute identified by the given path.

If path refers to an existing attribute in the builder and the builder was created with GroupBuilder::BuilderModeNormal, the attribute is replaced.

Remark

If the builder was created with GroupBuilder::BuilderModeStrict, note the caveats (documented above) for working in this mode.

Remark

The empty string (“”) is not a valid path component.

Parameters:

path – The path of the attribute whose value to set.
attr – The attribute object to set for the given path.
groupInherit – If path is a dot-delimited path, specifies the groupInherit flag for any new groups added by this set() call.

inline GroupBuilder &set(const char *path, int32_t length, const Attribute &attr, bool groupInherit = true)

inline GroupBuilder &set(const char *path, int32_t length, FnAttributeHandle attr, bool groupInherit = true)

inline GroupBuilder &setWithUniqueName(FnPlatform::StringView path, const Attribute &attr, bool groupInherit = true)

Sets the value for an attribute identified using a unique name derived from the given path.

If no attribute exists for the given path, this is equivalent to calling set(). Otherwise, setWithUniqueName() chooses a new path by suffixing the given path with an integer.

Parameters:

path – The base path of the attribute whose value to set.
attr – The attribute object to set for the resulting path.
groupInherit – If path is a dot-delimited path, specifies the groupInherit flag for any new groups added by this set() call.

inline GroupBuilder &del(FnPlatform::StringView path)

Deletes the attribute of the builder specified with the given path.

Remark

This has no effect if the builder was created with GroupBuilder::BuilderModeStrict.

inline GroupBuilder &update(const GroupAttribute &attr)

Updates the contents of the builder with the attributes from the given GroupAttribute.

Any new attributes with the same names as existing attributes replace the old ones. Existing attributes not matching new attributes are left intact. (This is analogous to the Python dictionary’s update method.)

If setGroupInherit() has not been previously called, the builder will also adopt the incoming GroupAttribute’s groupInherit flag.

Parameters:: attr – A GroupAttribute containing new attributes to add

inline GroupBuilder &deepUpdate(const GroupAttribute &attr)

Recursively updates the contents of the builder with the attributes held within the provided group attribute.

Groups are traversed until set operations can be applied at the leaves which are not GroupAttribute objects themselves.

If setGroupInherit() has not been previously called, the builder will also adopt the incoming GroupAttribute’s groupInherit flag.

inline GroupBuilder &reserve(int64_t n)

Reserves space for n attributes.

This is an optimisation only. Calling reserve() before adding attributes will avoid having to reallocate internal data structures.

Parameters:: n – The number of attributes the group attribute is to have.

inline GroupBuilder &setGroupInherit(bool groupInherit)

Sets a special flag on the builder that determines the value returned by GroupAttribute::getGroupInherit() for the top-level GroupAttribute returned by build().

This groupInherit flag is sticky, so once it’s been set — either through an explicit call to setGroupInherit(), or indirectly via a call to update()/ further calls to setGroupInherit() will have no effect.

inline GroupBuilder &sort()

Sorts the top-level attributes of the builder by name.

Remark

sort() uses bytewise lexicographic ordering.

inline GroupAttribute build(BuilderBuildMode builderMode = BuildAndFlush)

Returns a newly created group attribute with the contents of the builder.

Warning

GroupAttribute supports up to 2^28 children. An invalid attribute will be returned if this limit is breached.

Warning

By default, the contents of the builder are cleared following a call to build(). To reuse the builder while retaining its contents, pass GroupBuilder::BuildAndRetain for the optional builderMode argument.

Parameters:: builderMode – An optional argument specifying whether the builder’s contents are retained.

Utility Classes

group FnAttribute_Utility_Classes

Typedefs

typedef ConstVectorBase<int32_t> IntConstVectorBase

typedef ConstVectorBase<float> FloatConstVectorBase

typedef ConstVectorBase<double> DoubleConstVectorBase

typedef ConstVectorBase<const char*> StringConstVectorBase

typedef ConstVector<int32_t> IntConstVector

typedef ConstVector<float> FloatConstVector

typedef ConstVector<double> DoubleConstVector

typedef ConstVector<const char*> StringConstVector

template<class T> class ConstVectorBase

#include <FnConstVector.h>

Helper class used to wrap raw attribute data contained on the host side.

There are several convenience typedefs of this class for the different Attribute types, which remove the template from ConstVectorBase: IntConstVectorBase, FloatConstVectorBase, DoubleConstVectorBase, StringConstVectorBase

Subclassed by Foundry::Katana::ConstVector< T >

Public Types

typedef T value_type: Basic type of the data in ConstVectorBase

typedef std::size_t size_type: Typedef of the sizetype

typedef std::ptrdiff_t difference_type

Public Functions

inline ConstVectorBase(const Attribute &attr, float t): Constructor for a ConstVectorBase that shares ownership of attr.

inline ConstVectorBase(Attribute &&attr, float t): Constructor for a ConstVectorBase that takes ownership of attr.

inline ConstVectorBase()

inline size_type size() const: Returns the number of data elements

inline bool empty() const: Returns false if the ConstVectorBase contains any data

template<class T> class ConstVector : public Foundry::Katana::ConstVectorBase<T>

#include <FnConstVector.h>

Helper class used to wrap raw attribute data contained on the host side, with a stl::vector style interface.

The data is immutable so only const references are available.

There are several convenience typedefs of this class for the different Attribute types, which remove the template from ConstVector: IntConstVector, FloatConstVector, DoubleConstVector, StringConstVector

Public Types

typedef T value_type: Basic type of the data in ConstVectorBase

typedef const value_type *const_iterator: Const iterator for the data type

typedef const value_type &const_reference: Const reference for the data type

typedef std::size_t size_type: Typedef of the sizetype

typedef std::ptrdiff_t difference_type

Public Functions

inline ConstVector(const Attribute &attr, float t): Constructor for a ConstVector that shares ownership of attr.

inline ConstVector(Attribute &&attr, float t): Constructor for a ConstVector that takes ownership of attr.

inline ConstVector(const ConstVectorBase<T> &other)

inline ConstVector()

inline size_type size() const: Returns the number of data elements

inline bool empty() const: Returns false if the ConstVector contains any data

inline const_iterator begin() const &: Returns an iterator at the beginning of the data

inline const_iterator end() const &: Returns an iterator at the end of the data

inline const_reference operator[](size_type i) const &: Individual element access read only

inline const_reference at(size_type i) const &: Individual element access read only

inline const_reference front() const &: Returns a const reference to the first element

inline const_reference back() const &: Returns a const reference to the last element

inline const value_type *data() const &: Pointer to the raw data (read-only)

template<typename ValueT> class SampleIterator

Public Types

typedef std::ptrdiff_t difference_type

typedef Sample<ValueT> value_type

typedef Pointer pointer

typedef Sample<ValueT> reference

typedef std::random_access_iterator_tag iterator_category

Public Functions

inline SampleIterator()

inline explicit SampleIterator(const SampleAccessor<ValueT> &acc, int64_t sampleIndex = 0)

inline reference operator*() const

inline pointer operator->() const

inline reference operator[](difference_type n) const

inline SampleIterator &operator++()

inline SampleIterator &operator--()

inline SampleIterator operator++(int)

inline SampleIterator operator--(int)

inline SampleIterator &operator+=(difference_type n)

inline SampleIterator &operator-=(difference_type n)

Friends

inline friend bool operator==(SampleIterator lhs, SampleIterator rhs)

inline friend bool operator!=(SampleIterator lhs, SampleIterator rhs)

inline friend bool operator<(SampleIterator lhs, SampleIterator rhs)

inline friend bool operator>(SampleIterator lhs, SampleIterator rhs)

inline friend bool operator<=(SampleIterator lhs, SampleIterator rhs)

inline friend bool operator>=(SampleIterator lhs, SampleIterator rhs)

inline friend SampleIterator operator+(SampleIterator lhs, difference_type n)

inline friend SampleIterator operator+(difference_type n, SampleIterator rhs)

inline friend SampleIterator operator-(SampleIterator lhs, difference_type n)

inline friend difference_type operator-(SampleIterator lhs, SampleIterator rhs)

template<typename ValueT> class SampleAccessorBase

Subclassed by Foundry::Katana::SampleAccessor< T >, Foundry::Katana::SampleAccessor< ValueT >

Public Functions

inline SampleAccessorBase()

inline explicit SampleAccessorBase(const Attribute &attr): Constructor for an accessor that shares ownership of attr.

inline explicit SampleAccessorBase(const Attribute *attr): Constructor for an accessor that does not take ownership of attr.

inline explicit SampleAccessorBase(Attribute &&attr): Constructor for an accessor that takes ownership of attr.

inline ~SampleAccessorBase()

inline SampleAccessorBase(const SampleAccessorBase &rhs)

inline SampleAccessorBase(SampleAccessorBase &&rhs)

inline SampleAccessorBase &operator=(const SampleAccessorBase &rhs)

inline SampleAccessorBase &operator=(SampleAccessorBase &&rhs)

inline bool isValid() const: Returns true if this is a valid accessor — an accessor that was created from a valid FnAttribute and not via the default constructor.

inline int64_t getNumberOfTimeSamples() const: Returns the number of samples in the attribute.

inline int64_t getNumberOfValues() const: Returns the number of values per sample.

inline size_t size() const: Returns the number of samples in the attribute.

inline bool empty() const: Returns true if the attribute has no time samples (or the accessor is invalid).

template<typename ValueT> class SampleAccessor : public Foundry::Katana::SampleAccessorBase<ValueT>

#include <FnSampleAccessor.h>

A SampleAccessor provides access to the sample buffers contained in a DataAttribute. Create one by calling the getSamples() method of any DataAttribute.

C++11 Example:

auto accessor = attr.getSamples();
for (const auto& sample : accessor)
{
    int64_t idx = sample.getSampleIndex();
    float t = sample.getSampleTime();
    const int* data = sample.data();
    for (int val : sample)
    {
        // ...
    }
}

C++98 Example:

IntAttribute::accessor_type accessor = attr.getSamples();
for (IntAttribute::accessor_type::const_iterator it = accessor.begin();
     it != accessor.end();
     ++it)
{
    int64_t idx = it->getSampleIndex();
    float t = it->getSampleTime();
    const int* data = it->data();

    for (IntAttribute::sample_type::const_iterator valIt = it->begin();
         valueIt != sampleIt->end();
         ++valueIt)
    {
        int val = *it;
    }
}

Note

Pointers and references returned by SampleAccessor are invalidated when the accessor is destructed.

Public Types

typedef SampleIterator<ValueT> iterator

typedef iterator const_iterator

typedef size_t size_type

typedef std::iterator_traits<iterator>::difference_type difference_type

typedef std::iterator_traits<iterator>::value_type value_type

typedef std::iterator_traits<iterator>::reference reference

typedef reference const_reference

Public Functions

inline explicit SampleAccessor(const Attribute &attr)

Constructs a SampleAccessor to access data of the given attribute. You should call getSamples() on a DataAttribute instead.

Parameters:: attr – The attribute whose data is to be accessed.

inline explicit SampleAccessor(const Attribute *attr): Constructor for an accessor that does not take ownership of attr.

inline explicit SampleAccessor(Attribute &&attr): Constructor for an accessor that takes ownership of attr.

inline SampleAccessor(): Constructs an invalid SampleAccessor, that is, isValid() will return false.

inline SampleAccessor(const SampleAccessorBase<ValueT> &other)

inline const_iterator begin() const &: Returns an iterator to the first sample.

inline const_iterator end() const &: Returns an iterator to the past-the-end sample.

inline const_reference front() const &: Returns a reference to the first sample.

inline const_reference back() const &: Returns a reference to the last sample.

inline const_reference operator[](difference_type i) const &: Returns a reference to the ith sample.

inline const_reference at(difference_type i) const &

Returns a reference to the ith sample.

Throws:: std::out_of_range – if i is not a valid index.

inline FnPlatform::ArrayView<float> getSampleTimes() const &: Returns a view of the samples times present in this attribute.

inline const_reference getNearestSample(float t) const &: Returns a reference to the sample closest to t, or a reference to a default-constructed Sample if the accessor contains no time samples.

inline int64_t getNearestSampleIndex(float t) const: Returns the index of the sample closest to t, or 0 if the accessor contains no time samples.

template<typename ValueT> class Sample : public FnPlatform::ArrayView<ValueT>

#include <FnSampleAccessor.h>

Reference to a single time sample.

Note

Sample objects do not own any data; any pointers or references obtained from a Sample object will be invalidated if the backing SampleAccessor object is destructed.

Public Functions

inline Sample(const ValueT *data, int64_t valueCount, int64_t sampleIndex, float time)

inline Sample()

inline float getSampleTime() const

inline int64_t getSampleIndex() const

inline int64_t getNumberOfValues() const

template<typename T, size_t N> inline T getAs(const T &defValue = T()) const

Convenience function that creates an object of type T by passing the first N values from the sample.

Note

The C++98 implementation supports constructors that take at most 16 arguments.

Template Parameters:

T – The type of object to construct.
N – The number of values to pass to T’s constructor.

Parameters:

defValue – The value to return if the sample contains less than N values.

Returns:

An object of type T, constructed with the first N values from the sample.

Utility Functions

group FnAttribute_Utility_Functions

Functions

std::string DelimiterEncode(const std::string &str)

Encodes the given name or scene graph location path for use as an attribute name.

Useful to manually work around the case where one wants to have a FnAttribute::GroupAttribute, where the immediate children have dots in their names.

0x2E ('.') -> 0x09 ('\t' -- Character Tabulation)
0x2F ('/') -> 0x0A ('\n' -- Line Feed)

std::string DelimiterDecode(const std::string &str)

Decodes the given encoded name or scene graph location path that might have been used as an attribute name.

Useful to manually work around the case where one wants to have a FnAttribute::GroupAttribute, where the immediate children have dots in their names.

0x2E ('.') <- 0x09 ('\t' -- Character Tabulation)
0x2F ('/') <- 0x0A ('\n' -- Line Feed)

uint64_t GetTotalSize(): Returns the total memory currently allocated by the FnAttribute library.