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 Foundry::Katana::Attribute

The base class of all Attributes.

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

Public Functions

Attribute()

Create empty attribute class (isValid() == false).

~Attribute()
bool isValid() const

Returns true if this attribute is valid.

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.
Return
The total allocated memory of the attribute in bytes.

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.

Hash getHash() const
Attribute(const Attribute &rhs)
Attribute &operator=(const Attribute &rhs)
Attribute(Attribute &&rhs)
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

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

Null Attributes

class Foundry::Katana::NullAttribute

A class representing a null value.

Inherits from Foundry::Katana::Attribute

Public Functions

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

Public Static Functions

static FnKatAttributeType getKatAttributeType()

Data Attributes

class Foundry::Katana::DataAttribute

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.

Inherits from Foundry::Katana::Attribute

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

Public Functions

DataAttribute()

Create empty attribute class (isValid() == false).

int64_t getTupleSize() const

Return the number of data values per tuple for this attribute.

int64_t getNumberOfValues() const

Return the total number of data values for this attribute. This will be equal to getNumberOfTuples() * getTupleSize()

int64_t getNumberOfTuples() const

Return the number of tuples in this attribute.

int64_t getNumberOfTimeSamples() const

Return the number of time samples at which data is recorded in this attribute.

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.

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

DataAttribute(const Attribute &rhs)
DataAttribute &operator=(const Attribute &rhs)
DataAttribute(Attribute &&rhs)
DataAttribute &operator=(Attribute &&rhs)
class Foundry::Katana::IntAttribute

A class representing a data attribute containing integers.

Inherits from Foundry::Katana::DataAttribute

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

IntAttribute()

Create empty attribute class (isValid() == false).

IntAttribute(value_type value)

Creates an integer attribute containing one value.

Parameters
  • value -

    The integer value for the new attribute

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.

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.

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.

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.

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>
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.
Return
An object of type T, constructed with the first N values from the attribute’s primary time sample.
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.

Exceptions
  • std::runtime_error -

    if an error occurs and throwOnError is true.

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

Public Static Functions

static FnKatAttributeType getKatAttributeType()

Returns the intended type of this Attribute, without needing a valid handle.

class Foundry::Katana::FloatAttribute

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

Inherits from Foundry::Katana::DataAttribute

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

FloatAttribute()

Create empty attribute class (isValid() == false).

FloatAttribute(value_type value)

Creates a float attribute containing one value.

Parameters
  • value -

    The float value for the new attribute

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.

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.

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.

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

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>
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.
Return
An object of type T, constructed with the first N values from the attribute’s primary time sample.
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.

Exceptions
  • std::runtime_error -

    if an error occurs and throwOnError is true.

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

Public Static Functions

static FnKatAttributeType getKatAttributeType()

Returns the intended type of this Attribute, without needing a valid handle.

class Foundry::Katana::DoubleAttribute

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

Inherits from Foundry::Katana::DataAttribute

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

DoubleAttribute()

Create empty attribute class (isValid() == false).

DoubleAttribute(value_type value)

Creates a double attribute containing one value.

Parameters
  • value -

    The double value for the new attribute

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.

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.

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.

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

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>
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.
Return
An object of type T, constructed with the first N values from the attribute’s primary time sample.
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.

Exceptions
  • std::runtime_error -

    if an error occurs and throwOnError is true.

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

Public Static Functions

static FnKatAttributeType getKatAttributeType()

Returns the intended type of this Attribute, without needing a valid handle.

class Foundry::Katana::StringAttribute

A class representing a data attribute containing strings.

Inherits from Foundry::Katana::DataAttribute

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

StringAttribute()

Create empty attribute class (isValid() == false).

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.

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.

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.

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.

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.

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.

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>
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.
Return
An object of type T, constructed with the first N values from the attribute’s primary time sample.
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.

Exceptions
  • std::runtime_error -

    if an error occurs and throwOnError is true.

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.

bool operator==(const char *str) const
bool operator!=(const char *str) const
bool operator==(const std::string &str) const
bool operator!=(const std::string &str) const
StringAttribute(const Attribute &rhs)
StringAttribute &operator=(const Attribute &rhs)
StringAttribute(Attribute &&rhs)
StringAttribute &operator=(Attribute &&rhs)

