Anatomy of a Scene¶
Tip
In this article, if a term is vital to describing scenes in Gaffer, its first occurence will be highlighted in bold.
A scene node in Gaffer outputs data structured to describe a 3D scene. In this article we will describe this structure and the terminology associated with it.
The structure of a scene can be broken down into two main areas:
- Hierarchy
- Globals
Scene hierarchy¶
In common with most DCCs, Gaffer represents a 3D scene as a hierarchy or tree structure. We refer to positions within this tree as locations, specified by their path within the scene, e.g. /world/city/building01. Locations are arranged via parent-child relationships, such that /world/city is considered the parent of the child /world/city/building01. Do not confuse locations in the scene hierachy with nodes in the node graph; nodes output scenes, but are not part of them.
Each location has a number of properties that describe the content of the scene at that point in the hierarchy. They can be inspected in the Selection tab of the Scene Inspector. Each property of each location is computed independently, allowing Gaffer to generate the scene lazily on demand.
Important
In this article, “property” only refers generically to a piece of data that describes a scene. It does not carry the more specific meanings from other DCCs.
Transform¶
The transform contains a 4x4 matrix storing the local transformation of the location. It is used to position the location in 3D space using a combination of translation, rotation and scaling.
Bound¶
The bound contains the union of the bounding box of the location’s contents and of the contents of all of its descendants. This is stored relative to the location’s local space. The bound may be computed independently of the contents themselves.
Object¶
When a location contains a 3D object, such as a primitive or a camera, it is stored in the object property. Although any location can have an object, typically they are only stored at leaf locations.
Primitive variables¶
Primitive variables are properties of primitives (example primitive types include meshes, curves, and points). Common examples are “P”, which stores vertex positions, “N” which stores normals and “uv” which stores texture coordinates. In addition to these, objects can store any number of additional variables. Primitive variables can store a single value for the whole object, or can store values per-face, per-vertex or per-face-vertex.
Attributes¶
The attributes store an arbitrary number of named values for the location. Gaffer defines standard attributes for object visibility, motion blur, and more. Additional attributes are defined to provide renderer-specific settings for things such as shader assignment, ray visibility and tessellation. Custom attributes may additionally be created by users for any purpose, often to control shading variation.
Locations inherit attributes from their parent, with attributes local to the location overriding any equivalent attribute from the parent.
Note
Maya users should note that attributes in Gaffer are not equivalent to attributes in Maya’s Attribute Editor. The equivalent term in Gaffer is plug. An attribute in Gaffer always refers to a property of a scene.
Katana users may be accustomed to thinking of every property in a scene as an attribute. In Gaffer, attributes only refer to arbitrary values for the location. Transforms, geometry, and bounds are not attributes.
Users familiar with RenderMan may be reassured to know that Gaffer derives its use of the term attribute from RenderMan. Gaffer and RenderMan attributes are very much alike.
Globals¶
The globals are properties of a scene as a whole, rather than a particular location.
Options¶
The options are typically used to define render settings. Gaffer defines standard options for settings such as render resolution, pixel aspect ratio, and overscan. Additional options are defined to provide renderer-specific settings for things such as ray depth, sampling, and logging. Users can create custom options to store arbitrary information.
Outputs¶
The outputs define the images to be generated by the renderer. They specify things such as output data, filename, filetype and filtering.
Note
Both options and outputs in Gaffer can be considered similar to render globals in Maya.
Sets¶
Sets are collections of paths specifying a subset of locations within the scene. They are typically used to specify which locations a node acts upon. Gaffer automatically maintains a set containing all lights and a set containing all cameras. Users can create arbitrary custom sets of their own.