Attributes (OpScript)¶

Base Attributes¶

class Attribute¶

The abstract base class of all attributes.

getType()¶: Returns a number representing the type of the attribute. This is useful for checking whether two attributes are of the same type.

getHash()¶: Returns a string representation of the hash of the attribute.

getHash64()¶: Returns a number representation of the hash of the attribute. Note that the value is a 64-bit hash value truncated to a 53-bit integer, which is guaranteed to be representable as a lua number.

getXML()¶: Returns a string containing a serialized XML representation of the attribute.

Null Attributes¶

class NullAttribute¶: A class representing a null value.

Data Attributes¶

class DataAttribute(number|string|table data[, number tupleSize=1])¶

The abstract base class of attributes containing data, possibly at multiple samples in time. DataAttribute implements common, data-agnostic functionality, such as querying the number and orientation of values and time samples. This class cannot be instantiated directly. Instead, use one of:

IntAttribute
FloatAttribute
DoubleAttribute
StringAttribute

data should be one of:

A single value, e.g. 1
A table of values, e.g. {1, 2, 3}
An associative table that maps each time sample to a table of values, e.g. {[0.25] = {1, 2, 3}, [0.75] = {4, 5, 6}}

When time samples are not explicitly given, the attribute is created with a single sample at t=0.0.

getNearestSample(float time)¶: Returns the unmodified values of the sample nearest to a given time as value list.

Note

getNearestSample() returns a Lua table. Lua tables cannot contain more than 2^27 (134 million) values. This means that OpScript cannot be used to manipulate very large attributes.

getNumberOfTimeSamples()¶: Returns the number of time samples at which data is recorded in this attribute.

getNumberOfTuples()¶: Returns the number of tuples in this attribute.

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

getSampleTime(int sampleIndex)¶: Returns a float value containing the time at a particular index for this attribute. If the index is not valid, 0.0 is returned.

getTupleSize()¶: Returns the number of data values for this attribute.

getValue([T defaultValue, boolean throwOnError])¶

Returns the 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 exception if there are no time samples or no values available. However, if defaultValue is provided and throwOnError is false, defaultValue will be returned.

class IntAttribute(number|table data[, number tupleSize=1])¶: A class representing a data attribute containing integers.

class FloatAttribute(number|table data[, number tupleSize=1])¶: A class representing a data attribute containing single-precision floats.

class DoubleAttribute(number|table data[, number tupleSize=1])¶: A class representing a data attribute containing double-precision floats.

class StringAttribute(string|table data[, number tupleSize=1])¶: A class representing a data attribute containing strings.

Group Attributes¶

class GroupAttribute([table children={}, boolean groupInherit=true])¶

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

children, if given, should be a table of key-value pairs. Each pair should be a 2-element table, where the key is a string giving the attribute name, and the value is an attribute.

local myGroup = GroupAttribute({{"a", IntAttribute(1)},
                                {"b", IntAttribute(2)}}, true)

groupInherit, if given, specifies whether this attribute should be inherited by descendant scene graph locations.

GroupBuilder can be used to incrementally build a group attribute.

getChildByIndex(int index)¶: Returns a child attribute at given index. If index is out of range, nil is returned.

getChildByName(string name)¶: Looks up a child attribute by name and returns it. Returns nil if named child does not exist.

getChildName(int index)¶: Returns the name of the child attribute at given index.

getGroupInherit()¶: Returns group inherit flag.

getNumberOfChildren()¶: Returns the number of child attributes.

GroupBuilder¶

A factory class for constructing GroupAttribute objects.

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

Warning

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

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

local gb = GroupBuilder()
gb:set("my.nested.attribute", IntAttribute(2))
gb:set("myTopLevelAttribute", StringAttribute("taco"))
gb:set("myOtherTopLevelAttribute", FloatAttribute(4.0))

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

GroupBuilder([GroupBuilder.BuilderMode mode= GroupBuilder.BuilderMode.Normal])¶

Creates a new, empty GroupBuilder object.

Possible values for mode:

