Canvas Core API

The Canvas Core API is the lowest-level interface at which Canvas can be used. The API is designed for use by a visual programming interface, but can be driven directly by scripting.

The objects that are used by the Canvas Core API generally start with the the letters DFG for historical reasons. Occasionally Canvas may be referred to as “the DFG” in documentation.

The main classes that the Canvas Core API exposes are:

  • FabricCore::DFGHost: this object manages everything shared between different Canvas executables and bindings, such as the undo/redo stack and the preset tree, and is also the interface to use to create new bindings.
  • FabricCore::DFGBinding: this object is a binding of an executable to a set of arguments, and is the interface for actually computing things in Canvas. The executable that it binds may be a very complex graph with subgraphs, but fundamentally all computation happens at the level of bindings.
  • FabricCore::DFGExec: this object is a Canvas executable, which can be either a graph of nodes or a KL function.

Each of these objects has its API details laid out below.

Canvas Core API in Python

Note that the entire Canvas Core API is also available in Python through the FabricEngine.Core module. The calls are 1-1 with the CAPI calls. For examples of using the Python API to access the Canvas Core, please refer to the Canvas Core unit tests located under $FABRIC_DIR/Tests/Core/Canvas.

Canvas Core API Enums

enum FabricCore::DFGPortType

The type of a port in Canvas. One of:

  • DFGPortType_In
  • DFGPortType_IO
  • DFGPortType_Out

FabricCore::DFGExecType

The type of an executable in Canvas. One of:

  • DFGExecType_Graph
  • DFGExecType_Func

FabricCore::DFGNodeType

The type of a node in a Canvas graph. One of:

  • DFGNodeType_Inst - an instance of an executable
  • DFGNodeType_Get - a variable get node
  • DFGNodeType_Set - a variable set node
  • DFGNodeType_Var - a variable definition node
  • DFGNodeType_User - a user node

Canvas Core API Classes

class FabricCore::DFGExec : public FabricCore::Ref
DFGExec()
DFGExec(DFGExec const &that)
DFGExec &operator=(DFGExec const &that)
~DFGExec()
DFGExecType getType() const

Returns the type of the executable, either FabricCore::DFGExecType_Graph or FabricCore::DFGExecType_Func.

Returns:The type of the executable
DFGNodeType getNodeType(char const *nodePath) const

Returns the type of a node in a graph. See DFGNodeType for various node types.

Parameters:nodeName – The name of the node in the graph
Returns:The type of the node
DFGHost getHost() const

Returns the host to which the executable belongs.

Returns:FabricCore::DFGHost
String getExecPath() const

Returns the canonical rooted path of the executable.

DFGExec getSubExec(char const *execPath) const

Returns the sub-executable of an executable path. A sub-executable is referenced through a path of the form “node.subnode.subnode”, where each element of the path is a node in its containing graph.

Parameters:execPath – The path to the sub-executable
Returns:The sub-executable
String getErrors(bool recursive, bool connectedOnly) const

Returns the errors on the executable as a JSON array of strings.

String getErrors(bool recursive) const

Returns the errors on the executable as a JSON array of strings.

String getErrors(bool recursive, bool connectedOnly) const

Returns the errors on the executable as a JSON array of strings.

String getErrors(bool recursive) const

Returns the errors on the executable as a JSON array of strings.

String getLoadDiags() const

Returns the load diagnostics on the binding as a JSON array of objects.

String getExtDeps() const

Get the extension dependencies description for the executabe in JSON-encoded form.

Returns:The extension dependencies description for the executabe in JSON-encoded form
unsigned getExtDepCount() const

Get the numbed of extension dependencies for the executable. Extension dependency information can be accessed on an index-basis; see also FabricCore::DFGExec::getExtDepName() and FabricCore::DFGExec::getExtDepVersion().

Returns:The number of extension dependencies
char const *getExtDepName(unsigned index) const

Get the name of the extension dependency at the given index. Extension dependency information can be accessed on an index-basis; see also FabricCore::DFGExec::getExtDepCount() and FabricCore::DFGExec::getExtDepVersion().

Parameters:index – The index of the extension dependency
Returns:The name of the extension
String getExtDepVersion(unsigned index) const

Get the version specification of the extension dependency at the given index. Extension dependency information can be accessed on an index-basis; see also FabricCore::DFGExec::getExtDepCount() and FabricCore::DFGExec::getExtDepName().

Parameters:index – The index of the extension dependency
Returns:The version specification name of the extension
bool haveExecPort(char const *portName) const

Query whether the executable has a port with the given name.

Parameters:portName – The name to query
Returns:true if there is a port with the given name, false if not
unsigned getExecPortCount() const

Get the number of ports on the executable.

Returns:The number of ports on the executable
unsigned getExecFixedPortCount() const

Get the number of ExecFixedPorts on the executable.

Returns:The number of ExecFixedPorts on the executable
unsigned getNLSPortCount() const

Get the number of ports on the executable.

Returns:The number of ports on the executable
unsigned getExecBlockCount() const

Get the number of blocks on the executable.

Returns:The number of ports on the executable
char const *getExecBlockName(unsigned index) const

Get the name of the executable block at the given index.

Parameters:index – The index of the port
Returns:The name of the port
unsigned getNodeCount() const

Get the number of nodes in a graph. Will throw an exception if the executable is not a graph.

Returns:The number of nodes in the graph
char const *getNodeName(unsigned index) const

Get the name of the node at the given index. Will throw an exception if the executable is not a graph.

Parameters:index – The index of the node
Returns:The number of nodes in the graph
DFGNodeType getNodeType(unsigned index) const

Get the type of the node at the given index. Will throw an exception if the executable is not a graph. See DFGNodeType for the various node types.

Parameters:index – The index of the node
Returns:The type of the node
DFGExec getInstExec(unsigned index) const

Gets a handle to the executable that the instance node at the given index is an instance of. Will throw an exception if the executable is not a graph or the node is not an instance.

Parameters:index – The index of the instance node
Returns:The executable that the instance node is an instance of
String getDesc()

Gets a description of the executable. The description is in JSON form, and can be useful for debugging. Note, however, that it should not be used for persistence; instance, use FabricCore::DFGExec::exportJSON().

Returns:A description of the executable in JSON form
String isExecPort(char const *path)

Returns true if the give path refers to an ExecPort

String getExecPortDesc(char const *execPortName)

Gets a description of a port of the executable. The description is in JSON form, and can be useful for debugging.

Parameters:execPortName – The name of the port of the executable
Returns:A description of the port in JSON form
String getNodeDesc(char const *nodeName)

Gets a description of a node of the executable. The description is in JSON form, and can be useful for debugging.

Parameters:nodeName – The name of the node of the graph
Returns:A description of the node in JSON form
String getNodePortDesc(char const *nodePortPath)

Gets a description of a port of a node of the executable. The path should be of the form “nodeName.portName”. The description is in JSON form, and can be useful for debugging.

Parameters:nodeName – The path to a port of a node in the graph
Returns:A description of the port in JSON form
bool isExecPortResolvedType(unsigned index, char const *typeName)

Determine whether the resolved type of a port of the executable is the given type (or an alias of that type).

Parameters:
  • index – The index of the port of the executable
  • typeName – The name of the type
Returns:

Whether the resolved type of the port is the given type

char const *getExecPortResolvedType(unsigned index)

Get the resolved type of a port of the executable at a given index.

Note

This will return the type alias for the resolved type, so it shouldn’t generally be used for type checking; for example, this function could return Integer or SInt32, depending on how the graph was created.

Parameters:index – The index of the port of the executable
Returns:The resolved type of the port
char const *getPortResolvedType(char const *path)

Get the resolved type of the port in the executable with a given path.

Note

This will return the type alias for the resolved type, so it shouldn’t generally be used for type checking; for example, this function could return Integer or SInt32, depending on how the graph was created.

Parameters:path – The path to a port in the executable
Returns:The resolved type of the port
char const *getExecPortResolvedType(char const *path)

An alias for getPortResolvedType for backwards compatibility.

char const *getNodePortResolvedType(char const *path)

An alias for getPortResolvedType for backwards compatibility.

String exportJSON()

Create a JSON representation of the executable that can later be used by FabricCore::DFGExec::addInstFromJSON() to create a new executable that is the same.

Returns:The JSON representation of the graph
char const *addInstFromPreset(char const *presetFilePath, char const *desiredName = 0)

Create a new instance node in the graph that is an instance of the preset with the given preset path. Will throw an exception if the preset is not found or if the executable is not a graph. The name of the new node will be derived from the name of the preset, but made unique within the graph.

Parameters:presetFilePath – The path to the preset in the preset tree
Returns:The name of that node that was created
char const *addInstWithNewGraph(char const *title = 0)

Create a new instance node in the graph that is an instance of a new (empty) graph. Optionally, specify the title of the new graph; if present, the name of the new node is derived from the title of the graph.

Parameters:title – (optional) The title of the graph that will be created
Returns:The name of that node that was created
char const *addInstWithNewFunc(char const *title = 0)

Create a new instance node in the graph that is an instance of a new (empty) function. Optionally, specify the title of the new function; if present, the name of the new node is derived from the title of the function.

Parameters:title – (optional) The title of the function that will be created
Returns:The name of that node that was created
char const *addInstFromJSON(char const *json)

Create a new instance node in the graph that is an instance of a new executable described by JSON obtained from FabricCore::DFGExec::exportJSON(). The name of the node will be derived from the title of the executable.

Parameters:json – The JSON description of the executable
Returns:The name of that node that was created
char const *addVar(char const *desiredName, char const *dataType, char const *extDep = 0)

Create a new variable declaration node in the graph with a given type and, optionally, an extension dependency for the type. The actual name of the node will be derived from the desiredName parameter.

Parameters:
  • desiredName – The desired name of the new variable within the graph
  • dataType – The KL data type of the variable
  • extDep – (optional) An extension dependency for the type of the form {ExtensionName}:{VersionSpec}.
Returns:

The actual name of the variable declaration node that was created

char const *addGet(char const *desiredName, char const *varPath)

Create a new get variable node in the graph.

Parameters:
  • desiredName – The desired name of the get variable node within the graph
  • varPath – The path to the variable. Variable paths follow “namespacing” rules whereby the are looked up starting from the current graph and continue searching in parent graphs until a match is found.
Returns:

The actual name of the get variable node that was created

char const *addSet(char const *desiredName, char const *varPath)

Create a new set variable node in the graph.

Parameters:
  • desiredName – The desired name of the get variable node within the graph
  • varPath – The path to the variable. Variable paths follow “namespacing” rules whereby the are looked up starting from the current graph and continue searching in parent graphs until a match is found.
Returns:

The actual name of the set variable node that was created

bool hasVar(char const *name)

Returns true if a variable with a given name exists.

Parameters:name – The name of the variable within the graph
Returns:True if the variable exists
char const *getVarType(char const *name)

Get the current KL type name of a variable within the graph.

Parameters:name – The name of the variable within the graph
Returns:The current KL type name of the variable
RTVal getVarValue(char const *name)

Get the current value of a variable within the graph.

Parameters:name – The name of the get variable within the graph
Returns:The current value of the variable as an RTVal, or a null RTVal if there is no current value
void setVarValue(char const *name, RTVal value)

Set the current value of a variable within the graph.

Parameters:
  • name – The name of the get variable within the graph
  • value – The new value of the variable
char const *getRefVarPath(char const *name)

Get the variable path associated with the given variable reference (get or set) node.

Parameters:name – The name of the variable reference node
Returns:The current variable path of the node
void setRefVarPath(char const *name, char const *varPath)

Set the variable path associated with the given variable reference (get or set) node.

Parameters:
  • name – The name of the variable reference node
  • varPath – The new variable path to set
char const *addUser(char const *desiredName)

Create a new user node in the graph.

Parameters:desiredName – The desired name of the user node within the graph
Returns:The actual name of the user node that was created
void addExtDep(char const *extName, char const *versionRange = "")

Add an extension dependency to the executable.

Parameters:
  • extName – The name of the extension
  • versionRange – (optional) The version range of the extension
void setExtDeps(uint32_t nameAndVerCount, char const **nameAndVers)

