class RED::ShaderString

ARB shader programs construction helper. More...

#include <REDShaderString.h>

Inherits: String.

Public functions:

ShaderString ( )
virtual ~ShaderString ( )
voidAlias ( const char * iAlias, const char * iParam )
voidAreaCentricLightDirection ( const char * oLightDir, const char * iPosition )
voidAreaLighting ( const char * oDotNL, const char * iNormal, const char * iSurfaceNormal, const char * iPos, const char * iAttenuationTex, const char * iSampleTex )
template< class T_As > const T_As *As ( ) const
virtual void *As ( const RED::CID & iCID )
virtual const void *As ( const RED::CID & iCID ) const
template< class T_As > T_As *As ( )
voidAttrib ( const char * iAttrib, const char * iParam )
voidBeamLightAttenuation ( const char * oRAtt, const char * iLightVector, const char * iProjectorUV, const char * iTEXatt, const char * iTEXr )
voidChannelAsParam ( const char * iName0, const char * iName1, const char * iName2, int iLocal )
voidChannelAsParamWithMatrix ( const char * oUV, const char * iTUV, int iLocalBind, int iTransformBind = -1 )
voidConvertUVInCubeFaceVector ( const char * oR, int iNumFace, const char * iRUV )
voidCross ( const char * oRD, const char * iR1, const char * iR2 )
voidDirLightAttenuation ( const char * oRAtt, const char * oLightVector, const char * iTEXatt )
RED_RCGeometryShaderStart ( const RED::String & iLibrary, const RED::String & iLabel, const RED::Version & iVersion )
voidGetRayVsTriangleHitPoint ( const char * oRHit, const char * iRUV, const char * iRPos, const char * iRDir )
voidGetRayVsTriangleUV ( const char * ioRUV )
voidGlossyRayDeviation ( const char * ioR, const char * iN, int iJitterBind, int iDevBind, int iSampleBind )
voidIndirectBeamLightAttenuation ( const char * oRAtt, const char * oLightVector, const char * iRPos, const char * iTEXn, const char * iTEXr, const char * ioRTemp )
voidIndirectPointLightAttenuation ( const char * oRAtt, const char * oLightVector, const char * iRPos, const char * iTEXatt, bool iDeclareParams = true )
voidIndirectSpotLightAttenuation ( const char * oRAtt, const char * oLightVector, const char * iRPos, const char * iTEXatt, const char * iTEXs, bool iDeclareParams = true )
voidInterpolate ( const char * oR, const char * iUV, const char * iV0, const char * iV01, const char * iV02 )
voidIntersectRayVsTriangle ( const char * oRUV, const char * oRPos, const char * oRDir, int ifN )
voidLightAttenuation ( const char * oRAtt, const char * iLightVector, const char * iTEXn, bool iDeclareParams = true )
voidMatrix3x3Transform ( const char * oR, const char * iV, const char * iM0, const char * iM1, const char * iM2 )
voidNormalize ( const char * oRUnitVector, const char * iVector )
RED_RCParam ( const char * iName, int iLocal )
RED_RCPixelShaderStart ( )
voidPointLightAttenuation ( const char * oRAtt, const char * oLightVector, const char * iLightVector, const char * iTEXatt, bool iDeclareParams = true )
voidReadBumpMap ( const char * oRVec, const char * iTEXb, const char * iUV2Db, int iTextureCode, int iTextureCodeEntry )
RED_RCShaderEnd ( )
RED_RCShadowMapGaussianBlur ( const char * iS, int iSize, const char * iUV, const char * iTexture, RED::HARDWARE_PLATFORM iPlatformId, bool iDeclareParams = true )
voidSkylightDecay ( const char * oDecay, const char * iTexDecay )
voidSkylightDiffuseLighting ( const char * oDiffuse, const char * iNormal, const char * iSurfaceNormal, const char * iSkylightTex )
RED_RCSmoothStep ( const char * oResult, const char * iMin, const char * iMax, const char * iWeight )
RED_RCSoftShaderStart ( const RED::String & iLibrary, const RED::String & iLabel, const RED::Version & iVersion )
RED_RCSoftShaderStart ( unsigned int iShaderClass )
voidSpotLightAttenuation ( const char * oRAtt, const char * oLightVector, const char * iLightVector, const char * iTEXatt, const char * iTEXs, bool iDeclareParams = true )
voidSpotLightFalloff ( const char * oDecay, const char * iLightDir, const char * iTEXs )
RED_RCTemp ( const char * iName )
voidTex ( const char * oColor, const char * iColor, const char * iTexture, const char * iUV, int iComposite, int iCompositeChannel )
voidTex ( const char * oColor, int iColor, const char * iTexture, const char * iUV, int iComposite, int iCompositeChannel )
RED_RCTriangleIdTransfer ( RED::HARDWARE_PLATFORM iPlatformId )
RED_RCTriangleOwnershipTest ( RED::HARDWARE_PLATFORM iPlatformId )
voidUVTransform ( const char * oRx, const char * oRy, int iN, const char * iUV )
voidUVTransform ( const char * oRUV, const char * iRUV, int iMatrixRowBindPos )
voidVectorLength ( const char * oLength, const char * iVector )
voidVectorTransform ( const char * oR, const char * iRow0, const char * iRow1, const char * iRow2, const char * iV )
voidVectorTransform ( const char * oR, const char * iM, const char * iV )
voidVectorTransform ( const char * oR, int iN, const char * iV )
voidVertexHomogeneousTransform3x4 ( const char * oR, const char * iM, const char * iV )
RED_RCVertexShaderStart ( )
voidVertexTransform ( const char * oR, const char * iM, const char * iV )
voidVertexTransform ( const char * oR, int iN, const char * iV )
voidVertexTransform ( const char * oR, const char * iM0, const char * iM1, const char * iM2, const char * iM3, const char * iV )
voidVertexTransform3x4 ( const char * oR, const char * iM, const char * iV )

