FindObjects

Introduced

v1.0

Description

Finds objects by their type

Scripting Syntax

oReturn = FindObjects( [Path], [Type] );

Return Value

Returns an XSICollection object that contains the found objects.

Parameters

Parameter Type Description
Path String Object path name - NOT IMPLEMENTED
Type String The Class ID of the Object. This is GUID which uniquely identifies each type of object. For example, each instance of a Phong shader has the same Class ID, which is different from the Class ID of a Lambert shader. You can determine the Class ID from the Reference line of the SPDL file or via DataRepository.GetIdentifier. Note: To find Self-Installed Custom Operators use "{72936430-9B0C-4167-8CA7-C30FC2188BB9}" and to find Self-Installed Custom Properties use "{76332571-D242-11d0-B69C-00AA003B3EA6}".

Examples

1. JScript Example

/*
        Demonstrates how to use FindObjects to get all models
*/
NewScene( null, false ) ;
var oModel = ActiveSceneRoot.AddModel(null, "MyModel" ) ;
var oNestedModel = oModel.AddModel(null, "Nested1" ) ;
var oNestedModel = oModel.AddModel(null, "Nested2" ) ;
var oNotAModel = oModel.AddNull() ; // Won't be found
var classIDOfModels = XSIUtils.DataRepository.GetIdentifier( oModel, siObjectCLSID ) ;
var oColl = FindObjects( null, classIDOfModels ) ;
Application.LogMessage( "FindObjects found " + oColl.GetAsText() ) ;
// An alternative way to find models is with the Model property
var oModelsUnderSceneRootModel =  ActiveSceneRoot.Models ;
for ( var i = 0 ; i < oModelsUnderSceneRootModel.count ; i++ )
{
        Application.LogMessage( oModelsUnderSceneRootModel.Item( i ) ) ;                
}
//Expected results:
//
//INFO : FindObjects found MyModel,Nested1,Nested2,Scene_Root
//INFO : MyModel
//INFO : Nested1
//INFO : Nested2

2. JScript Example

