RTS API v2.0 Callback Reference
Each shader need to implement the following callback functions:
The <shader>_Execute function is mandatory.
The <shader> prefix is the name of the shader as identified in the SPDL file. For example, if the shader is named OGL13Shade, then you need to implement OGL13Shade_Init, OGL13Shade_Execute, OGL13Shade_Term and OGL13Shade_GetRequirements.
|
These functions return TRUE if successful; otherwise FALSE. All functions receive the system parameters, the property page parameters, and the shader instance user data. Shader instance user data is useful if you want to pass instance data to the <shader>_Term, <shader>_Execute and <shader>_GetRequirements entry points. |
Example
// Implementation RTSHADER_API bool OGL13Shade_Execute ( XSI_RTS_SystemParams *in_pSysParams, // The system parameters void *in_pParams, // The property page parameters XSI_RTS_TriangulatedGeometry *in_pGeom, // The geometry information void **io_pShaderInstanceData // The shader instance data ) { OGL13ShadePPG *ppg = (OGL13ShadePPG *) in_pParams; ::glMaterialfv(GL_FRONT_AND_BACK, GL_AMBIENT , (float *)&ppg->Ambient); ::glMaterialfv(GL_FRONT_AND_BACK, GL_DIFFUSE , (float *)&ppg->Diffuse); ::glMaterialfv(GL_FRONT_AND_BACK, GL_SPECULAR , (float *)&ppg->Specular); ::glMaterialfv(GL_FRONT_AND_BACK, GL_EMISSION , (float *)&ppg->Emission); ::glMaterialf(GL_FRONT_AND_BACK, GL_SHININESS, ppg->Shininess); if(ppg->Lighting) ::glEnable( GL_LIGHTING ); else { ::glDisable( GL_LIGHTING ); ::glColor4fv((float *)&ppg->Diffuse); } // needed because we don't want to have visual regressions with old scenes ::glLightModeli( GL_LIGHT_MODEL_COLOR_CONTROL_EXT, GL_SINGLE_COLOR ); return TRUE; }
Each dynamic library needs to implement the GetVersion callback function. This will tell SOFTIMAGE|XSI which version of the Realtime Shader API this shader was compiled with. The implementation should always be:
RTSHADER_API ULONG RTS_GetVersion()
{
return XSI_RTSHADER_VERSION;
}
The <shader>_Init callback function is called the first time the shader is instantiated:
RTSHADER_API bool <shader>_Init ( XSI_RTS_SystemParams *in_pSysParams, // The system parameters void *in_pParams, // The property page parameters void **io_pShaderInstanceData // The shader instance data )
|
As of v6.5 this callback function is fired the first time the shader is instantiated, but prior to v6.5, this callback function wasn’t called until the first time drawing. |
This function receives the system parameters, the property page parameters, and the shader instance user data.
For example:
typedef struct tagOGLTextureInstanceData
{
int m_Handle;
LONG m_MipMap;
LONG m_Compression;
LONG m_Format;
} OGLTextureInstanceData;
RTSHADER_API bool OGL13Texture_Init
(
XSI_RTS_SystemParams *in_pSysParams, // The system parameters
void *in_pParams, // The property page parameters
void **io_pShaderInstanceData // The shader instance data
)
{
OGLTextureInstanceData *pInstanceData = new OGLTextureInstanceData();
pInstanceData->m_Handle = -1;
*io_pShaderInstanceData = pInstanceData;
return TRUE;
}
The <shader>_InitUI callback function is called when the shader connections change, or one of the two specified parameters is changed:
RTSHADER_API bool <shader>_InitUI ( XSI_RTS_SystemParams *in_pSysParams, // The system parameters void *in_pParams, // The property page parameters void **io_pShaderInstanceData // The shader instance data )
This function receives the system parameters, the property page parameters, and the shader instance user data. The parameters that trigger a call to this callback are defined by returning an answer to <shader>_GetRequirements with the two requirement types RTS_REQUIRE_PRIMARYINITUIGUID and RTS_REQUIRE_SECONDARYINITUIGUID.
For example:
RTSHADER_API bool CgFX_InitUI ( XSI_RTS_SystemParams *in_pSysParams, // The system parameters void *in_pParams, // The property page parameters void **io_pShaderInstanceData // The shader instance data ) { CgFXInstanceData *pInstanceData = (CgFXInstanceData*) *io_pShaderInstanceData; CgFXPPG *l_pPPG = (CgFXPPG*) in_pParams; #ifndef __XSI_PLUGIN_ CGraphicSequencer *pXGS = (CGraphicSequencer *)in_pSysParams->m_pGS; Shader l_Shader = *( (CRef *) in_pSysParams->m_pShaderHandle); #else CSLXSIShader *l_Shader = (CSLXSIShader *) in_pSysParams->m_pShaderHandle; #endif __XSI_PLUGIN_ if(!pInstanceData->m_CPSet.IsValid()) { pInstanceData->m_CPSet = l_Shader.GetProperties().GetItem(L"CGFX_Parameters" ); if(!pInstanceData->m_CPSet.IsValid()) { pInstanceData->m_CPSet = l_Shader.AddProperty(L"CustomProperty",false,L"CGFX_Parameters"); } } // ... } RTSHADER_API bool CgFX_GetRequirements ( XSI_RTS_SystemParams *in_pSysParams, // The system parameters void *in_pParams, // The property page parameters XSI_RTS_TriangulatedGeometry *in_pGeom, // The geometry information void **io_pShaderInstanceData, // The shader instance data ULONG in_lRequirement, // The requirement ID ULONG *out_pRequirementValue // The returned Value ) { #ifndef GUID_DEFINED #define GUID_DEFINED typedef struct _GUID { ULONG Data1; unsigned short Data2; unsigned short Data3; unsigned char Data4[8]; } GUID; #endif /* GUID_DEFINED */ if(in_lRequirement == RTS_REQUIRE_PRIMARYINITUIGUID) { GUID *l_pGuid = (GUID *) out_pRequirementValue; GUID l_Guid = {0x08C5D27C, 0x200B, 0x4fbd, 0x85, 0x77, 0xCA, 0x1D, 0xF3, 0x15, 0x3C, 0x11}; *l_pGuid = l_Guid; } else if(in_lRequirement == RTS_REQUIRE_SECONDARYINITUIGUID) { GUID *l_pGuid = (GUID *) out_pRequirementValue; GUID l_Guid = {0x9558C41C, 0x6C3D, 0x404b, 0x9E, 0x22, 0xE3, 0x85, 0x57, 0x9D, 0x26, 0xD1}; *l_pGuid = l_Guid; } return true; }
The <shader>_Term function is called when the shader is destroyed:
RTSHADER_API bool <shader>_Term ( XSI_RTS_SystemParams *in_pSysParams, // The system parameters void *in_pParams, // The property page parameters void **io_pShaderInstanceData // The shader instance data )
This function receives the system parameters, the property page parameters and the shader instance user data.
For example:
typedef struct tagOGLTextureInstanceData
{
int m_Handle;
LONG m_MipMap;
LONG m_Compression;
LONG m_Format;
} OGLTextureInstanceData;
RTSHADER_API bool OGL13Texture_Term
(
XSI_RTS_SystemParams *in_pSysParams, // The system parameters
void *in_pParams, // The property page parameters
void **io_pShaderInstanceData // The shader instance data
)
{
OGLTextureInstanceData *pInstanceData = (OGLTextureInstanceData *) *io_pShaderInstanceData;
if(pInstanceData != NULL)
{
// Delete the current handle if needed
if(pInstanceData->m_Handle != -1)
{
::glDeleteTextures(1, (unsigned int *)&pInstanceData->m_Handle);
}
// Delete our instance data
delete pInstanceData;
}
return TRUE;
}
The <shader>_Execute function is called when the shader is used to display the object:
RTSHADER_API bool <shader>_Term ( XSI_RTS_SystemParams *in_pSysParams, // The system parameters void *in_pParams, // The property page parameters XSI_RTS_TriangulatedGeometry *in_pGeom, // The geometry information void **io_pShaderInstanceData // The shader instance data )
|
As of v6.5 you can no longer set values or create data in this callback; use the <shader>_InitUI callback instead. Prior to v6.5, this restriction was not in force, so you may need to update shaders that had been implemented with set/change values in this callback; otherwise your shader may hang the system. |
This function receives the system parameters, the property page parameters, the geometry of the object it is connected to and the shader instance user data.
For example:
typedef struct tagOGLTextureInstanceData
{
int m_Handle;
LONG m_MipMap;
LONG m_Compression;
LONG m_Format;
} OGLTextureInstanceData;
RTSHADER_API bool OGL13Texture_Execute
(
XSI_RTS_SystemParams *in_pSysParams, // The system parameters
void *in_pParams, // The property page parameters
XSI_RTS_TriangulatedGeometry *in_pGeom, // The geometry information
void **io_pShaderInstanceData // The shader instance data
)
{
OGL13TexturePPG *pPpg = (OGL13TexturePPG *) in_pParams;
OGLTextureInstanceData *pInstanceData = (OGLTextureInstanceData *) *io_pShaderInstanceData;
assert(pInstanceData != NULL);
//
// code removed for readability
//
return TRUE;
}
The <shader>_GetRequirements function is called before the shader is used to display the object to query for specific shader requirements:
RTSHADER_API bool <shader>_GetRequirements ( XSI_RTS_SystemParams *in_pSysParams, // The system parameters void *in_pParams, // The property page parameters XSI_RTS_TriangulatedGeometry *in_pGeom, // The geometry information void **io_pShaderInstanceData, // The shader instance data ULONG in_lFlag, // The flag to check ULONG *out_pValue // The returned value )
This function receives the system parameters, the property page parameters, the geometry of the object it is connected to, the shader instance user data, the requirement ID and the returned requirement value.
The Realtime Shader API version 2.0 currently supports these requirements:
• RTS_REQUIRE_ZSORT
sort the object using the graphic pipeline; this is usually used for transparency sorting
• RTS_REQUIRE_OBJECTHANDLE
the shader code needs to access the object handle
• RTS_REQUIRE_MATERIALHANDLE
the shader code needs to access the material handle
• RTS_REQUIRE_LIGHTHANDLE
the shader code needs to access the light handles
• RTS_REQUIRE_PRIMARYINITUIGUID
redraw the UI if this parameter is changed
• RTS_REQUIRE_SECONDARYINITUIGUID
redraw the UI if this parameter is changed
If the shader does not need these requirements, then you should always answer FALSE to improve performance.
The result of the query is returned in out_pRequirementValue.
For example:
RTSHADER_API bool OGL13Draw_GetRequirements ( XSI_RTS_SystemParams *in_pSysParams, // The system parameters void *in_pParams, // The property page parameters XSI_RTS_TriangulatedGeometry *in_pGeom, // The geometry information void **io_pShaderInstanceData, // The shader instance data ULONG in_lFlag, // The flag to check ULONG *out_pRequirementValue // The returned value ) { OGL13DrawPPG *ppg = (OGL13DrawPPG *) in_pParams; *out_pRequirementValue = 0; switch(in_lFlag) { case RTS_REQUIRE_ZSORT: if((ppg->Blending) && (ppg->BlendFuncDst > 0)) *out_pRequirementValue = 1; break; }; return true; }