IImageComposite

Functions

Detailed Description

class IImageComposite : public RED::IREDObject 

This interface gives access to the composite image properties.

A composite image is a screen sized and screen space image. The contents of a composite image is dynamically calculated during the rendering of a frame, for each rendering workflow.

The contents of a composite image is therefore defined by two RED::RenderShader objects instances that are set to produce the composite contents. One shader is for direct rendering purposes, the other for indirect GPU ray-traced rendering purposes.

The geometry of the material using the composite image is used to draw the contents of the composite into a screen sized buffer image. The resulting image, which is screen space and also sized to the screen (RED::TGT_TEX_RECT) of the rendered window can then be reused into any of the shaders of the material using the composite.

Recursive composites can be created, defining that way a shading tree inside a single material.

In order to use a composite, two steps must be taken care of:

Define the format of the composite: this defines the format of the texture of the composite.
Define the rendering shaders to define the composite contents. Note that using any of the built-in composite functions will do that job.

A composite image has no mipmaps, uses a clamp to edge wrap mode, and nearest texture filters.

For all built-in composite creation routines that are provided in this class, the image RED::RenderShader object that is used for all direct lighting calculations has two runtime platforms: a RED::HW_GENERIC configuration and a RED::HW_SOFT_TRACER configuration. The indirect render shader has two runtime platforms being defined: RED::HW_NVIDIA_GENERIC and RED::HW_ATI_GENERIC.

For an in-depth coverage of the images in REDsdk, please read: \ref bk_images.

Public Functions

SET_CID(CID_class_REDIImageComposite)

virtual RED_RC SetRenderShader(const RED::RenderShader &iRenderShader, bool iDirect, const RED::State &iState) = 0

Sets the composite image render shaders.

Parameters

iRenderShader – The compositing shader.
iDirect – true to assign the direct render shader, false to assign the indirect render shader.
iState – Current transaction.

Returns

RED_OK when the operation has succeeded,

RED_WORKFLOW_ERROR if a transaction error was found,

RED_WORKFLOW_ERROR if a software tracer image is being processed,

RED_ALLOC_FAILURE if an internal allocation has failed,

RED_FAIL otherwise.

virtual const RED::RenderShader *GetShader(bool iDirect, int iStateNumber = -1) const = 0

Gets a Read-Only access to the compositing shader.

Parameters

iDirect – true to get the direct shader, false to get the indirect shader.
iStateNumber – Queried state number.

Returns

The address of the compositing shader. NULL if an error has occurred.

virtual RED_RC GetShader(RED::RenderShader *&oShader, bool iDirect, const RED::State &iState) = 0

Gets a Read-Write access to the compositing shader.

Parameters

oShader – The address of our compositing shader.
iDirect – true to get the direct shader, false to get the indirect shader.
iState – Current transaction.

Returns

RED_OK when the operation succeeded,

RED_ALLOC_FAILURE if an internal allocation did fail,

RED_FAIL otherwise.

virtual RED_RC SetFormat(RED::FORMAT iFormat, const RED::State &iState) = 0

Defines the format of the composite image.

The same image composition may produce different results, depending on the format of the buffer that is used to generate the composite. This method is used to specify the final pixel format of the image.

Parameters

iFormat – Image format of the composite. Compressed formats are not accepted by composite images.
iState – Current transaction parameter.

Returns

RED_OK when the modification succeeded,

RED_BAD_PARAM if the format is not valid for a composite. This includes all compressed image format.

RED_WORKFLOW_ERROR if a transaction error was found,

RED_WORKFLOW_ERROR if a software tracer image is being processed,

RED_ALLOC_FAILURE if an internal memory allocation did fail,

RED_FAIL if a graphic driver error occurred.

virtual RED::FORMAT GetFormat(int iStateNumber = -1) const = 0

Gets the pixel format of the composite image.

Returns the pixel format of the composite image. If no pixel format has been set for the image, it’s assumed to be a NODATA composite.

Parameters: iStateNumber – Queried state number.
Returns: The pixel format of the composite image.

virtual RED_RC SetClearColor(const RED::Color &iColor, const RED::State &iState) = 0

Defines the composite clear color.

Define the clear color of the composite before proceeding to the draw of the geometry. The default color is black, no alpha.

Parameters

iColor – The clear color to use for this composite.
iState – Current transaction parameter.

Returns

RED_OK if the operation has succeeded,

RED_WORKFLOW_ERROR if a transaction error has occurred,

RED_ALLOC_FAILURE if an internal memory allocation has failed,

RED_FAIL otherwise.

