Cook Interface (OpScript) ========================= .. lua:module:: Interface Provides a unified interface for querying and manipulating the scene graph. Its methods can be broadly divided into two categories: - Functions that query the incoming, or upstream, scene graph. These functions provide *read-only* access to the incoming scene graph. - Functions that modify the output scene graph, observable after executing this Op. This involves creating new scene graph locations, modifying attributes of incoming scene graph locations, or deleting locations entirely. Attributes ---------- Information ~~~~~~~~~~~ .. lua:function:: GetAttr(string attrName, [string inputLocationPath, \ int inputIndex]) Returns the specified attribute on the Op's input. It is often necessary to perform some action or compute a value based on the result stored in another attribute. The :lua:func:`GetAttr` function allows you to interrogate any part of the incoming scene graph by providing the attribute name and a scene graph location path (either absolute or relative). By default :lua:func:`GetAttr` will return the specified attribute on the Op's default input. In most cases where the Op only has one input branch this will suffice. If the Op has multiple inputs (e.g. the Merge node) the ``inputIndex`` parameter can be used to specify a particular branch. When specified, ``inputIndex`` must satisfy ``0 <= inputIndex < GetNumInputs()``. .. note:: It is important to remember that :lua:func:`GetAttr` will only interrogate the Op's *input* scene graph. Calls made to :lua:func:`SetAttr` will not be visible to :lua:func:`GetAttr`. If you need to see what attributes have been set during an Op's execution you should call :lua:func:`GetOutputAttr`. :param attrName: The name of the attribute. :param inputLocationPath: The input location path the attribute should be retrieved from. :param inputIndex: The input index the attribute should be retrieved from. :returns: The attribute at the specified location path and input index. .. seealso:: :lua:func:`GetNumInputs`, :lua:func:`GetOutputAttr` .. lua:function:: GetOutputAttr(string attrName) Returns the specified attribute on the Op's output for the current location. This is useful for inspecting the output attributes set during an :lua:func:`ExecOp` that may potentially require further processing after the exec'd Op has returned. .. note:: This is not recommended for normal usage. :param attrName: The name of the attribute to query. :returns: The attribute set on the Op's output. If not set ``nil`` will be returned. .. lua:function:: GetGlobalAttr(string name, [string inputLocation, \ int inputIndex]) Returns attribute from the input scene, including inherited attributes. :param name: The name of the attribute. :param inputLocation: The location at which the attribute should be found. :param inputIndex: The input index of which to search for the input scene graph location. :returns: The specified attribute at the given location including inherited attributes. .. lua:function:: GetBoundAttr([string inputLocationPath, int inputIndex]) Returns the bound attribute at the specified input scene graph location. :param inputLocationPath: The scene graph location to obtain the bound attribute from. :param inputIndex: The input index on which to find the scene graph location. :returns: A 6-element DoubleAttribute containing the bound attribute or ``nil`` if bounds do not exist at the specified location. .. lua:function:: GetTransformedBoundAttrPoints(DoubleAttribute boundAttr, \ number sampleTime, number[16] xform) -> number[8][3] Returns the bounding box specified by the bound attribute ``boundAttr`` after being transformed by the 4x4 transform matrix ``xform``. :param boundAttr: A 6-element DoubleAttribute specifying the bounding box to be transformed. :param sampleTime: The sample time that the bounds attribute ``boundAttr`` should be sampled at. :param xform: A 4x4 transform matrix by which boundAttr will be transformed. :returns: A table of 8 3-valued tables representing the 8 transformed points of the bounding box. .. lua:function:: GetTransformedBoundAttrMinMax(DoubleAttribute boundAttr, \ number sampleTime, number[16] xform) -> number[3], number[3] Returns the axis-aligned bounding box specified by the bound attribute ``boundAttr`` after being transformed by the 4x4 transform matrix ``xform``. :param boundAttr: A 6-element DoubleAttribute specifying the bounding box to be transformed. :param sampleTime: The sample time that the bounds attribute ``boundAttr`` should be sampled at. :param xform: A 4x4 transform matrix by which ``boundAttr`` will be transformed. :returns: Two 3-element tables that contain the transformed (x-min, y-min, z-min) and the transformed (x-max, y-max, z-max) values. .. lua:function:: GetGlobalXFormGroup([string inputLocationPath, \ int inputIndex]) Returns the global transform as a GroupAttribute, where the immediate children represent all the entries from ``/root`` to the leaf which have an ``xform`` attribute present. .. note:: If a collapsed 4x4 transform matrix is required, pass the result of this function to the :lua:func:`XFormUtils.CalcTransformMatrixAtTime` function. :param inputLocationPath: The input scene graph location to retrieve the global transform from. :param inputIndex: The input index from which to retrieve the scene graph location. :returns: The global transform at the specified location. Manipulation ~~~~~~~~~~~~ .. lua:function:: SetAttr(string attrName, Attribute attrValue, \ [boolean groupInherit]) Sets the specified attribute on the Op's output. ``attrName`` can be specified in dot-delimited form e.g. ``attr1.attr2.attr3``, in which case a new GroupAttribute is created for each level required and the value of ``groupInherit`` will determine the GroupAttribute's inheritance state. .. note:: Calls to :lua:func:`SetAttr` made in the current Op will not be reflected in subsequent calls to :lua:func:`GetAttr`. This is because functions which mutate the scene graph only affect the output of this Op. Methods such as :lua:func:`GetAttr` and :lua:func:`DoesLocationExist` query the input to this Op. This is also true for non-local queries i.e., when an Op queries attributes of its parent. In this case it will be querying the input at its parent, and thus does see the results of its own processing. If you need to see the attributes set during a cook you should use :lua:func:`GetOutputAttr`. :param attrName: The name of the attribute to create. This can be specified in dot-delimited form. :param attrValue: The Attribute instance to be associated with ``attrName``. :param groupInherit: The group inheritance state for newly created GroupAttributes. .. seealso:: :lua:func:`GetOutputAttr` .. lua:function:: CopyAttr(string dstAttrName, string srcAttrName, \ [boolean groupInherit=true, string inputLocationPath, int inputIndex]) Copies the specified source attribute to the specified destination attribute. The specified source attribute (determined by ``inputLocationPath`` and ``inputIndex``) will be copied to the output of this Op as ``dstAttrName``. If the source attribute or location does not exist this call is equivalent to calling :lua:func:`DeleteAttr` with the destination attribute. :param dstAttrName: The name of the attribute to copy the attribute at ``srcAttrName`` to. :param srcAttrName: The name of the attribute to copy to ``dstAttrName.`` :param groupInherit: The group inheritance state of the destination attribute. :param inputLocationPath: The scene graph location path on this Op's input to copy from. :param inputIndex: The input index to copy from (where multiple branches in the Op tree exist). .. lua:function:: ReplaceAttrs([string inputLocationPath, int inputIndex]) Replaces the attributes on this Op's output with those specified by the input scene graph location path. :param inputLocationPath: The attributes at inputLocationPath will replace those on this Op's output. :param inputIndex: The input index to use where multiple input branches exist for this Op. .. lua:function:: ExtendAttr(string dstAttrName, Attribute value, \ [string srcAttrName='', \ boolean groupInherit=true, \ string inputLocationPath, int inputIndex]) Extends the existing input attribute with additional values if the types match. If no input attribute exists with the specified name then this call is equivalent to :lua:func:`SetAttr`. Multi-sampling is supported; the new attribute is constructed as the union of all incoming and new time samples, leveraging the FnAttribute's existing interpolation. If there is a type mismatch, it will be reported as a scene graph error. If more sophisticated or fine-grained type mismatch handling is required it is recommended to instead manually call :lua:func:`GetAttr` / :lua:func:`SetAttr` Incoming NullAttribute's are equivalent to the attribute not being set in the incoming scene. :param dstAttrName: The name of the attribute to be extended. :param value: The Attributes that will extend the specified attribute. :param srcAttrName: The name of the attribute a specified location to be extended, if empty string is used this is the equivalent of :lua:func:`SetAttr`. :param groupInherit: The value of the group inheritance flag. :param inputLocationPath: The input location path from which ``srcAttrName`` should be sourced from. :param inputIndex: The input index to search for ``inputLocationPath`` on. .. seealso:: :lua:func:`SetAttr`, :lua:func:`GetAttr` .. lua:function:: DeleteAttr(string attrName) Deletes the attribute specified by ``attrName`` so it will no longer on this Ops output. :param attrName: The name of the attribute to delete from the Op's output. .. lua:function:: DeleteAttrs() Deletes all attributes on this Op's output. Scene graph ----------- Information ~~~~~~~~~~~ .. lua:function:: AtRoot() Returns whether we are at the topmost location this Op has been cooked at. This is often, but not always, ``/root``. This is equivalent to testing if :lua:func:`GetRootLocationPath` is the same as :lua:func:`GetOutputLocationPath`. .. lua:function:: GetRootLocationPath() Returns the scene graph location corresponding to the root of the Op's execution. This may or may not be ``/root``, specifically in the case where :lua:func:`ExecOp` is called beneath ``/root``. :returns: The root of the Op's execution. .. seealso:: :lua:func:`ExecOp` .. lua:function:: GetInputLocationType([string inputLocationPath, \ int inputIndex]) Returns the location type for specified location on the corresponding input. :param inputLocationPath: The scene graph location path. :param inputIndex: The input index on which to retrieve the specified scene graph location path. :returns: The location's ``type`` attribute. If type attribute is not present, an empty string will be returned, if it is not set then ``group`` will be returned by default. .. lua:function:: GetInputName() Returns the leaf name for the input location. This will typically match :lua:func:`GetOutputName`, but may differ when :lua:func:`CopyLocationToChild` is used. :returns: The leaf name for the input location. .. seealso:: :lua:func:`CopyLocationToChild` .. lua:function:: GetInputLocationPath() Returns the scene graph location path corresponding to the input scene graph location that is currently being traversed. :returns: The input scene graph location that is currently being traversed. .. lua:function:: GetRelativeInputLocationPath() Returns the relative location path corresponding to the input scene graph location that is currently being traversed. :returns: The relative location path corresponding to the input scene graph location that is currently being traversed. .. lua:function:: GetAbsInputLocationPath(string inputLocationPath) Resolves a relative *input* scene graph location path to an absolute path. This method cannot be used to query output locations (such as those used with methods such as :lua:func:`CreateChild`) but those methods that operate on the Op's output such as :lua:func:`GetAttr`. If you require the absolute scene graph location path for an output location you should use :lua:func:`GetAbsOutputLocationPath`. :param inputLocationPath: The relative input scene graph location path. :returns: The corresponding absolute location path. .. seealso:: :lua:func:`GetAbsOutputLocationPath` .. lua:function:: GetOutputName() Returns the leaf name for the output location. Example: ``/root/world/geo`` -> ``geo`` :returns: The leaf name of the output location. .. lua:function:: GetOutputLocationPath() Returns the output scene graph location path in its absolute form. The output scene graph location path is the scene graph location that is currently being cooked. Example: ``/root/world/geo`` :returns: The absolute output scene graph location path. .. lua:function:: GetRelativeOutputLocationPath() Returns the location path relative to the root execution location currently being traversed. For Ops instantiated at document level: .. code-block:: none "/root" -> "" "/root/world" -> "world" "/root/world/geo" -> "world/geo" For an Op first executed at /root/world/geo (producing "a/b") .. code-block:: none "/root/world/geo" -> "" "/root/world/geo/a" -> "a" "/root/world/geo/a/b" -> "a/b" :returns: The location path relative to the root execution location currently being traversed .. lua:function:: GetAbsOutputLocationPath(string outputLocationPath) Resolves a relative *output* scene graph location path to an absolute path. This method cannot be used to query input locations (such as those used with methods such as :lua:func:`GetAttr`) but those methods that operate on the Op's output such as :lua:func:`CreateChild`. If you require the absolute scene graph location path for an input location you should use :lua:func:`GetAbsInputLocationPath`. :param outputLocationPath: The relative output scene graph location path. :returns: The corresponding absolute location path. .. seealso:: :lua:func:`GetAbsInputLocationPath` .. lua:function:: DoesLocationExist([string inputLocationPath, int inputIndex]) Returns ``true`` if the specified location exists on the Op's input. :param inputLocationPath: The scene graph location path. :param inputIndex: The input index that should be searched. :returns: ``true`` if the location exists at the specified location and index otherwise false. .. lua:function:: GetPotentialChildren([string inputLocationPath, \ int inputIndex]) Returns a StringAttribute containing list of names of potential children on input. The ability for Ops, via :lua:func:`DeleteSelf`, to delete themselves gives rise to a subtle behavior. When an upstream Op is evaluated and creates children, if downstream Ops have the ability to delete them, the upstream Op can only go so far as to state that the children it creates may potentially exist after a downstream Op has been evaluated at those child locations. This is because the Op has no knowledge of what a downstream Op may do when evaluated at such a location. To that extent, :lua:func:`GetPotentialChildren` returns a list of all the children of a given location on the input of an Op. :param inputLocationPath: The input location path to obtain the potential children for. :param inputIndex: The input index to be used. :returns: A StringAttribute containing the potential children at the specified input location. Manipulation ~~~~~~~~~~~~ .. lua:function:: ResetRoot() Marks this location as the new root location in the Op's traversal. Subsequent calls to :lua:func:`GetRelativeOutputLocationPath` at child locations will return paths relative to this one. .. note:: Calls to :lua:func:`GetRelativeOutputLocationPath` at the current location will remain unaffected by this function. .. lua:function:: CreateChild(string name, [string opType='', \ Attribute|nil args, \ ResetRootMode resetRoot=ResetRootMode.Auto]) Creates a new child at the specified location if one didn't already exist. If the child already exists in the incoming scene then the Op will be run and previously created attribute values and children will be preserved. To ensure the child will not have any pre-existing attributes or children it is recommended to first call :lua:func:`DeleteChild`, doing so will maintain the original child index ordering. If the Op type is not specified or is an empty string the calling Op's type will be inherited by the child. To modify the result of :lua:func:`GetRelativeOutputLocationPath` in calls beneath this location the ``resetRoot`` argument can be set. If :lua:data:`ResetRootMode.Auto` is specified then the child's root location will be reset if and only if the Op's type differs from the parent's. .. note:: Multiple calls to :lua:func:`CreateChild` for the same named child location causes the last specified ``opType`` to be used, that is to say, successive calls to :lua:func:`CreateChild` mask prior calls. :param name: The name of the child to create. :param opType: The type of the Op that will be evaluated at the child location. If an empty string or nothing is specified then the current Op's type will be used. :param args: The Op arguments that will be passed to the Op when run at the child location. :param resetRoot: Specifies what the root location for Ops run at child location should be. .. seealso:: :lua:func:`ResetRoot` .. lua:function:: ReplaceChildren([string inputLocationPath, int inputIndex]) Replaces the children under the Op's current scene graph location with children from an alternate input location and/or input index. :param inputLocationPath: The input scene graph location whose children will replace this location's children. :param inputIndex: The input index on which the where the input location path should be retrieved. .. lua:function:: CopyLocationToChild(string child, \ [string inputLocationPath, \ int inputIndex, string orderBefore]) Copies the specified location in the input scene, to the specified child location. The specified ``inputLocationPath`` will not be evaluated until the new child location is traversed. At this time, if the input does not exist, neither will the new child. :lua:func:`CopyLocationToChild` can be used to rename a child location: .. code-block:: lua CopyLocationToChild(dst, src, InputIndex.Default, src) DeleteChild(src) The ``inputLocationPath`` always refers to the input name, and child refers to output name, so multiple :lua:func:`CopyLocationToChild` calls are unambiguous. :param child: The name of the child to be copied to the *output* of this Op. :param inputLocationPath: The input scene graph location path to copy. :param inputIndex: The input index to copy the ``inputLocationPath`` from. :param orderBefore: The child that this should be precede in the scene graph ordering. .. lua:function:: RenameChild(string src, string dst) Renames the specified child. :param src: The name of the child to rename. :param dst: The new name of the child. .. lua:function:: DeleteChild(string name) Deletes the specified child location on the Op's output. :param name: The name of the child location to delete. .. note:: Calling :lua:func:`DeleteChild` is more efficient than allowing the child location to delete itself. Where possible you should prefer :lua:func:`DeleteChild` over :lua:func:`DeleteSelf`. .. lua:function:: DeleteChildren() Deletes all children on this Op's output, both newly created by the current Op and any incoming children. .. lua:function:: DeleteSelf() Deletes the current output location. It is common to ``return`` immediately following this call. .. note:: Calls to :lua:func:`DeleteSelf` will not remove the location from the location's parent :lua:func:`GetPotentialChildren` list. Thus, if there is a way to structure code to use :lua:func:`DeleteChild` instead, it is generally preferable. Enumerations ^^^^^^^^^^^^ .. lua:data:: ResetRootMode Controls which root scene graph location will be used for Ops when run at child locations. .. lua:data:: ResetRootMode.Auto The root location is reset only if opType is different to the Op calling :lua:func:`CreateChild`. .. lua:data:: ResetRootMode.True The root location of the Op evaluated at the new location is reset to the new location path. .. lua:data:: ResetRootMode.False The root location of the Op evaluated at the new location is inherited from the Op that called :lua:func:`CreateChild`. .. lua:data:: InputIndex .. lua:data:: InputIndex.Null Special value returned by :lua:func:`GetInputIndex` when the current location does not exist in the incoming scene. .. lua:data:: InputIndex.Default Special value that can be specified to :lua:func:`GetAttr` and many other Cook Interface functions. It indicates the operation should apply to the "default" index. This is defined as the input index in which the current location was created (by :lua:func:`CreateChild()`, :lua:func:`CopyLocationToChild()` or :lua:func:`ReplaceChildren()`). Traversal ~~~~~~~~~ .. lua:function:: ReplaceChildTraversalOp(string opType, GroupAttribute args) Replaces the Op type and Op arguments for child locations of this Op. Newly created child locations (created with :lua:func:`CreateChild`) only have access to the Op arguments and type they were created with originally. Conceptually, this is the type and Op arguments used when traversing locations in the incoming scene. :param opType: The Op type that will be evaluated at child locations. :param args: The arguments that will be passed to the Op when run at the child locations. .. lua:function:: StopChildTraversal() Stops this Op from running at descendants of the current location. Graph State ----------- .. lua:function:: GetCurrentTime() Returns the current time from the current Graph State. :returns: The current time. .. lua:function:: GetShutterOpen() Returns the shutter open time from the current Graph State. :returns: The shutter open time. .. lua:function:: GetShutterClose() Returns the shutter close time from the current Graph State. :returns: The shutter close time. .. lua:function:: GetNumSamples() Returns the number of time samples from the current Graph State. :returns: The number of time samples. .. lua:function:: GetGraphStateVariable(string variableName) Returns the specified variable from the current Graph State. :param variableName: The name of the Graph State Variable. :returns: The Graph State Variable specified by ``variableName``. Error Reporting --------------- .. lua:function:: ReportError(string message) Reports the specified error message to the scene graph at the current scene graph location. :param message: The error message. .. lua:function:: ReportWarning(string message) Reports the specified warning message to the scene graph at the current scene graph location. :param message: The warning message. Miscellaneous ------------- .. lua:function:: Prefetch([string inputLocationPath, int inputIndex]) Indicates to the Runtime that the caller depends on the specified location. Calling the ``Prefetch()`` function instructs the Runtime that the specified location is required for the Op's processing task. The ``Prefetch()`` function will return immediately, scheduling the computation of the requested location to be cooked concurrently or at some point in the future. ``Prefetch()`` is recommended if your Op makes multiple scattered queries during a cook. Note that it is not necessary to prefetch parent locations of your default input. The use of a prefetch creates a data flow dependency, so do not prefetch locations or inputs you do not need. :param inputLocationPath: The scene graph location path to be prefetched. :param inputIndex: The input index from which to request the specified ``inputLocationPath``. In common cases the default input will suffice, however if your Op has multiple input branches (like a Merge Op) you will need to specify a particular input index. .. lua:function:: GetOpType() Returns the type of this Op. :returns: A string containing the Op's type. In OpScript, this returns ``OpScript.Lua``. .. lua:function:: GetOpArg([string argName]) Returns the specified Op argument or all Op arguments if an empty string is provided. Op arguments are passed to the Op to configure how it should run. Op arguments are stored in a GroupAttribute. This method allows you to query the Op arguments available to this Op. If you supply an argument name this can be in the dot-delimited form i.e. ``a.b.c`` or the single name form. :param argName The dot-delimited name of the Op argument. :returns: An instance of Attribute containing the Op argument. .. lua:function:: ExecOp(string opType, GroupAttribute opArgs) Runs the specified Op with the provided arguments at the current location. Children created as a result of the :lua:func:`ExecOp` call will behave as expected in such that they will retain the type and Op arguments of the exec'd Op. :param opType: The type of Op to be run. :param opArgs: A GroupAttribute describing the arguments that will be passed to the Op when run. .. lua:function:: GetNumInputs() Returns the number of input branches this Op has. An Op can have the output from multiple other Ops as its input. Obvious use cases for this are instances where you wish to merge multiple scene graphs produced by different OpTrees into a single scene graph, comparing attribute values in two scene graph states, or copying one scene graph into another one. The :lua:func:`GetNumInputs` function allows you to determine how many Ops you have as inputs, which is a precursor to interrogating different branches of the OpTree for scene graph data. :returns: The number of inputs this Op has. .. lua:function:: GetInputIndex() Returns the input index this scene graph location was created in. In most cases :lua:func:`GetInputIndex` will return 0. This reflects the fact that most Ops operate on the default input or branch. It can also return a special value of :lua:data:`InputIndex.Null` if the current location doesn't exist in the incoming scene. In specific cases, such as in a Merge Op, :lua:func:`GetInputIndex` may return an index > 0. Certain locations may be present only in additional input scenes, but not in the first (connected) input scene. Those locations are created in the output scene, and are then cooked by subsequent cooks of the Merge Op. For those locations, the Runtime keeps track of the index of the scene in which they were created. This index is returned by :lua:func:`GetInputIndex`. This value allows the Merge Op to know which input scene a particular location came from, and is used for performance optimizations when certain circumstances apply. :returns: The input index this location was created on. .. seealso:: :lua:data:`InputIndex`