Scripting: ApplyShader

ApplyShader

Introduced

v1.0

Description

Creates and connects a shader to the material property of an object, group, layer, partition or cluster. If the object does not own a material property, but rather inherits it, then one is created and added to the object. For 3D objects you can control whether the material is added locally or on branch by using the PropagationType argument; by default the material is added locally. Groups, Layers, Partitions, and Clusters do not support both local and branch properties. Materials on clusters are always added locally; and for Groups, Layers, and Partitions, materials are always added in branch mode.

Note: If you use the ApplyShader command on an object that already has either a local or branch material property, the material property is deleted and replaced with a new material property.

Scripting Syntax

ApplyShader( [PresetObj], [InputObjs], [Name], [PropagationType], [ActionWhenLocalMaterialsOverlap] );

Parameters

Parameter	Type	Description
PresetObj	String or a preset object (for example, an object obtained from SIGetPreset)	One of the Shader Presets representing the shader you want to connect. Warning: The default value ("Phong") does not work with some objects. For instance, if the target object is a light, then Preset must be specified since phongs don't apply to a light. Default Value: "Phong" (Phong shader)
InputObjs	String	The list of objects to connect the shader to. Default Value: Current selection
Name	String	Name of the shader Default Value: Default shader name
PropagationType	siBranchFlag	Propagation type of the shader, node or branch Default Value: siUnspecified
ActionWhenLocalMaterialsOverlap	siActionWhenLocalMaterialsOverlap	What to do when the material is applied on a cluster which overlaps with another. Default Value: siPromptUser (unless user pref dictates otherwise)

Examples

VBScript Example

'
' This example demonstrates how to apply different kinds of shaders
' to scene objects. It also shows how you can set individual values
' on your shader material once it is applied.
'
NewScene , false
' Get the default pass
Set oDefPass = GetValue( "Passes.Default_Pass" )
' Create a sphere and apply a default shader to it (since the
' sphere is already selected we don't need to specify it as 
' an input object)
Set oSphere = CreatePrim( "Sphere", "MeshSurface" )
ApplyShader
' Tweak the color values on the sphere's material using the Shader
' parameter shortcuts "diffuse" and "ambient"
Set oPhong = oSphere.Material.Shaders( "Phong" )
oPhong.diffuse.Parameters( "red" ).Value = 0.9
oPhong.diffuse.Parameters( "green" ).Value = 0.5
oPhong.ambient.Parameters( "green" ).Value = 0.7
' View the results in a rendered frame. (You can see the sphere
' has a magenta color)
RenderPasses oDefPass, 1, 1
' Create a default light and apply a preset shader to it
Set oLight = GetPrimLight()
Translate oLight, 8, 3.0, 3, siAbsolute, siView, siObj, siXYZ
ApplyShader "Light\Fast_light_effects", oLight
' View the results in a rendered frame. (You can see the sphere
' now has the default texture wrapped around it)
RenderPasses oDefPass, 1, 1
' Create a cube
Set oCube = CreatePrim( "Cube", "MeshSurface" )
Scale oCube, 0.3, 0.3, 0.3, siAbsolute, siParent, siObj, siXYZ
Translate oCube, 3.5, -2.5, 4, siAbsolute, siView, siObj, siXYZ
' Add the cube to a new layer 
CreateLayer , "CubeLayer", oCube, oLayer
' Apply a shader to the layer and tweak its values
ApplyShader "Illumination\Blinn_shading", oLayer
Set oBlinn = oLayer.Material.Shaders( "Blinn_shading" )
oBlinn.ambient.Parameters( "green").Value = 0.9
' View the results in a rendered frame. (Now there is a small
' cube next to the sphere and on its top the sphere's texture 
' is reflected)
RenderPasses oDefPass, 1, 1