SetupDemoScene() ;
DemoSearchFunctions(); 
// General function to find all custom properties. This returns a XSICollection and includes all custom properties
// that are part of the scene, or installed as custom preferences or "free-floating"
function FindAllCustomProperties( oParent )
{
        // All Custom Properties are registered with this GUID
        return FindObjects( null, "{76332571-D242-11d0-B69C-00AA003B3EA6}" ) ;
}
// Function to only find the "CustomColor" Custom Property
function FindCustomColorProperties()
{
        var oAllCustomProperties = FindObjects( null, "{76332571-D242-11d0-B69C-00AA003B3EA6}" ) ;
        var oFilteredList = new ActiveXObject( "XSI.Collection" ) ;
        for ( var i = 0 ; i < oAllCustomProperties.Count ; i++ )
        {
                if ( oAllCustomProperties(i).Type == "CustomColor" )
                {
                        oFilteredList.Add( oAllCustomProperties(i) ) ;
                }
        }               
        return oFilteredList ;
}
// Function to find all psets under a particular 3dobject
function FindNestedCustomProperties( oParent )
{
        var oAllCustomProperties = FindObjects( null, "{76332571-D242-11d0-B69C-00AA003B3EA6}" ) ;
        var oFilteredList = new ActiveXObject( "XSI.Collection" ) ;
        for ( var i = 0 ; i < oAllCustomProperties.Count ; i++ )
        {
                // This will be null for free floating custom properties, 
                // custom preferences, objects nested under a shader etc
                o3DObjectOfCustomProperty = oAllCustomProperties(i).Parent3DObject ;
                if ( o3DObjectOfCustomProperty  != null &&
                        o3DObjectOfCustomProperty.FullName == oParent.FullName )
                {
                        oFilteredList.Add( oAllCustomProperties(i) ) ;
                }
        }               
        return oFilteredList ;
}
// Build a scene with Custom Properties at various places
function SetupDemoScene()
{
        NewScene( null, false ) ;
        ActiveSceneRoot.AddProperty( "CustomColor", false, "MyColor" ) ;
        ActiveSceneRoot.AddProperty( "CustomColor", false, "MyColor2" ) ;
        ActiveSceneRoot.AddProperty( "CustomProperty", false, "MyEmptyCustomProp" ) ;
        oSphere = ActiveSceneRoot.AddGeometry( "Sphere", "MeshSurface" ) ;
        oSphere.AddProperty( "CustomColor", false, "ColorUnderSphere" ) ;
        oCls = oSphere.ActivePrimitive.Geometry.AddCluster( "edge", "MyCluster" ) ;
        oCls.AddProperty( "CustomColor", false, "MyColor" ) ;
        oSphere.AddMaterial( "Phong" ) ;
        var oPhongShader = oSphere.Material.Shaders(0)
        oPhongShader.AddProperty( "CustomProperty", false, "EmptyNestedProp" ) ;
        oPhongShader.AddProperty( "CustomProperty", false, "MyColor" ) ;        
        var oModel = ActiveSceneRoot.AddModel(null, "MyModel" ) ;
        oModel.AddProperty( "CustomColor", false, "MyColor3" ) ;
        oModel.AddProperty( "CustomProperty", false, "EmptyProperty" ) ;
        oModel.AddNull().AddProperty( "CustomColor", false, "MyColor4" ) ;
        // Create a PSet that doesn't belong anywhere in the scene
        // It's fullname will be something like "CustomColor<yyyy>"
        // where yyyy is a number.
        var oFreeFloatingPSet = XSIFactory.CreateObject( "CustomColor" ) ;                      
}
// Show the result of calling the Find functions
// with the demo scene
function DemoSearchFunctions()
{
        // All Custom Properties
        //
        //Example output (in this case a Custom Preference called
        //XSI_UserNormalEditing is installed):
        //INFO : ------------------------------------------------
        //INFO : All Custom Properties
        //INFO : ------------------------------------------------
        //INFO : sphere.polymsh.cls.MyCluster.MyColor
        //INFO : Sources.Materials.DefaultLib.Material.Phong.EmptyNestedProp
        //INFO : MyEmptyCustomProp
        //INFO : MyColor2
        //INFO : preferences.XSI_UserNormalEditing
        //INFO : CustomColor<1068>
        //INFO : MyColor
        //INFO : MyModel.EmptyProperty
        //INFO : Sources.Materials.DefaultLib.Material.Phong.MyColor
        //INFO : sphere.ColorUnderSphere
        //INFO : MyModel.null.MyColor4
        //INFO : MyModel.MyColor3
        var oAllCustomProperties = FindAllCustomProperties() ;
        PrintCollection( oAllCustomProperties, "All Custom Properties" ) ;
        // Find only the Custom Properties that come from the "Custom Color"
        // Self-installed Property
        //
        //Example output:       
        //INFO : ------------------------------------------------
        //INFO : Custom Color Properties
        //INFO : ------------------------------------------------
        //INFO : sphere.polymsh.cls.MyCluster.MyColor
        //INFO : MyColor2
        //INFO : CustomColor<1068>
        //INFO : MyColor
        //INFO : sphere.ColorUnderSphere
        //INFO : MyModel.null.MyColor4
        //INFO : MyModel.MyColor3               
        var oCustomColorOnly = FindCustomColorProperties() ;
        PrintCollection( oCustomColorOnly , "Custom Color Properties" ) ;
        // Find all the custom properties nested under the sphere
        // Note: It does not include custom properties that are part 
        // of the material of the Sphere.
        //
        //Example output:
        //INFO : ------------------------------------------------
        //INFO : Custom Properties Under Sphere
        //INFO : ------------------------------------------------
        //INFO : sphere.polymsh.cls.MyCluster.MyColor
        //INFO : sphere.ColorUnderSphere
        var oSphereCustomProps = FindNestedCustomProperties( GetValue( "Sphere" ) ) ;
        PrintCollection( oSphereCustomProps , "Custom Properties Under Sphere" ) ;
        // These are custom properties directly under the scene root (not
        // including those nested inside X3DObjects)
        //
        //Example output:
        //INFO : ------------------------------------------------
        //INFO : Custom Properties Under Scene Root
        //INFO : ------------------------------------------------
        //INFO : MyEmptyCustomProp
        //INFO : MyColor2
        //INFO : MyColor        
        var oSceneRootCustomProps = FindNestedCustomProperties( ActiveSceneRoot ) ;
        PrintCollection( oSceneRootCustomProps, "Custom Properties Under Scene Root" ) ;                
}
// Show contents of a XSICollection object in the Script history
function PrintCollection( in_col, in_title )
{
        LogMessage( "------------------------------------------------" ) ;
        LogMessage( in_title ) ;
        LogMessage( "------------------------------------------------" ) ;
        for ( var i = 0 ; i < in_col.Count ; i++ )
        {
                LogMessage( in_col(i).FullName ) ;              
        }
}

