Proxy Parameters

A proxy parameter is a kind of a linked custom parameter, but with a fundamental difference. Linked custom parameters can drive target parameters (that is, the parameters they are linked to), but they are still separate and different parameters. This means that when you set keyframes, you key the custom parameter and not the driven parameter.

So what do you do when you want to drive the actual parameter or expose only certain parameters to build a custom property editor? You can use proxy parameters.

Unlike custom parameters, proxy parameters are actually cloned parameters: they reflect the data of another parameter in the scene. Any operation done on a proxy parameter has the same result as if it had been done on the real parameter itself (change a value, save a key, etc.).

Note

For more information about proxies, see the user guide.

Creating and Accessing Proxy Parameters

You can use the CustomProperty.AddProxyParameter method or AddProxyParam command to create the ProxyParameter object, which gives you access to the master parameter (through the ProxyParameter.MasterParameter property). Otherwise, finding a proxy parameter is the same procedure as finding a regular parameter.

VBScript Example: Creating and Finding a Proxy Parameter

'-----------------------------------------------------
	'SETUP
'
' Set up scene with a null, a cube and a cpset
' containing a proxy to the cube.sclx parameter
NewScene , false
set root = ActiveSceneRoot
root.AddNull
root.AddGeometry "Cube", "MeshSurface"

'-----------------------------------------------------
	'CREATION
'
set cpset = root.AddCustomProperty( "proxy_test" )
cpset.AddProxyParameter "cube.kine.local.sclx"


'-----------------------------------------------------
	'SEARCH
'
' Get a pointer to the proxy parameter and return its info
' NB: The AddProxyParameter method returns the parameter, so this would not
' normally be necessary, this is just to demonstrate finding existing proxies
if TypeName(cpset) <> "Nothing" then
	bFound = false
	for each pxy in cpset.Parameters
		if TypeName(pxy) = "ProxyParameter" then
			bFound = true
			LogMessage pxy.FullName & " is linked to " & pxy.MasterParameter.FullName
		end if
	next
	if Not(bFound) then
		LogMessage "Could not find a proxy parameter on cpset."
	end if
else
	LogMessage "Could not find 'proxy test' custom pset."
end if

'-----------------------------------------------------
	'OUTPUT
'
'INFO : "proxy_test.cube_sclx is linked to cube.kine.local.sclx"

Proxy Parameters in a Self-Installing Plug-in

You can use proxy parameters in self-installing custom properties as well. Instead of defining them in the OnInit callback, check to see if they have already been defined in the OnInit callback and if not, define them and then refresh the page.

JScript Example: Using Proxy Parameters in a Self-Installing Custom Property

This example basically does the same thing as the previous VBScript example but inside a self-installing custom property plug-in. Notice that opening the property page more than once does not create new proxy parameters.

//-----------------------------------------------------
//	SETUP
//
// Set up scene with a null, a cube and a cpset containing a proxy to the cube.sclx parameter
NewScene( null, false );
var root = Application.ActiveSceneRoot;
root.AddNull();
root.AddGeometry( "Cube", "MeshSurface" );

//-----------------------------------------------------
//	SELF-INSTALLING PROPERTY 
//
// Write the helper functions under CREATION & SEARCH below to the plug-in file
var fso = XSIFactory.CreateObject( "Scripting.FileSystemObject" );
var sFilename = XSIUtils.BuildPath( Application.InstallationPath(siUserPath),
	"Application", "Plugins", "ProxyParamDemo.js" );
var ts = fso.CreateTextFile( sFilename, true /* overwrite old ones */ );
ts.Write( XSILoadPlugin.toString() + ProxyParamDemo_Define.toString() + 
	ProxyParamDemo_DefineLayout.toString() + ProxyParamDemo_OnInit );

// Load the plug-in and then open the property page (to fire the OnInit callback)
var oPlugin = Application.LoadPlugin( sFilename );
var oCusProp = root.AddProperty( oPlugin.Items(0).Name );
var bCancel = InspectObj( oCusProp, "", "ProxyParamDemo", siModal, false );


//-----------------------------------------------------
//	OUTPUT
//
//INFO : ProxyParamDemo.cube_sclx is linked to cube.kine.local.sclx


//-----------------------------------------------------
//	CREATION & SEARCH
//
function XSILoadPlugin( in_reg )
{
	in_reg.Author = "Demo";
	in_reg.Name = "ProxyParamDemoPlugin";
	in_reg.Major = 1;
	in_reg.Minor = 0;

	in_reg.RegisterProperty("ProxyParamDemo");
	return true;
}

function ProxyParamDemo_Define( in_ctxt )
{
	var oCustomProperty = in_ctxt.Source;
	return true;
}

function ProxyParamDemo_DefineLayout( in_ctxt )
{
	var oLayout = in_ctxt.Source;
	oLayout.Clear();
	return true;
}

function ProxyParamDemo_OnInit()
{
	// Get the custom property
	var oCustomProperty = PPG.Inspected.Item(0);
	
	// Does the proxy parameter already exist? If not, create it
	if ( oCustomProperty.Parameters.Count < 1 ) {
		// Make sure the cube actually exists
		var oCube = Application.ActiveSceneRoot.FindChild( "", siCubePrimType );
		if ( oCube ) {
			oCustomProperty.AddProxyParameter( oCube.sclx );
		} else {
			Application.LogMessage( "Could not create proxy parameter because the cube does not exist.", siWarning );
		}
	}
	
	// Check each parameter to find the proxy
	var eParams = new Enumerator( oCustomProperty.Parameters );
	for ( ; !eParams.atEnd(); eParams.moveNext() ) {
		var oProxy = eParams.item();
		if ( oProxy.IsClassOf(siProxyParameterID) ) {
			Application.LogMessage( oProxy.FullName + " is linked to " + oProxy.MasterParameter.FullName );
		}
	}
	
	// Refresh the layout so that it appears
	PPG.Refresh();
}

Except where otherwise noted, this work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License