RenderLayer

Types

LAYER_TYPE

Fields

LT_UNKNOWN

LT_COLOR

LT_DEPTH

LT_OBJECT_ID

LT_PRIMITIVE_ID

LT_MATERIAL_ID

LT_NORMAL

LT_REFLECTION

LT_REFRACTION

LT_MASK

LT_COMPUTED

LT_DIRECT

LT_INDIRECT

LT_DIFFUSE

LT_PATH

LT_COUNT

Functions

CID

GetClassID

void *

As

const void *

As

class T_As

As

class T_As

As

RenderLayer

RenderLayer

~RenderLayer

RED_RC

operator=

LAYER_TYPE

GetType

Object *

GetImage

Object *

GetViewpoint

Object *

GetMaterialFromMaterialID

const ShapePath &

GetShapePathFromObjectID

Vector < Object * > &

GetMIDToMatrTable

Map < unsigned int, ShapePath > &

GetUIDToPathTable

void

SetMaskColor

const Color &

GetMaskColor

int

GetUpdateState

void

SetUpdateState

Detailed Description

class RenderLayer : public RED::Object

Defines a rendering layer that can be sent and returned during the software processing of an image.

The RED::RenderLayer class is used to specify a given rendering layer (color information, depth buffer normal directions, objects ID, …) that is to be calculated and returned from the software ray-tracer while processing an image. A render layer can also specify extra input informations sent to the software ray-tracer (such as the RED::RenderLayer::LT_MASK).

A RED::RenderLayer is set as a parameter of RED::IWindow::FrameTracingImageLayers. After completion, the RED::RenderLayer is filled with all the relevant informations of that layer. The RED::RenderLayer object neither creates the image filled during the calculation of the layer nor releases it. It’s the responsibility of the caller to allocate and destroy the image used by the layer.

A render layer image has the following format:

The color and depth layer images are available both on the CPU and on the GPU. All other render layers are only available on the CPU for those rendered using a RED::IWindow::FrameTracingImageLayers call.

Some layers have specific shading requirements: The RED::RenderLayer::LT_NORMAL can only be calculated for geometries that are rendered with materials that have a shader describing their normals - e.g. that are supplying informations for the RED_SHAD_TARGET_GI_NORMAL rendering target.

The reflection and refraction layers have no luminance information stored in their images. The luminance of the rendering result of a scene comes from the global scene signal. Therefore luminance information is found on the RED::RenderLayer::LT_COLOR layer and only on this layer.

The RED::RenderLayer::LT_MASK layer is used as an input layer to mask the pixels calculated in an image. Any pixel in the image whose first color component is equal to zero is discarded from the processing of the software ray-tracer. The masking layer pixels are read back on the CPU using a RED::IImage2D::GetPixels call, therefore any contents stored in local storage of the masking layer will be lost.

A pixel discarded by the RED::RenderLayer::LT_MASK is returned with a color defined by RED::RenderLayer::SetMaskColor. The default color is RED::Color::BLACK.

All layers have their (0,0) pixel located at the anchoring position of the rendered camera in the VRL. Therefore if a camera is anchored at (100,100) pixels in a viewport whose dimensions are (300,300) in a window whose size is 1024 x 768, then layers images will cover a 300 x 300 pixel surface.

Public Types

enum LAYER_TYPE

Enumeration of all the possible layer types that can be generated.

Values:

enumerator LT_UNKNOWN

Unspecified layer type.

enumerator LT_COLOR

Color buffer image layer. Layer format varies with the rendering setup. Depends on the HDR setup and anti-aliasing of the rendered scene. May be in RED::FMT_RGB, RED::FMT_RGBA, RED::FMT_HALF_FLOAT_RGBA, RED::FMT_FLOAT_RGBA, RED::FMT_FLOAT_RGBA_AA.

enumerator LT_DEPTH

Depth buffer image layer. Image format is RED::FMT_FLOAT.

enumerator LT_OBJECT_ID

Object unique identifier image layer. Image format is RED::FMT_RGBA.

enumerator LT_PRIMITIVE_ID

Triangle / line / point number image layer. Image format is RED::FMT_RGBA. Value is encoded as: number = r + ( g << 8 ) + ( b << 16 ) + ( a << 24 ).

enumerator LT_MATERIAL_ID

Material identifier image layer. Image format is RED::FMT_RGBA.

enumerator LT_NORMAL

Geometrical normal image layer. Image format is RED::FMT_FLOAT_RGB.

enumerator LT_REFLECTION

Reflection image layer. Image format is the same as RED::RenderLayer::LT_COLOR.

enumerator LT_REFRACTION

Refraction image layer. Image format is the same as RED::RenderLayer::LT_COLOR.

enumerator LT_MASK

Input image masking layer. Can be of any image format. If the first color component of a pixel is zero, then that pixel will not be processed by the software ray-tracer and black will be returned.

enumerator LT_COMPUTED

Generated pixels image layer. This render layer is filled with 0 for pixels that have not been calculated yet and with 255 for pixels that have been calculated. Please note that other layers informations associated to the LT_COMPUTED layer may still vary during the different rendering phases, due to the feedback image reconstruction.

enumerator LT_DIRECT

Direct lighting image layer. This render layer contains the direct light received by the surface seen through the pixel. Image format is the same as RED::RenderLayer::LT_COLOR.

enumerator LT_INDIRECT

Indirect lighting image layer. This render layer contains the indirect light received by the surface seen through the pixel. Image format is the same as RED::RenderLayer::LT_COLOR.