Replace the current extension dependencies of the executable with a new set.

Parameters:
  • nameAndVerCount – The number of new extension dependencies
  • nameAndVers – The new extension dependencies. Each is a string of the form {ExtensionName}:{VersionRange}
void removeExtDep(char const *extName)

Remove the extension dependency for the extension with the given name

Parameters:extName – The name of the extension
char const *addExecPort(char const *desiredName, FEC_DFGPortType portType, char const *typeSpec = 0)

Add a new port to the executable.

Parameters:
  • desiredName – The desired name for the new port
  • portType – The type of the port, one of DFGPortType
  • typeSpec – The type specification of the port (eg. Float32 or $TYPE$). Note that type specifications only work with functions, and not with graphs.
Returns:

The actual name of the new port

char const *addNLSPort(char const *desiredName, char const *typeSpec)

Add a new NLS to the executable.

Parameters:
  • desiredName – The desired name for the new NLS
  • typeSpec – The typeSpec for the new NLS
Returns:

The actual name of the new NLS

char const *addExecBlock(char const *desiredName)

Add a new block to the executable.

Parameters:desiredName – The desired name for the new block
Returns:The actual name of the new block
bool isInstExec()

Returns whether the exec is the implementation of an inst.

unsigned getInstBlockCount(char const *instName)

Returns the number of InstBlocks below an Inst.

bool isInstBlock(char const *path)

Returns whether the item is an inst block.

bool isInstBlock(char const *instName, char const *childName)

Returns whether the the child below the Inst is an InstBlock (as opposed to a port).

bool isInstBlockExec()

Returns whether the exec is the implementation of an inst block.

bool isExecBlock(char const *name)

Returns whether the given name in an exec is an exec block.

char const *addExecBlockPort(char const *blockName, char const *desiredPortName, FEC_DFGPortType portType, char const *typeSpec = 0)

Add a new port to the executable block.

Parameters:
  • blockName – The name of the executable block
  • desiredPortName – The desired name for the new port
  • portType – The type of the port, one of DFGPortType
  • typeSpec – The type specification of the port (eg. Float32 or $TYPE$). Note that type specifications only work with functions, and not with graphs.
Returns:

The actual name of the new port

DFGExec getInstBlockExec(char const *instName, char const *blockName) const

Returns the sub-executable associated with an instance block.

Parameters:
  • instName – The name of the instance
  • blockName – The name of the block within the instance
Returns:

The sub-executable

unsigned getInstBlockPortCount(char const *instName, char const *blockName) const

Returns the number of ports on an inst block.

Parameters:
  • instName – The name of the instance
  • blockName – The name of the block within the instance
char const *getInstBlockPortName(char const *instName, char const *blockName, unsigned portIndex) const

Returns the name of the give inst block port.

Parameters:
  • instName – The name of the instance
  • blockName – The name of the block within the instance
  • portIndex – The index of the port withing the inst block
void reorderPorts(char const *itemPath, unsigned newIndCount, unsigned const *newInds)

Reorder the ports of the item (Exec or ExecBlock). Takes an array of integers for which the element at index oldIndex is the newIndex for the existing port.

Parameters:
  • itemPath – The path to the item.
  • newIndCount – The number of elements in the index map. Must be equal to the number of ports.
  • newInds – The elements of the index map.
void reorderExecPorts(unsigned newIndCount, unsigned const *newInds)

Reorder the ExecPorts of the Exec. Takes an array of integers for which the element at index oldIndex is the newIndex for the existing port.

Parameters:
  • newIndCount – The number of elements in the index map. Must be equal to the number of ports.
  • newInds – The elements of the index map.
void reorderNLSPorts(char const *itemPath, unsigned newIndCount, unsigned const *newInds)

Reorder the NLS ports of the Exec. Takes an array of integers for which the element at index oldIndex is the newIndex for the existing port.

Parameters:
  • newIndCount – The number of elements in the index map. Must be equal to the number of ports.
  • newInds – The elements of the index map.
bool isConnectedTo(char const *srcPortPath, char const *dstPortPath) const

Query whether the source port is connected to the destination port. The ports can be either node ports, in which case the path is of the form “nodeName.portName”, or executable ports, in which case the path is of the form “portName”.

Parameters:
  • srcPortPath – The source port to check for connection
  • dstPortPath – The destination port to check for connection
bool hasSrcPorts(char const *portPath) const

Query whether a given port has a connection from another port.

Parameters:portPath – The port to check
bool hasDstPorts(char const *portPath) const

Query whether a given port has one or more connections to other ports.

Parameters:portPath – The port to check
String canConnectTo(char const *srcPortPath, char const *dstPortPath, char const *separator) const

Query whether a given port can connect to another port. If connection is possible, it will return the empty string; otherwise, it will return a list of errors that would occur if the connection were made, with the errors separated by the specified separator string.

Parameters:
  • srcPortPath – The source port for which to check connection
  • dstPortPath – The destination port for which to check connection
  • separator – The separator string for the errors
void connectTo(char const *srcPortPath, char const *dstPortPath)

Connect two ports in a graph.

Parameters:
  • srcPortPath – The source port to connect
  • dstPortPath – The destination port to connect
void disconnectFrom(char const *srcPortPath, char const *dstPortPath)

Disconnect two ports in a graph.

Parameters:
  • srcPortPath – The source port to disconnect
  • dstPortPath – The destination port to disconnect
void disconnectFromAll(char const *portPath)

Disconnect any existing connections to the given port.

Parameters:portPath – The port to disconnect
char const *attachPresetFile(char const *parentPresetDirPath, char const *desiredName, bool replaceExisting)

Attach the executable to a location in the preset tree, making it an available preset.

Parameters:
  • parentPresetDirPath – The path of the directory in the preset tree in which to attach the preset
  • desiredName – The desired name of the preset within the preset directory
  • replaceExisting – If true and the desired name is used by an existing preset, replace the existing preset with this one; otherwise, a unique new name will be generated.
Returns:

The actual name of the preset within the preset directory

char const *renamePort(char const *portPath, char const *desiredNewPortName)

Rename a port of the executable.

