ShaderString

Functions

	`SET_CID`
	`IMPLEMENT_AS`
	`ShaderString`
	`~ShaderString`
`RED_RC`	`VertexShaderStart`
`RED_RC`	`PixelShaderStart`
`RED_RC`	`AppleMetalVertexShaderAddHeader`
`RED_RC`	`AppleMetalPixelShaderAddHeader`
`RED_RC`	`SoftShaderStart`
`RED_RC`	`GeometryShaderStart`
`RED_RC`	`SoftShaderStart`
`RED_RC`	`ShaderEnd`
`RED_RC`	`Temp`
`RED_RC`	`Param`
void	`ChannelAsParam`
void	`ChannelAsParamWithMatrix`
void	`Alias`
void	`Attrib`
void	`VertexTransform`
void	`VertexTransform`
void	`VertexTransform`
void	`VertexTransform3x4`
void	`VertexHomogeneousTransform3x4`
void	`VectorTransform`
void	`VectorTransform`
void	`VectorTransform`
void	`UVTransform`
void	`SpotLightFalloff`
void	`LightAttenuation`
void	`PointLightAttenuation`
void	`IndirectPointLightAttenuation`
void	`SpotLightAttenuation`
void	`IndirectSpotLightAttenuation`
void	`DirLightAttenuation`
void	`BeamLightAttenuation`
void	`IndirectBeamLightAttenuation`
void	`AreaCentricLightDirection`
void	`AreaLighting`
void	`SkylightDiffuseLighting`
void	`SkylightDecay`
void	`Tex`
void	`Tex`
void	`VectorLength`
void	`Normalize`
void	`ReadBumpMap`
void	`UVTransform`
void	`Cross`
void	`Matrix3x3Transform`
void	`ConvertUVInCubeFaceVector`
`RED_RC`	`TriangleIdTransfer`
`RED_RC`	`TriangleOwnershipTest`
void	`IntersectRayVsTriangle`
void	`GetRayVsTriangleUV`
void	`GetRayVsTriangleHitPoint`
void	`Interpolate`
void	`GlossyRayDeviation`
`RED_RC`	`ShadowMapGaussianBlur`
`RED_RC`	`SmoothStep`

Detailed Description

class ShaderString : public RED::String 

ARB shader programs construction helper.

Shader programming at the pseudo assembly level of the OpenGL ARB language usually involves a lot of repetitive small operations. The aim of this class is to provide a basic function package making shader easier to write.

The ShaderString is used in the following workflow:

Start a vertex or a pixel shader program with a call to RED::ShaderString::VertexShaderStart or to RED::ShaderString::PixelShaderStart.
Program your shader program body using the corresponding set of functions,
End your shader with RED::ShaderString::ShaderEnd.

The ShaderString does not declare temporaries it uses. These must be declared by the caller. The ShaderString uses “R0”, “R1”, “R2”… as temporaries. The number of temporaries and their names are specified for each routine of the class.

Public Functions

SET_CID(CID_class_REDShaderString)

IMPLEMENT_AS()

ShaderString(): ShaderString construction method.

virtual ~ShaderString(): ShaderString destruction method.

RED_RC VertexShaderStart()

Starts an ARB 1.0 vertex shader string.

!!ARBvp1.0

Clears the string contents and adds the vertex shader header.

See also \ref wf_cartoon_shading.

RED_RC PixelShaderStart()

Start an ARB 1.0 pixel shader string.

!!ARBfp1.0

Clears the string and adds the pixel shader header.

See also \ref wf_cartoon_shading.

RED_RC AppleMetalVertexShaderAddHeader()

Starts an Apple Metal vertex shader string.

Clears the string contents and adds the vertex shader header.

The following Metal Shading Languages definitions are added. They provide access to the data provided by REDsdk in the shader code.

!!REDShaderAppleMetal

// This structure provides access to the REDsdk transform matrices
struct REDStateMatrixData {
    metal::float4x4 modelview;
    metal::float4x4 projection;
    metal::float4x4 mvp;
    metal::float4x4 program[4];
    
    metal::float4x4 modelview_inv;
    metal::float4x4 projection_inv;
    metal::float4x4 mvp_inv;
    metal::float4x4 program_inv[4];
    
    metal::float4x4 modelview_trans;
    metal::float4x4 projection_trans;
    metal::float4x4 mvp_trans;
    metal::float4x4 program_trans[4];
    
    metal::float4x4 modelview_invtrans;
    metal::float4x4 projection_invtrans;
    metal::float4x4 mvp_invtrans;
    metal::float4x4 program_invtrans[4];
}
REDStateMatrixData;

// This structure provides access to the REDsdk shader parameters
#define REDMETAL_MAX_PROGRAM_ENV_PARAMETERS ...
struct REDProgramLocalsData
   float4 value[REDMETAL_MAX_PROGRAM_ENV_PARAMETERS];
};

// This structure provides access to the REDsdk inputs
#define REDMETAL_STATEMATRIXDATA_IDX ...
#define REDMETAL_PROGRAMLOCALDATA_IDX ...
struct REDContext {
   constant REDStateMatrixData &state_matrix [[buffer(REDMETAL_STATEMATRIXDATA_IDX)]];
   constant REDProgramLocalsData &program_local [[buffer(REDMETAL_PROGRAMLOCALDATA_IDX)]];
};

// These values provides access to the REDsdk vertex buffer locations (vertex shader only)
enum RED_VSH_INPUT { RED_VSH_VERTEX  = 0,
                     RED_VSH_USER0   = 1,
                     RED_VSH_NORMAL  = 2,
                     RED_VSH_COLOR   = 3,
                     RED_VSH_USER1   = 4,
                     RED_VSH_USER2   = 5,
                     RED_VSH_USER3   = 6,
                     RED_VSH_USER4   = 7,
                     RED_VSH_TEX0    = 8,
                     RED_VSH_TEX1    = 9,
                     RED_VSH_TEX2    = 10,
                     RED_VSH_TEX3    = 11,
                     RED_VSH_TEX4    = 12,
                     RED_VSH_TEX5    = 13,
                     RED_VSH_TEX6    = 14,
                     RED_VSH_TEX7    = 15 };

