== Appendices anchor:appendices_appendices[]
This section contains additional miscellaneous material to be referenced whilst using Gaffer.
It is composed of the following appendices:
* xref:appendices_hotkeys[Appendix A: Hotkeys]
* xref:appendices_scriptingNuggets[Appendix B: Scripting Nuggets]
* xref:appendices_rendermanShaderWriting[Appendix C: RenderMan Shader Writing]
* xref:appendices_customAttributesAndOptions[Appendix D: Custom Attributes and Options]
=== Hotkeys anchor:appendices_hotkeys[]
.Global Hotkeys
[options="header",cols="20%,80%"]
|=======================
|Keypress|Result
|`right-arrow`|Increment current frame
|`left-arrow` |Decrement current frame
|` |Set Gaffer to run in full-screen mode
|`Ctrl+z` |Undo last action
|`Ctrl+Shift+z`|Redo last undone action
|`Ctrl+n` |Create blank script in new Gaffer session
|`Ctrl+o` |Launch dialog to open .gfr script file
|`Ctrl+s` |Save current script
|`Ctrl+Shift+s`|Launch dialog to save current script with new file name
|`Ctrl-q` |Quit application
|======================
.NodeGraph Hotkeys
[options="header",cols="20%,80%"]
|=======================
|Keypress|Result
|`f` |Frame current node selection, or all nodes if nothing selected
|`d` |Disable/enable current node selection
|`+` |Zoom in !!!!not yet implemented!!!!
|`-` |Zoom out !!!!not yet implemented!!!!
|`Tab` |Raise node creation menu and searchbox
|`Delete` |Delete current node selection
|`Backspace`|Delete current node selection
|`Ctrl+a` |Select all nodes
|`Ctrl+Shift+a`|Clear selection
|`Ctrl+x` |Cut current node selection
|`Ctrl+c` |Copy current node selection
|`Ctrl+v` |Paste node(s)
|`up-arrow`|Exit current box
|`down-arrow`|Enter current box
|=======================
[NOTE]
The copy/paste buffer for nodes persists between instances of gaffer, allowing you to quickly duplicate nodes between different scripts.
Also, as nodes are described by plain text you can cut and paste into emails/IM communications to share nodes with other users.
.Viewer Hotkeys - 3D mode
[options="header",cols="20%,80%"]
|=======================
|Keypress|Result
|`f` |Frame current selection, or whole scene if nothing selected
|`up-arrow`|Expand hierarchy of any selected bounding boxes
|`down-arrow`|Collapse hierarchy of any selected items/bounding boxes
|`+` |Zoom in !!!!not yet implemented!!!!
|`-` |Zoom out !!!!not yet implemented!!!!
|=======================
.Viewer Hotkeys - 2D mode
[options="header",cols="20%,80%"]
|=======================
|Keypress|Result
|`f` |Fit image to Viewer
|`r` |Isolate RED channel of image. Press again to revert back to RGB image
|`g` |Isolate GREEN channel of image. Press again to revert back to RGB image
|`b` |Isolate BLUE channel of image. Press again to revert back to RGB image
|`a` |Isolate ALPHA channel of image. Press again to revert back to RGB image
|`+` |Zoom in !!!!not yet implemented!!!!
|`-` |Zoom out !!!!not yet implemented!!!!
|=======================
.NodeEditor Hotkeys
[options="header",cols="20%,80%"]
|=======================
|Keypress|Result
|`up-arrow`|When focus is set to a numerical input field, this will increment the value of the field
|`down-arrow`|When focus is set to a numerical input field, this will decrement the value of the field
|`Tab` |Move focus to the next input field
|=======================
.ScriptEditor Hotkeys
[options="header",cols="20%,80%"]
|=======================
|Keypress|Result
|`Ctrl+a` |Select all text
|`Ctrl+Shift+a`|Clear selection
|`Ctrl+x` |Cut current selection
|`Ctrl+c` |Copy current selection
|`Ctrl+v` |Paste
|`Enter` |Execute selected input text
|=======================
=== Scripting Nuggets anchor:appendices_scriptingNuggets[]
These one or two-liners achieve simple tasks via the python scripting interface, and serve as examples to build from.
////
More complete details of the gaffer api are available !!!!HERE!!!!
////
Using the current frame to drive a plug (in this case the number of pixel samples). Enter in an expression for constant update:
[source, python]
------------------------------------
parent['RenderManOptions']['options']['pixelSamples']['value']['y'] = int(context.getFrame())
------------------------------------
Looping over a frame range:
[source, python]
------------------------------------
for i in range(1,120):
script.context().setFrame(i)
------------------------------------
Get the current script's start and end frame:
[source, python]
------------------------------------
start = script['frameRange']['start'].getValue()
end = script['frameRange']['end'].getValue()
------------------------------------
Execute a named executable node - i.e. render:
[source, python]
------------------------------------
script['RenderManRender'].execute( [script.context()] )
------------------------------------
Get the file name of the open script:
[source, python]
------------------------------------
script['fileName'].getValue()
------------------------------------
Query value of script variables:
[source, python]
------------------------------------
rd = script.context()['project:rootDirectory']
------------------------------------
Create a RenderManShader node pointing to a specific shader on disk:
[source, python]
------------------------------------
import GafferRenderMan
shaderNode = GafferRenderMan.RenderManShader("MyShaderNode")
shaderNode.loadShader( '/path/to/my/shader' )
script.addChild( shaderNode )
------------------------------------
Set the current selection to be a specific node:
[source, python]
------------------------------------
script.selection().clear()
script.selection().add(script['MyNodeName'])
------------------------------------
Set the value of a plug:
[source, python]
------------------------------------
# 'MySceneReaderNode' is the node name
# 'fileName' == the plug name
script['MySceneReaderNode']['fileName'].setValue( '/path/to/my/cache.scc' )
------------------------------------
Set the value of a nested plug:
[source, python]
------------------------------------
# 'MyStandardOptionsNode' is the node name
# the plug name would be shown as 'options.renderResolution.value.x' in the Gaffer UI tooltips
script['MyStandardOptionsNode']['options']['renderResolution']['value']['x'].setValue( 2048 )
------------------------------------
Connect one node to another (in this case connecting the 'out' plug of myNodeA to the 'in' plug of myNodeB):
[source, python]
------------------------------------
myNodeB['in'].setInput(myNodeA['out'])
------------------------------------
=== RenderMan Shader Writing anchor:appendices_rendermanShaderWriting[]
Gaffer allows RenderMan shader writers to provide information about shaders and their parameters in the form of *annotations*. This metadata is then used by Gaffer to draw suitable shader interface elements in its various Editor panels. In this manner GUIs for shaders can be provided to end users.
The annotation system is derived from the metadata section of the +++OSL Language Spec+++. Gaffer supports a subset of these tags, and introduces the extensions *activator*, *divider*, *primaryInput*, *coshaderType*, and *type*.
Annotations are optional and Gaffer will provide default appearances for all shader parameter types if given no other instruction.
.Available Annotations
[options="header",cols="20%,80%"]
|=======================
|Annotation|Use
|help |Provides documentation for the shader. This will be displayed as a tooltip in the NodeEditor.
|primaryInput |If declared, this annotation determines which input will be passed to downstream nodes if the current node is disabled. Value of this annotation should be a "shader" parameter.
|coshaderType |Specifies a space-separated list of 'types' for the shader. Only of use for co-shaders designed to be connected to other shaders.
|PARAMETER.coshaderType|Specifies the 'type' of co-shader this plug will accept as for connection. Aids usability as noodles will automatically latch on to valid connections, and invalid connections are made impossible.
|PARAMETER.label |Can be used to override the label drawn for the plug. Value of label will be displayed as-is (i.e. you must include your own characters)
|PARAMETER.help |Allows small documentation strings to be attached to parameters. The help strings are shown in popup tooltips when users hovers over a parameter labels.
|PARAMETER.page |Parameters can be arranged into collapsible boxes by specifying 'page' annotations. Matching page values result in those parameters appearing grouped together.
|page.PAGE_NAME.collapsed|Sets the default open/closed state of the page group.
|PARAMETER.widget |Allows parameters to drawn as one of the specific widget types. The available widgets are:
mapper : A pop-up menu with associative choices (an enumerated type, if the values are integers). This widget further the annotation "options", a ‘\|’-delimited string with “key:value” pairs.
popup : A pop-up menu of literal choices. This widget further the annotation "options", a ‘\|’-delimited string with “key:value” pairs.
checkBox : A boolean widget displayed as a checkbox.
filename : Treats a string as a file path. Adds file browser button, and enables Gaffer's in place path editing.
null : Hides the parameter.
|PARAMETER.type |Allows numeric shader parameters (which are always floats) to be represented within gaffer as FloatPlugs, IntPlugs or BoolPlugs by specifying a value of "float", "int" or "bool"
|PARAMETER.min |Minimum value a numeric parameter can have.
|PARAMETER.max |Maximum value a numeric parameter can have.
|PARAMETER.divider |A horizontal divider bar is drawn below any parameters with this annotation.
|activator.ACTIVATOR_NAME.expression|Declares an activator expression that can be used to drive the enabled/disabled state of parameters. Inputs to expressions can include parameter values and the connected state of a plug on the ShaderNode. Simple logic is possible - see examples.
|PARAMETER.activator|Sets the parameter to use the specified activator expression. If the expression evaluates as False (or 0), the parameter will be disabled in the NodeEditor, otherwise the parameter will be enabled for editing.
|======================
------------------------------------
Example shader showing parameter annotations:
include::../images/autoGenerated_source/annotationsExample.sl[]
------------------------------------
.The example shader loaded into Gaffer
image::images/autoGenerated_target/appendices_rendermanShaderWriting_figAA.png[align="center"]
=== Custom Attributes and Options anchor:appendices_customAttributesAndOptions[]
Alongside the default settings that can be specified via the *Attributes and *Options nodes, Gaffer supports arbitrary renderer attributes/options by means of a naming convention. Strings are used to specify the scope of the setting (i.e. which renderer to apply to), and the specific attribute or option to set.
This syntax is utilised by the CustomAttributes and CustomOptions nodes to pass the relevant setting to the renderer.
[note]
When adding the individual attributes/options to a node, ensure you select the correct 'type', as the translation mechanism is type sensitive. For example, in the RenderMan case 'Matte' is a boolean attribute, so you must add a 'bool' member to the CustomAttributes node.
==== Syntax
In the general form, the syntax for specifying an attribute or option is:
------------------------------------
::
------------------------------------
is optional, and valid values are `ri` (RenderMan), `ai` (Arnold), `gl` (openGL).
==== Examples
The `ri` examples use descriptions taken from the 3delight documentation to demonstrate the translation.
[options="header",cols="40%,20%,20%,20%"]
|=======================
| Docs description | Syntax in Gaffer | Type in Gaffer | Relevant node
| Color [1 1 1] | `ri:color` | color | CustomAttributes
| Matte 0 | `ri:matte` | bool | CustomAttributes
| Attribute "visibility" "integer specular" [0] | `ri:visibility:specular` | bool | CustomAttributes
| Attribute "grouping" "string tracesubset" [""] | `ri:grouping:tracesubset` | string | CustomAttributes
| Attribute "user" "uniform type variable" value | `ri:user:`__name__ | _varies_ | CustomAttributes
| Option "render" "integer nthreads" n | `ri:render:nthreads` | int | CustomOptions
| Option "limits" "integer bucketsize[2]" [16 16] | `ri:limits:bucketsize` | V2i | CustomOptions
| Option "user" "type variable" value | `ri:user`__name__ | _varies_ | CustomOptions
| Hider "raytrace" "int progressive" [0] | `ri:hider:progressive` | bool | CustomOptions
|=======================
.Example of custom 3delight attributes and options in Gaffer
image::images/autoGenerated_target/appendices_customAttributesOptions_figAA.png[align="center"]