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.

@related The GPU Programming Pipeline, Writing a Custom Rendering Shader in ARB, class RED::RenderShader

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:

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.

  • iMMatrix 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.

  • iMMatrix 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.

  • iMMatrix 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.

  • iMMatrix 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.

  • iRow0Matrix row.

  • iRow1Matrix row.

  • iRow2Matrix 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.

  • iColorColor 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.

  • iColorColor 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.

  • iVectorVector 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
  • oRVecVector retrieved from the bump map.

  • iTEXb – Bump map texture channel.

  • iUV2Db – Bump UV for 2D texture targets.

  • iTextureCodeShader 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).

  • iV0Vector at p0.

  • iV01Vector at p1-p0.

  • iV02Vector 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.