Parameters:
  • portPath – The current path to the port (exec, node, exec block or instance block)
  • desiredNewPortName – The desired new name of the port
Returns:

The actual new name of the port

char const *renameExecPort(char const *oldName, char const *desiredNewName)

An alias for renamePort.

char const *renameItem(char const *oldName, char const *desiredNewName)

Rename an item of the executable.

Parameters:
  • oldName – The old name of the node
  • desiredNewName – The desired new name of the node
Returns:

The actual new name of the node

char const *renameNode(char const *oldName, char const *desiredNewName)

An alias for renameItem

char const *getTitle()

Get the title of the executable.

Returns:The title of the executable
void setTitle(char const *title)

Set the title of the executable.

Parameters:title – The new title of the executable
void setVersion(char const *version)

Set the version of the executable; used when referencing presets with version requirements

Parameters:version – The new version of the executable in the form “X.Y.Z”
char const *getInstTitle(unsigned index)

Get the title of the instance node at the given node index.

Parameters:index – The index of the instance node
Returns:The title of the instance node
char const *getInstTitle(char const *nodeName)

Get the title of the instance node with the given name.

Parameters:nodeName – The name of the instance node
Returns:The title of the instance node
void setInstTitle(unsigned index, char const *title)

Set the title of the instance node at the given index. If the title that is passed is empty, the instance will adopt the title of the executable it is an instance of.

Parameters:
  • index – The index of the instance node
  • title – The new title of the instance node
void setInstTitle(unsigned index, char const *title)

Set the title of the instance node with the given name. If the title that is passed is empty, the instance will adopt the title of the executable it is an instance of.

Parameters:
  • nodeName – The name of the instance node
  • title – The new title of the instance node
DFGPortType getPortType(char const *path)

Get the port type of a port in the executable.

The port type is the type of the port for connection within the graph. This is the inverse of the executable port type for an executable port; for example, if you have an ‘In’ executable port on a graph, this has a node port type of ‘Out’ because it acts like an ‘Out’ port within the graph, ie. it connects to other ‘In’ and ‘IO’ ports.

Parameters:path – The port path
Returns:The node port type of the port
DFGPortType getNodePortType(char const *path)

An alias of getPortType for backwards compatibility.

DFGPortType getOutsidePortType(char const *portPath)

Returns the outside port type for an ExecPort, ExecBlockPort or ExecFixedPort. This is the inverse of the port type; see comments in getPortType.

Parameters:portPath – The path to the port.
Returns:The outside port type of the port.
DFGPortType getExecPortType(char const *name)

An alias for getOutsidePortType().

DFGPortType getExecPortType(unsigned index)

Get the executable port type of the port of the executable at the given index. This is the inverse of the port type; see comments in getPortType.

Parameters:index – The index of the executable port
Returns:The executable port type of the port
DFGPortType getExecFixedPortType(unsigned index)

Get the executable port type of the ExecFixedPort of the executable at the given index. This is the inverse of the port type; see comments in getPortType.

Parameters:index – The index of the ExecFixedPort
Returns:The executable port type of the port
void setOutsidePortType(char const *portPath, DFGPortType portType)

Set the outside port type of an ExecPort or ExecBlockPort.

Parameters:
  • portPath – The path to the ExecPort or ExecBlockPort.
  • portType – The new outside port type for the port.
void setExecPortType(char const *portName, DFGPortType portType)

An alias for setOutsidePortType(portName, portType).

char const *getCode()

Get the KL code of the function executable. If the executable is not a function executable an exception will be thrown.

Returns:The KL code of the function executable
void setCode(char const *code)

Set the KL code of the function executable. If the executable is not a function executable an exception will be thrown.

Parameters:code – The new KL code of the function executable
char const *getMetadata(char const *key) const

Gets the metadata for the executable for the given key.

Parameters:key – The key for the metadata
Returns:The metadata for that key, or the empty string if there is no metadata for that key
char const *getPortMetadata(char const *portPath, char const *key)

Gets the metadata for a port for the given key.

Parameters:
  • portPath – The portPath to the port
  • key – The key for the metadata
Returns:

The metadata for that key, or the empty string if there is no metadata for that key

char const *getExecPortMetadata(char const *path, char const *key)

An alias for getPortMetadata for backwards compatibility.

char const *getPortModelMetadata(char const *portPath, char const *key)

For a port that is an instance of another port, get the metadata associated with that other port.

Parameters:
  • portPath – The portPath to the port
  • key – The key for the metadata
Returns:

The metadata for that key, or the empty string if there is no metadata for that key

char const *getItemMetadata(char const *itemName, char const *key)

Gets the metadata for an item (node, exec block, exec port) for the given key.

Parameters:
  • itemName – The name of the node
  • key – The key for the metadata
Returns:

The metadata for that key, or the empty string if there is no metadata for that key

char const *getNodeMetadata(char const *nodeName, char const *key)

An alias for getItemMetadata.

char const *getNodePortMetadata(char const *path, char const *key)

An alias for getPortMetadata for backwards compatibility.

void setMetadata(char const *key, char const *value, bool canUndo = true, bool shouldSplitFromPreset = true)

Sets the metadata on the executable for the given key.

Parameters:
  • key – The key for the metadata
  • value – The value for the metadata
  • canUndo – Whether the action should be undoable
  • shouldSplitFromPreset – Whether the metadata change should split from the preset, if the executable is an instance of a preset
void setExecBlockPortMetadata(char const *blockName, char const *portName, char const *key, char const *value, bool canUndo = true, bool shouldSplitFromPreset = true)

Sets the metadata for an executable port for the given key.

Parameters:
  • blockName – The name of the block
  • portName – The name of the block port
  • key – The key for the metadata
  • value – The value for the metadata
  • canUndo – Whether the action should be undoable
  • shouldSplitFromPreset – Whether the metadata change should split from the preset, if the executable is an instance of a preset
void setExecPortMetadata(unsigned index, char const *key, char const *value, bool canUndo = true, bool shouldSplitFromPreset = true)

Sets the metadata for an executable port for the given key.

Parameters:
  • index – The index of the executable port
  • key – The key for the metadata
  • value – The value for the metadata
  • canUndo – Whether the action should be undoable
  • shouldSplitFromPreset – Whether the metadata change should split from the preset, if the executable is an instance of a preset