// These function_constants are true is vertex buffer data is available (vertex shader only)
constant bool RED_VSH_VERTEX_enabled [[function_constant(...)]];
constant bool RED_VSH_USER0_enabled  [[function_constant(...)]];
constant bool RED_VSH_NORMAL_enabled [[function_constant(...)]];
...
constant bool RED_VSH_TEX7_enabled [[function_constant(...)]];

// These macros allow to access REDsdk texture samplers
#define RED_DECLARE_SAMPLERS ...
#define RED_DEFINE_SAMPLERS ...
#define RED_GET_SAMPLER(texunit) ...

// This value is the 'main' shader entry point name
#define REDMETAL_MAIN_FUNC ...

Some special comments must be used in shader source code. They allow REDsdk to know which resources are used by the shader.

RED_USE_VERTEX_ATTRIB(<RED_VSH_INPUT_value>)
RED_USE_TEXTURE(<textureUnit>,<RED_TEX_(1D|2D|3D|CUBE|RECT)>)

A vertex shader can be written as follows.

struct Attributes {
   // RED_USE_VERTEX_ATTRIB(RED_VSH_VERTEX)
   float4 vertexpos [[attribute(RED_VSH_VERTEX), function_constant(RED_VSH_VERTEX_enabled)]];
   // RED_USE_VERTEX_ATTRIB(RED_VSH_NORMAL)
   float3 normal    [[attribute(RED_VSH_NORMAL), function_constant(RED_VSH_NORMAL_enabled)]];
};
struct Varyings {
   float4 pos [[position]];
   float3 normal;
};

vertex Varyings REDMETAL_MAIN_FUNC(
   Attributes in [[stage_in]],
   REDContext red
) {
    float4 in_pos = RED_VSH_VERTEX_enabled ? in.pos : 0.0;
    Varyings result;
    result.pos = red.state_matrix.mvp * in_pos;
    result.normal = RED_VSH_NORMAL_enabled ? in.normal : 0.0;
    return result;
}

A fragment shader can be written as follows.

fragment FragmentOutput REDMETAL_MAIN_FUNC(
   Varyings in [[stage_in]],
   // RED_USE_TEXTURE(0,RED_TEX_2D)
   metal::texture2d<float> someTexture [[texture(0)]],
   REDContext red, RED_DECLARE_SAMPLERS)
{
    RED_DEFINE_SAMPLERS;
    const metal::sampler someTexture_sampler = RED_GET_SAMPLER(0);
    ...
    color = someTexture.sample(someTexture_sampler, uv);
    ...
}

As Apple Metal does not support Geometry Shaders, two special comments allow to change the way geometry is drawn.

RED_EXPAND_INDICES_TO_TRIANGLES(<vertexCountPerIndex>)
RED_EXPAND_INDICES_TO_TRIANGLESTRIPS(<vertexCountPerIndex>)

When these features are used, it is up to the shader code to pull the vertex data from the buffers, based on the current vertex_id / instance_id values.

The following example uses RED_EXPAND_INDICES_TO_TRIANGLESTRIPS to expand points geometry to hexagons. In this case, hardware instancing is used to draw multiple strips. instance_id gives the original point index value, vertex_id is the vertex index in the current strip.

// RED_EXPAND_INDICES_TO_TRIANGLESTRIPS(6) // 6-vertex strip for each input index
// RED_USE_VERTEX_ATTRIB(RED_VSH_VERTEX)
vertex Varyings REDMETAL_MAIN_FUNC(
   REDContext red,
   // There is implicit no conversion when using a 'device pointer'
   //   the type must match the input buffer layout (N.B. 'packed_')
   const device packed_float3* vertexpos_buf [[buffer(RED_VSH_VERTEX)]],
   uint v_id [[vertex_id]],
   uint v_instance [[instance_id]]
) {
   Varyings result;
   // Emitting a screen space hexagon, adjust the current vertex position based on the vertex_id
   //
   //     3 -- 1     To be emitted as a strip: 0, 1, 2, 3, 4, 5
   //    /      \
   //   5        0
   //    \      /
   //     4 -- 2
   uint in_point_id = v_instance;
   uint hex_vtx_id  = v_id;
   const float2 OFFSETS[6] = ...
   float4 a_vertexpos = RED_VSH_VERTEX_enabled ? float4(vertexpos_buf[in_point_id], 1.0) : float4(0.0);
   ...
   a_vertexpos += r * OFFSETS[hex_vtx_id].x * right;
   a_vertexpos += r * OFFSETS[hex_vtx_id].y * top;
   ...
}

When using RED_EXPAND_INDICES_TO_TRIANGLES, only vertex_id value is used and have to be decoded to reconstruct resulting individual triangles geometry.

As the index buffer is ignored when using RED_EXPAND_INDICES_TO_TRIANGLES and RED_EXPAND_INDICES_TO_TRIANGLES it can come handy to access it from the shader. In order to access it, the special comment RED_EXPAND_INDICES_USE_INDEXBUFFER can be used in combinaison of one of the other two.

Then the shader main function receive the index buffer with following signature:

