Shader Script .SHD

by Christoph Kubisch

Content

Definition

A shader allows multiple texture effects on a single surface. That can be blending different textures or complex operations such as Cg or Vertex/Fragment programs.
The shader defines how textures should be blend, while a MTL-Material sets the textures to be used, however the shader can have hardwired textures and special textures.

It is made of several stages, you should try to limit the amount of stages cause it will affect performance.

The header is necessary
current layout version:
luxinia_Shader_v310

Syntax

All commands are case sensitive and closed by ; or "newline". A keyword and its arguments may not span multiple lines.
<id> ranges from 0 to 7
<vector4> is (float,float,float,float)
<bool> is 1 = true, 0 = false

Branching

You can do branching with following commands. Enclose the branches in curly brackets { }

The condition string can be set from luxinia API with resource.condition, or it may be part of a "define" in the Cg Compiler string.
You can also negate a statement with !<condition string>.
Following conditions are automatically set if applicable:

Be aware that the parser is not fully rock solid, so at best use COMMAND{<newline> <what><newline> }<newline> , when problems occur.

Annotations & Comments

You can add annotations anywhere in the file and later query them after load. Anything between the two will become part of the annotation, so use with caution.

// comment until lineend

// multi-line annotation
<<_ "A"    
test = a * b
// this will be part of annotation as well
blahblubb
_>>

/* block commenting ...
<<_ "B"; min=25,max=90 _>>;    
//inlined annotation but ignored, due to active block comment
*/

C-style comments with // and /*...*/ may not start within command & keywords. So start comments always after ; in a line that contains command words.

Content


Example

luxinia_Shader_v310
Technique:VID_LOWDETAIL{
    Texture{
        TEX "Texture:0"
    }
}
Technique:VID_CG_TEX4{
    RenderFlag{
        //comment blah

        lit;
        nocull;
    }
    GpuProgram{
        BASE 0 "gpuprogs/test.cg" "unlit";
        SKIN 0 "gpuprogs/test.cg" "skin_unlit";
        BASE 1 "gpuprogs/test.cg" "lit1";
        SKIN 1 "gpuprogs/test.cg" "skin_lit1";

        VCG;

        param "angle" 0 VID_VALUE (45.0,0.0,0.0,1.0);
        tangents;
    }
    GpuProgram{
        BASE 0 "gpuprogs/test_pixel.cg" "main";
        FCG;
        param "color" 0 VID_LIGHTCOLOR (0.0,0.0,0.0,0.0) 0;
    }
    Color{
        RGBA "Color:0";
    }
    Texture{
        TEX "Texture:1";
    }
    Texture{
        ATTENUATE3D;
    }
    Texture{
        NORMALIZE;
    }
    /*    blockcomment
        ...
    */

}
Technique:VID_DEFAULT{
    RenderFlag{
        lit;
        nocull;
    }
    Color{
        RGBA "Color:0";
    }
    Texture{
        VTEX "Texture:0";
    }
    IF:DOSIMPLEANI{
        Texture{
            TEX "textures/fx/aniso.jpg";
            blendmode VID_ADD;
        }
    }
} 

Content


Technique

you can specify techniques if the same shader should look different depending on hardware capabilities, if no technique is specified VID_DEFAULT is assumed.
If a technique is defined there also must be a VID_DEFAULT technique. The first technique that is valid for the system's hardware will be used, so you should put the "highest detail" ones above default in. If there is any VID_LOWDETAIL must come first. It works like the IF in branching, just that the parser will stop after the first valild technique was over.

following techniques are defined:

Content

RenderFlag

These are independent from stages and used for all surfaces assigned, so be careful.
They are added to the object's renderflags when the material using this shader is assigned to the object. You can change the mesh/object's renderstate afterwards using the renderinterface.renderflag in luxinia.api.

setting.

Content


Stages

There are 4 different types of stages. All stages are processed in the same order, it is written in the shader file.
Limits: MAX_TEXSTAGES = 16, MAX_COLORSTAGES = 1
Beyond the limit will be ignored

DrawPass

