Previous Topic (MagmaFlow Operator Nodes) Up (Particle Channels Editor Node Types) Next Topic (None)

MagmaFlow BlackOp Compound Nodes

 Available in Krakatoa v1.5.0 and higher

Overview

  • BlackOp Compound Nodes are custom flows of interconnected Input and Operator nodes (excluding the Output node which cannot be part of a BlackOp) which appear in the MagmaFlow Editor as a single node with an arbitrary number of input sockets and one output socket.
  • BlackOps can be used to
    • Implement useful functionality once and reuse it in many flows
    • Share complex functions with other users by sending a BlackOp file that can be inserted into any flow
    • Collapse a portion of an existing flow into a single node to reduce clutter.
  • It is possible to nest BlackOps at arbitrary depths. 
 Note: A BlackOp is a User Interface Level construct. When the KCM is processed, an expanded version of the flow
 is compiled which does not contain BlackOps but has them replaced with the nodes they encapsulate.
 This happens on the fly and transparently to the user. Keep in mind that the actual flow being executed
 might be much more complex in its expanded form than the top-level flow makes you think.

Creating a BlackOp From Existing Nodes

  • To create a BlackOp, select at least two nodes you want to be included in it, right-click over the selection and pick [BlackOp] From Selected Nodes.
    • All selected nodes must have valid connections. If an empty unconnected socket is found in one of the selected nodes, an error will be displayed at the bottom of the editor and no BlackOp will be created.
    • The node selection must have exactly one Output connection which will become the Output of the BlackOp. If there are two nodes in the connection that have Output connections to nodes outside of the selection, an error will be displayed and no BlackOp will be created.
    • All Input connections coming from other nodes that are not in the selection will be turned into Input Sockets of the BlackOp.
    • If no Input sockets of the selection are connected to nodes outside of the selection, the BlackOp will have no inputs.
    • If all nodes except in a flow are selected, the whole flow can be turned into a BlackOp. If the Output node was selected, it will be ignored and the BlackOp will be connected to it. This allows for the encapsulation of a complete flow into a BlackOp as an alternative to saving a MagmaFlow file.
    • If Auto-Reorder is off, the BlackOp will be created at the center of the selected nodes.
  • For example, let's take the simple Push Positions Along Normals example:

  • Let's select all nodes except the Output and the Float Input which is meant to control the Push Amount:

  • Right-click the selection and select [BlackOp] From Selection:

  • Note that the only socket of the BlackOp is called "Float" because that is the name of the Input node connected to it.
  • The BlackOp node itself does not have a name yet - we can rename it manually. In contrast, when creating a BlackOp from a file, the file name will be used as the node name.

Saving a BlackOp Directly To Disk

  • Instead of creating a BlackOp in the current flow, you can create it directly on Disk by picking the Save Selection As BlackOp.
    • A Save File Dialog will appear, asking for the folder and file name to save the BlackOp under.
    • The default folder for BlackOps is located in C:\Documents and Settings\YourUserName\Local Settings\Application Data\Prime Focus\Krakatoa\BlackOps\, but you can also create one-level-deep folders within this folder and save your BlackOps there - these will be displayed as new Categories in the Depot when the option Show BlackOp Categories In Depot is checked in the Depot Right-Click Menu.
    • The BlackOp will be stored with the file extension .KCB

Saving a BlackOp From Flow To Disk

  • You can also save an already created BlackOp from your flow to disk at any time.
    • Select the BlackOp and in the Command Panel in the BlackOp rollout, press the Save Definition To Disk... button.
    • The same dialog will appear as in the direct saving to disk operation.
    • You can use the Explore BlackOp Folders... button to open the Windows Explorer at the default location for BlackOp saving and reorder your files into Category folders, back them up, copy and send to colleagues etc.

