ARB shading language reference

This paragraph does not aim at replacing the official shader specifications. It's simply a quick reference, listing all useful assembly commands, available program parameters and state variables.

Official ARB shader specifications

• Shader Assembly Language (ARB/NV) Quick Reference Guide for OpenGL

ARB vertex program

Vertex program inputs:

• Size: 1, 2, 3 or 4 values.
• Normalized: yes / no (defined in the RED::RenderCode)
• Values: byte; unsigned byte; short; unsigned short; int; unsigned int; float; double. This is defined by the format of the corresponding mesh channels.
• Syntax: vertex.attrib[0 - 15].

Vertex program outputs:

• result.position: position in clip coordinates.
• result.color.primary: primary color.
• result.color.secondary: secondary color.
• result.fogcoord: fog coordinates.
• result.pointsize: point size.
• result.texcoord[0 - 6]: output texture coordinates.

Vertex program parameters (not exhaustive):

• program.env[a]: (x,y,z,w). Program environment parameter number 'a'.
• program.local[a]: (x,y,z,w). Program local parameter 'a'.

Vertex program state matrices (not exhaustive):

• state.matrix.modelview: Modelview matrix.
• state.matrix.projection: Projection matrix.
• state.matrix.mvp: Modelview-projection matrix.
• state.matrix.program[0]: View matrix (specified in the RED::RenderCode).
• state.matrix.program[1]: Model matrix (specified in the RED::RenderCode).

Access to inverse and transpose matrices is possible through the addition of a suffix to the targeted matrix: '.inverse' to get the inverse matrix; '.transpose' to get the transposed matrix; '.invtrans' to get the inverse transposed matrix.

Vertex program temporaries:

• TEMP R0;
• TEMP myValue;
• PARAM myParam = program.local[10];

Note that shader performance is better when fewer temporaries are being used. Low end hardware may have limits in the number of temporaries that can be declared.

Vertex program commands: (V: Vector; S: Scalar; U: Texture image unit identifier; T: Texture target)

ABS R1, R1; // R1 = |R1|

ADD R0, R1, R2; // R0 = R1 + R2;

DP3 R0, R1, R2; // R0 = R1.x * R2.x + R1.y * R2.y + R1.z * R2.z;

DP4 R0, R1, R2; // R0 = R1.x * R2.x + R1.y * R2.y + R1.z * R2.z + R1.w * R2.w;

DPH R0, R1, R2; // R0 = R1.x * R2.x + R1.y * R2.y + R1.z * R2.z + R2.w;

FRC R0, R0; // FLR R1, R0; SUB R0, R0, R1;

MAD R0, R1, R2, R3; // R0 = R1 * R2 + R3

MAX R0, R1, R2; // R0.x = (R1.x > R2.x) ? R1.x : R2.x; Same for y, z, w.

MIN R0, R1, R2; // R0.x = (R1.x < R2.x) ? R1.x : R2.x; Same for y, z, w.

MOV R1, value; // R1 = value;

MUL R0, R1, R2; // R0 = R1 * R2

POW R0, R1.x, R2.z;

RCP R0, R0.x; // R0.xyzw = 1.0 / R0.x

RSQ R0, R0.x; // R0 = 1.0 / sqrt( R0.x )

SGE R0, R1, R2; // R0.x = (R1.x >= R2.x) ? 1.0 : 0.0; Same for y, z, w.

SLT R0, R1, R2; // R0.x = (R1.x < R2.x) ? 1.0 : 0.0; Same for y, z, w.

SUB R0, R1, R2; // Is equivalent to ADD R0, R1, -R2;

SWZ R0, R0.zwxy; // Is equivalent to: ADD R0, R1, R0; // ADD R0, R1, R0.zwxy;

XPD R0, R1, R2; // Is equivalent to: MULR R0.xyz, R1.zxyz, R2.yzxy; MADR R0.xyz, R1.yzxy, R2.zxyz, -R0.xyzx;

ARB pixel / fragment program

Pixel program inputs:

• fragment.texcoord[0-6]: texture coordinates interpolators.
• fragment.color.primary: Primary color. Clamped to [0, 1].
• fragment.color.secondary: Secondary color. Clamped to [0, 1].
• fragment.fogcoord: Fog coordinates. Single interpolated value.

