Structure¶

Args Files are XML document files with a .args file extension [1] that contain a top-level <args> element:

<args format="1.0">
  <!-- content -->
</args>

Within the top-level <args> element, an Args File may contain <param>, <page>, and <group> elements. A single <help> or (for shader args) <outputs> element may also be present. <param> elements are used to expose parameters in the user interface.

Parameters¶

<param> XML elements describe the presence and order of parameters within the UI. Each <param> element is required to have a name attribute; all other properties are optional.

Args Files can be used to specify the types of widgets to use for parameters in Katana’s UI. The type of widget to use for a particular parameter can be specified using a widget XML attribute on a <param> element:

<param name="someParameter" widget="fileInput"/>

A number of hints can be specified to affect the appearance and behavior of a widget of the respective type. Some hints are respected by most or all widget types, such as Conditional Visibility and Locking; other hints are specific to only particular types of widgets.

In their simplest form, hints can be specified using an XML attribute named the same as the hint name:

<param name="someParameter" widget="fileInput" fileTypes="exr|png"/>

Pages and Groups¶

Pages can be used to visually group parameters. Pages can be nested with dot-delimited values:

<param name="someParameter" page="Lighting" />
<param name="anotherParameter" page="Lighting.Advanced"/>

Page grouping may also be specified via enclosing <page> elements. This is often preferable as it provides a place to attach UI hints to pages themselves. Nested <page> elements specify their name properties as a dot-delimited path relative to the enclosing value. The following is equivalent to the previous example:

<page name="Lighting">
  <param name="someParameter"/>
  <page name="Advanced">
    <param name="anotherParameter"/>
  </page>
</page>

Pages appear in Katana’s UI as groups of their contents under a common header, with a disclosure triangle allowing the user to open or close the respective group. The initial state of whether a page’s group appears as open or closed can be specified with the open property, which accepts a boolean value. Pages default to appearing as closed unless otherwise specified. For example:

<page name="Lighting" open="true"></page>

A group is visually identical to a page, but differs in that it creates a group parameter to contain its children, whereas pages have no impact on the underlying parameter structure. This is most useful when writing Args Files for GenericAssign, where parameter groups correspond with attribute groups.

Help Text¶

Help text may be defined for any <param>, <page>, or <group> element by adding a help attribute or element to it, for example:

<!-- Using an attribute -->
<param type="float" name="color" help="The color of the light"/>

<!-- Using an element -->
<param type="float" name="color">
  <help>The color of the light</help>
</param>

<help> elements may contain arbitrary HTML.

Additional emphasis may be placed on given help text via the helpAlert attribute, which can be set to one of three values:

normal: The help button’s icon is shown in its default appearance.
warning: The help button’s icon appears with a yellow border.
error: The help button’s icon appears with a red border.

For example:

<param name="someParameter" helpAlert="warning">
  <help>
    This parameter is <strong>very</strong> important. Be careful!
  </help>
</param>

Help may also be added at the top level with a <help> element, for example:

<args format="1.0">
  <help>
    This is a <em>lovely</em> shader.
  </help>
  <!-- content -->
</args>

Comments¶

Comments use standard XML markup:

<!-- Useful commentary goes here. -->