Public static functions:

static RED::CIDGetClassID ( )

Protected variables:

RED::Map< RED::String, int >_params

Detailed description:

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:

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.

Functions documentation

ShaderString construction method.

ShaderString destruction method.

public void RED::ShaderString::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.
public void RED::ShaderString::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:

Parameters:

oLightDir:Normalized light direction.
iPosition:Fragment position.
public void RED::ShaderString::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.
template< class T_As > public const T_As * RED::ShaderString::As() const

Template version of the as const method.

Simply set T to be the class you want to retrieve an interface to.

Returns:

A pointer to a const instance of class T on success, NULL otherwise.

Reimplements: RED::String::As.

public virtual void * RED::ShaderString::As(const RED::CID &iCID)

Converts the object to an instance of the given type.

Parameters:

iCID:Requested class.

Returns:

An object pointer of the given class on success, NULL otherwise.

Reimplements: RED::String::As.

public virtual const void * RED::ShaderString::As(const RED::CID &iCID) const

Converts the object to an instance of the given type.

Parameters:

iCID:Requested class.

Returns:

An object pointer of the given class on success, NULL otherwise.

Reimplements: RED::String::As.

template< class T_As > public T_As * RED::ShaderString::As()

Template version of the as method.

Simply set T to be the class you want to retrieve an interface to.

Returns:

A pointer to an instance of class T on success, NULL otherwise.

Reimplements: RED::String::As.

public void RED::ShaderString::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.
public void RED::ShaderString::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:

  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.
public void RED::ShaderString::ChannelAsParam(const char *iName0,
const char *iName1,
const char *iName2,
intiLocal
)

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.
public void RED::ShaderString::ChannelAsParamWithMatrix(const char *oUV,
const char *iTUV,
intiLocalBind,
intiTransformBind = -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.
public void RED::ShaderString::ConvertUVInCubeFaceVector(const char *oR,
intiNumFace,
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.
public void RED::ShaderString::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.
public void RED::ShaderString::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:

  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.
public RED_RC RED::ShaderString::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.
public void RED::ShaderString::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.
public void RED::ShaderString::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))
public void RED::ShaderString::GlossyRayDeviation(const char *ioR,
const char *iN,
intiJitterBind,
intiDevBind,
intiSampleBind
)

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.
public void RED::ShaderString::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:

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.
public void RED::ShaderString::IndirectPointLightAttenuation(const char *oRAtt,
const char *oLightVector,
const char *iRPos,
const char *iTEXatt,
booliDeclareParams = true
)

Computes the indirect attenuation for a point light.

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

Uses:

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.
public void RED::ShaderString::IndirectSpotLightAttenuation(const char *oRAtt,
const char *oLightVector,
const char *iRPos,
const char *iTEXatt,
const char *iTEXs,
booliDeclareParams = true
)

Computes the indirect attenuation for a spot light.

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

