Shader Network | Python

Shader networks are different from the native C4D materials because they have a custom graph view implementation. Basically, a graph view is attached to the Arnold Material and shaders are represented as GV nodes, similar to an Xpresso graph (except it's not a real data flow, only the parameters and network connections are exported to Arnold). That's why managing them via python scripts requires some custom logic.

Messages

The C4D python API is limited and does not allow access to the node master of the graph view. That's why querying and modifying a shader network is done via sending custom messages to the material.

Available Messages

The following tables show the available actions or messages which can be sent to a material: message ids,  parameters and return values.

 

  • Query the network, shaders (GV nodes) and their connections.
Message idC4DTOA_MSG_QUERY_SHADER_NETWORK = 1028
Parameters-
Return values

C4DTOA_MSG_RESP1 (Int32): number of nodes in the network. Nodes can be accessed from id 10000.

C4DTOA_MSG_RESP2 (Int32): number of connections. This means only a connection between two shader nodes, not root connections. Connections can be accessed from id 20000. Each connection is represented as a BaseContainer with the following ids:

  • 0 (Link of GvNode): Source GV node.
  • 1 (Int32): Port id of the source GV node. (Shader nodes have only one output port at the moment with an id of 0).
  • 2 (Link of GvNode): Destination GV node.
  • 3 (Int32): Port id of the destination GV node.

C4DTOA_MSG_RESP3 (Link of GvNode): root GV node connected to the beauty port.

C4DTOA_MSG_RESP4 (Link of GvNode): root GV node connected to the displacement port.

 

  • Create a new shader in the network.
Message idC4DTOA_MSG_ADD_SHADER = 1029
Parameters

C4DTOA_MSG_PARAM1 (Int32): specifies the type of the GV node which can be the following:

  • ARNOLD_SHADER_GV = 1033990: an Arnold shader (e.g. standard_surface, image, etc.).
  • ARNOLD_C4D_SHADER_GV = 1034190: a supported C4D shader (e.g. Bitmap, VertexMap, etc.).
  • ARNOLD_REFERENCE_GV = 1035541: reference to another shader network.

C4DTOA_MSG_PARAM2 (Int32 or Link of BaseMaterial): specifies the shader type for Arnold and C4D shaders or the referenced material if param 1 is set to ARNOLD_REFERENCE_GV. For built-in Arnold node ids see api/util/NodeIds.h. Node ids can also be generated from the node entry name using a hash function.

C4DTOA_MSG_PARAM3 (Int32): x position of the new GV node.

C4DTOA_MSG_PARAM4 (Int32): y position of the new GV node.

Return values

C4DTOA_MSG_RESP1 (Link of GvNode): the new shader node or null when creating the shader is failed.

 

  • Remove a shader from the network.
Message idC4DTOA_MSG_REMOVE_SHADER = 1030
ParametersC4DTOA_MSG_PARAM1 (Link of GvNode): the shader to remove.
Return values

C4DTOA_MSG_RESP1 (Bool): TRUE when successful, FALSE on error.

 

  • Create a connection (link) between two shaders.
Message idC4DTOA_MSG_ADD_CONNECTION = 1031
Parameters

C4DTOA_MSG_PARAM1 (Link of GvNode): source shader node.

C4DTOA_MSG_PARAM2 (Int32): output port id of the source shader node. Only one output port with id 0 exists at the moment.

C4DTOA_MSG_PARAM3 (Link of GvNode): destination shader node.

C4DTOA_MSG_PARAM4 (Int32): input port id of the destination shader node. See resource files in res/description folder for parameter ids.

Return valuesC4DTOA_MSG_RESP1 (Bool): TRUE when successful, FALSE on error.

 

  • Disconnect two shaders.
Message idC4DTOA_MSG_REMOVE_CONNECTION = 1032
Parameters

C4DTOA_MSG_PARAM1 (Link of GvNode): destination shader node.

C4DTOA_MSG_PARAM2 (Int32): input port id of the destination shader node. See resource files in res/description folder for parameter ids.

Return valuesC4DTOA_MSG_RESP1 (Bool): TRUE when successful, FALSE on error.

 

  • Connect a shader to the given root port (beauty or displacement). When a root shader already exists it will be disconnected first.
Message idC4DTOA_MSG_CONNECT_ROOT_SHADER = 1033
Parameters

C4DTOA_MSG_PARAM1 (Link of GvNode): the new root shader node.

C4DTOA_MSG_PARAM2 (Int32): output port id of the root shader node. Only one output port with id 0 exists at the moment.

C4DTOA_MSG_PARAM3 (Int32): root port to connect to which can be the following:

  • ARNOLD_BEAUTY_PORT_ID = 537905099

  • ARNOLD_DISPLACEMENT_PORT_ID = 537905100

Return valuesC4DTOA_MSG_RESP1 (Bool): TRUE when successful, FALSE on error.

 

  • Disconnect the given root shader (e.g. beauty or displacement).
Message idC4DTOA_MSG_DISCONNECT_ROOT_SHADER = 1034
Parameters

C4DTOA_MSG_PARAM1 (Int32): root port to connect to which can be the following:

  • ARNOLD_BEAUTY_PORT_ID = 537905099

  • ARNOLD_DISPLACEMENT_PORT_ID = 537905100

Return valuesC4DTOA_MSG_RESP1 (Bool): TRUE when successful, FALSE on error.

Modify parameters

If you query a shader network with message C4DTOA_MSG_QUERY_SHADER_NETWORK (1028) then you can access the GV nodes and so you can modify any parameters. Parameter ids can be found in the header files from res/description folder (e.g. ainode_standard_surface.h).

Identifiers

Node and parameter ids are generated from Arnold node entry names and parameter names using the following hash function:

For built-in shaders, you can find these ids in the resource files. For third-party shaders use the above function to generate the ids.

Get Shader Type

C4DtoA uses generic GV nodes to represent shaders which means there's one GV node which can display the UI of different shaders depending on the parameter. You can use the following code to define the type (Arnold node id or C4D shader type) of the shader.

If the GV node is a shader network reference (ARNOLD_REFERENCE_GV), then there's no shader type. If it's an Arnold shader (ARNOLD_SHADER_GV), then the type is defined by the C4DAI_GVSHADER_TYPE parameter. If it's a C4D shader (ARNOLD_C4D_SHADER_GV) then type is defined by the C4DAI_GVC4DSHADER_TYPE parameter. Otherwise, the type is the operator id of the GV node.

Examples

This section offers some example scripts to download which give you more details about how to use the above messages and functions:

  • create_network.py: creates an Arnold Shader Network material with a standard_surface and noise shader connected together.
  • query_network.py: queries the first material and prints details of the network to the console.
  • remove_shaders_and_connections.py: this script shows how to disconnect and remove shaders from a network.
  • print_textures.py: prints all textures defined in image or Bitmap shaders in the scene.
  • convert_c4dmat_color.py: this script iterates over all C4D native materials of the scene and creates Arnold materials with a standard_surface shader using the same diffuse color and a connected image shader for color texture.

 

  • No labels