3. JScript Example

/*
        This example demonstrates how FindObjects can be used to quickly find all instances of a particular type of shader.
        This approach can be faster than doing a recursive search through all the scene shader trees.
*/
SetupDemoScene() ;
LogMessage( DiscoverCloudClassID() ) ;
//INFO : {A85CBE5F-DDD7-11D1-804A-00A0C906835D}
LogMessage( DiscoverImageClassID() ) ;
//INFO : {1C500B61-023C-11D3-8C03-00A0243E3672}
var oAllClouds = FindCloudShaders() ;
PrintCollection( oAllClouds, "All Cloud Shaders" ) ;
//INFO : ------------------------------------------------
//INFO : All Cloud Shaders
//INFO : ------------------------------------------------
//INFO : Sources.Materials.DefaultLib.Material.Phong.Cloud1
//INFO : Sources.Materials.DefaultLib.Material.Phong.Cloud1.Cloud2
//INFO : Sources.Materials.DefaultLib.Material1.Lambert.Cloud3
//INFO : Sources.Materials.DefaultLib.Material1.Lambert.Cloud3.Cloud4
//INFO : Sources.Materials.DefaultLib.Material1.Lambert.Cloud5
var oAllImages = FindImageShaders() ;
PrintCollection( oAllImages, "All Image Shaders" ) ;
//INFO : ------------------------------------------------
//INFO : All Image Shaders
//INFO : ------------------------------------------------
//INFO : Sources.Materials.DefaultLib.Material.Phong.Image
function FindCloudShaders()
{
        // This GUID was determined by calling DiscoverCloudClassID().
        // Because it never changes it can be hardcoded rather than
        // being re-discovered each time the script is run
        return FindObjects( null, "{A85CBE5F-DDD7-11D1-804A-00A0C906835D}" ) ;  
}
function FindImageShaders()
{       
        // Using GUID returned by DiscoverImageClassID()        
        return FindObjects( null, "{1C500B61-023C-11D3-8C03-00A0243E3672}" ) ;  
}
// Function to determine the ClassID of the Cloud Shader
// Similar code can work for custom shaders, and the GUID can also
// be read from the SPDL file and is visible in the SDK Explorer 
function DiscoverCloudClassID()
{
        var oTempCloud = XSIFactory.CreateObjectFromPreset( 
                        "Cloud", 
                        "Texture Shaders" ) ;
        var oCloudGUID = GetClassID( oTempCloud ) ;
        // Delete the shader right away so it doesn't appear when we search
        DeleteObj( oTempCloud ) ;
        return oCloudGUID ;
}
function DiscoverImageClassID()
{
        var oTempImageNode = XSIFactory.CreateObjectFromPreset( 
                        "Image", 
                        "Texture Shaders" ) ;
        var oImageGUID = GetClassID( oTempImageNode ) ;
        DeleteObj( oTempImageNode ) ;
        return oImageGUID ;
}
// Determine the ClassID GUID of a particular object.
// All other instances of this object have this same GUID
// and it never changes.
function GetClassID( in_ExampleObject )
{
        oDataRepository = XSIUtils.DataRepository ;
        return oDataRepository.GetIdentifier( in_ExampleObject, siObjectCLSID ) ;
}
// Build some render trees with the Object Model
// They don't make any sense in terms of rendering
// a nice texture, but show nodes connected in various ways
function SetupDemoScene()
{
        NewScene( null, false ) ;
        // First render tree
        oSphere = ActiveSceneRoot.AddGeometry( "Sphere", "MeshSurface" ) ;
        oSphere.AddMaterial( "Phong" ) ;
        var oPhongShader = oSphere.Material.Shaders(0) ;
        ImageFile1 = XSIUtils.BuildPath( Application.InstallationPath(siFactoryPath),
                                        "Data",
                                        "XSI_SAMPLES",
                                        "Pictures",
                                        "jaiqua_face.jpg" ) ;
        var oImageClip1 = SICreateImageClip2( ImageFile1 ).Item(0) ;
        var oAmbientParam = oPhongShader.Parameters( "ambient" )
        var oImageNode1 = oAmbientParam.connectfrompreset("Image", siTextureShaderFamily) ;
        oImageNode1.Parameters( "tex" ).Connect( oImageClip1 ) ;
        var oDiffuseParam = oPhongShader.Parameters( "diffuse" )
        var oCloud1 = oDiffuseParam.connectfrompreset("Cloud", siTextureShaderFamily) ;
        oCloud1.Name = "Cloud1" ;
        var oCloud1Color1 = oCloud1.Parameters("color1") ;
        var oCloud2 = oCloud1Color1.connectfrompreset("Cloud", siTextureShaderFamily) ;
        oCloud2.Name = "Cloud2" ;
        //Second render tree
        oCone = ActiveSceneRoot.AddGeometry( "Cone", "MeshSurface" ) ;
        oCone.AddMaterial( "Lambert" ) ;
        var oLamberShader = oCone.Material.Shaders(0) ;
        oDiffuseParam = oLamberShader.Parameters( "diffuse" ) ;
        var oCloud3= oDiffuseParam.connectfrompreset("Cloud", siTextureShaderFamily);
        oCloud3.Name = "Cloud3" ;
        oCloud3Color2 = oCloud3.Parameters( "color2" ) ;
        oCloud4= oCloud3Color2.connectfrompreset("Cloud", siTextureShaderFamily);
        oCloud4.Name = "Cloud4"
        // Fractal is connected twice. This can provide a tricky
        // scenario for recursive scans of a shader tree, because the
        // same shaders can appear multiple times.  
        // But FindObjects() would have not trouble finding just one instance
        // of this object
        oCloud3Color1 = oCloud3.Parameters( "color1" ) ;
        oCloud3Color1.Connect( oCloud4 ) ;      
        oAmbientParam = oLamberShader.Parameters( "ambient" ) ;
        oCloud5 = oAmbientParam.connectfrompreset("Cloud", siTextureShaderFamily) ;
        oCloud5.Name = "Cloud5" ;       
}
// Show contents of a XSICollection object in the Script history
function PrintCollection( in_col, in_title )
{
        LogMessage( "------------------------------------------------" ) ;
        LogMessage( in_title ) ;
        LogMessage( "------------------------------------------------" ) ;
        for ( var i = 0 ; i < in_col.Count ; i++ )
        {
                LogMessage( in_col(i).FullName ) ;              
        }
}