virtual RED_RC GetClearColor(RED::Color &oColor, int iStateNumber = -1) const = 0

Returns the composite clear color.

Return the clear color of the composite.

Parameters

oColor – The current clear color for the composite.
iStateNumber – Queried state number.

Returns

RED_OK if the operation has succeeded,

RED_BAD_PARAM if the method has received an invalid parameter,

virtual RED_RC Channel(const RED::Color &iColorR, const RED::Object *iTexR, const RED::Matrix &iMatxR, RED::MESH_CHANNEL iUVR, RED::CHANNEL iSourceR, const RED::Color &iColorG, const RED::Object *iTexG, const RED::Matrix &iMatxG, RED::MESH_CHANNEL iUVG, RED::CHANNEL iSourceG, const RED::Color &iColorB, const RED::Object *iTexB, const RED::Matrix &iMatxB, RED::MESH_CHANNEL iUVB, RED::CHANNEL iSourceB, const RED::Color &iColorA, const RED::Object *iTexA, const RED::Matrix &iMatxA, RED::MESH_CHANNEL iUVA, RED::CHANNEL iSourceA, RED::Object *iResMgr) = 0

Composite image built from separate channels from different source images.

This method builds a composite images that uses four different colors or images as source for each of its channels.

A color or a texture can be specified for each channel. When a texture is specified, it overrides the provided color value.

Parameters

iColorR – Red source color.
iTexR – Red channel source texture.
iMatxR – Red channel texture transformation matrix.
iUVR – Red channel texture source UV.
iSourceR – source channel of the Red color or texture to use.
iColorG – Green source color.
iTexG – Green channel source texture.
iMatxG – Green channel texture transformation matrix.
iUVG – Green channel texture source UV.
iSourceG – source channel of the Red color or texture to use.
iColorB – Blue source color.
iTexB – Blue channel source texture.
iMatxB – Blue channel texture transformation matrix.
iUVB – Blue channel texture source UV.
iSourceB – source channel of the Red color or texture to use.
iColorA – Alpha source color.
iTexA – Alpha channel source texture.
iMatxA – Alpha channel texture transformation matrix.
iUVA – Alpha channel texture source UV.
iSourceA – source channel of the Red color or texture to use.
iResMgr – The cluster’s resource manager.

Returns

RED_OK when the composite image could be setup properly,

RED_BAD_PARAM if the method has received an invalid parameter,

RED_WORKFLOW_ERROR if a transaction error has been found,

RED_WORKFLOW_ERROR if a software tracer image is being processed,

RED_ALLOC_FAILURE if an internal memory allocation has failed,

RED_FAIL otherwise.

virtual RED_RC Mix(const RED::Color &iColor1, const RED::Object *iTex1, const RED::Matrix &iMatx1, RED::MESH_CHANNEL iUV1, const RED::Color &iColor2, const RED::Object *iTex2, const RED::Matrix &iMatx2, RED::MESH_CHANNEL iUV2, const RED::Color &iColorMix, const RED::Object *iTexMix, const RED::Matrix &iMatxMix, RED::MESH_CHANNEL iUVMix, RED::Object *iResMgr) = 0

Creation of a composite mixing two textures with a third one.

This method builds a composite image that uses one texture as a color mixer over two others. The used mixing formula is:

color = cmix * ctexture1 + (1.0f - cmix) * ctexture2.

Parameters

iColor1 – First color to mix.
iTex1 – First texture to mix. Overrides iColor1 when set.
iMatx1 – First texture matrix.
iUV1 – First texture UV channel.
iColor2 – Second color to mix.
iTex2 – Second texture to mix. Overrides iColor2 when set.
iMatx2 – Second texture matrix.
iUV2 – Second texture UV channel.
iColorMix – Mixing color.
iTexMix – Mixing texture. Overrides iColorMix when set.
iMatxMix – Mixing texture transformation matrix.
iUVMix – Mixing texture UV channel.
iResMgr – The cluster’s resource manager.

Returns

RED_OK when the composite image could be setup properly,

RED_BAD_PARAM if the method has received an invalid parameter,

RED_WORKFLOW_ERROR if a transaction error has been found,

RED_WORKFLOW_ERROR if a software tracer image is being processed,

RED_ALLOC_FAILURE if an internal memory allocation has failed,

RED_FAIL otherwise.