void setItemMetadata(char const *name, char const *key, char const *value, bool canUndo = true, bool shouldSplitFromPreset = true)

Sets the metadata for an item (port, node or block, as appropriate) for the given key.

Parameters:
  • name – The name of the node
  • key – The key for the metadata
  • value – The value for the metadata
  • canUndo – Whether the action should be undoable
  • shouldSplitFromPreset – Whether the metadata change should split from the preset, if the executable is an instance of a preset
void setNodeMetadata(char const *nodeName, char const *key, char const *value, bool canUndo = true, bool shouldSplitFromPreset = true)

An alias for setItemMetadata.

void setPortMetadata(char const *portPath, char const *key, char const *value, bool canUndo = true, bool shouldSplitFromPreset = true)

Sets the metadata for a port (exec, node, exec block or inst block) for the given key.

Parameters:
  • portPath – The path to the port
  • key – The key for the metadata
  • value – The value for the metadata
  • canUndo – Whether the action should be undoable
  • shouldSplitFromPreset – Whether the metadata change should split from the preset, if the executable is an instance of a preset
void setExecPortMetadata(char const *portPath, char const *key, char const *value, bool canUndo = true, bool shouldSplitFromPreset = true)

An alias for setPortMetadata.

void setNodePortMetadata(char const *nodePortPath, char const *key, char const *value, bool canUndo = true, bool shouldSplitFromPreset = true)

An alias for setPortMetadata.

bool isDepsPort(char const *portPath)

Returns true iff the port is a deps (built in exec) port.

Parameters:portPath – The path the port (node, exec, exec block or inst block)
bool isDepsExecPort(unsigned portIndex)

Returns true iff the exec port is a deps (built in exec) port.

bool isDepsExecBlockPort(char const *blockName, unsigned portIndex)

Returns true iff the exec block port is a deps (built in exec) port.

RTVal getPortDefaultValue(char const *portPath, char const *typeName)

Gets the current default value for a port for a given type. The default value is the value the port has when it is disconnected but resolved to that type. The path can be either to a node port (of the form “nodeName.portName”) or just the name of an executable port.

Parameters:
  • portPath – The path the node port or executable port
  • typeName – The name of type for which to return the current default value
Returns:

The current default value for the port for the given type

RTVal getPortResolvedDefaultValue(char const *path, char const *typeName)

Gets the current resolved default value for a port for a given type. The default value is the value the port has when it is disconnected but resolved to that type. The resolved default value differs from the default value in that it will fall back on the executable port that backs an instance port if there is no default value for the resolved type on the instance port.

Parameters:
  • path – The path to the port
  • typeName – The name of type for which to return the current default value
Returns:

The current default value for the port for the given type

RTVal getInstPortResolvedDefaultValue(char const *path, char const *typeName)

An alias for getPortResolvedDefaultValue for backwards compatibility.

void setPortDefaultValue(char const *portPath, RTVal defaultValue, bool canUndo = true)

Sets the current default value for a port. The default value for a given type is the value the port has when it is disconnected but resolved to that type. In this case, the type is the type of the RTVal. The path can be either to a node port (of the form “nodeName.portName”) or just the name of an executable port.

Parameters:
  • portPath – The path the node port or executable port
  • defaultValue – The new default value for the port for the type of the default value
  • canUndo – Whether the action should be undoable
char const *getImportPathname()

Gets the current import pathname for an executable. The import pathname is automatically set for executables when they are loaded as presets; it is the path on disk from which the preset was loaded.

Returns:The import pathname for the executable
void setImportPathname(char const *importPathname)

Sets a new import pathname for an executable.

Parameters:importPathame – The new import pathname for the executable
DFGBinding bind(uint32_t rtValCount = 0, RTVal const *rtVals = 0)

Create a new binding that is bound to this executable as its root executable, optionally providing RTVals to use as the binding’s arguments.

Parameters:
  • rtValCount – (optional) The number of RTVal arguments for the binding
  • rtValCount – (optional) The RTVal arguments for the binding
void removePort(char const *portPath)

Remove the ExecPort or ExecBlockPort with the given path.

void removeExecPort(char const *portName)

An alias for removePort().

Parameters:portName – The name of the port
void removeExecPort(unsigned index)

Remove the executable port at the given index

Parameters:index – The index of the port
void removeNode(char const *nodeName)

Remove the node with the given name

Parameters:nodeName – The name of the node
void removeElement(char const *name)

Remove the element (port, node or block) with the given name

Parameters:name – The name of the node
DFGView createView(DFGNotificationCallback callback, void *userdata)

Create a view object that receives notifications of things that happen within the executable.

Note

Views are not recursive; you will received notifications about the executable itself, its ports, its nodes and its node ports, but not about subexecutables or their components.

Parameters:
  • callback – The callback function to be invoked when a notification is sent
  • userdata – The userdata to pass to the callback function
char const *getItemPortTypeSpec(char const *itemPath, unsigned portIndex)

Get the current typeSpec for an item port.

char const *getExecPortTypeSpec(unsigned execPortIndex)

Get the current typeSpec for the executable port with the given index.

Parameters:execPortIndex – The index of the executable port
Returns:The current typeSpec for the port
char const *getPortTypeSpec(char const *portPath)

Get the current typeSpec for the ExecPort or ExecBlockPort with the given path.

char const *getExecPortTypeSpec(char const *execPortName)

An alias for getPortTypeSpec().

void setExecPortTypeSpec(unsigned execPortIndex, char const *typeSpec)

Set the current typeSpec for the executable port with the given index.

Parameters:
  • execPortIndex – The index of the executable port
  • typeSpec – The new typeSpec to set
char const *getNLSPortTypeSpec(unsigned execPortIndex)

Get the current typeSpec for the executable port with the given index.

Parameters:execPortIndex – The index of the executable port
Returns:The current typeSpec for the port
void setPortTypeSpec(char const *portPath, char const *typeSpec)

Set the current typeSpec for the ExecPort or ExecBlockPort with the given path.

void setExecPortTypeSpec(char const *execPortName, char const *typeSpec)

