User:Phonybone/Archive/CustomNodes

From BlenderWiki

Custom Nodes or Python Nodes are a way to dynamically extend the set of available nodes in Blender. Currently the process of creating a new type of node involves many different steps:

• Unique identifier number
• Registration function
• DNA struct for specialized data
• RNA definition as interface to that data
• Draw functions to display data in the editor
• Optional functions for init/copy/free of a node and other editor behavior
• Execution functions, depending on overall node system (compositor, materials/cylces shaders, textures)
• Read/Write code for .blend files

While not all of the steps are needed for all types of nodes, they all require editing C code and recompile. This in turn means that no node types can be added or modified without a SVN trunk patch and the necessary approval.

Custom nodes aim to remove this problem by making node types dynamically registered using an API. This way new node types can be added from python or any other external system using the RNA.

Example of Python Node Definition

Custom node tree type

# Derived from the NodeTree base type, similar to Menu, Operator, Panel, etc.
class MyCustomTree(bpy.types.NodeTree):
    # Description string
    '''A custom node tree type that will show up in the node editor header'''
    # Optional identifier string. If not explicitly defined, the python class name is used.
    bl_idname = 'CustomTreeType'
    # Label for nice name display
    bl_label = 'Custom Node Tree'
    # Icon identifier
    # NOTE: If no icon is defined, the node tree will not show up in the editor header!
    #       This can be used to make additional tree types for groups and similar nodes (see below)
    #       Only one base tree class is needed in the editor for selecting the general category
    bl_icon = 'NODETREE'

Nodes in the new tree category

# Derived from the Node base type.
class MyCustomNode(bpy.types.Node):
    # Description string
    '''A custom node'''
    # Optional identifier string. If not explicitly defined, the python class name is used.
    bl_idname = 'CustomNodeType'
    # Label for nice name display
    bl_label = 'Custom Node'
    # Icon identifier
    bl_icon = 'SOUND'

Implementation Notes

Identifying Nodes

Main way of identifying node is bNodeType->idname string, not bNodeType->type integer. The type id stays for compatibility reasons and to keep old systems working until it can be replaced at later date. Complex nodes that require pointers and data structs also still need to register static integer types, at least until better id properties are implemented (see below).

Custom nodes use the NODE_CUSTOM type (value -1) to distinguish them and make functions use idname instead. For static node types (type!=NODE_CUSTOM) the NOD_static_types.h header file (previously rna_nodetree_types.h) is used to generate usable idnames.

Registering Custom Node Types

Custom node types can be created using the RNA API functions. Node struct has register/unregister functions defined, which allocate a bNodeType struct and initialize from validation function.

Tree and node types use global hashes now for storing registered types. Node types are not directly stored in tree types any more, to have more flexibility: a node type can be used for multiple different tree types, if necessary.