Loading a BlackOp From Disk

  • Once you have BlackOps saved to your folders, you can insert them in your flows using one of the following methods:
    • Right-click the Editor's background and select [BlackOp] Compound Operator From File - a file open dialog will let you pick a previously saved BlackOp and it will appear as a new node in the Editor.
    • From the Depot, drag the BlackOp red node found under the Loaders Category into the Editor to open the same dialog.
    • If the Depot option Show BlackOp Categories In Depot is checked, drag the BlackOp you want from the Category it resides in.
      • The default folder will be shown as "BlackOps", the sub-folders of that path will display the names you gave them.
      • This is the fastest way to access BlackOps as it requires only DragAndDrop to create the correct node without using a file open dialog.
  • The name of the BlackOp node will be the name of the file it was loaded from.

Replacing a BlackOp's Content From Disk

  • You can replace the content of any BlackOp found in your flow with any BlackOp definition from disk.
  • The new definition could be an updated version of the original BlackOp flow, or a completely different flow altogether.
    • If the new definition has the same number of Input Sockets, the existing connections will be preserved, otherwise connections will either be lost of empty sockets will be created.

Editing a BlackOp Definition

  • The content of the BlackOp is a flow similar to the top-level flow you work with in the MagmaFlow Editor.
  • The BlackOp definition is stored as a sub-flow inside the BlackOp node and can be modified after the node's creation.
  • To Edit a BlackOp, right-click the node and select Edit BlackOp from the context menu.

  • The MagmaFlow Editor will display only the definition of the BlackOp as a special kind of flow where every Input socket is represented as a node on the left side of the editor and the Output socket is on the right side where the Output node usually is.
  • The title bar of the MagmaFlow Editor will show that you are editing a BlackOp and its name.
  • If the Depot is visible, a new Connector node will appear in the Inputs Category.
    • You can drag new Connector nodes to add more Input Sockets, or delete existing Connector nodes to reduce the number of Input Sockets.
    • You can also rename Connector nodes to change the names of the Input sockets shown by the BlackOp node.
  • You can add new Input and Operator nodes, remove existing ones and reconnect all sockets as needed, change parameters and so on as with any regular flow.

  • Once you are done editing, right-click the Editor's background and select Exit BlackOp Editing Mode
    • If any changes have been made (including even the moving or selecting of a single node), a Yes/No/Cancel dialog will appear asking you to confirm the changes, discard the changes or cancel the exit and continue editing.

  • It is important to understand that the BlackOp in your flow has NO CONNECTION to the Disk definition it might have come from.
    • Thus editing a BlackOp inside the flow does NOT affect any saved BlackOps (unless you resave the edited version) and will not affect any other flows using the same definition.
    • All changes will be stored in the local BlackOp node which is part of the current flow only.
    • This means that BlackOps can also be used as templates and then modified in place to fit the needs of the current flow.

Renaming and Reordering Sockets

  • The names of the Input Sockets of the BlackOp will be based on the names of the Nodes they were connected to when the BlackOp was created.
    • For example, if a node was connected to an Input called "Float", the resulting Input Socket will also be called "Float".
  • The order of the sockets in the BlackOp will depend on the order of creation of the nodes connected to the sockets.
  • You can use the BlackOp rollout in the MagmaFlow Command Panel to both rename and reorder the sockets.
    • To rename a socket, select it on the list and enter a new name in the text field below the list.
    • To move a socket up or down the list, use the Up and Dn buttons on the right side of the list.
    • Alternatively, you can use the Editing mode described below to edit the names of the sockets and even add or remove sockets.
  • The name of the BlackOp node will be the same as the name of the file it was loaded from (if any), or blank if created from nodes in the flow.
    • In either cases, you can edit the name of the node to reflect the BlackOp's functionality.

Exploding a BlackOp

  • You can explode a BlackOp into its parts by right-clicking it and selecting Explode BlackOp from the context menu.
  • The BlackOp will be replaced with the sub-flow it represented, preserving all existing connections and changes to its nodes.
  • The exploded nodes will be selected so you could move them together or even create a new BlackOp from them again.
  • The positions of the exploded nodes will be based on the original positions of the nodes during the BlackOp creation relative to the center of the BlackOp node they are replacing.