Uses:

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.
public void RED::ShaderString::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.
public void RED::ShaderString::IntersectRayVsTriangle(const char *oRUV,
const char *oRPos,
const char *oRDir,
intifN
)

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].
public void RED::ShaderString::LightAttenuation(const char *oRAtt,
const char *iLightVector,
const char *iTEXn,
booliDeclareParams = true
)

Computes the attenuation of a light.

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

Uses built-in parameters:

  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.
public void RED::ShaderString::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.
public void RED::ShaderString::Normalize(const char *oRUnitVector,
const char *iVector
)

Normalizes a vector or register.

  DP3 oRUnitVector.w, iVector, iVector;
  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.
public RED_RC RED::ShaderString::Param(const char *iName,
intiLocal
)

Declares a parameter name from a program local.

  PARAM iName = program.local[iLocal];

See also 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.

Start an ARB 1.0 pixel shader string.

  !!ARBfp1.0

Clears the string and adds the pixel shader header.

See also Cartoon shading.

public void RED::ShaderString::PointLightAttenuation(const char *oRAtt,
const char *oLightVector,
const char *iLightVector,
const char *iTEXatt,
booliDeclareParams = true
)

Computes the attenuation for a point light.

Calculates the attenuation for a point light intensity falloff.

Uses built-in parameters:

  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.
public void RED::ShaderString::ReadBumpMap(const char *oRVec,
const char *iTEXb,
const char *iUV2Db,
intiTextureCode,
intiTextureCodeEntry
)

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.

Marks the end of the shader.

  END

Adds the shader termination tag to the string contents.

See also Cartoon shading.

Returns:

RED_OK if the operation has succeeded,
RED_ALLOC_FAILURE if a memory allocation has failed.
public RED_RC RED::ShaderString::ShadowMapGaussianBlur(const char *iS,
intiSize,
const char *iUV,
const char *iTexture,
RED::HARDWARE_PLATFORMiPlatformId,
booliDeclareParams = 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.
public void RED::ShaderString::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.
public void RED::ShaderString::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.
public RED_RC RED::ShaderString::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.
public RED_RC RED::ShaderString::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 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.
public RED_RC RED::ShaderString::SoftShaderStart(unsigned intiShaderClass)

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.
public void RED::ShaderString::SpotLightAttenuation(const char *oRAtt,
const char *oLightVector,
const char *iLightVector,
const char *iTEXatt,
const char *iTEXs,
booliDeclareParams = true
)

Computes the attenuation for a spot light.

Calculates the attenuation for a spot light intensity falloff.

Uses:

  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.
public void RED::ShaderString::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.
public RED_RC RED::ShaderString::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 Cartoon shading.

Parameters:

iName:Parameter string name.

Returns:

RED_OK if the operation has succeeded,
RED_ALLOC_FAILURE if a memory allocation has failed.
public void RED::ShaderString::Tex(const char *oColor,
const char *iColor,
const char *iTexture,
const char *iUV,
intiComposite,
intiCompositeChannel
)

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 ].
public void RED::ShaderString::Tex(const char *oColor,
intiColor,
const char *iTexture,
const char *iUV,
intiComposite,
intiCompositeChannel
)

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 ].

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.

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.
public void RED::ShaderString::UVTransform(const char *oRx,
const char *oRy,
intiN,
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.
public void RED::ShaderString::UVTransform(const char *oRUV,
const char *iRUV,
intiMatrixRowBindPos
)

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.
public void RED::ShaderString::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.
public void RED::ShaderString::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.
public void RED::ShaderString::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.
public void RED::ShaderString::VectorTransform(const char *oR,
intiN,
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.
public void RED::ShaderString::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.

Starts an ARB 1.0 vertex shader string.

  !!ARBvp1.0

Clears the string contents and adds the vertex shader header.

See also Cartoon shading.

public void RED::ShaderString::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 Cartoon shading.

Parameters:

oR:Output register.
iM:Matrix string name. We use "iM.row[0-3]".
iV:Input vector.
public void RED::ShaderString::VertexTransform(const char *oR,
intiN,
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 Cartoon shading.

Parameters:

oR:Output register.
iN:Register number with matrix rows. We use "program.local[n-n+3]".
iV:Input vector.
public void RED::ShaderString::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 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.
public void RED::ShaderString::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 Cartoon shading.

Parameters:

oR:Output register.
iM:Matrix string name. We use "iM.row[0-2]".
iV:Input vector.

Variables documentation

_params: List of parameters that have been declared for the current shader.