Command plug-ins

Coden provides a rich specification for creating various types of plug-ins for numerous hosts. In addition to defining the plug-ins, however, it is also important to properly expose them to the end user. This might mean simply creating an instance of your custom plug-in inside a scene or, more involved, performing some operations on objects already existing within a scene to incorporate your custom functionality into it.

The scene graph

As with all the other plug-in types, Coden defines a high level abstraction when it comes to accessing and manipulating scenes. We do this through a generalized acyclic dependency graph which represents an instance of a file currently being edited by a user. Each node within this graph represents a specific object within a scene. For example, a node could represent a polygon mesh, its transform, or some animation controller. The nodes are then inter-connected between each other to define their relationships.

For example, an animation data node might be connectable to a polygon mesh node to give it movement. The nodes are specified in a way to be abstract enough for every host application which Coden supports. While the node itself might not map directly to a specific object within a host application the overall structure of the graph will be applicable to that host and will produce the expected behaviour.

Types of nodes

There are numerous types of nodes present within a Coden scene graph. Each node has its own purpose and is only connectable to a specific set of other nodes. To learn more about each node type please click on a more detailed description from this list:

  • World object node: An object which appears inside a view of a host application. This node specifies information about what the displayed object is, its location, its material, and other information.
  • Object node: Represents some data which can be passed to a scene node. Object nodes can take other object nodes as input and modify them.
  • Function node: Returns simple values as opposed to complex values returned by object nodes. These can be simple scalar values or things like transformation to control a scene node's position.

Creating a command plug-in

Defining a command plug-in in Coden is very trivial: create a pluggable function returning a boolean value and taking first parameter of type IGraph. You can then specify more parameters for the function for your needs. Here is a simple example of a function plug-in:

public static bool MyCommand( IGraph graph, float parameter1, int parameter2 )
{
	// Do stuff to graph here...
	return true;
}

For more complex examples please download our samples project and browse the "Commands" directory.

Using IGraph to create nodes

To create a new instance of a node use IGraph.CreateNode command as illustrated in the following example: The string parameter you pass is the full name of the Coden plug-in you want to create or a predefined name such a world object node. The following predefined names can be created: While creating a node you must also assign it a unique name.

Accessing existing scene nodes

IGraph interface provides a Nodes property which allows you to browse through all currently available scene nodes. Note that some of these nodes may be instances of Coden plug-ins but all of the nodes will either directly or indirectly represent objects inside a host application. You may perform a number of operations on existing scene nodes such as renaming, deleting or connecting them. You may also use these nodes to access their properties and other nodes connected to them.

Getting and setting node selection

If you provide a second parameter for your pluggable command function which has an integer array type and a "selection" tag you will be passed the indices of currently selected nodes within the graph's Nodes array. These are the nodes which have been selected by a user inside the host application's UI. Having access to the current selection can be used to perform some action on just the currently selected nodes within the scene. Following example demonstrates a sample usage of node selection:

public static bool MyCommand( IGraph graph, [Input( Tags = "selection" )] int[] graphSelection )
{
	foreachvar selectedIndex in graphSelection )
	{
		var selectedNode = graph.Nodes[selectedIndex];
		// Do stuff to selectedNode...
	}
	return true;
}

Executing other commands

Your command can execute other commands defined either by you as a plug-in or present within a host application. To execute a command use IGraph.ExecuteCommand function. As with node creation be careful to make sure that all hosts that you want to potentially run your command will have the commands you want to execute within them. A good practice is to only call other commands which you have defined through Coden and provided within the same plug-in. This guarantees their availability within the same host application.

Examples

For examples of command plug-ins see CenterSelectedNodes.cs, CreateCube.cs, and EnumerateSceneNodes.cs files available in the samples project.