IFXShader

The IFXShader interface maintains shaders that contain state and functionality for rendering polygon meshes. Combining simple shaders into ordered chains exposes fine control of the texturing, lighting, or geometric pipelines. Each shader has an associated pointer to a ShaderData interface, which couples the shader to specific elements (meshes and particle groups, for example). IFXShader inherits the IFXMarker and IFXUnknown interfaces and is supported by objects which inherit the IFXShader interface; namely, shaders.

When to Use

The IFXShader interface is used when an object needs to be drawn in a specific fashion by the rendering layer. The interface allows for retrieval or assignment of the ShaderData object that is associated with each shader. Every IFXShader interface can be treated as the interface to a linked list of shaders. When IFXShader::Render() is called, the shader sets up the rendering layer according to its state, and then calls the Render() method of the next shader in the list, if one exists. The Render() method needs to be called for the first shader only in a list to render as the call will cascade through the end of the list.

Interface Methods

Description

GetEnabled

Determines whether or not the shader is currently enabled

SetEnabled

Enables or disables the shader

GetOpaque

Determines whether or not the shader is opaque

AlphaAndTransparent

Determines whether or not the shader is transparent

GetContainer

Obtains the container for the shader

SetContainer

Inserts the container ID for the shader

GetNextShader

Obtains a pointer to the next shader in the linked list

SetNextShader

Inserts the specified shader into the linked list

GetShaderData

Obtains a pointer to the IFXShaderData interface currently associated with this shader

SetShaderData

Associates the specified IFXShaderData interface with the shader

GetIndexInShaderChain

Obtains the index number of the shader in the shader chain

SetIndexInShaderChain

Inserts the index number of the shader in the shader chain

Render

Causes the mesh currently associated with the shader to be rendered using the render layer settings established by the shader


IFXShader::GetEnabled()

This method returns the state of the shader. If the shader is disabled when its Render() method is called, it simply passes on to the next shader, without executing its rendering behavior. If it is enabled when Render() is called, the shader will perform its setup and rendering actions and then call the Render() method of the next shader in the list.

Parameters:

None

Return Values


IFXShader::SetEnabled(BOOL bInEnabled)

This method enables or disables the shader, as specified by the argument. If the shader is disabled, then when its Render() method is called, it simply passes onto the next shader, without executing its rendering behavior. If it is enabled, then when Render() is called, the shader will perform its setup and rendering actions and then call the Render() method of the next shader in the list.

Parameters:

bInEnabled

The state that the shader will assume. TRUE = enabled, FALSE = disabled

Return Values:

None


IFXShader::GetOpaque()

This method determines whether the shader is opaque.

Parameters:

None

Return Values:

BOOL


IFXShader::AlphaAndTransparent()

This method determines whether the alpha channel is used and is transparent.

Parameters:

None

Return Values:

BOOL


IFXShader::GetContainer()

This method gets the container for the shader.

Parameters:

None

Return Values:

U32


IFXShader::SetContainer(U32 uContainer)

This method sets the container for the shader.

Parameters:

uContainer

Container ID

Return Values:

None


IFXShader::GetNextShader()

Returns a pointer to the interface of the next shader in the linked list, if it exists.

Parameters:

None

Return Values:

NextShader--A pointer to the interface of the next shader in the chain.

Comments:

You must call Release() on the returned pointer when it will no longer be used. The method can return a NULL pointer.


IFXShader::SetNextShader(IFXShader* pInNextShader)

This method inserts a shader into a linked list of shaders. The shader is inserted in the list after the shader whose interface is called. The shader list is not otherwise disrupted. The input shader, however, is treated as a single element and subsequently has its NextShader assigned as well. If the input shader was part of a pre-existing list, that list becomes broken, unless steps are taken to patch the extraction.

Parameters:

pInNextShader

A pointer to the interface of the shader being inserted into the list

Return Values

Comments:

Any existing next shader will be released during this call. You may pass a NULL value to force the end of the chain.


IFXShader::GetShaderData()

Retrieves the interface pointer to the IFXShaderData interface currently associated with the shader.

Parameters:

None

Return Values:

IFXShaderData*

The address of a pointer to an IFXShaderData interface

Comments:

The calling function must call Release() on the returned IFXShaderData* if it will no longer be used.


IFXShader::SetShaderData(IFXShaderData* pInShaderData)

Associates the specified IFXShaderData component with the shader. When a shader is told to Render(), it acts upon the mesh information as provided by its current IFXShaderData interface.

Parameters:

pInShaderlData

A pointer to the IFXShaderData interface which will be assigned to the shader

Return Values

Comments:

None


IFXShader::GetIndexInShaderChain(U32* puIndex)

This method gets the ID number of the shader.

Parameters:

puIndex

A pointer to the IFXShader ID

Return Values


IFXShader::SetIndexInShaderChain(U32 uIndex)

This method causes the attachment of a specified shader onto the end of the linked list of shaders.

Parameters:

uIndex

IFXShader ID

Return Values


IFXShader::Render(IFXRenderLayer* pInRenderLayer, U32 uInLightCount, IFXLight** ppInLight, IFXView* pInView)

Parameters:

pInRenderLayer

A pointer to the interface of the rendering layer that the shader will use

uInLightCount

The number of lights that the shader will use

ppInLight

An array of pointers to IFXLight interfaces. There are uInLightCount interface pointers in the array

pInView

A pointer to the interface of the view that the shader will use

Return Values

Comments:

A shader is required to instruct the next shader in the list to Render() before terminating its own render method. A call to Render() for any shader results in all of the following shaders being rendered as well.

§See asterisked (*) statement at Legal Information © 2001 Intel Corporation.