virtual RED_RC ReferenceMix(const RED::Color &iColor1, const RED::Object *iTex1, const RED::Matrix &iMatx1, RED::MESH_CHANNEL iUV1, RED::RenderShaderParameter::TYPE iRef1, const RED::Color &iColor2, const RED::Object *iTex2, const RED::Matrix &iMatx2, RED::MESH_CHANNEL iUV2, RED::RenderShaderParameter::TYPE iRef2, const RED::Color &iColorMix, const RED::Object *iTexMix, const RED::Matrix &iMatxMix, RED::MESH_CHANNEL iUVMix, RED::RenderShaderParameter::TYPE iRefMix, RED::Object *iResMgr) = 0

Creation of a composite mixing two textures with a third one.

This method is similar to REDImageComposite::Mix, except that the two texture may use RED::RenderShaderParameter image references as source parameters.

Parameters

iColor1 – First color to mix.
iTex1 – First texture to mix. Overrides iColor1 when set.
iMatx1 – First texture matrix.
iUV1 – First texture UV channel.
iRef1 – Reference image to use. Overrides iTex1 when set. Use RED::RenderShaderParameter::TYPE::FREE to invalidate the reference selection.
iColor2 – Second color to mix.
iTex2 – Second texture to mix. Overrides iColor2 when set.
iMatx2 – Second texture matrix.
iUV2 – Second texture UV channel.
iRef2 – Reference image to use. Overrides iTex2 when set. Use RED::RenderShaderParameter::TYPE::FREE to invalidate the reference selection.
iColorMix – Mixing color.
iTexMix – Mixing texture. Overrides iColorMix when set.
iMatxMix – Mixing texture transformation matrix.
iUVMix – Mixing texture UV channel.
iRefMix – Reference image to use. Overrides iTexMix when set. Use RED::RenderShaderParameter::TYPE::FREE to invalidate the reference selection.
iResMgr – The cluster’s resource manager.

Returns

RED_OK when the composite image could be setup properly,

RED_BAD_PARAM if the method has received an invalid parameter,

RED_WORKFLOW_ERROR if a transaction error has been found,

RED_WORKFLOW_ERROR if a software tracer image is being processed,

RED_ALLOC_FAILURE if an internal memory allocation has failed,

RED_FAIL otherwise.

virtual RED_RC Layered(const RED::Object *iTex[7], const RED::Matrix iMatx[7], RED::MESH_CHANNEL iUV[7], int iNbImages, RED::LAYER_MODE iLayerMode, RED::Object *iResMgr) = 0

Creation of a composite made of overlapping textures.

This method builds a composite image made of successive overlaps of the provided textures. The compositing formula takes the alpha values into consideration:

1 texture: c0 = tex0_rgba.
2 textures: c1 = tex1_a * tex1_rgba + (1-tex1_a)*c0.
n textures: cn = texn_a * texn_rgba + (1-texn_a)*c(n-1).

We can’t composite more than 7 textures, due to low end GPU binding capabilities. To layer more textures, please assemble a hierarchy of composite images.

Parameters

iTex – Array of addresses of all images to composite.
iMatx – Array of transformation matrices for these images.
iUV – Array of mesh channels to use for the sampling of the images.
iNbImages – Number of entries to composite. Maximum allowed is 7.
iLayerMode – Indicates the layer composition mode.
iResMgr – The cluster’s resource manager.

Returns

RED_OK when the composite image could be setup properly,

RED_BAD_PARAM if the method has received an invalid parameter,

RED_WORKFLOW_ERROR if a transaction error has been found,

RED_WORKFLOW_ERROR if a software tracer image is being processed,

RED_ALLOC_FAILURE if an internal memory allocation has failed,

RED_FAIL otherwise.

virtual RED_RC Fresnel(const RED::Color &iOpacityColor, const RED::Object *iOpacityTexture, const RED::Matrix &iOpacityMatrix, RED::MESH_CHANNEL iOpacityUV, const RED::StateShader &iAlphaMask, RED::Object *iResMgr) = 0

Creation of a fresnel term composite image.

This method sets up a composite that produces a per pixel fresnel value that can be used to balance the amount of reflection and refraction to apply to an object.

This method uses the Schlick approximation of the Fresnel equations within a dielectric material.

The value produced by this method is the modulation of the provided opacity parameters by the calculated fresnel term. This means that this composite should replace the base transparency parameters of the object, for the part that modulates the destination buffer color at the object’s rendering startup:

// Schlick's formula (n1, n2 are our material refractive indices
// on both sides of the surface we cross). 'r' is the reflectance:
r0 = ((n1 - n2) / (n1 + n2))^2
r  = r0 + (1 - r0)*(1 - cos(angle(normal,eye)))^5

// Resulting interpolation (opacity stands for our opacity value,
// whatever may be the source (color or texture)):
result.color.xyz = (1 - r)* opacity + r
result.color.w   = r