An alias for setPortTypeSpec().

char const *getExecPortName(unsigned execPortIndex)

Get the name of the executable port at the given index.

Parameters:execPortIndex – The index of the executable port
char const *getExecPortName(char const *execPortPathCStr)

Get the name of the executable port given the port path

Parameters:execPortPathCStr – The port path
char const *getNLSPortName(unsigned execPortIndex)

Get the name of the executable port at the given index.

Parameters:execPortIndex – The index of the executable port
char const *getExecFixedPortName(unsigned execPortIndex)

Get the name of the ExecFixedPort at the given index.

Parameters:execPortIndex – The index of the ExecFixedPort
unsigned getItemPortCount(char const *itemName)

Get the number of ports on the given item (node or exec block).

Parameters:itemName – The name of the node
unsigned getNodePortCount(char const *nodeName)

An alias for getItemPortCount.

char const *getNodePortName(unsigned nodeIndex, unsigned nodePortIndex)

Get the name of the node port for the given node and node port indices

Parameters:
  • nodeIndex – The index of the node
  • nodePortIndex – The index of the node port
char const *getInstBlockName(char const *instName, unsigned instBlockIndex)

Get the name of an inst block.

Parameters:
  • instName – The name of the item
  • instBlockIndex – The index of the item block
char const *getItemPortName(char const *itemName, unsigned itemPortIndex)

Get the name of an item (node or exec block) port.

Parameters:
  • itemName – The name of the item
  • itemPortIndex – The index of the item port
char const *getNodePortName(char const *nodeName, unsigned nodePortIndex)

An alias for getItemPortName.

String exportItemsJSON(uint32_t itemCount, char const *const *itemNames)

Export a collection of items (nodes, blocks or ports) as JSON that can later be used by FabricCore::DFGExec::importItemsJSON() to recreate the items elsewhere.

Parameters:
  • itemCount – The number of items to export
  • itemNames – The names of the items to export
Returns:

The items encoded as JSON

String exportNodesJSON(uint32_t nodeCount, char const *const *nodeNames)

An alias for FabricCore::DFGExec::exportItemsJSON().

String importItemsJSON(char const *itemsJSON)

Import a collection of nodes from JSON that were exported using FabricCore::DFGExec::exportItemsJSON().

Parameters:itemsJSON – The nodes, encoded as JSON
Returns:The names of the newly created nodes as a JSON array of strings
String importNodesJSON(char const *nodesJSON)

An alias for FabricCore::DFGExec::importItemsJSON().

char const *implodeNodes(char const *desiredName, uint32_t nodeCount, char const *const *nodeNames)

Implode a collection of nodes down to a single node.

Note

Imploding a collection of nodes will also include any nodes that are “between” nodes in the collection with respect to connections.

Parameters:
  • desiredName – The desired name of the resulting node
  • nodeCount – The number of nodes to implode
  • nodeNames – The names of the nodes to implode
Returns:

The actual name of the resulting node.

String explodeNode(char const *nodeName)

Explode a single node that is an instance of a graph into individual nodes within the executable.

Parameters:nodeName – The name of the node to explode
Returns:The names of the resulting nodes, encoded as a JSON array of strings
char const *getPresetName() const

Get the name component of the preset path of the executable if it is an instance of a preset; otherwise, returns the empty string.

String getPresetPath() const

Get the preset path of the executable if it is an instance of a preset; otherwise, returns the empty string.

String getPresetGUID() const

Get the preset GUID of the executable if it is an instance of a preset, otherwise returns the empty string.

void setPresetGUID(char const *presetGUID) const

Set the preset GUID of the executable. The preset GUID must be a exactly 32 hex digits.

Warning

This function does not split the executable from the preset; it will change the preset GUID for all instance of the preset.

String getOrigPresetGUID() const

Get the original preset GUID of the executable if it was an instance of a preset, but is no longer a preset; otherwise, returns the empty string.

bool isPreset() const

Queries whether the executable is a preset

bool instExecIsPreset(char const *instName) const

Queries whether the executable is a preset

bool editWouldSplitFromPreset() const

Queries whether editing the executable would cause it or one of its containing graphs would cause a preset split.

unsigned getExecPortIndex() const

Get the exec port index for the named exec port.

void maybeSplitFromPreset()

Split the executable from the preset it is an instance of if it is an instance of a preset; otherwise, has no effect.

void addPriorPortName(char const *oldName, char const *newName) const

Add a prior port name for a port, so that persisted versions of executable will be able to resolve the old port name.

bool allowsBlocks() const

Returns whether the executable allows blocks to be created within it

void promoteInstBlockExecsToDefault(char const *instPath)

Makes the current implementation of the inst blocks the defaults for their associated exec blocks.

class FabricCore::DFGBinding : public FabricCore::Ref
DFGBinding()
DFGBinding(DFGBinding const &that)
DFGBinding &operator=(DFGBinding const &that)
~DFGBinding()
DFGBinding getBindingID()

Get the binding ID for the binding. This can be used by FabricCore::DFGHost::getBindingForID() to obtain a handle to a given binding in situations where it is not possible to pass the binding as a DFGBinding object.

Returns:The binding ID for the DFGBinding
DFGHost getHost() const

Get the DFGHost that owns the DFGBinding.

Returns:The DFGHost that owns the DFGBinding.
DFGExec getExec() const

Get the root DFGExec for the DFGBinding.

Returns:The root DFGExec for the DFGBinding
RTVal getArgValue(unsigned index)

Get the RTVal value for the binding argument at the given index. Throws an exception if the index is not less than the result of FabricCore::DFGExec::getExecPortCount on the root executable of the binding.

Parameters:index – The index of the port for which to get the argument.
Returns:The value of the argument as an RTVal.
RTVal getArgValue(char const *name)

Get the RTVal value for the binding argument with the given name. Throws an exception if there is no port with the given name.

Parameters:name – The name of the port for which to get the argument.
Returns:The value of the argument as an RTVal.
void setArgValue(LockType lockType, unsigned index, RTVal value, bool canUndo = true)

Set the RTVal value for the binding argument at the given index. Throws an exception if there is no port with the given name.

