DataRepository.GetConnectionStackInfo

Introduced

v5.1

Description

Returns information in XML format about which objects read from and write to an object. The connection stack is called the ConstructionHistory in the context of a Primitive.

The connection stack can contain connections to Operators, FCurves, Shaders and other objects, so it is more than just a "Operator Stack". The order of the objects in the connection stack is important because it determines the order in which the scene is evaluated. For example, if a scripted operator reads from a Primitive above a deform operator that reads and writes to the Primitive, then the scripted operator will read the deformed version of the geometry, not the original version.

This method returns low-level information, including the presence of hidden objects, that is intended for internal Softimage usage. It is exposed in the SDK primarily to help users write and debug CustomOperators.

The format of the XML may change in the future. Currently it returns the following possible attributes:

object - SIObject.FullName of the object. Empty if there is no active connection.

type - "in" or "out". If "in" it means that the object being queried is reading data from the connected object.

localparameter - Some connections read and write to a specific Parameter. In that case this contains the Parameter.ScriptName.

remoteparameter - If the connection is to a specific parameter on the connected object, then this contains its Parameter.ScriptName.

hidden - "true" if the object has the siNotInspectable capability. See ProjectItem.Capabilities.

region - For internal use.

datacopy - For internal use. This is the internal handle to the object, for example "0x1c9f0448". The value of this handle serves no meaningful purpose in the context of the SDK. Softimage may create several temporary "datacopies" of an individual object to assist in the clean evaluation of the scene.

Scripting Syntax

oString = DataRepository.GetConnectionStackInfo( Object );

Return Value

XML String, containing the connections in a top-to-bottom ordering.

Parameters

Parameter Type Description
Object Softimage Object Object to query, for example a Property or Primitive. Connections are managed at the object level, not the Parameter level.

Examples

1. JScript Example

/*
        This example demonstrates how to use DataRepository.GetConnectionStackInfo
        to find which objects read from a particular object.
*/
NewScene( null, false ) ;
CreatePrim( "Sphere", "MeshSurface" );
ApplyOp( "Twist", "sphere", 3, siPersistentOperation, null, 0 );
SetSelFilter( "Vertex" );
AddToSelection( "sphere.pnt[26,33]", null, true );
Translate( null, 1, 0.2, -1.2, siRelative, siView, siObj, siXYZ );
SelectObj( "Sphere.polymsh" ) ;
// Get the connection information
var oDR = XSIUtils.DataRepository ;
opInfo = oDR.GetConnectionStackInfo( Selection(0) )
// This line would dump the actual XML content:
//Application.LogMessage( "\n----------------\nRAW XML OUTPUT\n------------------\n" + opInfo ) ;
// Get the list of output objects
aOutputs = GetOutputObjects( opInfo ) ;
Application.LogMessage( "Objects that read from the Sphere primitive:\n" + aOutputs.join("\n") ) ;
// Helper function to load the XML data using the Microsoft
// implementation of the DOM (see msdn.microsoft.com for documentation)
function ParseXML( strXML )
{
        var oXMLParser = new ActiveXObject( "Microsoft.XMLDOM" ) 
        oXMLParser.async = false        
        oXMLParser.loadXML( opInfo ) ;
        if (oXMLParser.parseError.errorCode != 0) 
        {
                Application.LogMessage( "Invalid XML " + oXMLParser.parseError.reason , siError ) ;     
                return null ;
        }
        // the xsi_file node
        // If this is NULL we must have failed to load the XML
        var oTopNode = oXMLParser.documentElement ;
        return oTopNode ;
}
// Go through the connection information and determine which connected
// operators/objects are reading from the object
//
// opInfo is the XML string returned by calling DataRespository.GetOperatorStackInfo
function GetOutputObjects( opInfo )
{
        aOutputs = new Array() ;
        var oTopNode = ParseXML( opInfo ) ;
        if ( oTopNode == null ) 
                return aOutputs ;
        var oConnections = oTopNode.childNodes ;
        for ( var i = 0 ; i < oConnections.length ; i++ )
        {
                oConnection= oConnections.item(i) ;
                oObjNode = oConnection.selectSingleNode( "object" ) ;
                strObj = oObjNode.text ;                                
                oTypeNode = oConnection.selectSingleNode( "type" ) ;
                if ( oTypeNode != null && oTypeNode.text == "out" )
                        aOutputs[aOutputs.length] = strObj ;
        }                                               
        return aOutputs ;
}
//Example output:
//
//INFO : Objects that read from the Sphere primitive:
//sphere.polymsh.secondaryshapemarker
//sphere.polymsh.animationmarker
//sphere.polymsh.shapemarker
//sphere.polymsh.modelingmarker
//sphere.polymsh.movecomponentop
//sphere.polymsh.cls.Point_INTERNAL.AddToClsOp
//sphere.polymsh.twistop
//sphere.polymsh.cls.default_Point.SetClsOp

