Attributes (C++)¶

Attributes¶

namespace Foundry¶

namespace Katana¶

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_v2 *)¶: Initializes the API with the given Attribute Host suite.

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

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

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

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

struct Hash¶

Public Functions

std::string str() const¶

uint64_t uint64() const¶

Attribute attr() const¶

Hash()¶

Hash(uint64_t hash1_, uint64_t hash2_)¶

Hash(FnAttributeHash h)¶

bool operator==(const Hash &rhs) const¶

bool operator!=(const Hash &rhs) const¶

bool operator<(const Hash &rhs) const¶

Public Members

uint64_t hash1¶

uint64_t hash2¶

class Attribute¶

#include <FnAttribute.h>

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.

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

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

class DataAttribute¶

#include <FnAttribute.h>

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 the number and orientation of values and time samples.

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

class NullAttribute¶

#include <FnAttribute.h>

A class representing a null value.

Inherits from Foundry::Katana::Attribute

Public Functions

NullAttribute()¶

NullAttribute(const Attribute &rhs)¶

NullAttribute &operator=(const Attribute &rhs)¶

Public Static Functions

static FnKatAttributeType getKatAttributeType()¶

Private Functions

NullAttribute(FnAttributeHandle handle)¶

class IntAttribute¶

#include <FnAttribute.h>

A class representing a data attribute containing integers.

Inherits from Foundry::Katana::DataAttribute

Public Types

typedef int32_t value_type¶

typedef IntConstVector array_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)¶

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

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.

IntAttribute(const float *times, int64_t timeCount, const value_type **values, int64_t valueCount, int64_t tupleSize)¶

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

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.

array_type getNearestSample(float time) const¶: Returns the unmodified values of the sample nearest to a given time. This returns a ConstVector to the data at the sample.

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.

IntAttribute(const Attribute &rhs)¶

IntAttribute &operator=(const Attribute &rhs)¶

Public Static Functions

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

Private Functions

IntAttribute(FnAttributeHandle handle)¶

class FloatAttribute¶

#include <FnAttribute.h>

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

Inherits from Foundry::Katana::DataAttribute

Public Types

typedef float value_type¶

typedef FloatConstVector array_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)¶

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.

FloatAttribute(const float *times, int64_t timeCount, const value_type **values, int64_t valueCount, int64_t tupleSize)¶

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

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.

array_type getNearestSample(float time) const¶: Returns the unmodified values of the sample nearest to a given time. This returns a ConstVector to the data at the sample.

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.

FloatAttribute(const Attribute &rhs)¶

FloatAttribute &operator=(const Attribute &rhs)¶

Public Static Functions

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

Private Functions

FloatAttribute(FnAttributeHandle handle)¶

class DoubleAttribute¶

#include <FnAttribute.h>

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

Inherits from Foundry::Katana::DataAttribute

Public Types

typedef double value_type¶

typedef DoubleConstVector array_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)¶

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.

DoubleAttribute(const float *times, int64_t timeCount, const value_type **values, int64_t valueCount, int64_t tupleSize)¶

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

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.

array_type getNearestSample(float time) const¶: Returns the unmodified values of the sample nearest to a given time. This returns a ConstVector to the data at the sample.

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.

DoubleAttribute(const Attribute &rhs)¶

DoubleAttribute &operator=(const Attribute &rhs)¶

Public Static Functions

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

Private Functions

DoubleAttribute(FnAttributeHandle handle)¶

class StringAttribute¶

#include <FnAttribute.h>

A class representing a data attribute containing strings.

Inherits from Foundry::Katana::DataAttribute

Public Types

typedef std::string value_type¶

typedef StringConstVector array_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

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 char **values, int64_t valueCount, int64_t tupleSize)¶

StringAttribute(const float *times, int64_t timeCount, const char ***values, int64_t valueCount, int64_t tupleSize)¶

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

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.

array_type getNearestSample(float time) const¶: Returns the unmodified values of the sample nearest to a given time. This returns a ConstVector to the data at the sample.

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.

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.

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

bool operator==(const std::string &str) const¶

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

StringAttribute(const Attribute &rhs)¶

StringAttribute &operator=(const Attribute &rhs)¶

Public Static Functions

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

Private Functions

StringAttribute(FnAttributeHandle handle)¶

class GroupAttribute¶

#include <FnAttribute.h>

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

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(const std::string &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) 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.

bool getGroupInherit() const¶

void fillChildVector(NamedAttrVector_Type *children) const¶

GroupAttribute(const Attribute &rhs)¶

GroupAttribute &operator=(const Attribute &rhs)¶

Public Static Functions

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

Private Functions

GroupAttribute(FnAttributeHandle handle)¶

GroupBuilder¶

namespace Foundry¶

namespace Katana¶

class GroupBuilder¶

#include <FnGroupBuilder.h>

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¶

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¶

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

typedef enum Foundry::Katana::GroupBuilder::BuilderMode BuilderMode¶

typedef enum Foundry::Katana::GroupBuilder::BuilderBuildMode BuilderBuildMode¶

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

bool isValid() const¶

GroupBuilder &set(const std::string &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, const Attribute &attr, bool groupInherit = true)¶

GroupBuilder &setWithUniqueName(const std::string &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 &setWithUniqueName(const char *path, const Attribute &attr, bool groupInherit = true)¶

GroupBuilder &del(const std::string &path)¶

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

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

GroupBuilder &del(const char *path)¶

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

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 GroupAttributes 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()/deepUpdate() – 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

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.