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

See Also

AddObjectsToShader RemoveObjectsFromShader RemoveShaderFromCnxPoint RemoveAllShadersFromCnxPoint SIConnectShaderToCnxPoint ReplaceShaderWithPreset ReplaceShaderWithProgID