Adding a new node to the Cycles source code

If you want to extend or enhance the Blender Cycles nodes collection you must know how to find your way around the code. The Blender source code consists of thousands of files so in the beginning it might not be easy to find where to start.

Because I wanted to create a new node that can be used to create a Voronoi Crackle pattern I documented each step in the creation. This is based on Linux and CMake but the contents of the files themselves are no different on other systems (unless you do not use CMake, in which case you have to adapt SConstruct files instead of CMakeList.txt files)

Areas where a new node needs changes

• In the shader code as it gets executed on the CPU, as OSL or on the GPU
• In the shader node tree before it gets compiled to shader code
• In the node editor menu
• In Blenders internal representation, so a shader node tree containing our new node can be saved/reload form a .blend
• In some files of the built system

This results in 17 files that need to be changed and 3 files to be added for adding an extra texture node to Cycles (without even adding the BI texture node as well)

sidebar: development workflow with git

Assuming you have checked out a Blender source repository and installed all dependencies check the development docs and were successful in compiling Blender, developing a new node while keeping you source tree up to date requires shuffling your changes around while you update.

• change or add files as shown below, stage new untracked files with git add
• before updating the sources: git stash save a-meaningful-name-for-your-node [will remove staged files from the index as well]
• make update
• make
• test that it worked
• git stash apply stash@{0}, followed by git stash drop (if you don want to create new stashes again and again)
• make
• test that it worked

If you would want to save a patch, simply do git diff HEAD > filename

A breakdown

Each file I changed or added is listed below. The actual changes (in the form of a patch) can be found here

Not necessary for an extra node, but needed just for my development environment:
intern/cycles/device/device_cuda.cpp

I had to adapt this so that when Blender compiles a new cuda kernel when you switch to Cycles, it compiles for shader model 5.0 even though I have a shader model 5.2 capabable GTX970. My cuda drivers are slightly behind, but I don't want to update them because at the moment all is working fine and I don't want to break a working environment.

---

intern/cycles/blender/blender_shader.cpp
code necessary to put a shader tree together

The next few files implement the part of the new pattern that is executed on the CPU ot GPU, i.e. the actual shader

intern/cycles/kernel/CMakeLists.txt
make the new svm code known to the build system (Cmake)

intern/cycles/kernel/svm/svm.h
call the new svm crackle code when it is encountered in the shader tree as it is executed

intern/cycles/kernel/svm/svm_types.h
constant and typedef of paramters used in the shadere

intern/cycles/kernel/shaders/CMakeLists.txt
make the new OSL node known to the build system

[New file] intern/cycles/kernel/svm/svm_voronoi_crackle.h
the actual shader code, both for CPU and GPU

[New file] intern/cycles/kernel/shaders/node_voronoi_crackle_texture.osl
the actual shader code for OSL

These files are needed by Cycles to compile a shader tree before rendering

intern/cycles/render/nodes.cpp
intern/cycles/render/nodes.h
compile a node to a shader node on the svm stack. It's separated into an class declaration and member implementation.

The new node also has to be present in the node editor Add menu

release/scripts/startup/nodeitems_builtins.py
define just the ShaderNodeTex... (the TextureNodeTex... are for Blender Internal renderer texture nodes)

And the node widget itself needs to know how its buttons are drawn (this is apparently not done in Python)

source/blender/editors/space_node/drawnode.c
define the way buttons on the new shader node are drawn

Besides in a shader a node needs to be to represented as a node object inside blender as well

source/blender/blenkernel/BKE_node.h
define a unique id that will be used to identify this node

source/blender/blenkernel/intern/node.c
register the node (again just the shader node, node BI texture node)

source/blender/makesdna/DNA_node_types.h
define constants and typedef to be used in the internal representation

source/blender/makesrna/intern/rna_nodetree.c
create the internal representation

source/blender/nodes/CMakeLists.txt
make the new internal node representation code known to the build system (Cmake)

source/blender/nodes/NOD_shader.h
forward declaration of node register function

source/blender/nodes/NOD_static_types.h
node type definitions

[New file]source/blender/nodes/shader/nodes/node_shader_tex_voronoi_crackle.c
initialization code for node