enumerator LT_DIFFUSE

Diffuse image layer. This render layer contains the diffuse term of the surface seen through the pixel. Image format is the same as RED::RenderLayer::LT_COLOR.

enumerator LT_PATH

Path-tracing image layer. This render layer contains the accumulated pixel color during path-tracing. While the RGB components store the accumulated pixel color (sum of samples), the A component stores the number of accumulated colors (number of samples). Image format is the RED::FMT_FLOAT_RGBA.

enumerator LT_COUNT

Number of valid render layers we have in this enumeration.

Public Functions

virtual void *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.

virtual const void *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.

template<class T_As>
inline T_As *As()
template<class T_As>
inline const T_As *As() const
RenderLayer(RED::RenderLayer::LAYER_TYPE iType, RED::Object *iImage, RED::Object *iViewpoint, RED_RC &oRC)

RenderLayer construction method.

Builds a rendering layer.

Parameters

  • iType – The type of rendering layer to generate.

  • iImage – The image in which the results of the rendering are to be stored. iImage must be a valid image object created using RED::IResourceManager::CreateImage2D by the caller. In addition, the target of iImage must either be RED::TGT_NONE (case of an empty image after its creation) or RED::TGT_TEX_RECT.

  • iViewpoint – The camera from which the layer is to be calculated.

  • oRC –

    Returned set to RED_OK if the layer was successfully created,

    RED_BAD_PARAM if the method has received a bad camera or an invalid image,

    RED_FAIL otherwise.

RenderLayer(const RED::RenderLayer &iSourceOp)

Copy constructor.

Parameters

iSourceOp – The source render layer we’re copied from.

~RenderLayer()

Destructor.

This method does not release the image used by the layer. Other layer proprietary data are released.

RED_RC operator=(const RED::RenderLayer &iRightOp)

Assignment operator.

Parameters

iRightOp – Right operand to the equality operator.

Returns

RED_OK if the operation has succeeded,

RED_ALLOC_FAILURE if a memory allocation has failed.

inline RED::RenderLayer::LAYER_TYPE GetType() const
Returns

The type of the render layer.

inline RED::Object *GetImage() const
Returns

The address of the image currently used by the layer.

inline RED::Object *GetViewpoint() const
Returns

The address of the viewpoint of that layer.

RED::Object *GetMaterialFromMaterialID(unsigned char iR, unsigned char iG, unsigned char iB, unsigned char iA) const

Material ID to material access.

Retrieve the address of a material corresponding to an ID stored in the RED::RenderLayer::LT_MATERIAL_ID layer. The ID is sent as a [ iR, iG, iB, iA ] value that can be read directly from the material ID layer image.

Please note that this method should not be called before the return of RED::IWindow::FrameTracingImageLayer method.

Parameters

  • iR – The R component of the ID of the material read from the material ID image.

  • iG – The G component of the ID of the material read from the material ID image.

  • iB – The B component of the ID of the material read from the material ID image.

  • iA – The A component of the ID of the material read from the material ID image.

Returns

The address of the material corresponding to this ID, NULL if no material matches the specified ID.

const RED::ShapePath &GetShapePathFromObjectID(unsigned char iR, unsigned char iG, unsigned char iB, unsigned char iA) const

Retrieves the path of a shape instance from an object ID.

This method retrieves the full scene graph path of an object identified by a [ iR, iG, iB, iA ] value read from a RED::RenderLayer::LT_OBJECT_ID layer.

Please note that this method should not be called before the return of RED::IWindow::FrameTracingImageLayer method.

Parameters

  • iR – The R component of the ID of the object read from the object ID image.

  • iG – The G component of the ID of the object read from the object ID image.

  • iB – The B component of the ID of the object read from the object ID image.

  • iA – The A component of the ID of the object read from the object ID image.

Returns

The shape path corresponding to this ID. The shape path will be empty if the ID does not correspond to any valid object in the scene.

inline RED::Vector<RED::Object*> &GetMIDToMatrTable()

Gets the material ID to material table.

This table can be dynamically accessed by the rendering thread, and should be accessed only after RED::IWindow::FrameTracingImageLayers has returned.

Returns

The conversion table from an ID to a material.

inline RED::Map<unsigned int, RED::ShapePath> &GetUIDToPathTable()

Gets the object ID to shape path table.

This table can be dynamically accessed by the rendering thread, and should be accessed only after RED::IWindow::FrameTracingImageLayers has returned.

Returns

The conversion table from an object ID to a shape path.

inline void SetMaskColor(const RED::Color &iColor)

Defines the RED::RenderLayer::LT_MASK color for discarded pixels.

This method sets the color that is used by the renderer to fill-in pixels that are discarded using the RED::RenderLayer::LT_MASK input rendering layer. By default, this color is RED::Color::BLACK.

Parameters

iColor – The new discarded pixels mask color.

inline const RED::Color &GetMaskColor() const

Retrieves the RED::RenderLayer::LT_MASK color for discarded pixels.

Returns

The color used to fill pixels that are discarded by the RED::RenderLayer::LT_MASK render layer.

inline int GetUpdateState() const

Retrieves the transaction number for which layer association tables have been updated.

Returns

The number of the transaction for which the tables have been setup.

inline void SetUpdateState(int iStateNumber)

Defines the transaction number for which layers association tables have been updated.

Parameters

iStateNumber – Rendered transaction number.

Public Static Functions

static inline RED::CID GetClassID()