...
// RED_EXPAND_INDICES_USE_INDEXBUFFER
vertex Varyings REDMETAL_MAIN_FUNC(
   ...
   const device ushort* index_buf [[buffer(REDMETAL_INDEXBUFFER_IDX)]],
   ...
) {

Note that it is required to know the index type (ushort or uint) to adapt main shader function signature.

RED_RC AppleMetalPixelShaderAddHeader()

Starts an Apple Metal pixel shader string.

Clears the string contents and adds the pixel shader header.

See RED::ShaderString::AppleMetalVertexShaderAddHeader for details.

RED_RC SoftShaderStart(const RED::String &iLibrary, const RED::String &iLabel, const RED::Version &iVersion)

Starts a built-in software shader.

!!REDShader:iLibrary:iLabel:iVersion

Clears the string and adds the soft shader startup label. The iLabel method must point to a function whose prototype is defined according to the software tracer shading prototype:

typedef RED_RC (*SOFT_SHADER_CALLBACK)( RED::SoftFrameBufferSample        ioFrameBufferSample,
                                        const RED::ISoftRayContext&       iRayContext,
                                        const RED::ISoftShaderContext&    iShaderContext,
                                        const RED::ISoftRenderingContext& iRenderingContext,
                                        const RED::Version&               iVersion );

Note that iLibrary and iLabel can’t contain any ‘:’ character as this would cause a misleading interpretation of the shader header.

If both iLibrary and iLabel are defined, the engine will try to load the dynamic library named iLibrary and look for the iLabel entry point in it. This will be our shading function.

If iLibrary is set to an empty string and iLabel is defined, the engine will look for a registered shading callback called iLabel in the resource manager (users can register their own shading callbacks using RED::IResourceManager::RegisterShadingCallback).

See also \ref wf_cartoon_shading.

Parameters

iLibrary – file name of the library where the shading method is located.
iLabel – name of the shading method to invoke in the given library.
iVersion – version of the shader. If the shader implementation does not support this shader version, RED::IWindow::FrameTracing will return a RED_MAT_SOFT_SHADER_UNSUPPORTED_VERSION error.

Returns

RED_OK if the method has succeeded,

RED_BAD_PARAM if the method has received an invalid string parameter containing a ‘:’ character,

RED_ALLOC_FAILURE if a memory allocation has failed.

RED_RC GeometryShaderStart(const RED::String &iLibrary, const RED::String &iLabel, const RED::Version &iVersion)

Starts a custom geometry vertex shader.

!!REDShaderGeometry:iLibrary:iLabel:iVersion

Clears the string and adds the shader startup label for a custom geometry vertex shader rendered in software. The iLabel method must point to a function whose prototype is defined according to the geometry shader vertex shading prototype.

This kind of shader is needed for the rendering of double precision geometries on legacy RED::HARDWARE_PLATFORM graphic cards that have no native double precision support. It can also be used for displacement mapping purposes or dynamic geometry handling.

Parameters

iLibrary – file name of the library where the shading method is located.
iLabel – name of the shading method to invoke in the given library.
iVersion – version of the shader. If the shader implementation does not support this shader version, it will return a RED_MAT_SOFT_SHADER_UNSUPPORTED_VERSION error.

Returns

RED_OK if the method has succeeded,

RED_BAD_PARAM if the method has received an invalid string parameter containing a ‘:’ character,

RED_ALLOC_FAILURE if a memory allocation has failed.

RED_RC SoftShaderStart(unsigned int iShaderClass)

Helper method to declare a built-in soft shader.

Parameters

iShaderClass – Internal ID of the shader class.

Returns

RED_OK if the operation has succeeded,

RED_ALLOC_FAILURE if a memory allocation has failed.

RED_RC ShaderEnd()

Marks the end of the shader.

END

Adds the shader termination tag to the string contents.

See also \ref wf_cartoon_shading.

Returns

RED_OK if the operation has succeeded,

RED_ALLOC_FAILURE if a memory allocation has failed.

RED_RC Temp(const char *iName)

Declares a temporary parameter.

TEMP iName;

The iName parameter will be declared once per program, so repeated call to Temp with several times same iName will have no effect.

See also \ref wf_cartoon_shading.

Parameters

iName – Parameter string name.

Returns

RED_OK if the operation has succeeded,

RED_ALLOC_FAILURE if a memory allocation has failed.

RED_RC Param(const char *iName, int iLocal)

Declares a parameter name from a program local.

PARAM iName = program.local[iLocal];

See also \ref wf_cartoon_shading.

The iName parameter will be declared once per program, so repeated call to Temp with several times same iName will have no effect.

Parameters

iName – Parameter name.
iLocal – program.local[n] to use.

Returns

RED_OK if the operation has succeeded,

RED_ALLOC_FAILURE if a memory allocation has failed.

void ChannelAsParam(const char *iName0, const char *iName1, const char *iName2, int iLocal)

Declaration of three parameters for an indirect mesh channel.

PARAM iName0 = program.local[iLocal];
TEMP iName1;
TEMP iName2;
ADD iName1, program.local[iLocal + 1], -iName0;
ADD iName2, program.local[iLocal + 2], -iName0;

Parameters

iName0 – Parameter at p0.
iName1 – Parameter edge p1-p0.
iName2 – Parameter edge p2-p0.
iLocal – program.local[n, n+1, n+2] to use.

void ChannelAsParamWithMatrix(const char *oUV, const char *iTUV, int iLocalBind, int iTransformBind = -1)

Declares and transforms an input UV send as local.

Calculates oUV, given three consecutive program.local[iLocalBind] and a possible matrix bind slot.

Uses:

R0, R1, R2.

MOV R0, program.local[iLocalBind];
ADD R1, program.local[iLocalBind + 1], -R0;
ADD R2, program.local[iLocalBind + 2], -R0;
if( matx_bind == -1 )
{
  Interpolate( oUV, iTUV, "R0", "R1", "R2" );
}
else
{
  Interpolate( oUV, iTUV, "R0", "R1", "R2" );
  UVTransform( oUV, oUV, matx_bind );
}

Parameters

oUV – Resulting UV.
iTUV – Triangulation UVs.
iLocalBind – Where we find our initial vertices UVs.
iTransformBind – Binding position of the matrix if to be applied.

void Alias(const char *iAlias, const char *iParam)

Renames a parameter.

ALIAS iAlias = iParam;

Parameters

iAlias – New name for the parameter.
iParam – Parameter string to rename.

void Attrib(const char *iAttrib, const char *iParam)

Renames a program parameter.

ATTRIB iAttrib = iParam;

Parameters

iAttrib – New name for the parameter.
iParam – Program parameter string to rename.

void VertexTransform(const char *oR, const char *iM, const char *iV)

Homogeneous transformation of a vector by a 4x4 matrix.

DP4 oR.x, iM.row[0], iV;
DP4 oR.y, iM.row[1], iV;
DP4 oR.z, iM.row[2], iV;
DP4 oR.w, iM.row[3], iV;

See also \ref wf_cartoon_shading.

Parameters

oR – Output register.
iM – Matrix string name. We use “iM.row[0-3]”.
iV – Input vector.

void VertexTransform(const char *oR, int iN, const char *iV)

Homogeneous transformation of a vector by a 4x4 matrix.

DP4 oR.x, program.local[iN], iV;
DP4 oR.y, program.local[iN+1], iV;
DP4 oR.z, program.local[iN+2], iV;
DP4 oR.w, program.local[iN+3], iV;

See also \ref wf_cartoon_shading.

Parameters

oR – Output register.
iN – Register number with matrix rows. We use “program.local[n-n+3]”.
iV – Input vector.

void VertexTransform(const char *oR, const char *iM0, const char *iM1, const char *iM2, const char *iM3, const char *iV)

Homogeneous transformation of a vector by a 4x4 matrix.

oR.x = iM0.x * iV.x + iM1.x * iV.y + iM2.x * iV.z + iM3.x * iV.w;
oR.y = iM0.y * iV.x + iM1.y * iV.y + iM2.y * iV.z + iM3.y * iV.w;
oR.z = iM0.z * iV.x + iM1.z * iV.y + iM2.z * iV.z + iM3.z * iV.w;
oR.w = iM0.w * iV.x + iM1.w * iV.y + iM2.w * iV.z + iM3.w * iV.w;

Declares and used the register ‘R0’.

See also \ref wf_cartoon_shading.

Parameters

oR – Output register.
iM0 – First matrix column.
iM1 – Second matrix column.
iM2 – Third matrix column.
iM3 – Fourth matrix column.
iV – Input vector.

void VertexTransform3x4(const char *oR, const char *iM, const char *iV)

Homogeneous transformation of a vector by a 3x4 matrix.

DP4 oR.x, iM.row[0], iV;
DP4 oR.y, iM.row[1], iV;
DP4 oR.z, iM.row[2], iV;

See also \ref wf_cartoon_shading.

Parameters

oR – Output register.
iM – Matrix string name. We use “iM.row[0-2]”.
iV – Input vector.

void VertexHomogeneousTransform3x4(const char *oR, const char *iM, const char *iV)

Homogeneous transformation of a vertex by a 3x4 matrix.

DPH oR.x, iV, iM.row[0];
DPH oR.y, iV, iM.row[1];
DPH oR.z, iV, iM.row[2];

Parameters

oR – Output register.
iM – Matrix string name. We use “iM.row[0-2]”.
iV – Input vector. As we do a “DPH”, only iV.xyz are used by the operation. DPH is assuming that iV.w = 1.

void VectorTransform(const char *oR, const char *iM, const char *iV)

Transformation of a vector by a 3x3 matrix.

DP3 oR.x, iM.row[0], iV;
DP3 oR.y, iM.row[1], iV;
DP3 oR.z, iM.row[2], iV;

Parameters

oR – Output register.
iM – Matrix string name. We use “iM.row[0-2]”.
iV – Input vector.

void VectorTransform(const char *oR, const char *iRow0, const char *iRow1, const char *iRow2, const char *iV)

Transformation of a vector by a 3x3 matrix.

DP3 oR.x, iRow0, iV;
DP3 oR.y, iRow1, iV;
DP3 oR.z, iRow2, iV;

Parameters

oR – Output register.
iRow0 – Matrix row.
iRow1 – Matrix row.
iRow2 – Matrix row.
iV – Input vector.

void VectorTransform(const char *oR, int iN, const char *iV)

Transformation of a vector by a 3x3 matrix.

DP3 oR.x, program.local[iN], iV;
DP3 oR.y, program.local[iN+1], iV;
DP3 oR.z, program.local[iN+2], iV;

Parameters

oR – Output register.
iN – Program locals used get the matrix program.local[iN]->[iN+2].
iV – Input vector.

void UVTransform(const char *oRx, const char *oRy, int iN, const char *iUV)

Homogeneous transformation of UV coordinates by a 4x4 matrix.

The matrix is provided by row vectors, starting at the program local constant iN. We only use the two first matrix rows as we are only transforming iV.xy.

DP4 oRx, program.local[iN], iUV;
DP4 oRy, program.local[iN+1], iUV;

Parameters

oRx – Output register x.
oRy – Output register y.
iN – Program locals used get the matrix program.local[iN]->[iN+1].
iUV – Input UVs.

void SpotLightFalloff(const char *oDecay, const char *iLightDir, const char *iTEXs)

Calculates the angular falloff decay.

This method calculates the intensity decay that result of a spotlight’s angular falloff. The method works either in VCS or WCS assuming that all references are bound in the same space.

PARAM RED_SHADER_LIGHT_SIGHT = RED_PSH_BINDPOS_LIGHT_SIGHT;
PARAM RED_SHADER_LIGHT_TOP   = RED_PSH_BINDPOS_LIGHT_TOP;
PARAM RED_SHADER_LIGHT_RIGHT = RED_PSH_BINDPOS_LIGHT_RIGHT;

TEMP lsproj;

DP3 lsproj.x, RED_SHADER_LIGHT_SIGHT, -iLightDir;
DP3 lsproj.y, RED_SHADER_LIGHT_TOP,   -iLightDir;
DP3 lsproj.z, RED_SHADER_LIGHT_RIGHT, -iLightDir;
TEX oDecay lsproj, TEXs, CUBE;

Parameters

oDecay – Contains the light angular attenuation resulting of the spot falloff.
iLightDir – Fragment position to centric light position vector.
iTEXs – Spot falloff texture channel.

void LightAttenuation(const char *oRAtt, const char *iLightVector, const char *iTEXn, bool iDeclareParams = true)

Computes the attenuation of a light.

This is the attenuation resulting of a light source intensity falloff.

Uses built-in parameters:

RED_SHADER_LIGHT_RANGE,
RED_SHADER_LIGHT_RANGE_BINDPOS.

PARAM RED_SHADER_LIGHT_RANGE = program.local[RED_SHADER_LIGHT_RANGE_BINDPOS];

DP3 oRAtt, iLightVector.xyzx, iLightVector.xyzx;
RSQ oRAtt, oRAtt.x;
RCP oRAtt.xzw, oRAtt.x;
MUL oRAtt.zw, oRAtt, RED_SHADER_LIGHT_RANGE.xxxy;
TEX oRAtt.x, oRAtt.zwxx, iTEXn, RECT;

Parameters

oRAtt – Attenuation (att,1.0f/length(iLightVector)).
iLightVector – VCS or WCS light vector storage.
iTEXn – Light source attenuation ramp texture (RECT).
iDeclareParams – Set to false to remove the parameter declarations from the routine. The default behavior is to declare parameters.

void PointLightAttenuation(const char *oRAtt, const char *oLightVector, const char *iLightVector, const char *iTEXatt, bool iDeclareParams = true)

Computes the attenuation for a point light.

Calculates the attenuation for a point light intensity falloff.

Uses built-in parameters:

RED_SHADER_LIGHT_RANGE,
RED_SHADER_LIGHT_RANGE_BINDPOS.

LightAttenuation( oRAtt, iLightVector, iTEXatt );
MUL oLightVector, iLightVector, oRAtt.yyyy;

Parameters

oRAtt – oRAtt.x is the light attenuation.
oLightVector – Normalized light vector.
iLightVector – Input light vector register.
iTEXatt – Attenuation ramp texture.
iDeclareParams – Set to false to remove the parameter declarations from the routine. The default behavior is to declare parameters.

void IndirectPointLightAttenuation(const char *oRAtt, const char *oLightVector, const char *iRPos, const char *iTEXatt, bool iDeclareParams = true)

Computes the indirect attenuation for a point light.

Calculates the attenuation for a point light during an indirect rendering workflow.

Uses:

RED_SHADER_LIGHT_RANGE,
RED_SHADER_LIGHT_RANGE_BINDPOS,
RED_SHADER_LIGHT_POS,
RED_SHADER_LIGHT_POS_BINDPOS.

Parameters

oRAtt – oRAtt.x is the light attenuation.
oLightVector – Normalized WCS light vector.
iRPos – Fragment hit position.
iTEXatt – Attenuation ramp texture.
iDeclareParams – Set to false to remove the parameter declarations from the routine. The default behavior is to declare parameters.

void SpotLightAttenuation(const char *oRAtt, const char *oLightVector, const char *iLightVector, const char *iTEXatt, const char *iTEXs, bool iDeclareParams = true)

Computes the attenuation for a spot light.

Calculates the attenuation for a spot light intensity falloff.

Uses:

R0 (temporary),
RED_SHADER_LIGHT_RANGE,
RED_SHADER_LIGHT_RANGE_BINDPOS,
RED_SHADER_LIGHT_SIGHT,
RED_SHADER_LIGHT_SIGHT_BINDPOS,
RED_SHADER_LIGHT_TOP,
RED_SHADER_LIGHT_TOP_BINDPOS,
RED_SHADER_LIGHT_RIGHT,
RED_SHADER_LIGHT_RIGHT_BINDPOS.

LightAttenuation( oRAtt, iLightVector, iTEXatt );
MUL oLightVector, iLightVector, oRAtt.yyyy;

PARAM RED_SHADER_LIGHT_SIGHT = program.local[RED_SHADER_LIGHT_SIGHT_BINDPOS];
PARAM RED_SHADER_LIGHT_TOP   = program.local[RED_SHADER_LIGHT_TOP_BINDPOS];
PARAM RED_SHADER_LIGHT_RIGHT = program.local[ RED_SHADER_LIGHT_RIGHT_BINDPOS];

DP3 R0.x, RED_SHADER_LIGHT_SIGHT, -oLightVector;
DP3 R0.y, RED_SHADER_LIGHT_TOP,   -oLightVector;
DP3 R0.z, RED_SHADER_LIGHT_RIGHT, -oLightVector;
TEX R0.x, R0.xyzx, iTEXs, CUBE;
MUL oRAtt.x, oRAtt.x, R0.x;

Parameters

oRAtt – oRAtt.x is the light attenuation.
oLightVector – Normalized light vector.
iLightVector – Input light vector register.
iTEXatt – Attenuation ramp texture.
iTEXs – Spot falloff texture channel.
iDeclareParams – Set to false to remove the parameter declarations from the routine. The default behavior is to declare parameters.

void IndirectSpotLightAttenuation(const char *oRAtt, const char *oLightVector, const char *iRPos, const char *iTEXatt, const char *iTEXs, bool iDeclareParams = true)

Computes the indirect attenuation for a spot light.

Calculates the attenuation for a spot light during an indirect rendering workflow.

Uses:

R0 (temporary),
RED_SHADER_LIGHT_RANGE,
RED_SHADER_LIGHT_RANGE_BINDPOS,
RED_SHADER_LIGHT_POS,
RED_SHADER_LIGHT_POS_BINDPOS,
RED_SHADER_LIGHT_SIGHT,
RED_SHADER_LIGHT_SIGHT_BINDPOS,
RED_SHADER_LIGHT_TOP,
RED_SHADER_LIGHT_TOP_BINDPOS,
RED_SHADER_LIGHT_RIGHT,
RED_SHADER_LIGHT_RIGHT_BINDPOS.

Parameters

oRAtt – oRAtt.x is the light attenuation.
oLightVector – Normalized light vector.
iRPos – Fragment hit position.
iTEXatt – Attenuation ramp texture.
iTEXs – Spot falloff texture channel.
iDeclareParams – Set to false to remove the parameter declarations from the routine. The default behavior is to declare parameters.

void DirLightAttenuation(const char *oRAtt, const char *oLightVector, const char *iTEXatt)

Computes the attenuation for a directional light.

Calculates the attenuation for a directional light intensity falloff. Note that the same routine is used for indirect rendering workflows.

Uses:

RED_SHADER_LIGHT_SIGHT,
RED_SHADER_LIGHT_SIGHT_BINDPOS.

TEX oRAtt, {1,0,0,0}, iTEXatt, RECT;
PARAM RED_SHADER_LIGHT_SIGHT = program.local[RED_SHADER_LIGHT_SIGHT_BINDPOS];
MOV oLightVector, -RED_SHADER_LIGHT_SIGHT;

Parameters

oRAtt – Attenuation in oRAtt.x (set to the constant intensity stored in the attenuation texture ramp for a directional light).
oLightVector – Normalized VCS or WCS light vector register.
iTEXatt – Attenuation texture ramp.

void BeamLightAttenuation(const char *oRAtt, const char *iLightVector, const char *iProjectorUV, const char *iTEXatt, const char *iTEXr)

Computes the attenuation for a beam light with a radial texture lookup.

Calculates the attenuation for a beam light intensity falloff.

Uses:

R0,
RED_SHADER_LIGHT_RANGE,
RED_SHADER_LIGHT_RANGE_BINDPOS,
RED_SHADER_LIGHT_SIGHT,
RED_SHADER_LIGHT_SIGHT_BINDPOS,

LightAttenuation(oRAtt,iLightVector,iTEXatt);

PARAM RED_SHADER_LIGHT_SIGHT = program.local[RED_SHADER_LIGHT_SIGHT_BINDPOS];

DP3 R0.x, RED_SHADER_LIGHT_SIGHT, iLightVector;
SGE R0.x, R0.x, {0}.x;   // Clamps all fragments behind our lighting area.
MUL oRAtt.x, oRAtt.x, R0.x;
TEX R0.x, iProjectorUV, iTEXr, 2D;
MUL oRAtt.x, oRAtt.x, R0.x;

Parameters

oRAtt – Attenuation in oRAtt.x, iLightVector’s length in oRAtt.y.
iLightVector – VCS light vector register.
iProjectorUV – UV to use for the radial texture sampling.
iTEXatt – Light source attenuation ramp texture (RECT).
iTEXr – Radial texture channel.

void IndirectBeamLightAttenuation(const char *oRAtt, const char *oLightVector, const char *iRPos, const char *iTEXn, const char *iTEXr, const char *ioRTemp)

Computes the indirect attenuation for a beam light.

Calculates the attenuation for a beam light, for an indirect lighting workflow.

Uses:

R0 (temporary),
RED_SHADER_LIGHT_RANGE,
RED_SHADER_LIGHT_RANGE_BINDPOS,
RED_SHADER_LIGHT_POS,
RED_SHADER_LIGHT_POS_BINDPOS,
RED_SHADER_LIGHT_SIGHT,
RED_SHADER_LIGHT_SIGHT_BINDPOS,
RED_SHADER_LIGHT_TOP,
RED_SHADER_LIGHT_TOP_BINDPOS,
RED_SHADER_LIGHT_RIGHT,
RED_SHADER_LIGHT_RIGHT_BINDPOS.
RED_SHADER_LIGHT_PROJUV.

Parameters

oRAtt – Attenuation in oRAtt.x.
oLightVector – Normalized WCS light vector.
iRPos – Fragment hit position.
iTEXn – Light source attenuation ramp texture (RECT).
iTEXr – Beam radial texture (2D).
ioRTemp – Another temporary register that we need.

void AreaCentricLightDirection(const char *oLightDir, const char *iPosition)

Computes the light direction for an area light.

This is the fragment position to central light position vector.

Uses parameters:

RED_SHADER_LIGHT_POS bound to RED_PSH_BINDPOS_LIGHT_POS.

Parameters

oLightDir – Normalized light direction.
iPosition – Fragment position.

void AreaLighting(const char *oDotNL, const char *iNormal, const char *iSurfaceNormal, const char *iPos, const char *iAttenuationTex, const char *iSampleTex)

Computes the diffuse and attenuation terms for an area light.

This method computes a diffuse and attenuation terms for an area light. Both terms are combined by the calculation method and are returned in the oDotNL value.

Declared temporaries:

av0, av1, av2, av3, acorner, adecay,
an0, an1, an2, an3, aldir, adot,
xi, xn, acs, xpos, xneg, acsneg,
aintensity.

Parameters

oDotNL – Diffuse and attenuation term.
iNormal – Unit fragment normal.
iSurfaceNormal – NULL or base surface normal. Provide the non bumpy surface normal if the shading occurs for a bumpy surface to avoid collecting backside surface lighting.
iPos – WCS fragment position.
iAttenuationTex – Light source attenuation texture (intensity).
iSampleTex – Sample positions texture.

void SkylightDiffuseLighting(const char *oDiffuse, const char *iNormal, const char *iSurfaceNormal, const char *iSkylightTex)

Computes the diffuse term for an skylight.

This method computes a diffuse term for a skylight, by taking a number of directional samples over the skylight and by weighting the diffuse contribution for each sample.

Parameters

oDiffuse – The diffuse color contribution from the sky at the shaded fragment.
iNormal – Unit fragment normal.
iSurfaceNormal – NULL or base surface normal. Provide the non bumpy surface normal if the shading occurs for a bumpy surface to avoid collecting backside surface lighting.
iSkylightTex – Skylight texture.

void SkylightDecay(const char *oDecay, const char *iTexDecay)

Lookups the skylight intensity.

This is the constant intensity multiplier of the skylight that is retrieved here.

Parameters

oDecay – Intensity of the area light.
iTexDecay – Light source decay texture.

void Tex(const char *oColor, const char *iColor, const char *iTexture, const char *iUV, int iComposite, int iCompositeChannel)

Sample a texture, for various possible inputs.

Parameters

oColor – Sampled color.
iColor – Color variable to use if we have no texture input.
iTexture – Texture slot to use if we do have a texture input.
iUV – UV channel to use.
iComposite – Composite texture selection flag. See RED::RenderShader::CompositeTextureSelection.
iCompositeChannel – Number of the channel to select in the composite flag in [ 0, 15 ].

void Tex(const char *oColor, int iColor, const char *iTexture, const char *iUV, int iComposite, int iCompositeChannel)

Sample a texture, for various possible inputs.

Parameters

oColor – Sampled color.
iColor – Color program local number to use if we have no texture input.
iTexture – Texture slot to use if we do have a texture input.
iUV – UV channel to use.
iComposite – Composite texture selection flag. See RED::RenderShader::CompositeTextureSelection.
iCompositeChannel – Number of the channel to select in the composite flag in [ 0, 15 ].

void VectorLength(const char *oLength, const char *iVector)

Computes the length of a vector.

DP3 oLength.x, iVector, iVector;
RSQ oLength.x, oLength.x;
RCP oLength.x, oLength.x;

Parameters

oLength – Resulting vector length in oLength.x.
iVector – Vector whose length has to be calculated.

void Normalize(const char *oRUnitVector, const char *iVector, bool iSecure = true)

Normalizes a vector or register.

DP3 oRUnitVector.w, iVector, iVector;
MAX oRUnitVector.w, oRUnitVector.w, { 1e-12 }.x;
RSQ oRUnitVector.w, oRUnitVector.w;
MUL oRUnitVector.xyz, iVector, oRUnitVector.w;

Normalizes iVector, stores the result in oRUnitVector. The same vector can be used as input and output. iVector.w is ignored.

Note that oRUnitVector can’t be a shader output register such as ‘result.color’ or ‘result.depth’.

Parameters

oRUnitVector – Register receiving the normalized vector. oRUnitVector.w is set to 1/sqrtf(length(iVector.xyz)).
iVector – Source vector.
iSecure – If true, the MAX operation is done, if false, it’s not done, leading possibly to 1/0 divisions.

void ReadBumpMap(const char *oRVec, const char *iTEXb, const char *iUV2Db, int iTextureCode, int iTextureCodeEntry)

Retrieves a vector from a bumpmap.

Parameters

oRVec – Vector retrieved from the bump map.
iTEXb – Bump map texture channel.
iUV2Db – Bump UV for 2D texture targets.
iTextureCode – Shader texture target selection code.
iTextureCodeEntry – Texture entry in ‘iTextureCode’ for the bump channel.

void UVTransform(const char *oRUV, const char *iRUV, int iMatrixRowBindPos)

Matrix transformation of an UV coordinate set.

Uses

R0 (temporary).

MOV R0, iRUV;
MOV R0.zw, {0,0,0,1};
DP4 oRUV.x, program.local[iMatrixRowBindPos], R0;
DP4 oRUV.y, program.local[iMatrixRowBindPos+1], R0;

Parameters

oRUV – Register receiving the transformed UVs.
iRUV – Source UVs.
iMatrixRowBindPos – Binding position of the matrix rows.

void Cross(const char *oRD, const char *iR1, const char *iR2)

Cross product of two operand vectors.

MUL oRD.xyz, iR1.zxyz, iR2.yzxy;
MAD oRD.xyz, iR1.yzxy, iR2.zxyz, -oRD.xyzx;

Parameters

oRD – Destination parameter.
iR1 – First operand.
iR2 – Second operand.

void Matrix3x3Transform(const char *oR, const char *iV, const char *iM0, const char *iM1, const char *iM2)

Multiplies a vector by a matrix.

Multiplies iV by the matrix [iM0,iM1,iM2], sent with each of its column vectors.

Uses: R0.

oR.x = iM0.x * iV.x + iM1.x * iV.y + iM2.x * iV.z;
oR.y = iM0.y * iV.x + iM1.y * iV.y + iM2.y * iV.z;
oR.z = iM0.z * iV.x + iM1.z * iV.y + iM2.z * iV.z;

Parameters

oR – Output register.
iV – Input register.
iM0 – First matrix column.
iM1 – Second matrix column.
iM2 – Third matrix column.

void ConvertUVInCubeFaceVector(const char *oR, int iNumFace, const char *iRUV)

ConvertUVInCubeFaceVector.

Converts the contents in iRUV (normalized in [0,1]x[0,1]) in a vector to perform a lookup in a CUBE texture for the iNumFace cube image face.

This method can be used to extract texels in a cube face.

switch(iNumFace)
{
  case 0:
  {
    // oR = [1,(1-2*V),(1-2*U)]
    MUL oR, iRUV.wyxw, {0,-2,-2,0};
    ADD oR, oR, {1,1,1,0};
    break;
  }
  case 1:
  {
    // oR = [-1,(1-2*V),(-1+2*U)]
    MUL oR, iRUV.wyxw, {0,-2,2,0};
    ADD oR, oR, {-1,1,-1,0};
    break;
  }
  case 2:
  {
    // oR = [(-1+2*U),1,(-1+2*V)]
    MUL oR, iRUV.xwyw, {2,0,2,0};
    ADD oR, oR, {-1,1,-1,0};
    break;
  }
  case 3:
  {
    // oR = [(-1+2*U),-1,(1-2*V)]
    MUL oR, iRUV.xwyw, {2,0,-2,0};
    ADD oR, oR, {-1,-1,1,0};
    break;
  }
  case 4:
  {
    // oR = [(-1+2*U),(1-2*V),1]
    MUL oR, iRUV.xyww, {2,-2,0,0};
    ADD oR, oR, {-1,1,1,0};
    break;
  }
  case 5:
  {
    // oR = [(1-2*U),(1-2*V),-1]
    MUL oR, iRUV.xyww, {-2,-2,0,0};
    ADD oR, oR, {1,1,-1,0};
    break;
  }
}

Parameters

oR – Resulting vector, ready for the cube lookup.
iNumFace – Cube face number.
iRUV – Normalized input UVs for the lookup.

RED_RC TriangleIdTransfer(RED::HARDWARE_PLATFORM iPlatformId)

Transfers the triangle identifier to the pixel shader.

Transfers the triangle identifier sent by the indirect lighting rendering pipeline to the pixel shader, considering the different hardware channels capabilities & numerical tolerancies.

The vertex.attrib[1] input channel is reserved for triangle ID transmission in indirect lighting.

Parameters

iPlatformId – Identifier of the runtime platform for which we generate a shader code.

Returns

RED_OK when the operation has succeeded,

RED_BAD_PARAM if the method has received an invalid parameter. This includes an invalid iPlatformId that must be of the NVIDIA or ATI kind.

RED_RC TriangleOwnershipTest(RED::HARDWARE_PLATFORM iPlatformId)

Rejects fragments calculated for a wrong triangle.

Tests whether we are doing an indirect rendering of a triangle that is the triangle really visible for that pass or not.

Uses:

R0, R1 (temporaries),
RED_SHADER_INDIRECT_RAY_TRIANGLE_BINDTEX,
fragment.color.primary (NVIDIA),
program.local[RED_SHADER_INDIRECT_ATI_TRIANGLE_ID_BINDPOS] (ATI).

Parameters

iPlatformId – Identifier of the runtime platform for which we generate a shader code.

Returns

RED_OK when the operation has succeeded,

RED_BAD_PARAM if the method has received an invalid parameter. This includes an invalid iPlatformId that must be of the NVIDIA or ATI kind.

void IntersectRayVsTriangle(const char *oRUV, const char *oRPos, const char *oRDir, int ifN)

Performs a ray vs triangle intersection.

This routine preserves the partial derivatives over the whole triangle surface, so that texture sampling can leverage LODs and anisotropic filtering.

Uses:

R0,R1,R2 (temporaries),
RED_SHADER_INDIRECT_RAY_POS_BINDTEX texture.
RED_SHADER_INDIRECT_RAY_DIR_BINDTEX texture.

Parameters

oRUV – Register with the output UVs. oRUV is set with these values: (uv.x, 1/det, uv.y, dot(vq,p02)). UVs are not normalized yet.
oRPos – Register used for the ray position.
oRDir – Register used for the ray direction.
ifN – Triangle vertices channels. We assume that the first triangle vertex is at fragment.texcoord[n], and then the two triangle edges are at fragment.texcoord[n+1] and fragment.texcoord[n+2].

void GetRayVsTriangleUV(const char *ioRUV)

Normalizes UVs resulting of a RayVsTriangle call.

UVs resulting of a RayVsTriangle need to be divided by ‘det’.

Parameters: ioRUV – Register holding UVs. (uv.x, 1/det, uv.y, dot(vq,p02))

void GetRayVsTriangleHitPoint(const char *oRHit, const char *iRUV, const char *iRPos, const char *iRDir)

Gets the point hit on the triangle.

Parameters

oRHit – Register receiving the hit point.
iRUV – Register holding the output UVs. We use iRUV.yw.
iRPos – Ray starting position.
iRDir – Ray direction.

void Interpolate(const char *oR, const char *iUV, const char *iV0, const char *iV01, const char *iV02)

Interpolates a vector at a triangle’s corners.

Parameters

oR – Resulting vector.
iUV – Interpolation UVs (uses UV.xz with the ray vs tri UVs).
iV0 – Vector at p0.
iV01 – Vector at p1-p0.
iV02 – Vector at p2-p0.

void GlossyRayDeviation(const char *ioR, const char *iN, int iJitterBind, int iDevBind, int iSampleBind)

Computes the deviation of a ray for ray-traced glossiness.

This routines modifies the specified vector ioR according to the values provided by the engine for the glossiness references.

Uses:

R0,R1,R2 (temporaries)

Parameters

ioR – Ray to modify.
iN – Surface normal at fragment.
iJitterBind – Binding channel for REF_GLOSSY_JITTER_TEX.
iDevBind – Binding channel for REF_GLOSSY_DEVIATION_TEX.
iSampleBind – Binding constant for REF_GLOSSY_SAMPLE_NUMBER.

RED_RC ShadowMapGaussianBlur(const char *iS, int iSize, const char *iUV, const char *iTexture, RED::HARDWARE_PLATFORM iPlatformId, bool iDeclareParams = true)

Blur the shadows of a shadow map.

Uses: R0 and R1.

Parameters

iS – Name of the shadow register.
iSize – Size of the blur kernel in [ 2, 20 ].
iUV – Source UV for the shadow map sampling.
iTexture – Shadow map texture.
iPlatformId – The run-time hardware platform for which the string is generated.
iDeclareParams – true to declare internal parameters, false to avoid declaring them.

RED_RC SmoothStep(const char *oResult, const char *iMin, const char *iMax, const char *iWeight)

Performs smooth Hermite interpolation. Equivalent to GLSL smoothstep function.

Parameters

oResult – output interpolation result.
iMin – lower edge of the Hermite function.
iMax – upper edge of the Hermite function.
iWeight – source value for interpolation between 0 and 1.

Returns

RED_OK if the method has succeeded,

RED_BAD_PARAM if the method has received an invalid parameter.