Attributes (OpScript) ===================== Base Attributes --------------- .. lua:class:: Attribute() The abstract base class of all attributes. .. lua:method:: getType() Returns a number representing the type of the attribute. This is useful for checking whether two attributes are of the same type. .. lua:method:: getHash() Returns a string representation of the hash of the attribute. .. lua:method:: 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. .. lua:method:: getXML() Returns a string containing a serialized XML representation of the attribute. Null Attributes --------------- .. lua:class:: NullAttribute() A class representing a null value. Data Attributes --------------- .. lua: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: - :lua:class:`IntAttribute` - :lua:class:`FloatAttribute` - :lua:class:`DoubleAttribute` - :lua:class:`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. .. lua:method:: getNearestSample(float time) Returns the unmodified values of the sample nearest to a given time as value list. .. note:: :lua:func:`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. .. lua:method:: getNumberOfTimeSamples() Returns the number of time samples at which data is recorded in this attribute. .. lua:method:: getNumberOfTuples() Returns the number of tuples in this attribute. .. lua:method:: getNumberOfValues() Returns the total number of data values for this attribute. This will be equal to ``getNumberOfTuples() * getTupleSize()``. .. lua:method:: 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. .. lua:method:: getTupleSize() Returns the number of data values for this attribute. .. lua:method:: 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. .. lua:class:: IntAttribute(number|table data, [number tupleSize=1]) A class representing a data attribute containing integers. .. lua:class:: FloatAttribute(number|table data, [number tupleSize=1]) A class representing a data attribute containing single-precision floats. .. lua:class:: DoubleAttribute(number|table data, [number tupleSize=1]) A class representing a data attribute containing double-precision floats. .. lua:class:: StringAttribute(string|table data, [number tupleSize=1]) A class representing a data attribute containing strings. Group Attributes ---------------- .. lua: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. .. code-block:: lua 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. :lua:class:`GroupBuilder` can be used to incrementally build a group attribute. .. lua:method:: getChildByIndex(int index) Returns a child attribute at given index. If index is out of range, ``nil`` is returned. .. lua:method:: getChildByName(string name) Looks up a child attribute by name and returns it. Returns ``nil`` if named child does not exist. .. lua:method:: getChildName(int index) Returns the name of the child attribute at given index. .. lua:method:: getGroupInherit() Returns group inherit flag. .. lua:method:: 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 :lua:meth:`~GroupBuilder:set` method, and, when finished, retrieving a newly constructed :lua:class:`GroupAttribute` using the GroupBuilder's :lua:meth:`~GroupBuilder:build` method. .. warning:: There is currently no way to inspect the contents of the builder, other than by calling :lua:meth:`~GroupBuilder:build` and inspecting the generated :lua:class:`GroupAttribute`. Note that by default :lua:meth:`~GroupBuilder:build` clears the contents of the builder; to override this behaviour pass ``GroupBuilder.BuilderBuildMode.BuildAndRetain`` to :lua:meth:`~GroupBuilder:build`. As a convenience, GroupBuilder has support for creating arbitrarily nested :lua:class:`GroupAttribute` structures by passing a dot-delimited string to :lua:meth:`~GroupBuilder:set`, which is referred to as a "path". Note that this implies that the ``.`` character is *not* a valid attribute name! .. code-block:: lua 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) -- } .. lua:function:: GroupBuilder([GroupBuilder.BuilderMode mode=\ GroupBuilder.BuilderMode.Normal]) Creates a new, empty :lua:class:`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 :lua:meth:`~GroupBuilder:set` method. - Callers must not make multiple calls to :lua:meth:`~GroupBuilder:set` using the same path - Deletions are disallowed: the :lua:meth:`~GroupBuilder:del` method becomes a no-op. .. lua:class:: GroupBuilder All methods except for :lua:meth:`~GroupBuilder:build` return a reference to self for method chaining. .. lua:method:: 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. .. lua:method:: 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 :lua:meth:`~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. .. lua:method:: 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 :lua:meth:`~GroupBuilder:setGroupInherit` has not been previously called, the GroupBuilder will also adopt on the incoming GroupAttribute's ``groupInherit``. .. lua:method:: 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 :lua:meth:`~GroupBuilder:setGroupInherit` has not been previously called, the GroupBuilder will also adopt on the incoming GroupAttribute's ``groupInherit``. .. lua:method:: del(string path) Deletes the attribute of the builder specified with the given *path*. .. lua:method:: 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. .. lua:method:: sort() Sorts the top-level attributes by name. .. note:: ``sort()`` uses bytewise lexicographic ordering .. lua:method:: setGroupInherit(boolean groupInherit) Sets a special attribute on the builder that determines the value returned by :lua:meth:`~GroupAttribute:getGroupInherit` for the top-level :lua:class:`GroupAttribute` returned by :lua:meth:`~GroupBuilder:build`. This ``groupInherit`` flag is *sticky*, so once it's been set -- either through an explicit call to :lua:meth:`~GroupBuilder:setGroupInherit`, or indirectly via a call to :lua:meth:`~GroupBuilder:update`/:lua:meth:`~GroupBuilder:deepUpdate()` -- further calls to ``setGroupInherit()`` will have no effect. .. lua:method:: 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 ----------------- .. lua:module:: Attribute .. lua:function:: DelimiterEncode(string token) Utility function that encodes (escapes) period (``.``) and slash (``/``) characters in *token* and returns the result. This is useful when adding :lua:class:`GroupAttribute` children with periods and slashes in their names. On retrieval these names can be decoded with :lua:func:`DelimiterDecode`. Performs the following substitutions: - FULL STOP (``0x2E``) -> DEGREE SIGN (``0xB0``) - SLASH (``0x2F``) -> PLUS-MINUS SIGN (``0xB1``) .. lua:function:: DelimiterDecode(string token) Utility function that decodes escaped period (``.``) and slash (``/``) characters in *token* and returns the result. This is useful when retrieving :lua:class:`GroupAttribute` children whose names were previously encoded via :lua:func:`DelimiterEncode`. Performs the following substitutions: - DEGREE SIGN (``0xB0``) -> FULL STOP (``0x2E``) - PLUS-MINUS SIGN (``0xB1``) -> SLASH (``0x2F``) .. lua:function:: GetIntValue(object obj, number defaultValue) If *obj* is an :lua:class:`IntAttribute`, this function returns its first value. Otherwise it returns *defaultValue*. .. lua:function:: GetFloatValue(object obj, number defaultValue) If *obj* is a :lua:class:`FloatAttribute`, this function returns its first value. Otherwise it returns *defaultValue*. .. lua:function:: GetDoubleValue(object obj, number defaultValue) If *obj* is a :lua:class:`DoubleAttribute`, this function returns its first value. Otherwise it returns *defaultValue*. .. lua:function:: GetStringValue(object obj, string defaultValue) If *obj* is a :lua:class:`StringAttribute`, this function returns its first value. Otherwise it returns *defaultValue*. .. lua:function:: IsAttribute(object obj) Returns ``true`` if *obj* is an :lua:class:`Attribute`, ``false`` otherwise. .. lua:function:: IsNull(object obj) Returns ``true`` if *obj* is an :lua:class:`NullAttribute`, ``false`` otherwise. .. lua:function:: IsInt(object obj) Returns ``true`` if *obj* is an :lua:class:`IntAttribute`, ``false`` otherwise. .. lua:function:: IsFloat(object obj) Returns ``true`` if *obj* is an :lua:class:`FloatAttribute`, ``false`` otherwise. .. lua:function:: IsDouble(object obj) Returns ``true`` if *obj* is an :lua:class:`DoubleAttribute`, ``false`` otherwise. .. lua:function:: IsString(object obj) Returns ``true`` if *obj* is an :lua:class:`StringAttribute`, ``false`` otherwise. .. lua:function:: IsGroup(object obj) Returns ``true`` if *obj* is an :lua:class:`GroupAttribute`, ``false`` otherwise.