Element/Shader

The shader class represents a Microsoft HLSL Effect File(.fx) loaded by the client, which can be used instead of an texture when calling dxDrawImage

The element type of this class is "shader".

How HLSL Effect Files file integrate into MTA:SA

Note: This assumes you know what an Effect File and HLSL is. If not, you had better do some research first.

You can use this shadertest resource to try the examples below. Copy the effect source from the code boxes into shadertest/clientshader.fx and (re)start shadertest to see the output.

After you've done all that, (or maybe before if glancing below is making you panic), visit here to see some more shader resource examples.

Techniques

Effect Files usually contain several techniques, but for simplicity, MTA will only use the first technique that will run correctly on the clients hardware. So, for any given Effect File, put your high end techniques first, and the simplest ones last. That way, players with good hardware get the best technique applied, and players with older hardware get at least something.

Simplest

Here is the contents of an Effect File with one technique which should work on all hardware:

//-- Declare the textures. These are set using dxSetShaderValue( shader, "Tex0", texture )
texture Tex0;
texture Tex1;

//-- Very simple technique
technique simple
{
    pass P0
    {
        //-- Set up texture stage 0
        Texture[0] = Tex0;
        ColorOp[0] = SelectArg1;
        ColorArg1[0] = Texture;
        AlphaOp[0] = SelectArg1;
        AlphaArg1[0] = Texture;
            
        //-- Disable texture stage 1
        ColorOp[1] = Disable;
        AlphaOp[1] = Disable;
    }
}

It doesn't use vertex or pixel shaders, only standard D3D render states. Confusing reference of all the states you can set is here: http://msdn.microsoft.com/en-us/library/bb173347%28v=VS.85%29.aspx

Not so simple

Here is an Effect File containing a vertex and pixel shader:

//-- Declare the textures. These are set using dxSetShaderValue( shader, "Tex0", texture )
texture Tex0;
texture Tex1;

//-- Declare a user variable. This can be set using dxSetShaderValue( shader, "PositionOfCheese", 1, 2, 3 )
float3 PositionOfCheese;

//-- These variables are set automatically by MTA
float4x4 World;
float4x4 View;
float4x4 Projection;
float4x4 WorldViewProjection;
float Time;


//-- Samplers for the textures are needed for pixel shaders
sampler Sampler0 = sampler_state
{
    Texture   = (Tex0);
};

sampler Sampler1 = sampler_state
{
    Texture   = (Tex1);
};


//-- Vertex shader output structure for transfer of info from vertex to pixel shader
struct VS_OUTPUT_Yeah
{
    float4 Pos  : POSITION;
    float4 Diffuse : COLOR0;
    float2 TexCoord0: TEXCOORD0;
};

//-----------------------------------------------------------------------------
//-- Name: VS_Example
//-- Type: Vertex shader
//-- Desc: Transform vertices and output
//-----------------------------------------------------------------------------
VS_OUTPUT_Yeah VS_Example(
      float3 InPos          : POSITION
    , float4 InDiffuse      : COLOR0
    , float2 InTexCoord0     : TEXCOORD0
    )
{
    VS_OUTPUT_Yeah Out = (VS_OUTPUT_Yeah)0;

    Out.Pos = mul(float4(InPos, 1), WorldViewProjection);
    Out.Diffuse = InDiffuse;
    Out.TexCoord0 = InTexCoord0;
    return Out;
}


//-----------------------------------------------------------------------------
//-- Name: PS_Example
//-- Type: Pixel shader
//-- Desc: Calculates the pixel color based on texture lookup and interpolated vertex color
//-----------------------------------------------------------------------------
float4 PS_Example(
    VS_OUTPUT_Yeah In
    ) : COLOR
{
    //-- Example of using Time for animation
    In.TexCoord0.y += sin(In.TexCoord0.y * 100 + Time * 10)*0.03;

    return tex2D(Sampler0, In.TexCoord0) * In.Diffuse;
}



//-----------------------------------------------------------------------------
//-- Techniques
//-----------------------------------------------------------------------------

//--
//-- MTA will try this technique first:
//--
technique complercated
{
    pass P0
    {
        VertexShader = compile vs_2_0 VS_Example();
        PixelShader  = compile ps_2_0 PS_Example();
    }
}

//--
//-- And if the preceding technique will not validate on
//-- the players computer, MTA will try this one:
//--
technique simple
{
    pass P0
    {
        //-- Set up texture stage 0
        Texture[0] = Tex0;
        ColorOp[0] = SelectArg1;
        ColorArg1[0] = Texture;
        AlphaOp[0] = SelectArg1;
        AlphaArg1[0] = Texture;
            
        //-- Disable texture stage 1
        ColorOp[1] = Disable;
        AlphaOp[1] = Disable;
    }
}

Technique 'complercated' will be used if the computer supports Shader Model 2, otherwise technique 'simple' will be used. Comments in the source explain what MTA does and where.

Misc

Points to remember when switching between editing lua and .fx files:

HLSL statements often end with a ; (semi-colon)
HLSL indices start from 0 (where as Lua usually starts from 1)
HLSL compile errors can be viewed by typing 'debugscript 3' into the client console

Related scripting functions

Client

ADDED/UPDATED IN VERSION 1.6.0 r22271:

dxDrawModel3D