A pass is started from here on.
Be warned that once you start using DrawPass no automatic blend-compilation will be done. This is why you must make sure, that the stages after and before newpass can actually be processed within a single pass. This means on Techniques with 2 Texture units you must not use more than 2 TextureStages?.

The advantage is that you can use a lot more blendmodes/combiners for texturing. You can also define your own here or with the lua api.

Color

Just a simple color, overrides vertexcolors of surface. For most "models" you will need to use "nocolorarray" renderflag to actually see an effect of the values specified here.

Texture

A single texturemap:

GpuProgram

only allowed in higher techniques, you are responsible for pass setup as in DrawPass?.
To use more than one pair of GpuPrograms? (vertex/fragment) you need to use DrawPass? mechanism.
Also, GpuPrograms? of a pass must come next to each other. When Cg is used none of the "OpenGL?" state variables are allowed ("state.???" or "gl_???").

For Vertex Processing

For Fragment Processing

Notes:

Content

Commands

After the stage specific commands there is multiple possibilities to change the stage

blendmode <mode enum>;

to blend fragments on top of each other, enums start with VID_...

Allowed in RenderFlag-,DrawPass-,Texture- and Color-Stages (same for 'blendinvert', 'alphamode' only in Texture).

RESULT = the fragment produced after blend
TEX = current fragment, normally a texture but could as well be a plain color
PREV = the previous fragment drawn (the one "below" TEX)

only in VID_ARB_V and higher techniques:

Alternatively you can generate a texture combiner from a string. This is equivalent to using texturecombiner class.
The string is created like this:
VIDTC_<OPCODE>:<ARGSOURCE>.<ARGOPERAND>|...|...

OPCODE

ARGSOURCE
  • TEX current texture
  • VERTEX current vertex color
  • CONST constant texture color of current textureunit
  • PREV previous

ARGOPERAND
  • C color
  • CINV color inverted
  • A alpha
  • AINV alpha inverted

Texture flags

Texture functions

GpuProgram flags

GpuProgram functions:

DrawPass flags:

DrawPass functions:

Content

History

1st Draft 17.4.2004
This is just a basic idea about functionality. Shaders may change on implentation if too complex to a more rigid system with a hardcoded set of FX

2nd Draft 28.4.2004
moved stageflags to renderflags, moved alpha/blend to renderflag as well, this is easier to work with in OGL, but needs a new system for texture blending which needs to be done soon (mainly combine)

3rd Draft 1.5.2004
texture blending and combining is now set.

4th Draft 10.5.2004
added a new custom texmode called VID_COLORDECAL, removed GL_SUBTRACT cause it brings us in trouble with older systems. CBF to do workaround.

5th Draft 12.5.2004
okay texcombine is removed, instead there are fixed effect types possible for the combining of texlayers. depending on hardware I will create the proper texcombiners/multipass renders.

6th Draft 2.6.2004
it will stay as is, although multiple textures per shader may not work well on all hardware until a "brute force" rendering pipeline is part of the engine.

7th Draft 7.6.2004
added reflectmap,eyelinmap as texture coord generation mode

8th Draft 31.7.2004
blendfunc is not valid for all passes just the first pass (first tex + color) also added LITMODADD and ADDMOD modes

9th Draft 13.8.2004
added LITDECAL_VERTEX and DECAL_VERTEX modes

10th Draft 30.8.2004
added BUMP mode

11th Draft 2.8.2004
added SPECBUMP mode

12th Draft 27.9.2004
changed BUMP to NORMAL and SPECBUMP to SPECNORMAL

13th Draft 15.10.2004
LIT renamed to COLOR

14th Draft 18.10.2004
ALPHA as texture mode to upload greyscales added nocolorarray renderflag

15th Draft 20.10.2004
blendfunc taken out, heavy reorganisation of blends now part of every stage as blendmode

16th Draft 1.11.2004
added LowDetail? stage

17th Draft 6.12.2004
addded GPUProgram? and FXShader? stage, the latter is not implemented at all and the first doesnt allow DXPSA yet

