User:OmarSquircleArt/GSoC2019/Documentation/Adding A New Shading Node

= Adding A New Shading Node =

This guide covers the necessary steps to add a new shading node to Blender. This guide shall not cover the details of the SVM, OSL, or GPU backends, please read the guides on SVM, OSL, and GPU for more details. We will start by providing a summary then we will cover each of the steps in details. Check the code of existing nodes as a reference to get the most out of this guide.


 * Add a new node type ID  in.
 * If needed, create a  struct in  . If needed, also create definitions and enums for the node properties.
 * If the node have properties, add a  function in.
 * Add a case for the node in.
 * If needed, add a case for the node in the  function in.
 * Add a new function  in a new file   in.
 * Add the  file to the source list in.
 * Add the  function prototype to.
 * Call the  function in the   function in.
 * Create a Cycles class for the node in.
 * Instantiate the Cycles class in the  function in.
 * Define the node in.
 * Add the node to the add menus in.

Defining A New Node Type ID
Start by defining a new node type ID  for the node in , making sure not to change other definitions. This node type ID will be used to identify the node in the code base.

Creating A DNA Struct
The  struct provides two shorts (  and  ) and two floats (  and  ) to be used for storing node properties. So most nodes don't need a dedicated DNA struct. However, if needed, a new DNA struct can be defined in  to be used as a storage for the node properties, we call such node a node with custom storage. This is also where you create definitions and enums for your properties if needed.

Creating RNA Properties
If the node have properties, create a  RNA definition function in. Nodes with custom storage should call the  function to create the struct from the the node storage.

Nodes that have an update callback for updating sockets should use the  update function.

Static Types
Add a case/entry for the node in  using the   macro. The entries will be used to associate the node type ID  with the RNA struct type and the   struct.

The  macro have the following signature:


 * Categroy - The node tree type this node is used in. It can be,  ,  , or.
 * ID - The node type ID.
 * Definition Function - The RNA definition function  we just created in  . This should be   if no definition function exist.
 * Enum Name - A unique name used in the API.
 * Struct Name - The name of the RNA struct. The final name will be prefixed with the aformentioned category.
 * UI Name - The name used in the UI.
 * UI Description - The node description.

Draw Function
If the node have properties, add a drawing function  in   and add a case for it in the   function.

Creating And Registering A New Node Type
A node is defined by a  struct, where it stores the node attributes and callback functions implementing the node behavior. Create a file  in   and add it to the source list in. In this file, create a function  where we will create the   struct, initialize it, and register it.

Node Type Base
We usually start by calling the  function to set some common defaults for shading nodes.

It is also used to initialize the node with the following basic attributes:


 * Type - The node type ID we just created.
 * Name - The node name.
 * Class - The node class, which classify the node for the add menu and for UI theming. See   for the available classes.
 * Flag - The node flag. See  for the available flags.

Inputs And Outputs
To define the input and output sockets of the node, we call the  function.

This function takes two arrays of  struct, one representing the inputs and the other representing the outputs. Both arrays should always end with the terminating struct  to mark the end of the array.

The  struct defines:


 * Type - The socket type. For instance  or  . See the   enum in   for the available types.
 * Limit - A limit to the number of links that can be connected to the socket. This is typically  for inputs and   for outputs, where   means any number of links.
 * Name - The name of the socket. This name should be enclosed in the translation-marker macro.
 * Default - The default value of the socket. The default value is defined by four floats, some of which may be ignored depending on the type. For instance, for a float socket, only the first float  is used and the last three are ignored, and for a vector socket, only the first three floats ,  , and   are used and the last one is ignored.
 * Min/Max - The soft minimum and maximum values of the socket.
 * Subtype - The socket property subtype. For instance,  to mark the vector socket as an euler. See the   enum in   for the available subtypes.
 * Flag - The socket flag . For instance,   to hide the socket value if it gets an auto default, like the normal inputs of the BSDF nodes. See the   enum in   for the available flags.

Node Initialization
Nodes that have custom storage should call the function  to set an   for the node.

The, in most cases, just dynamically allocate the DNA struct of the node, set some defaults, and set the DNA struct to the   attribute of the. For instance:

Node Storage
If your node have properties, then you have to call the  function.

The functions sets the following:


 * Storage Name - The name of the DNA structure used for storage. For nodes that don't use custom storage, this should be an empty string.
 * Free Function - A function that frees the allocated data in the init function, typically the DNA struct. For nodes that don't use custom storage, this should be . In most cases, the   function can be supplied, which just calls   on the node storage.
 * Copy Function - A function that copies the storage from a node to another. For nodes that don't use custom storage, this should be . In most cases, the   function can be supplied, which just calls   on the source node storage and set the new struct to the destination node storage.

Update Callback
A node can have an update function to be called whenever an update is required. This is typically used to make some sockets available/unavailable based on some node property. If needed, call the  to set the update function.

GPU Execution
The  function should be called to set the GPU execution function for OpenGL/EEVEE display. The details of the GPU execution function is available in the GPU guide.

Other Attributes And Callbacks
There are numerous other less commonly used attributes and callbacks you can set. For instance  to dynamically set node labels based on node properties or   to set the size attributes of the node.

Registering The Node Type
To actually register the node type, first, add the function prototype to. Then add a call to the  function in the   function in.

Add Node To Menu
Add the node to a menu in.

Cycles Class
A node in cycles is represented by a class that inherit from the base class. The  macro can be used to quickly populate the class with the essential virtual functions, namely the clone and SVM and OSL compile functions. The class should have a public variable declaration for every input and property in the node.

A more detailed description of the class is be provided in the TODO guide.

Cycles Class Instantiation
Add a new case for the node in the  function in. In this case, instantiate a new instance of the node class and set the required class variables using the functions provided by the Blender class.

Cycles Node Definition
TODO