Parameter.SetInstanceValue

Introduced

v5.0

Description

Sets an instance value for specified object. Instance values only applied to Property objects that can be shared or Shader objects connected under shared Material object. For example, the ImageShader.tspace_id parameter is an instance value.

For parameters supporting object binding (such as a texturespace parameter) this method will accept a valid SIObject as an instance value. It will validate that the object is supported and will set the value using the name of the object. If the object is not supported it will return false.

If the object does not exist you can set the instance value using the name of the object and set the Bind argument to false.

Note: Instance values cannot be animated, so this method doesn't take a time argument.

Scripting Syntax

oBoolean = Parameter.SetInstanceValue( Object, Value, [Bind] );

Return Value

Boolean

Parameters

Parameter Type Description
Object Object such as a X3DObject Object nesting the shared property
Value Variant New value for instance. This may be the object itself, such as the UVW texture property or the name of the object.
Bind Boolean If the instance value supports object binding and the value passed is a string then the method will attempt to test for the existence of a supported object specified by the string. If the object does not exist the method will return False.

Default Value: False

Examples

JScript Example

/*
        This example illustrates how to set instance values on a shared material parameter
        Applies to parameters: ImageShader.tspace_id, Material.ImageClipName, Material.UV, Material.CAV.
*/
NewScene( null, false );
var app = Application;
var scene = app.ActiveProject.ActiveScene;
var root = scene.Root;
// Create cube with a texture projection (not connected)
var cube = root.AddGeometry( "Cube", "MeshSurface", "MyCubeWithTexture" );
// Create projection for cube
CreateProjection( 
        cube, 
        siTxtCubic, 
        siTxtDefaultCubic , 
        "MyCubicTextureSupport", 
        "MyCubicTextureProjection" ); 
// Create sphere with a texture projection (not connected)
var sphere = root.AddGeometry( "Sphere", "MeshSurface", "MySphereWithTexture" );
// Create projection for sphere
CreateProjection( 
        sphere, 
        siTxtSpherical, 
        siTxtDefaultSpherical, 
        "MySphericalTextureSupport", 
        "MySphericalTextureProjection" ); 
// Create a group with a material hooked up to texture image
var objs = XSIFactory.CreateObject( "XSI.Collection" );
objs.Add( cube );
objs.Add( sphere );
var group = root.AddGroup( objs, "MyGroup", false );
var mat = group.AddMaterial( "Blinn", false, "MyGroupMaterialWithTexture" );
var shaders = mat.Shaders;
var blinn = shaders(0);
var ambient = blinn.Parameters("ambient");
var diffuse = blinn.Parameters("diffuse");
// Create image clip
var strFileName = app.InstallationPath( siFactoryPath ) + "\\Data\\XSI_SAMPLES\\Pictures\\xsilogo.jpg";
var imageclip = CreateImageClip( strFileName, "MyImageClip" );
// Connect imageshader1 to blinn.ambient
var imageshader1 = ambient.ConnectFromPreset( "Image", siTextureShaderFamily );
// Connect imageshader2 to blinn.diffuse
var imageshader2 = diffuse.ConnectFromPreset( "Image", siTextureShaderFamily );
// Connect the imageshader1.tex to imageclip
var tex = imageshader1.Parameters("tex");
tex.Connect( imageclip );
// get tspace_id from imageshader
var tspace_id = imageshader1.Parameters("tspace_id");
// set the cube.material.image.tspace_id = MyCubicTextureProjection
tspace_id.SetInstanceValue( cube, "MyCubicTextureProjection" );
// set the sphere.material.image.tspace_id = MySphericalTextureProjection
tspace_id.SetInstanceValue( sphere, "MySphericalTextureProjection" );
// Dump all shader parameter instance values for each objects found using 
// a material from the active  material library
var matlib = scene.ActiveMaterialLibrary;
for ( var i=0; i<matlib.Items.Count; i++ ) {
        var mat = matlib.Items(i);
        // Get all shaders in materials shader tree
        var shaders = mat.FindShaders( siShaderFilter );
        for ( j=0; j<shaders.Count; j++ ) {  
                var shader = shaders(j);
                for ( var k=0; k<shader.Parameters.Count; k++ ) {
                        var shader_param = shader.Parameters(k);
                        // If the shader parameter has an instance value look up
                        // its object value
                        if ( shader_param.HasInstanceValue ) {
                                var eObjs = new Enumerator( mat.UsedBy );
                                for ( ; !eObjs.atEnd(); eObjs.moveNext() ) {
                                        var obj = eObjs.item();
                                        var instancevalue = shader_param.GetInstanceValue( obj );
                                        // Log parameter instance value for object
                                        app.LogMessage( obj.name + " " + shader.Name + " " + shader_param.Name + " = " + instancevalue  );
                                }
                        }
                }
        }       
}
// Expected results:
//INFO : MyCubeWithTexture Image tspace_id = MyCubicTextureProjection
//INFO : MySphereWithTexture Image tspace_id = MySphericalTextureProjection
//INFO : MyCubeWithTexture Image1 tspace_id = 
//INFO : MySphereWithTexture Image1 tspace_id =

See Also

Parameter.HasInstanceValue Parameter.IsSupportedInstanceValue Parameter.GetInstanceValue