Scripting: ExportShaderCompound

ExportShaderCompound

Introduced

v7.0

Description

Exports a shader compound. Shader compounds can only be used outside the scene in which they are created if they are saved to disk in the XML-based format that defines shader compounds: .xsirtcompound (Softimage Render Tree Compound).

By default, shader compounds are saved in text format and do not save any nested shaders embedded directly in the file, but rather reference them. However, if the nested shaders have not yet been exported themselves or their file cannot be found, they will be embedded in the .xsirtcompound file.

Once you have exported a shader compound, you can import it and reference it in any scene, or distribute it. If you would like to protect your compound by saving it in an encoded format, you can change the default behavior by passing True to the Private argument.

Scripting Syntax

oReturn = ExportShaderCompound( [Compound], FullPath, ForceEmbedded );

Return Value

Nothing

Parameters

Parameter	Type	Description
Compound	String	Compound to export. Default Value: Current selection
FullPath	String	Where to save the compound on disk.
ForceEmbedded	Boolean	True to force any nested shader compounds to be embedded inside the same exported .xsirtcompound file, instead of being referenced, as is the usual case. Note: If any nested shaders have not been exported already (that is, if there is no .xsirtcompound file on disk), they will be embedded, regardless of this setting. Default Value: False

Examples

JScript Example

/*
        This example demonstrates how to set up and export a shader compound containing another nested
        shader compound, where the nested shader compound can be either embedded or referenced.
*/
// For readability, we are always saving to the user's RTCompounds directory
var path = XSIUtils.BuildPath(
        Application.InstallationPath(siUserPath),
        "Data", "RTCompounds"
);
// Convenience function to create and export a shader compound (innerSC.xsirtcompound)
// that we will reference/nest in the outerSC*.xsirtcompound shader compounds.
function CreateInnerCompound()
{
        NewScene( null, false );
        CreatePrim( "Torus", "MeshSurface" );
        CreateShaderFromPreset( "Shaders\\Texture\\Gradient.Preset", 
                "Sources.Materials.DefaultLib.Scene_Material" );
        CreateShaderFromPreset( "Shaders\\Texture\\Grid.Preset", 
                "Sources.Materials.DefaultLib.Scene_Material" );
        SIConnectShaderToCnxPoint( "Sources.Materials.DefaultLib.Scene_Material.Grid", 
                "Sources.Materials.DefaultLib.Scene_Material.Phong.ambient", false );
        SIConnectShaderToCnxPoint( "Sources.Materials.DefaultLib.Scene_Material.Gradient", 
                "Sources.Materials.DefaultLib.Scene_Material.Grid.line_color", false );
        CreateShaderCompound( "Sources.Materials.DefaultLib.Scene_Material.Gradient,"
                + "Sources.Materials.DefaultLib.Scene_Material.Grid" );
        ExportShaderCompound( "Sources.Materials.DefaultLib.Scene_Material.ShaderCompound", 
                path+"\\innerSC.xsirtcompound" );
}
// Convenience function to create and export two shader compounds (outerSCembedd*.xsirtcompound)
// and outerSCreffed.xsirtcompound), both of which contain the nested shader compound created
// with the CreateInnerCompound() function. This function can be called to export the shader
// compound with either a referenced (default) nested shader, or an embedded nested shader.
function CreateOuterCompound( in_embed )
{
        NewScene( null, false );
        CreatePrim( "Torus", "MeshSurface" );
        // This is where we reference and connect the exported shader compound already
        // created in the CreateInnerCompound() function
        ImportShaderCompound( "Sources.Materials.DefaultLib.Scene_Material", 
                path+"\\innerSC.xsirtcompound" );
        SIConnectShaderToCnxPoint( "Sources.Materials.DefaultLib.Scene_Material.ShaderCompound.ambient", 
                "Sources.Materials.DefaultLib.Scene_Material.Phong.ambient", false );
        CreateShaderFromPreset( "Shaders\\Texture\\Fractal.Preset", 
                "Sources.Materials.DefaultLib.Scene_Material" );
        SIConnectShaderToCnxPoint( "Sources.Materials.DefaultLib.Scene_Material.Fractal", 
                "Sources.Materials.DefaultLib.Scene_Material.Phong.specular", false );
        CreateShaderFromPreset( "Shaders\\Texture\\Ripple.Preset", 
                "Sources.Materials.DefaultLib.Scene_Material" );
        SIConnectShaderToCnxPoint( "Sources.Materials.DefaultLib.Scene_Material.Ripple", 
                "Sources.Materials.DefaultLib.Scene_Material.Phong.diffuse", false );
        CreateShaderCompound( "Sources.Materials.DefaultLib.Scene_Material.ShaderCompound,"
                + "Sources.Materials.DefaultLib.Scene_Material.Fractal,"
                + "Sources.Materials.DefaultLib.Scene_Material.Ripple" );
        // Embedded or Referenced? This setting corresponds to the innerSC.xsirtcompound, which
        // was imported and connected earlier in this function
        if (in_embed) {
                ExportShaderCompound( "Sources.Materials.DefaultLib.Scene_Material.ShaderCompound1", 
                        path+"\\outerSCembedd.xsirtcompound", true );
        } else {
                ExportShaderCompound( "Sources.Materials.DefaultLib.Scene_Material.ShaderCompound1", 
                        path+"\\outerSCreffed.xsirtcompound", false );
        }
}
// Create a shader compound and save it disk
CreateInnerCompound();
// Create a shader compound which references the first one (innerSC.xsirtcompound)
// and then export two versions: one referenced (outerSCreffed.xsirtcompound) and
// the other embedded (outerSCembedd.xsirtcompound)
CreateOuterCompound();
CreateOuterCompound(true);