Public Static Functions

static FnKatAttributeType getKatAttributeType()

Returns the intended type of this Attribute, without needing a valid handle.

Group Attributes

class Foundry::Katana::GroupAttribute

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

Inherits from Foundry::Katana::Attribute

Public Types

typedef std::pair<std::string, Attribute> NamedAttr_Type
typedef std::vector<NamedAttr_Type> NamedAttrVector_Type

Public Functions

GroupAttribute()

Create empty attribute class (isValid() == false).

GroupAttribute(const bool groupInherit)
GroupAttribute(const std::string &name1, const Attribute &attr1, const bool groupInherit)
GroupAttribute(const char *name1, const Attribute &attr1, const bool groupInherit)
GroupAttribute(const std::string &name1, const Attribute &attr1, const std::string &name2, const Attribute &attr2, const bool groupInherit)
GroupAttribute(const char *name1, const Attribute &attr1, const char *name2, const Attribute &attr2, const bool groupInherit)
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)
GroupAttribute(const char *name1, const Attribute &attr1, const char *name2, const Attribute &attr2, const char *name3, const Attribute &attr3, const bool groupInherit)
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)
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)
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)
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)
int64_t getNumberOfChildren() const

Returns the number of child attributes under the group attribute.

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.

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.

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.

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.

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.

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.

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.

bool getGroupInherit() const
void fillChildVector(NamedAttrVector_Type *children) const
GroupAttribute(const Attribute &rhs)
GroupAttribute &operator=(const Attribute &rhs)
GroupAttribute(Attribute &&rhs)
GroupAttribute &operator=(Attribute &&rhs)

Public Static Functions

static FnKatAttributeType getKatAttributeType()

Returns the intended type of this Attribute, without needing a valid handle.

DataBuilder

template <class ATTR>
class Foundry::Katana::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

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 Foundry::Katana::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!

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().

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)
 // }

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:

BuilderModeNormal = kFnKatGroupBuilderModeNormal

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

BuilderModeStrict = kFnKatGroupBuilderModeStrict

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:

BuildAndFlush = kFnKatGroupBuilderBuildAndFlush

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

BuildAndRetain = kFnKatGroupBuilderBuildAndRetain

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

Public Functions

GroupBuilder()

Creates a new, empty GroupBuilder object.

Remark
The builder is created with GroupBuilder::BuilderModeNormal.

GroupBuilder(BuilderMode builderMode)

Creates a new, empty GroupBuilder that uses the specified BuilderMode .

~GroupBuilder()
void reset()
bool isValid() const
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.

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.

GroupBuilder &set(const char *path, int32_t length, const Attribute &attr, bool groupInherit = true)
GroupBuilder &set(const char *path, int32_t length, FnAttributeHandle attr, bool groupInherit = true)
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.

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.

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

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.

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.

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.

GroupBuilder &sort()

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

Remark
sort() uses bytewise lexicographic ordering.

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.

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

ConstVectorBase(const Attribute &attr, float t)

Constructor for a ConstVectorBase that shares ownership of attr.

ConstVectorBase(Attribute &&attr, float t)

Constructor for a ConstVectorBase that takes ownership of attr.

ConstVectorBase()
size_type size() const

Returns the number of data elements

bool empty() const

Returns false if the ConstVectorBase contains any data

template <class T>
class ConstVector
#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

Inherits from Foundry::Katana::ConstVectorBase< T >

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

ConstVector(const Attribute &attr, float t)

Constructor for a ConstVector that shares ownership of attr.

ConstVector(Attribute &&attr, float t)

Constructor for a ConstVector that takes ownership of attr.

ConstVector(const ConstVectorBase<T> &other)
ConstVector()
size_type size() const

Returns the number of data elements

bool empty() const

Returns false if the ConstVector contains any data

const_iterator begin() const

Returns an iterator at the beginning of the data

const_iterator end() const

Returns an iterator at the end of the data

const_reference operator[](size_type i) const

Individual element access read only

const_reference at(size_type i) const

Individual element access read only

const_reference front() const

Returns a const reference to the first element

const_reference back() const

Returns a const reference to the last element

const value_type *data() const

Pointer to the raw data (read-only)

