Matchbox in Action

While you can use interactive Matchbox shader effects elsewhere in Flame (such as from the timeline or Batch), using Matchbox in Action presents some unique benefits:

Keep in mind that the Matchbox XML schema contains tags to identify if the shader is designed as an Action node, a Timeline FX, or a Transition. The tags ShaderType and SoftwareVersion are added automatically to the XML by the shader_builder script.

The Action Priority Editor has a Matchbox Only mode to view and change the drawing order of Matchbox effects.

See the sections below for information on how to add, and things to watch for, when working with each type of Action Matchbox effect.

Matchbox Shaders Connected to Texture Nodes

To add a Matchbox node in Action connected to a Texture node:

  1. Do one of the following:
    • With a supported texture node selected in the schematic (Diffuse, Normal, UV, Displacement (HW Only), Parallax, IBL, Specular, Emissive, Lens Flare texture, or Substance texture), double-click the Matchbox node in the All Nodes bin.

      The file browser opens to allow you to select a Matchbox effect.

    • With an Action surface or 3D Geometry node selected in the schematic, double-click a Matchbox preset node from the dynamic Matchbox node bin.
      The Matchbox node with a parented Diffuse node (with its own parent axis) are added to the scene as children of the selected surface or geometry.
    Tip: If you add a Matchbox node to the schematic without a supported texture node present, you can parent the Matchbox to an image, and a Diffuse Map node (with accompanying Axis) is automatically added to create a proper Matchbox connection. Matchbox nodes are not supported on Stereo objects.

    Matchbox nodes and their links are displayed as black in the schematic to help you identify them. If you added the Matchbox from the dynamic node bin, the name of the effect also appears on the node in the schematic.

  2. Double-click the Matchbox node in the schematic to display its menu.

    The Matchbox node populates the user interface dynamically, based on the GLSL (and XML) code, but there are a few UI elements that are constant, located in the Shader tab.

  3. If you added a Matchbox effect from the All Nodes bin, you can change the effect by clicking Change Shader in the Shader tab of the Matchbox menu.
  4. Use the Action Object Solo (F8) view on the parent texture to cycle through three Matchbox views: Context, Result, and Result Matte. The F8 view also allows you to interact directly in the image window with icons, if they are present in the shader.
  5. Tip: Instead of using a source node for a simple front/matte transform, consider using the Front Matte Offset Matchbox (available as a preset, along with many other useful Matchbox effects).

Matchbox Shaders Connected to Cameras (Camera FX)

You can connect Matchbox shaders to the Action camera and have the result of the shader applied to the result of the Action scene. Similar to using Texture Matchbox shaders, the priority editor is used to handle the pipeline order.
Note: Post-processing (Camera FX, Lens Flares, and Rays) effects are only visible in the Live Preview view. Camera FX can have 2D and 3D widgets visible in the Live Preview view. Only the widget(s) of the currently selected Matchbox are shown. Lens Flares and Rays are rendered at the end of the Camera FX pipeline, when enabled in the Comp output.

GMasks can be connected to a Camera to limit their effect to the post-processing pipeline exclusively. GMask output passes have an option to only show GMasks connected to the current camera, so you can set GMask to not interact with the scene, and only be created to be used with the post-processing pipeline. You can also use a GMask input Matchbox shaders (if they have been implemented to use this input).

The Action post-processing pipeline can connect the Matchbox shader automatically to the appropriate Action output. To support this, shader developers need to set the InputType tag properly in the shader XML (each Action output has its equivalent InputType tag). This includes RGBA shader rendering. The following input types are supported:
  • Front (this defines the Primary Output render layer selection).
  • Back
  • Matte
  • 3D Motion Vectors
  • Albedo
  • Ambient Occlusion
  • Comp (this defines the Action Comp output of the render layer, in case the Primary is another type).
  • Emissive
  • GMask
  • Lens Flare
  • Motion Vectors
  • Normals
  • Occluder
  • Position
  • Reflection
  • Roughness
  • Shadows
  • Specularity
  • UV
  • Z-Depth
  • Z-Depth HQ (32-bit Z-Depth output packed in two 16-bit channels; you must use the Matchbox API to leverage the data).

Matchbox Camera FX also have access to the Acton output list in their patch panel (in the Shader tab on the Matchbox menu), so you can manually set the proper connection if the Matchbox shader hasn't been tagged properly in the XML.

To add a Matchbox node in Action connected to a Camera:

  1. Do one of the following:
    • With a Camera node selected in the schematic, double-click the Matchbox node in the All Nodes bin.

      The file browser opens to allow you to select a Matchbox effect. Some Matchbox shaders supplied with Flame are already optimized for use as Camera FX; navigate to the ACTION_CAMERA_FX sub-folder.

    • With a Camera node selected in the schematic, double-click a Matchbox preset node from the dynamic Matchbox node bin.
      The Matchbox node is added to the scene as a child of the selected camera. Once a Matchbox node is parented to a camera, it becomes a Camera FX, and you are not able to connect the Matchbox node to any other node in the schematic (other than other camera nodes).

    Matchbox nodes and their links are displayed as black in the schematic to help you identify them. If you added the Matchbox from the dynamic node bin, the name of the effect also appears on the node in the schematic.

    Note: Since a Matchbox connected to a Camera node (Camera FX) is considered a post-processing effect in Action, make sure that your image window is set to Live Preview mode to be able to see the results of the shader.
  2. Double-click the Matchbox node in the schematic to display its menu.

    The Matchbox node populates the user interface dynamically, based on the GLSL (and XML) code, but there are a few UI elements that are constant, located in the Shader tab.

  3. If you added a Matchbox effect from the All Nodes bin, you can change the effect by clicking Change Shader in the Shader tab of the Matchbox menu.

Rendering Camera FX

When rendering a Camera FX pipeline, Action uses Multi-Render Targets (MRT) to allow outputs to be much more efficient. Depending on the Rendering settings, the scene is rendered only once or twice instead of as many times as there are output passes, leading to a significant speed increase in the case of Camera FX requiring many input connections. The biggest speed improvement can be found when the Accumulation Rendering box is set to Accumulation On or Accumulation Off, since all passes can then be done using a single MRT. In the case of Accumulation RGBA, two MRTs are needed, which reduces the speed improvement compared to the other Accumulation settings, but still offers a significant boost compared to not using MRT at all.