The KL type of the RTVal can be the same as or different from the current value for the argument.

Parameters:
  • lockType – What type of locking do to. Note that this also affects the messages you will see.
  • index – The index of the port for which to set the argument
  • value – The new value of the argument
  • canUndo – Whether the change to the argument should be an undoable action.
void setArgValue(unsigned index, RTVal value, bool canUndo = true)

Alias for FabricCore::DFGBindign::setArgValue(FabricCore::LockType_Exclusive, index, value, canUndo)

void setArgValue(LockType lockType, char const *name, RTVal value, bool canUndo = true)

Set the RTVal value for the binding argument with the given name. Throws an exception if there is no port with the given name.

The KL type of the RTVal can be the same as or different from the current value for the argument.

Parameters:
  • lockType – What type of locking do to. Note that this also affects the messags you will see.
  • name – The name of the port for which to set the argument.
  • value – The new value of the argument
  • canUndo – Whether the change to the argument should be an undoable action.
void setArgValue(char const *name, RTVal value, bool canUndo = true)

Alias for FabricCore::DFGBindign::setArgValue(FabricCore::LockType_Exclusive, name, value, canUndo)

bool hasRecursiveConnectedErrors() const
String getErrors(bool recursive) const

Returns the errors on the binding as a JSON array of objects.

String getLoadDiags() const

Returns the load diagnostics on the binding as a JSON array of objects.

void dismissLoadDiag(unsigned diagIndex) const

Dismisses the given load diagnostic.

void setDirty()

Force the binding into the dirty state. A dirty notification for this binding will be emitted.

void suspendDirtyNotifs()

Suspends dirty notifications until resumeDirtyNotifs() is called

void resumeDirtyNotifs()

Suspends dirty notifications after suspectDirtyNotifs() has been called

void execute_lockType(LockType lockType)

Execute the binding, ie. execute the KL function that is generated from the root executable (graph or function), passing the argument values as the port values.

Throws an exception if the graph cannot be executed for some reason, for instance there is a node in error that is (transitively) connected to one of the output ports.

Parameters:lockType – The type of lock to hold during execution
void execute()

Alias for FabricCore::DFGBinding::execute_lockType(FabricCore::LockType_Exclusive)

void registerNotificationCallback(DFGNotificationCallback callback, void *userdata)

Register a notification callback function and userdata to pass it. The function must have the function signature:

void BindingNotificationCallback(
  void *userdata,
  char const *jsonCString,
  uint32_t jsonLength
  );

It will receive the value of userdata that was passed to registerNotificationCallback, and jsonCString and jsonLength will be a JSON-encoded string with the contents of the notification.

The callback must be removed with FabricCore::DFGBinding::unregisterNotificationCallback() if it is no longer intersted in notifications.

Parameters:
  • callback – The callback function to call for notifications
  • userdata – The userdata value to pass to the callback function
void setNotificationCallback(DFGNotificationCallback callback, void *userdata)

Set a notification callback function and userdata to pass it. The function must have the function signature:

void BindingNotificationCallback(
  void *userdata,
  char const *jsonCString,
  uint32_t jsonLength
  );

It will receive the value of userdata that was passed to registerNotificationCallback, and jsonCString and jsonLength will be a JSON-encoded string with the contents of the notification.

This function will throw an error if a callback has already been registered, unless callback is NULL in which case it will remove the existing callback.

Parameters:
  • callback – The callback function to call for notifications, or NULL to clear the current callback
  • userdata – The userdata value to pass to the callback function
void unregisterNotificationCallback(DFGNotificationCallback callback, void *userdata)

Unregister a notification callback function and userdata that was previously added with FabricCore::DFGBinding::registerNotificationCallback(). Both the callback and userdata must match what was passed to this function.

Parameters:
  • callback – The callback function to call for notifications
  • userdata – The userdata value to pass to the callback function
String exportJSON()

Export the binding as a JSON-encoded string. This string can be used by FabricCore::DFGHost::createBindingFromJSON() to create a binding with the same contents.

The contents of the binding are recusrsively encoded. Presets are reference through their preset path and/or GUID, while locally-defined graphs and functions are encoded inline. The values of the binding argument and the default values of ports are also encoded, provided that the RTVal codecs provided to the Core are able to encode them; see the Core client constructors for details.

Returns:The binding encoded as a JSON string
void deallocValues()

Flush any temporary storage used by the binding. This can be called on a binding that will never again be used in order to free memory used by the binding.

char const *getMetadata(char const *keyCStr) const

Gets a named metadata value associated with the binding. The key is case-sensitive, and if there is no metadata present for the given key this function returns the empty string. See FabricCore::DFGBinding::setMetdata().

Parameters:key – The key for the metadata to obtain
Returns:The value for the metadata, or the empty string if there is none.
void setMetadata(char const *keyCStr, char const *valueCStr, bool canUndo = true)

Sets a named metadata value associated with the binding. The key is case-sensitive. The current value for the key, if any, will be replaced. The canUndo parameter can optionally be provided to specify whether the action should be undoable; if it is not undoable then no undo action will be stored and then the previous value of the metadata for the key will not be restored when an undo occurs.

Parameters:
  • key – The key for the metadata to obtain
  • value – The new value for the metadata
  • canUndo – Optional; whether to make the change undoable
String getVars()

Returns a JSON-encoded description of Canvas variables available within the binding.

Result:The JSON-encoded descripton of Canvas variables
uint32_t getVersion()

Returns the version of the binding. The version of the binding is zero when the binding is first created, and is incremented every time the binding changes. The binding version changes are undone when actions on the binding are undone. The purpose of the version is to allow applications to know when the binding has changed and may need to be saved. Note that the binding version is not persisted when the binding is persisted.

Result:The version of the binding
class FabricCore::DFGHost : public FabricCore::Ref
DFGHost()
DFGHost(DFGHost const &that)
DFGHost &operator=(DFGHost const &that)
DFGHost &~DFGHost()
Context &getContext() const

Get the Fabric Core context to which the DFGHost belongs

bool maybeUndo()

Attempt to undo one Canvas Core command.

Returns:Whether a command was undone
bool maybeRedo()

Attempt to redo one Canvas Core command.