template <typename ValueT>
class SampleAccessorBase

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

Public Functions

SampleAccessorBase()
SampleAccessorBase(const Attribute &attr)

Constructor for an accessor that shares ownership of attr.

SampleAccessorBase(const Attribute *attr)

Constructor for an accessor that does not take ownership of attr.

SampleAccessorBase(Attribute &&attr)

Constructor for an accessor that takes ownership of attr.

~SampleAccessorBase()
SampleAccessorBase(const SampleAccessorBase &rhs)
SampleAccessorBase(SampleAccessorBase &&rhs)
SampleAccessorBase &operator=(const SampleAccessorBase &rhs)
SampleAccessorBase &operator=(SampleAccessorBase &&rhs)
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.

int64_t getNumberOfTimeSamples() const

Returns the number of samples in the attribute.

int64_t getNumberOfValues() const

Returns the number of values per sample.

size_t size() const

Returns the number of samples in the attribute.

bool empty() const

Returns true if the attribute has no time samples (or the accessor is invalid).

template <typename ValueT>
class SampleAccessor
#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)
     {
         // ...
     }
 }
Note
Pointers and references returned by SampleAccessor are invalidated when the accessor is destructed.

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;
     }
 }

Inherits from Foundry::Katana::SampleAccessorBase< ValueT >

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

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.

SampleAccessor(const Attribute *attr)

Constructor for an accessor that does not take ownership of attr.

SampleAccessor(Attribute &&attr)

Constructor for an accessor that takes ownership of attr.

SampleAccessor()

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

SampleAccessor(const SampleAccessorBase<ValueT> &other)
const_iterator begin() const

Returns an iterator to the first sample.

const_iterator end() const

Returns an iterator to the past-the-end sample.

const_reference front() const

Returns a reference to the first sample.

const_reference back() const

Returns a reference to the last sample.

const_reference operator[](difference_type i) const

Returns a reference to the ith sample.

const_reference at(difference_type i) const

Returns a reference to the ith sample.

Exceptions
  • std::out_of_range -

    if i is not a valid index.

FnPlatform::ArrayView<float> getSampleTimes() const

Returns a view of the samples times present in this attribute.

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.

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

Sample(const ValueT *data, int64_t valueCount, int64_t sampleIndex, float time)
Sample()
float getSampleTime() const
int64_t getSampleIndex() const
int64_t getNumberOfValues() const
template <typename T, size_t N>
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.
Return
An object of type T, constructed with the first N values from the sample.
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.

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

SampleIterator()
SampleIterator(const SampleAccessor<ValueT> &acc, int64_t sampleIndex = 0)
reference operator*() const
pointer operator->() const
reference operator[](difference_type n) const
SampleIterator &operator++()
SampleIterator &operator--()
SampleIterator operator++(int)
SampleIterator operator--(int)
SampleIterator &operator+=(difference_type n)
SampleIterator &operator-=(difference_type n)

Friends

bool operator==(SampleIterator lhs, SampleIterator rhs)
bool operator!=(SampleIterator lhs, SampleIterator rhs)
bool operator<(SampleIterator lhs, SampleIterator rhs)
bool operator>(SampleIterator lhs, SampleIterator rhs)
bool operator<=(SampleIterator lhs, SampleIterator rhs)
bool operator>=(SampleIterator lhs, SampleIterator rhs)
SampleIterator operator+(SampleIterator lhs, difference_type n)
SampleIterator operator+(difference_type n, SampleIterator rhs)
SampleIterator operator-(SampleIterator lhs, difference_type n)
difference_type operator-(SampleIterator lhs, SampleIterator rhs)

Utility Functions

group FnAttribute_Utility_Functions

Functions

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

Encodes and returns the string provided 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 -> 0xB0 Period -> Degree sign
 0x2F -> 0xB1 Slash -> Plus-or-minus sign

Both of these swaps correspond to a 0x82 offset.

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

Decodes and returns the string provided 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 -> 0xB0 Period -> Degree sign
 0x2F -> 0xB1 Slash -> Plus-or-minus sign

Both of these swaps correspond to a 0x82 offset.

uint64_t GetTotalSize()

Returns the total memory currently allocated by the FnAttribute library.