Simplygon Shading Network functions
The Simplygon Max plug-in exports a number of global MaxScript / Python functions. The following sections lists Simplygon ShadingNetwork functions and examples, general Simplygon functions and Simplygon Pipeline functions are listed separately.
Shading networks are usually generated automatically in the plug-in but for some material types, such as DirectX and CGFX (HLSL), the mapping has to be done manually. It is recommended to read Shading network concepts before proceeding.
Note: Max 2021 introduced a new (standard) material type, specifically Physical Material. Most shading network functions can be used in combination with Physical Material. As Physical Material is not HLSL based there are no shader properties to map against. This material type has its own predefined variables that can be used for mapping.See How to map a Physical Material for more details.
Script functions
Function | Parameter(s) | Description |
---|---|---|
sgsdk_RunPipelineOnSelection | int pipelineHandle | Optimizes the selected asset(s) based on the pipeline object. |
sgsdk_RunPipelineOnSelection | string pipelineFilePath | Optimizes the selected asset(s) based on the pipeline file. |
sgsdk_RunPipelineOnFile | int pipelineHandle string inputFilePath string outputFilePath | Optimizes the asset(s) in the specified input file and stores the result in the output file. The output file will get indexed if the Pipeline specifies a LOD chain, use sgsdk_GetProcessedOutputPaths to get the correct paths. |
sgsdk_RunPipelineOnFile | string pipelineFilePath string inputFilePath string outputFilePath | Optimizes the asset(s) in the specified input file and stores the result in the output file. The output file will get indexed if the Pipeline specifies a LOD chain, use sgsdk_GetProcessedOutputPaths to get the correct paths. |
sgsdk_UseShadingNetwork | bool isEnabled | Enables DirectX shading network pipeline. Note: not compatible with Physical Material! |
sgsdk_CreateMaterialMetadata | string materialName | Creates an override material for the named material. |
sgsdk_CreateShadingTextureNode | string textureName | Creates a texture node that connects to the given texture name in the shader. |
sgsdk_CreateShading<nodeType> Ex: sgsdk_CreateShadingColorNode | string nodeName | Creates a node of the given type. |
sgsdk_SetDefaultParameter | int nodeIndex uint inputSlot double a double b double c double d | Sets default values for the given node input. |
sgsdk_AddAttributeToNode | int nodeIndex uint inputSlot | Sets an attribute to the specified node. |
sgsdk_ConnectNodes | int nodeIndex uint inputSlot int nodeIndexToConnect | Connects a node to another node’s input slot. |
sgsdk_ConnectNodeToChannel | int nodeIndex int materialIndex string channelName | Sets the exit node for the given material channel. |
sgsdk_ConnectOutputToDirectXMaterial | string effectFile string channelName string textureSlot | Specifies to which shader and texture slot the result will be connected to. Note: not compatible with Physical Material! |
sgsdk_VertexColorNodeSetVertexChannel | int nodeIndex int mappingChannel | Specifies which color channel to read from. |
sgsdk_SwizzlingNodeSetChannelSwizzle | int nodeIndex uint inputSlot uint outputSlot | Sets output slot for the given input slot for the node, (RGBA -> 0, 1, 2, 3). |
sgsdk_GeometryNodeSetFieldName | int nodeIndex string geometryFieldName | Sets the field name for the given geometry field node. |
sgsdk_GeometryNodeSetFieldIndex | int nodeIndex int geometryFieldIndex | Sets the field index for the given geometry field node. |
sgsdk_GeometryNodeSetFieldType | int nodeIndex int geometryFieldType | Sets the field type for the given geometry field node. |
sgsdk_SetMappingChannel | int nodeIndex int mappingChannel | Sets the mapping channel/UV-set for the given texture node. |
sgsdk_SetSRGB | int nodeIndex bool isSRGB | Sets the sRGB flag for the given texture node. |
sgsdk_SetUVTiling | int nodeIndex float uTiling float vTiling | Sets the UV-tiling for the given texture node. |
sgsdk_SetUTiling | int nodeIndex float uTilingSets | Sets the U-tiling for the given texture node. |
sgsdk_SetVTiling | int nodeIndex float vTiling | Sets the V-tiling for the given texture node. |
sgsdk_SetUVOffset | int nodeIndex float uOffset float vOffset | Sets the UV-offset for the given texture node |
sgsdk_SetUOffset | int nodeIndex float uOffset | Sets the U-offset for the given texture node. |
sgsdk_SetVOffset | int nodeIndex float vOffset | Sets the V-offset for the given texture node. |
sgsdk_GetProcessedMeshes | <none> | Returns a list of processed mesh names from last run. |
sgsdk_GetProcessedOutputPaths | <none> | Returns a list of processed file paths from last run. |
sgsdk_GetMaterialForMesh | string meshName | Return material name for the specified mesh. |
sgsdk_GetMaterialsForMesh | string meshName | Return material names for the specified mesh. |
sgsdk_GetMeshReusesMaterial | string meshName | Returns material name if the material is shared, otherwise empty string. |
sgsdk_GetMeshReusesMaterials | string meshName | Returns material names of reused materials, otherwise empty list. |
sgsdk_GetChannelsForMaterial | string materialName | Returns a list of material channel names for the specified material. |
sgsdk_GetTexturePathForChannel | string materialName string channelName | Returns the texture path for the specified material channel. |
sgsdk_GetMappingChannelForChannel | string materialName string channelName | Returns the mapping channel for the specified material channel. |
sgsdk_GetMaterials | <none> | Returns a list of material names from the last run. |
sgsdk_GetSubMaterials | string materialName | Return a list of sub-material names for the specified material. |
sgsdk_GetMaterialReusesSubMaterial | string materialName string subMaterialName | Returns reused material name id reused, otherwise empty string. |
sgsdk_GetSubMaterialIndex | string materialName string subMaterialName | Returns sub-material index. |
sgsdk_SetGenerateMaterial | bool generateMaterial | Specifies whether the plug-in should generate a standard material for baked LODs. |
sgsdk_SetTextureOutputDirectory | string filePath | Sets the output texture directory for baked textures. |
Special node attributes
Special node attributes can be set using sgsdk_AddAttributeToNode
, see the list of attributes below.
Shading Node | Attribute Type |
---|---|
ShadingTextureNode | 1 – TileU, 2 – TileV 3 – MappingChannel 4 – TileUV 5 – OffsetU, 6 – OffsetV 7 – OffsetUV |
Examples
This section contains various Pipeline examples written in MaxScript and Python. We've left out some parts of the scripts to keep things as simple as possible.
from pymxs import runtime as rt
must be declared at the top of each Python script.reductionPipeline
settings-path must be declared for both MaxScript and Python scripts where it makes sense.effectFile
file-path to the target shader must be declared for both MaxScript and Python scripts where it makes sense.- a scene-selection is made before each
sgsdk_RunPipelineOnSelection
.
Create material
Creates a shading network material override for the specified material.
DirectXShader = sgsdk_CreateMaterialMetadata "MyMaterial"
from pymxs import runtime as rt
DirectXShader = rt.sgsdk_CreateMaterialMetadata('MyMaterial')
Create node
Creates a texture node that is linked to a shader's texture slot named DiffuseTexture.
DiffuseTexture = sgsdk_CreateShadingTextureNode "DiffuseTexture"
from pymxs import runtime as rt
DiffuseTexture = rt.sgsdk_CreateShadingTextureNode('DiffuseTexture')
Set default values
Creates a pow node, connects a texture to input 0 and sets a value for input 1.
powNode1 = sgsdk_CreateShadingPowNode "powNode1"
sgsdk_ConnectNodes powNode1 0 DiffuseTexture
sgsdk_SetDefaultParameter powNode1 1 0.5 0.5 0.5 0.5
from pymxs import runtime as rt
powNode1 = rt.sgsdk_CreateShadingPowNode('powNode1')
rt.sgsdk_ConnectNodes(powNode1, 0, DiffuseTexture)
rt.sgsdk_SetDefaultParameter(powNode1, 1, 0.5, 0.5, 0.5, 0.5)
Set exit node
Assigns a shading node to a material channel, in this case we connect as texture node (which points to DiffuseTexture in shader) to the Diffuse channel.
sgsdk_ConnectNodeToChannel DiffuseTexture DirectXShader "Diffuse"
from pymxs import runtime as rt
rt.sgsdk_ConnectNodeToChannel(DiffuseTexture, DirectXShader, 'Diffuse')
Set swizzle
Creates a swizzle node with the same texture input on all input channels and swizzles the output channels (in reverse). (R->A, G->B, B->G, A->R)
swizzNode = sgsdk_CreateShadingSwizzlingNode "swizzlingNode"
sgsdk_ConnectNodes swizzNode 0 DiffuseTexture
sgsdk_ConnectNodes swizzNode 1 DiffuseTexture
sgsdk_ConnectNodes swizzNode 2 DiffuseTexture
sgsdk_ConnectNodes swizzNode 3 DiffuseTexture
sgsdk_SwizzlingNodeSetChannelSwizzle swizzNode 0 3
sgsdk_SwizzlingNodeSetChannelSwizzle swizzNode 1 2
sgsdk_SwizzlingNodeSetChannelSwizzle swizzNode 2 1
sgsdk_SwizzlingNodeSetChannelSwizzle swizzNode 3 0
from pymxs import runtime as rt
swizzNode = rt.sgsdk_CreateShadingSwizzlingNode('swizzlingNode')
rt.sgsdk_ConnectNodes(swizzNode, 0, DiffuseTexture)
rt.sgsdk_ConnectNodes(swizzNode, 1, DiffuseTexture)
rt.sgsdk_ConnectNodes(swizzNode, 2, DiffuseTexture)
rt.sgsdk_ConnectNodes(swizzNode, 3, DiffuseTexture)
rt.sgsdk_SwizzlingNodeSetChannelSwizzle(swizzNode, 0, 3)
rt.sgsdk_SwizzlingNodeSetChannelSwizzle(swizzNode, 1, 2)
rt.sgsdk_SwizzlingNodeSetChannelSwizzle(swizzNode, 2, 1)
rt.sgsdk_SwizzlingNodeSetChannelSwizzle(swizzNode, 3, 0)
Set vertex color mapping channel
Creates a vertex color node and sets the node to read from mapping channel 0 (default vertex color channel in Max).
vertexColorNode = sgsdk_CreateShadingVertexColorNode "vertexColorNode"
sgsdk_VertexColorNodeSetVertexChannel vertexColorNode 0
from pymxs import runtime as rt
vertexColorNode = rt.sgsdk_CreateShadingVertexColorNode('vertexColorNode')
rt.sgsdk_VertexColorNodeSetVertexChannel(vertexColorNode, 0)
Specify geometry data field
Assigns a data field (of the mesh) to a geometry-field node. The node can be used to sample specific geometry fields in shading network such as Coords, TexCoords, Normals, Tangents, Bitangents, Colors, TriangleIds and MaterialIds (see EGeometryDataFieldType). In this example we will set up a geometry field node that samples from the color field named '0' (fields in Simplygon gets the name of the mapping channel index in Max).
sgsdk_GeometryFieldNodeSetFieldType specifies which type of the field to sample from, as all colors (normally mapping channel 0 (vc), -1 (illumination) and -2 (alpha)) unless overridden with sgsdk_SetIsVertexColorChannel are stored as 'Color'-fields in Simplygon we want to use the 'Color' index in EGeometryDataFieldType as the type, which is 5.
sgsdk_GeometryFieldNodeSetFieldName and sgsdk_GeometryFieldNodeSetFieldIndex specifies either the Name or Index of the Color field to sample from, Name har precedence over Index (index might also differ between meshes).
geometryFieldNode = sgsdk_CreateShadingVertexColorNode "geometryFieldNode"
sgsdk_GeometryFieldNodeSetFieldType geometryFieldNode 5
sgsdk_GeometryFieldNodeSetFieldName geometryFieldNode "0"
from pymxs import runtime as rt
geometryFieldNode = rt.sgsdk_CreateShadingVertexColorNode('geometryFieldNode')
rt.sgsdk_GeometryFieldNodeSetFieldType(geometryFieldNode, 5)
rt.sgsdk_GeometryFieldNodeSetFieldName(geometryFieldNode, "0")
Override mapping channel / UV-set
Creates a texture and overrides the mapping channel / UV-set.
DiffuseTexture = sgsdk_CreateShadingTextureNode "DiffuseTexture"
sgsdk_SetMappingChannel DiffuseTexture 3
from pymxs import runtime as rt
DiffuseTexture = rt.sgsdk_CreateShadingTextureNode('DiffuseTexture')
rt.sgsdk_SetMappingChannel(DiffuseTexture, 3)
If we have the mapping channel exposed in the shader we can create a direct link between the texture node and mapping channel shader parameter using attributes. The Texture2D
definition in the HLSL shader below contains a variable named MapChannel.
Texture2D <float4> DiffuseTexture : DiffuseMap<
string UIName = "Diffuse";
string ResourceType = "2D";
int Texcoord = 0;
int MapChannel = 1;
>;
Note that the mapChannel in the line below starts with lowercase.
sgsdk_AddAttributeToNode DirectXShader "DiffuseTexturemapChannel" 3
from pymxs import runtime as rt
rt.sgsdk_AddAttributeToNode(DirectXShader, "DiffuseTexturemapChannel", 3)
Override sRGB
Overrides the sRGB flag for a texture node.
sgsdk_SetSRGB DiffuseTexture false
from pymxs import runtime as rt
rt.sgsdk_SetSRGB(DiffuseTexture, false)
Override tiling / offset
Creates a texture node and overrides the U/V-tiling and U/V-offset.
DiffuseTexture = sgsdk_CreateShadingTextureNode "DiffuseTexture"
sgsdk_SetUVTiling DiffuseTexture 2.0 2.0
sgsdk_SetUVOffset DiffuseTexture 0.25 0.25
from pymxs import runtime as rt
DiffuseTexture = rt.sgsdk_CreateShadingTextureNode('DiffuseTexture')
rt.sgsdk_SetUVTiling(DiffuseTexture, 2.0, 2.0)
rt.sgsdk_SetUVOffset(DiffuseTexture, 0.25, 0.25)
If tiling and / or offset parameters are defined in the HLSL shader it might be preferred to create a link between the texture node and the shader parameter(s) using attributes.
float g_UTiling <
string UIName = "UTiling";
string UIWidget = "slider";
float UIMin = -10.0f;
float UIMax = 10.0f;
float UIStep = 0.01f;
> = 1.0f;
float g_VTiling <
string UIName = "VTiling";
string UIWidget = "slider";
float UIMin = -10.0f;
float UIMax = 10.0f;
float UIStep = 0.01f;
> = 1.0f;
float g_UOffset <
string UIName = "UOffset";
string UIWidget = "slider";
float UIMin = -10.0f;
float UIMax = 10.0f;
float UIStep = 0.01f;
> = 0.0f;
float g_VOffset <
string UIName = "VOffset";
string UIWidget = "slider";
float UIMin = -10.0f;
float UIMax = 10.0f;
float UIStep = 0.01f;
> = 0.0f;
Link the texture node to the parameters.
sgsdk_AddAttributeToNode DiffuseTexture "g_UTiling" 1
sgsdk_AddAttributeToNode DiffuseTexture "g_VTiling" 2
sgsdk_AddAttributeToNode DiffuseTexture "g_UOffset" 5
sgsdk_AddAttributeToNode DiffuseTexture "g_VOffset" 6
from pymxs import runtime as rt
rt.sgsdk_AddAttributeToNode(DiffuseTexture, 'g_UTiling', 1)
rt.sgsdk_AddAttributeToNode(DiffuseTexture, 'g_VTiling', 2)
rt.sgsdk_AddAttributeToNode(DiffuseTexture, 'g_UOffset', 5)
rt.sgsdk_AddAttributeToNode(DiffuseTexture, 'g_VOffset', 6)
Back-mapping to custom shader
Specifies to which shader and texture slot the baked texture will get connected to after the processing has been completed.
sgsdk_ConnectOutputToDirectXMaterial effectFile "Diffuse" "DiffuseTexture"
from pymxs import runtime as rt
rt.sgsdk_ConnectOutputToDirectXMaterial(effectFile, 'Diffuse', 'DiffuseTexture')
More about shading networks
Get to know how to work with shading networks: