## 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