4. JScript Example

// Demonstration of how to use FindObjects to 
// find Runtime scripted operators in the scene.
//
// This technique does not find SPDL-based custom operators
// because once a Custom Operator is stored inside a SPDL file
// it is assigned its own GUID, which is found as the Reference 
// value at the top of the file.
function GetAllRuntimeCustomOperators()
{
        var siScriptedOperatorID = "{CCECD9D9-10A3-11d4-879F-00A0C983050D}"
        var oItems = FindObjects(null,siScriptedOperatorID)
        // For convenience to the caller,
        // always return a collection even if nothing was found
        if ( oItems == null )
                oItems = new ActiveXObject( "XSI.Collection") ;
        return oItems ;
}
// Simple usage of GetAllRuntimeCustomOperators
function SelectAllRuntimeOperators()
{
        SelectObj( GetAllRuntimeCustomOperators() ) ;
}
//
// Demonstration of GetAllRuntimeCustomOperators
//
function BuildDemoScene()
{
        var oNull = Application.ActiveSceneRoot.AddNull() ;
        var oPosX = oNull.Kinematics.Global.Parameters( "posx" ) ;
        var oRotX = oNull.Kinematics.Local.Parameters( "rotx" ) ;
        AddSimpleOp( oPosX ) ;
        AddSimpleOp( oRotX ) ;  
}
function AddSimpleOp( in_param )
{
        // Build a runtime operator that drives in_param
        var oOp = XSIFactory.CreateScriptedOp( 
                                "FindMe",
                                FindMe_Update.toString(),
                                "JScript" ) ;
        oOp.AlwaysEvaluate = true ;             
        oOp.AddOutputPort( in_param ) ;
        oOp.Connect() ;
}
function FindMe_Update(ctx,out)
{
        // Just set the output parameter
        // to current frame value
        out.Value = ctx.CurrentFrame ;
}
BuildDemoScene() ;
var oOps = GetAllRuntimeCustomOperators() ;
for ( var i = 0 ; i < oOps.Count ; i++ )
{
        Application.LogMessage( oOps(i).FullName )  ;
}
//Expected output:
//INFO : null.kine.global.FindMe
//INFO : null.kine.local.FindMe

See Also

DataRepository.GetIdentifier X3DObject.FindChildren XSIFactory.CreateObject XSIFactory.CreateObjectFromPreset SIObject.NestedObjects