GroupBuilder.BuilderMode.Normal

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

GroupBuilder.BuilderMode.Strict

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 GroupBuilder:set() method.
Callers must not make multiple calls to GroupBuilder:set() using the same path
Deletions are disallowed: the GroupBuilder:del() method becomes a no-op.

class GroupBuilder

All methods except for GroupBuilder:build() return a reference to self for method chaining.

set(string path, Attribute attr[, boolean 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.BuilderMode.Normal, the attribute is replaced. attr must be an Attribute object. If path is a dot-delimited path, groupInherit specifies the groupInherit flag for any new groups added by this call.

setWithUniqueName(string path, Attribute attr[, boolean 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. For example, calling setWithUniqueName("foo", ...) multiple times will produce paths foo, foo1, foo2, and so on.

update(GroupAttribute group)¶

Updates the contents of the GroupBuilder 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 GroupBuilder:setGroupInherit() has not been previously called, the GroupBuilder will also adopt on the incoming GroupAttribute’s groupInherit.

deepUpdate(GroupAttribute group)¶

Recursively updates the contents of the builder with attributes from the given GroupAttribute.

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

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

del(string path)¶: Deletes the attribute of the builder specified with the given path.

reserve(int size)¶

Reserves space for size attributes.

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

sort()¶: Sorts the top-level attributes by name.

Note

sort() uses bytewise lexicographic ordering

setGroupInherit(boolean groupInherit)¶

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

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

build([BuilderBuildMode mode= GroupBuilder.BuilderBuildMode.BuildAndFlush])¶

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

Possible values for mode:

GroupBuilder.BuilderBuildMode.BuildAndFlush: Specifies that the builder’s contents are cleared following a call to build(). This is the default.
GroupBuilder.BuilderBuildMode.BuildAndRetain: Specifies that the builder’s contents are retained following a call to build().

Utility Functions¶

Attribute.DelimiterEncode(string token)¶

Utility function that encodes (escapes) period (.) and slash (/) characters in token and returns the result. This is useful when adding GroupAttribute children with periods and slashes in their names. On retrieval these names can be decoded with DelimiterDecode().

Performs the following substitutions:

FULL STOP (0x2E) -> DEGREE SIGN (0xB0)
SLASH (0x2F) -> PLUS-MINUS SIGN (0xB1)

Attribute.DelimiterDecode(string token)¶

Utility function that decodes escaped period (.) and slash (/) characters in token and returns the result. This is useful when retrieving GroupAttribute children whose names were previously encoded via DelimiterEncode().

Performs the following substitutions:

DEGREE SIGN (0xB0) -> FULL STOP (0x2E)
PLUS-MINUS SIGN (0xB1) -> SLASH (0x2F)

Attribute.GetIntValue(object obj, number defaultValue)¶: If obj is an IntAttribute, this function returns its first value. Otherwise it returns defaultValue.

Attribute.GetFloatValue(object obj, number defaultValue)¶: If obj is a FloatAttribute, this function returns its first value. Otherwise it returns defaultValue.

Attribute.GetDoubleValue(object obj, number defaultValue)¶: If obj is a DoubleAttribute, this function returns its first value. Otherwise it returns defaultValue.

Attribute.GetStringValue(object obj, string defaultValue)¶: If obj is a StringAttribute, this function returns its first value. Otherwise it returns defaultValue.

Attribute.IsAttribute(object obj)¶: Returns true if obj is an Attribute, false otherwise.

Attribute.IsNull(object obj)¶: Returns true if obj is an NullAttribute, false otherwise.

Attribute.IsInt(object obj)¶: Returns true if obj is an IntAttribute, false otherwise.

Attribute.IsFloat(object obj)¶: Returns true if obj is an FloatAttribute, false otherwise.

Attribute.IsDouble(object obj)¶: Returns true if obj is an DoubleAttribute, false otherwise.

Attribute.IsString(object obj)¶: Returns true if obj is an StringAttribute, false otherwise.

Attribute.IsGroup(object obj)¶: Returns true if obj is an GroupAttribute, false otherwise.