RenderShaderAmbient
Functions
Detailed Description
-
class RenderShaderAmbient : public RED::RenderShader
Ambient lighting shader.
@related Using Built-in Render Shaders, class RED::IMaterial, class RED::RenderShader, class RED::StateShader, class RED::RenderCode
This shader can be used to produce a base ambient lighting. There are two possible ambient shading equations in REDsdk. The new equation (iNewAmbient = true):
I = transpar_color * ( base_color * global_illumination + ambient_color * ambient_light + emissive_color )
I.w = transpar_color.w
In this equation, we have two ambient terms: the base color that modulates the global illumination contribution, and the ambient color that modulates the amount of ambient lighting that results of RED::ILightShape::SetAmbientLight if an ambient light is set into the scene.
The legacy equation (iNewAmbient = false):
I = transpar_color * ( base_color * ( global_illumination + ambient_color + ambient_light ) + emissive_color )
I.w = transpar_color.w
This legacy equation was used for all REDsdk ambient shaders prior to version 4.3. It’s kept for compatibility reasons. Compared to the previous equation, it does not allow the decoupling of the modulation applied to the ambient light from the light GI term.
Please, note that even if the transparency parameter is called transpar_color, it is an opacity value. It means that if this value is white, the shader is fully opaque, and if this value is black, the shader is fully transparent.
Each component of this equation may be defined as a color or as a texture. If a texture is used for the calculation, then it can be associated to its own texture matrix.
UVs must be specified if a texture is to be used by the shader. This shader supports RED::TGT_TEX_2D textures, that must be sampled with normalized UVs, composite textures, that are sampled at the shaded fragment position, or RED::TGT_TEX_RECT textures that are sampled using denormalized UVs.
As said above, if the engine does not find any RED_LIGHT_AMBIENT light source, then the ‘ambient_light’ color term is set to 0.
The ‘global_illumination’ term has different values depending on the rendering workflow that is being used:
In any configuration, the ‘global_illumination’ term is evaluated first using a pre-processed irradiance cache that may have been set on a camera thanks to RED::IViewpointRenderList::SetViewpointGICaches (see also the RED::IWindow::FrameTracingGICache for the generation of a GI cache).
If no pre-processed cache has been set, in the RED::HW_SOFT_TRACER configuration, the ‘global_illumination’ term is set to the amount of light received by all lighting phenomenon that are calculated by the global illumination setup. Otherwise, it’s set to 0.
In any hardware configuration, the ‘global_illumination’ term is 0 unless a pre-processed irradiance cache has been set as explained above.
This shader uses the following geometrical channels:
RED::MCL_VERTEX: vertex array of the rendered meshes.
RED::MCL_NORMAL: normal array of the rendered meshes (for global illumination needs).
RED::MCL_TEX0 - n: (optional) texture coordinates of the rendered meshes.
The RenderShaderAmbient can be used in a direct or indirect lighting configuration. This is selected at the shader’s creation time. A direct shader should go to the RED::MTL_PRELIT pass of the material, whereas an indirect shader should go to its RED::MTL_INDIRECT_PRELIT pass. Note that post-lighting passes may also be targeted.
This shader creates the following platform configurations. If created using a direct lighting pass:
If created using an indirect lighting pass:
All parameters declared by this shader are using the RED_SHAD_TARGET_LIGHT_NO_LIGHT shader target (commonly used in its shortcut form RED_L0).
See the REDRenderShaderAmbient.h file documentation for the list of all #define statements used to name all parameters of this shader.
Public Functions
-
SET_CID(CID_class_REDRenderShaderAmbient)
-
IMPLEMENT_AS()
-
RenderShaderAmbient(RED::MATERIAL_PASS iRenderingPass, const RED::Color &iBaseColor, const RED::Object *iBaseTexture, const RED::Matrix &iBaseTextureMatrix, RED::MESH_CHANNEL iBaseUV, const RED::Color &iAmbientColor, const RED::Object *iAmbientTexture, const RED::Matrix &iAmbientTextureMatrix, RED::MESH_CHANNEL iAmbientUV, const RED::Color &iEmissiveColor, const RED::Object *iEmissiveTexture, const RED::Matrix &iEmissiveTextureMatrix, RED::MESH_CHANNEL iEmissiveUV, const RED::Color &iTransparColor, const RED::Object *iTransparTexture, const RED::Matrix &iTransparTextureMatrix, RED::MESH_CHANNEL iTransparUV, bool iNewAmbient, RED::Object *iResMgr, RED_RC &oErrorCode)
Constructor.
All textures used by this method may either be 2D images using the RED::TGT_TEX_2D target or composite images or rectangular images using the RED::TGT_TEX_RECT target. Sampling UVs that are needed to sample 2D textures must be normalized. Sampling UVs that are needed to sample rectangular textures are denormalized with values directly sampling texels coordinates.
- Parameters
iRenderingPass – The target rendering pass in RED::MTL_PRELIT, RED::MTL_INDIRECT_PRELIT, RED::MTL_POSTLIT or RED::MTL_INDIRECT_POSTLIT.
iBaseColor – Base color.
iBaseTexture – Base texture. Overrides the base color when set.
iBaseTextureMatrix – Base texture transformation matrix.
iBaseUV – Base UV mesh channel number to use for the texture mapping.
iAmbientColor – Ambient color.
iAmbientTexture – Ambient texture. Overrides the ambient color when set.
iAmbientTextureMatrix – Ambient texture transformation matrix.
iAmbientUV – Ambient UV mesh channel number to use for the texture mapping.
iEmissiveColor – Emissive color.
iEmissiveTexture – Emissive texture. Overrides the emissive color when set.
iEmissiveTextureMatrix – Emissive texture transformation matrix.
iEmissiveUV – Emissive UV mesh channel number to use for the texture mapping.
iTransparColor – Opacity color (white: fully opaque; black: fully transparent).
iTransparTexture – Opacity texture. Overrides the transparency color when set.
iTransparTextureMatrix – Opacity texture transformation matrix.
iTransparUV – Opacity UV mesh channel number to use for the texture mapping.
iNewAmbient – If true, the shader uses the new ambient equation described in the class details, that allow the base color to modulate the GI contribution and the ambient color to modulate the ambient lighting contribution. If false, the legacy ambient equation is used for which the base color modulates the sum of the GI, ambient color and ambient light.
iResMgr – The cluster’s resource manager.
oErrorCode – Indicates a construction failure when not returned set to RED_OK.
-
virtual ~RenderShaderAmbient()
Destructor.
Public Static Functions
-
static RED_RC LoadProgram(RED::String &oString, const RED::ShaderProgramID &iID)
Loads a shader program.
Generates a shader program that corresponds to the specified iID.
- Parameters
oString – The created program string.
iID – The shader program unique ID.
- Returns
RED_OK if the shader could be loaded,
RED_ALLOC_FAILURE if an allocation has failed,
RED_FAIL otherwise.
-
static RED_RC EvaluateFromInputParameters(RED::RenderShader *ioShader, RED::Object *iResMgr)
Evaluate a shader from its input parameters.
- Parameters
ioShader – Shader to redefine using its own input parameters.
iResMgr – The cluster’s resource manager.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if iShader was not valid,
RED_BAD_PARAM if an invalid parameter was found during the evaluation,
RED_ALLOC_FAILURE if a memory allocation has failed,
Other RED_RC related to shader creation can be returned.