2. JScript Example

/*
        This example demonstrates how to use DataRepository.GetConnectionStackInfo
        to find which objects are influenced by a parameter.
*/
// Create simple scene
NewScene( null, false );
var oSphere = ActiveSceneRoot.AddGeometry( "Sphere", "MeshSurface", "sphere" ) ;
var oSphereGlobalPosx = oSphere.Kinematics.Global.posx ;
// posy parameter on light will be driven by posx parameter of the sphere.
// (This creates an Expression object between the two parameters)
CopyPaste( oSphereGlobalPosx, null, "light.kine.global.posy", 1 );
// posz parameter will also be driven by the posx parameter
CopyPaste( oSphereGlobalPosx, null, "light.kine.global.posz", 1 );
aDependentData = FindDataDrivenByParameter( oSphereGlobalPosx )
for ( var i = 0 ; i < aDependentData.length ; i++ )
{
        Application.LogMessage( aDependentData[i] ) ;
}
// Get the connection information for a particular parameter.  It returns an 
// array of strings with the full name of the expression operator or other 
// object that is reading the value of the in_Parameter argument
function FindDataDrivenByParameter( in_Parameter )
{
        var aConnections = [] ;
        // Connection information is managed at the Object level, not Parameter level
        var oObj = in_Parameter.Parent ;
        var oDR = XSIUtils.DataRepository ;
        opInfo = oDR.GetConnectionStackInfo( oObj )
        var oXMLParser = new ActiveXObject( "Microsoft.XMLDOM" ) 
        oXMLParser.async = false        
        oXMLParser.loadXML( opInfo ) ;
        var oTopNode = oXMLParser.documentElement ;
        var oConnections = oTopNode.childNodes ;
        for ( var i = 0 ; i < oConnections.length ; i++ )
        {
                var oConnection = oConnections(i) ;
                oObjNode = oConnection.selectSingleNode( "object" ) ;
                if ( oObjNode == null )
                        continue ; // Not connected to anything
                // See if this is a connection to the parameter we are interested in
                oParameterNode = oConnection.selectSingleNode( "localparameter" ) ;
                if ( oParameterNode != null )
                {
                        strConnectedParameter = oParameterNode.text ;
                        if ( strConnectedParameter == in_Parameter.ScriptName )
                        {                               
                                // Found a connection to this parameter 
                                strType = oConnection.selectSingleNode( "type" ).text ;
                                if ( strType == "out" )
                                {
                                        aConnections[aConnections.length] =oObjNode.text
                                }
                                // Tip if the type was "in" then it means that the connection is controlling the
                                // value of this parameter, e.g. a FCurve, expression, operator. This information
                                // can also be retrieved with Parameter.Source
                        }
                }       
        }       
        return aConnections ;
}
//Output of this example:
//INFO : light.kine.global.pos.posz.Expression
//INFO : light.kine.global.Expression