Then, this formula works with a 0 x SRC_COLOR + (1 - SRC_COLOR) x DST_COLOR blending formula for the first shader of the material.

The ‘.w’ output value of the resulting texture is the fresnel term value, without considering any relation with the opacity value.

The output of this composite is valid when ray-traced refractions are enabled. Otherwise, the returned value is the input opacity.

This composite image can be used directly in the RED::ReflectionShader as the iFresnel value for the reflective part (works similarly in the RED::ReflectionBackgroundShader) and it can be used in the transparency setup of the refractive part of the object (in the RED::StateShader).

Parameters

iOpacityColor – Opacity color (RED::Color::WHITE is fully opaque, RED::Color::BLACK is fully transparent). This parameter is ignored when iOpacityTexture is set.
iOpacityTexture – Opacity texture, NULL to use the color instead.
iOpacityMatrix – Opacity texture transformation matrix.
iOpacityUV – Opacity texture UV mesh channel.
iAlphaMask – Additional alpha masking parameter that may be specified to refine the object’s surface.
iResMgr – The cluster’s resource manager.

Returns

RED_OK when the composite image could be setup properly,

RED_BAD_PARAM if the method has received an invalid parameter,

RED_WORKFLOW_ERROR if a transaction error has been found,

RED_WORKFLOW_ERROR if a software tracer image is being processed,

RED_ALLOC_FAILURE if an internal memory allocation has failed,

RED_FAIL otherwise.

virtual RED_RC FresnelReflect(const RED::StateShader &iAlphaMask, float iIOR, const RED::Object *iNormalMap, const RED::Matrix &iNormalMatrix, RED::MESH_CHANNEL iNormalUV, RED::MESH_CHANNEL iTangentChannel, RED::Object *iResMgr) = 0

Creation of a fresnel reflection term composite image.

This image produces a per pixel Fresnel value that can be used to modulate the amount of reflection applied to an object. As the RED::IImageComposite::Fresnel method it’s integrated as the iFresnel term of the RED::ReflectionShader (or of the RED::ReflectionBackgroundShader).

This method uses the same approximation to the Fresnel equations than above (i.e Schlick’s approximation).

Parameters

iAlphaMask – Additional alpha masking parameter that may be specified to refine the objec’s surface.
iIOR – index of refraction of the surface.
iNormalMap – Normal map that affect the normal and therefore the Fresnel distribution.
iNormalMatrix – Transformation matrix for the normal map.
iNormalUV – UV channel used to sample the normal map.
iTangentChannel – Tangent space channel for the normal mapping.
iResMgr – The cluster’s resource manager.

Returns

RED_OK when the composite image could be setup properly,

RED_BAD_PARAM if the method has received an invalid parameter,

RED_WORKFLOW_ERROR if a transaction error has been found,

RED_WORKFLOW_ERROR if a software tracer image is being processed,

RED_ALLOC_FAILURE if an internal memory allocation has failed,

RED_FAIL otherwise.

virtual RED_RC FalloffColor(const RED::Color &iColor1, const RED::Color &iColor2, RED::Object *iResMgr) = 0

Creation of a falloff coloring effect.

The falloff is a blending of two colors by a coefficient which depends on the angle of the geometry normal at the shaded point and the viewing direction. The wider the angle, the greater the coefficient value, resulting in a greater view of iColor2.

Parameters

iColor1 – First falloff color (visibiliy increases with normals facing toward the viewer).
iColor2 – Second normal color (visibility increases with normals perpendicular to the viewing direction).
iResMgr – The cluster’s resource manager.

Returns

RED_OK when the composite image could be setup properly,

RED_BAD_PARAM if the method has received an invalid parameter,

RED_WORKFLOW_ERROR if a transaction error has been found,

RED_WORKFLOW_ERROR if a software tracer image is being processed,

RED_ALLOC_FAILURE if an internal memory allocation has failed,

RED_FAIL otherwise.

	`SET_CID`
`RED_RC`	`SetRenderShader`
const RenderShader *	`GetShader`
`RED_RC`	`GetShader`
`RED_RC`	`SetFormat`
`FORMAT`	`GetFormat`
`RED_RC`	`SetClearColor`
`RED_RC`	`GetClearColor`
`RED_RC`	`Channel`
`RED_RC`	`Mix`
`RED_RC`	`ReferenceMix`
`RED_RC`	`Layered`
`RED_RC`	`Fresnel`
`RED_RC`	`FresnelReflect`
`RED_RC`	`FalloffColor`