Returns:Whether a command was redone
void flushUndoRedo()

Flush the undo and redo stacks. This will purge memory used by the commands on the stack but the commands will destroyed.

bool isPresetFile(char const *presetPath)
bool isPresetDir(char const *presetPath)
char const *getPresetImportPathname(char const *nameSpacePath)

Get the filename from which a preset was imported.

Parameters:presetPath – The path to the preset in the preset tree
Returns:The filename from which the preset was imported, or the empty string if the preset was not imported from a file
char const *getPresetImportPathname(char const *nameSpacePath)

Get the filename from which a preset was imported.

Parameters:presetPath – The path to the preset in the preset tree
Returns:The filename from which the preset was imported, or the empty string if the preset was not imported from a file
String getPresetPathForPresetGUID(char const *presetGUID)
FabricCore::String getPresetDesc(char const *presetPath)

Generate a JSON description of a preset

Parameters:presetPath – The path to the preset in the preset tree
Returns:The JSON description
FabricCore::String getPresetTags(char const *presetPath)
char const *getPresetMetadata(char const *presetPath, char const *key)

Get the metadata associated with the given key for the given preset. Returns NULL if there is no metadata for the given key.

Parameters:
  • presetPath – The path to the preset in the preset tree
  • key – The key for the metadata to be retrieved
char const *addPresetDir(char const *parentPresetDirPath, char const *desiredName, char const *pathname = 0)

Add a new preset directory (child) to an existing preset directory (parent) within the preset tree.

Parameters:
  • parentPresetDirPath – The path of the parent preset directory to contain the new child preset directory
  • desiredName – The desired name of the new child preset directory
  • importPathname – If given, the import pathname to associate with the new child preset directory
Returns:

The actual name of the new child preset directory

char const *importPresetFileJSON(char const *parentPresetDirPath, char const *desiredName, char const *json, char const *importPathname = 0)

Import a new preset (child), encoded as JSON, into an existing preset directory (parent). The JSON-encoded representation is usually obtained through String exportPresetJSON().

Parameters:
  • parentPresetDirPath – The path of the parent preset directory to contain the new child preset
  • desiredName – The desired name of the new child preset
  • json – The new preset encoded as JSON
Returns:

The actual name of the new child preset

String exportPresetJSON(char const *presetPathCStr)

Export an existing preset as JSON.

Parameters:presetPath – The path to the preset
Returns:The preset encoded as JSON
void removePreset(char const *presetPath)

Remove an existing preset from the preset tree.

Parameters:presetPath – The path to the preset
DFGExec createNewUnboundGraph()

Create a new DFGExec object that references an empty graph. The graph is unbound, ie. it is not attached to a DFGBinding, and so can be edited but not executed.

Returns:The new DFGExec object
DFGExec createNewUnboundExecFromJSON(char const *json)

Create a new DFGExec object described by JSON. The JSON is usually obtained through FabricCore::DFGExec::exportJSON(). The executable is unbound, ie. it is not attached to a DFGBinding, and so can be edited but not executed.

Parameters:json – The JSON-encoded description of the executable
Returns:The new DFGExec object
DFGExec createNewUnboundFunc()

Create a new DFGExec object that references an empty function. The function is unbound, ie. it is not attached to a DFGBinding, and so can be edited but not executed.

Returns:The new DFGExec object
DFGExec createUnboundExecForPreset(char const *presetFile)

Create an unbound executable that is an instance of a specified preset.

Parameters:
  • presetFilePath – The path to the preset, within the preset tree, to use as the root executable
  • rtValCount – If given, the number of RTVals to bind to the arguments of the new DFGBinding
  • rtVals – If given, the RTVals to bind to the arguments of the new DFGBinding
Returns:

The DFGExec

DFGBinding createBindingToNewGraph()

Create a new DFGBinding object with an empty graph as its root executable.

Returns:The new DFGBinding
DFGBinding createBindingToNewFunc()

Create a new DFGBinding object with an empty function as its root executable.

Returns:The new DFGBinding
DFGBinding createBindingFromJSON(char const *json, uint32_t rtValCount = 0, RTVal const *rtVals = 0)

Create a new DFGBinding object with its root executable described by JSON. The JSON is usually obtained through FabricCore::DFGExec::exportJSON().

Parameters:
  • json – The JSON-encoded description of the root executable
  • rtValCount – If given, the number of RTVals to bind to the arguments of the new DFGBinding
  • rtVals – If given, the RTVals to bind to the arguments of the new DFGBinding
Returns:

The new DFGBinding

DFGBinding createBindingToPreset(char const *presetFile, uint32_t rtValCount = 0, RTVal const *rtVals = 0)

Create a new DFGBinding object with its root executable being an instance of a specified preset.

ss :param presetFilePath: The path to the preset, within the preset tree, to use as the root executable
param rtValCount:
 If given, the number of RTVals to bind to the arguments of the new DFGBinding
param rtVals:If given, the RTVals to bind to the arguments of the new DFGBinding
returns:The new DFGBinding
DFGBinding getBindingForID(uint32_t bindingID)

Obtain a reference to the DFGBinding with the given binding ID, obtained through FabricCore::DFGBinding::getBindingID().

Parameters:bindingID – The binding ID
Returns:The DFGBinding with the given binding ID
void blockComps()

Block recompilations of DFGBindings. This can be used to increase performance during long scripted building of graphs. Calling FabricCore::DFGBinding::execute() while recompilations are blocked will throw an exception.

void unblockComps()

Unblock recompilations of DFGBindings.

bool areCompsBlocked()

Returns whether recompilations of DFGBindings are blocked.

void searchPresets()
void dumpPresetDB()
void searchDBAddUser(char const *resultCStr, unsigned tagCount, char const *const *tagCStrs)
bool searchDBHasUser(char const *resultCStr)
void searchDBRemoveUser(char const *resultCStr)
class FabricCore::DFGNotifBracket

The DFGNotifBracket class is used to suspend notifications until a set of DFG commands has executed.

DFGNotifBracket(DFGHost host)

By creating a DFGNotifBracket in the current scope, all DFG notifications will be suspended until the scope closes.

~DFGNotifBracket()