18th Draft 10.12.2004
layer renderflag added, to allow user to mark certain surfaces to be rendered at certain times. allows Zsort, Glow, Haze, Top layer (thats also the order in which they are drawn) removed DXPSA gpuprog type

19th Draft 19.12.2004
modifers need a name to be accessible from gamecode

20th Draft 22.12.2004
added techniques and shaders "values" need to be put in () vectors separated by , special Textures allowed in higher techniques (skybox, normalize...) gpuprogram parameters will soon allow special values (campos, camdir..) to be auto linked with

21th Draft 29.12.2004
name is a unique identifier of the stage to allow easier access to stages from gamescript LIGHTMAP added

22nd Draft 23.2.2005
split shader into "shader/material" so that shader only contains info how textures are blend

23rd Draft 15.3.2005
added "skin" versions for vertex programs

24th Draft 31.3.2005
added "texcoord" to allow use of different texcoord channels

25th Draft 16.7.2005
added "lit" versions for gpu programs and entrynames

26th Draft 23.7.2005
added new Techniques for better hardware, also added new automatic shader parameters

27th Draft 6.1.2006
the NewPass? Stage is introduced to allow manual 'compiling'

28th Draft 27.5.2006
added .dds support

29th Draft 20.6.2006
sunreflectmap and sunnormalmap
added TEXDOTZ for special cubemaps

30th Draft 2.7.2006
lit renamed to sunlit
added alphaTEX

31st Draft 28.7.2006:
texture clamping and texgenplane added.
eyelinmap renamed to worldlinmap, objlinmap added as well.

32nd Draft 1.8.2006:
all combiners (alpha/color) are now accessible. alphamode was added
33rd Draft 10.8.2006:
added "preprocessor" branching

34th Draft 2.9.2006:
param for regular stages

35th Draft 25.12.2006:
param for regular stages got support for lightcolor/lightdir

36th Draft 31.1.2007:
normals; flag also added to RenderFlag?

37th Draft 17.3.2007:
added VIDTC texture combiner from string generation

38th Draft 6.4.2007:
shader parameters got an upvalue. Warning this renders some of the old VID_BLAHx versions illegal.

39th Draft 22.4.2007:
lightnormalmapX & lightreflectmapX added.

40th Draft 2.6.2007:
texchannel -1 disables passing texcoords

41th Draft 18.6.2007:
depthcompare and depthvalue flags added

42th Draft 21.6.2007:
compiled flag for cg programs

43th Draft 8.9.2007:
added shader parameter arrays

44th Draft 14.10.2007:
'nomipmap' added

45th Draft 30.10.2007:
'VID_MODULATE2' added

46th Draft 26.12.2007:
Cg 2.0 changes, version raised to 310, mandatory for Cg useage
VID_FOGCOLOR gpu param removed, FFIXED gpu type removed.
"|compiled" removed is done differently now
VID_CG Technique removed, Cg auto-parameter names for Particles changed.
VID_TEXSIZE, VID_TEXSIZEINV,VID_TEXLMSCALE as parameters and lowCgProfile added
shadercghostparam class in Luxinia api

47th Draft 24.1.2008:
proper block commenting with #{ ... #}

48th Draft 23.4.2008:
commenting now in C-Style, along with raised version number 310 now mandatory for all // and /* ... */ renamed VID_NORMALMAP to VID_NORMALMAPTAN

49th Draft 18.5.2008:
annotation system added

50th Draft 11.5.2008:
DUMMY texture added, texchannel 4 = 0&1 combined, 5 = 2&3 combined

51st Draft 24.9.2008:
renamed NewPass to DrawPass (old name remains backward compatible) added stateflag command to DrawPass, use of gpuprograms always disables blend-compiler added blendmode to RenderFlag RenderFlag is now a full "default copy" in luxinia, no longer does alphafunc in RenderFlag "override". However DrawPass states do. alphafunc removed from DrawPass

52nd Draft 15.11.2008:
VID_CG_SM3_TEX8 renamed to VID_CG_SM3, and VID_CG_SM4/VID_CG_SM4_GS added

53nd Draft 23.02.2009:
Cg Semantics added

Content