<     > 

Execution Flow

Realtime shaders appear in the Softimage interface under these circumstances:

• The object is using a material that has realtime shaders connected to it and the viewport is set to realtime shaders > OpenGL or realtime shader > DirectX.

• The object is using an override material as part of an graphic sequencer display pass.

The following sections describe the execution flow for a realtime shader in Softimage:

• DLL Initialization

• Realtime Shader Initialization

• Realtime Shader Property Page Redraw

• Realtime Shader Execution

• Realtime Shader Termination

The information in the following sections is overview (high-level) information only. For detailed information, see the Realtime Shader API reference.

DLL Initialization

When the .DLL/.SO is initialized, the first function to be called is GetVersion. This function should return the following constant:

XSI_RTSHADER_VERSION 

Realtime Shader Initialization

When realtime shaders can be executed (i.e. the viewport is set to one of the realtime shader modes), and a realtime shader is created, the Init function is called. This is where you can create instance user data and where you should initialize it via the IRTSExecutionState object.

Realtime Shader Property Page Redraw

You can trigger a re-initialization by returning an answer to the GetRequirements callback function with these two requirement types:

• RTS_REQUIRE_PRIMARYINITUIGUID

• RTS_REQUIRE_SECONDARYINITUIGUID

Then, when the shader connections change, or when one of the specified parameters is changed, the InitUI callback function is called. You can create instance user data and initialize it as well.

Realtime Shader Attribute Definition

You can define which attributes should be rendered by declaring XSI_RTS_Attribute structures for the GetAttributeList callback function to return. Softimage takes this list of XSI_RTS_Attribute structs and passes it to the Execute function when it’s time to draw. At that time you can set certain conditions under which each structure will be used to define how to render the geometry.

For more information, see Geometry Data. For an example demonstrating how the XSI_RTS_Attribute structure and the GetAttributeList and Execute callback functions work together, see Example: Rendering according to PPG settings.

Realtime Shader Execution

Every time the object that uses the material to which the shader is attached needs to be redrawn, the Execute function is called. The Execute function provides access to the IRTSExecutionState object, which allows you to:

• access scene data

• render geometry

• raise errors

• get legacy information

• etc.

Example: Rendering according to PPG settings

// Specify two color attributes 
XSI_RTS_Attribute __gAttributesWithColor [] =
{
   XSI_RTS_ATTRIBUTE_POSITION, ePOSITION,
   XSI_RTS_ATTRIBUTE_NORMAL, eNORMAL,
   XSI_RTS_ATTRIBUTE_COLOR, eCOLOR0,
   XSI_RTS_ATTRIBUTE_COLOR, eCOLOR1,
   "Foobar",   eTEXCOORD0
};

// Specify no color attributes 
XSI_RTS_Attribute __gAttributesWithoutColor [] =
{
   XSI_RTS_ATTRIBUTE_POSITION, ePOSITION,
   XSI_RTS_ATTRIBUTE_NORMAL, eNORMAL,
   "Foobar",   eTEXCOORD0
};

// The property page has a parameter to determine 
// whether or not to render color
struct ShaderPPG
{
   bool useColor;
};

// Tell Softimage to render with the two color attributes if the 
// PPG useColor parameter is set to true; otherwise no color
RTSHADER_API XSI_RTS_Attribute* MyShader_GetAttributeList
(
   IRTSExecutionState  *in_pExecState,
   void       *in_pParams,
   void       **io_pInstanceData
)
{
   ShaderPPG* options = (ShaderPPG*)in_pParams;

   if (options->useColor)
   {
       return __gAttributesWithColor;
   } else {
       return __gAttributesWithoutColor;
   }
}

// Now the correct attributes can be accessed for rendering:
// the third element could be either a color or a foobar
// depending on the context
RTSHADER_API bool MyShader_Execute
(
   IRTSExecutionState   *in_pExecState,
   void          *in_pParams,
   XSI_RTS_Primitive    *in_pPrimitive,
   void          *in_pAttributes,
   eXSI_Attribute_Size  *in_pAttributesSize,
   void          **io_pInstanceData
)
{
   ShaderPPG* options = (ShaderPPG*)in_pParams;

   if (options->useColor)
   {
       float* pfPositions = ((float**)in_pAttributes)[0];
       float* pfNormals = ((float**)in_pAttributes)[1];
       float* pfColors0 = ((float**)in_pAttributes)[2];
       float* pfColors1 = ((float**)in_pAttributes)[3];
       float* pfFoobars = ((float**)in_pAttributes)[4];
       ...
   } else {
       float* pfPositions = ((float**)in_pAttributes)[0];
       float* pfNormals = ((float**)in_pAttributes)[1];
       float* pfFoobars = ((float**)in_pAttributes)[2];
       ...
   }

   ...
}

Realtime Shader Termination

When a realtime shader is destroyed, the Term function is called.

Autodesk Softimage v7.5     <     >