Pixel program outputs:

• result.color: Output RGBA color.
• result.depth: Output fragment depth (in result.depth.z).

A pixel program must output at least one of both values.

Pixel program parameters (not exhaustive):

• program.env[a]: (x,y,z,w). Program environment parameter number 'a'.
• program.local[a]: (x,y,z,w). Program local parameter 'a'.

Pixel program temporaries:

• TEMP R0;
• TEMP myValue;
• PARAM myParam = program.local[10];

Note that shader performance is better when fewer temporaries are being used. Low end hardware may have limits in the number of temporaries that can be declared.

Pixel program state parameters:

• The same state information is available as for vertex shaders.

Pixel program commands:

Commands that are identical for both vertex and pixel programs are not mentioned again here. This includes: ABS, ADD, DP3, DP4, DPH, DST, EX2, FLR, FRC, LG2, LIT, MAD, MAX, MIN, MOV, MUL, POW, RCP, RSQ, SUB, SWZ, XPD. Pixel program specific commands are here:

CMP R0, R1, R2, R3; // R0.x = (R1.x < 0.0) ? R2.x : R3.x; Same applies for y, z, w.

LRP R0, R1, R2, R3; // R0.x = R1.x * R2.x + (1.0 - R1.x) * R3.x; Same applies for y, z, w.

TEX R0, fragment.texcoord[2], texture[3], 2D;

Indirect shaders

Indirect shading refers to all GPU lighting calculations that are performed after a ray-casting process. The indirect lighting calculation work as all direct lighting workflows except that it does not use the same shaders. The whole indirect lighting workflow is described in the 'My first indirect shader' tutorial. We'll focus here in describing services offered by the REDsdk to program indirect lighting shaders.

Indirect vertex programs

They render quads instead of triangles. An indirect vertex program operates in WCS and transmits the triangle attributes to the pixel program. It rarely does more than that because it does not know the results of the ray versus triangle intersection yet.

Indirect vertex program inputs:

• Input position: This is a quad position that must be transformed in DCS as usual.
• Triangle attributes bound by the RED::RenderCode used by the indirect shader. Every attribute is repeated 3 times, for each triangle's vertex. Therefore, if we send vertices and normals, we'll receive vertex.attrib[1] to vertex.attrib[6] filled respectively with P0, P1, P2, N0, N1, N2, where P stands for position and N for normal.
• Last received attribute is the triangle ID. In our previous example, it's received as vertex.attrib[7].
• Indirect vertex programs use the 'Object to World' space matrices. These matrices are set on the RED::RenderCode.

Indirect vertex programs outputs:

• Triangle ID. Usually transferred using RED::ShaderString::TriangleIDTransfer.
• Triangle attributes at P0, P1 - P0 and P2 - P0. Every received attribute should be transferred.

Indirect pixel programs

Indirect pixel programs perform the ray versus triangle intersection for the provided attributes. They interpolate the found intersection to perform all lighting calculations now based on the local information. Indirect programs start by feeding the standard intersection calculation code:

psh.TriangleOwnershipTest();
psh.IntersectRayVsTriangle("ray_uv","ray_start","ray_dir",0);
psh.GetRayVsTriangleHitPoint("ray_hit","ray_uv","ray_start","ray_dir");
psh.GetRayVsTriangleUV("ray_uv");

Indirect pixel program inputs:

• Triangle ID transferred from the indirect vertex program.
• Ray starting position textures (RED_SHADER_INDIRECT_RAY_POS_TEX reference).
• Ray direction textures (RED_SHADER_INDIRECT_RAY_DIR_TEX reference).
• Triangle attributes: Vertex positions P0, P1 - P0, P2 - P0.
• Triangle attributes (optional): UV at P0, P1 - P0, P2 - P0.
• Other triangle attributes for interpolation (optional): Normals, tangents, etc

Indirect pixel program outputs:

• result.color: Fragment color.
• No depth may be output by an indirect pixel program. Depth testing is disabled and depth writing is although disabled for an indirect pixel program.

The GPU programming pipeline

GLSL shading language reference