class RED::IImage2D

This interface gives access to the 1D or 2D image's properties. More...

#include <REDIImage2D.h>

Inherits: IREDObject.

Public functions:

virtual voidClearLocalPixels ( ) = 0
virtual RED_RCGetAverageLuminance ( float & oAverageLuminance, unsigned int & oSamplesCount, int iStateNumber = -1 ) const = 0
virtual RED::FORMATGetLocalFormat ( ) const = 0
virtual intGetLocalHeight ( ) const = 0
virtual const unsigned char *GetLocalPixels ( ) const = 0
virtual unsigned char *GetLocalPixels ( ) = 0
virtual voidGetLocalSize ( int & oWidth, int & oHeight ) const = 0
virtual intGetLocalWidth ( ) const = 0
virtual RED_RCGetLogAverageLuminance ( float & oLogAverageLuminance, unsigned int & oSamplesCount, int iStateNumber = -1 ) const = 0
virtual RED_RCGetMaxLuminance ( float & oMaxLuminance, int iStateNumber = -1 ) const = 0
virtual RED_RCGetMinLuminance ( float & oMinLuminance, int iStateNumber = -1 ) const = 0
virtual RED_RCGetPixels ( int iStateNumber = -1 ) const = 0
virtual RED_RCGetRenderImage ( RED::Object *& oVRL, int & oWidth, int & oHeight, int & oXAnchor, int & oYAnchor, TARGET & oTarget, int iStateNumber = -1 ) const = 0
virtual RED_RCIsRenderDepthImage ( bool & oDepth, int iStateNumber = -1 ) const = 0
virtual RED_RCIsRenderImage ( bool & oRender, int iStateNumber = -1 ) const = 0
virtual RED_RCNormalMap ( RED::FORMAT iFormat, RED::TARGET iTarget, float iScaling, const RED::Object * iSourceImage, const RED::State & iState ) = 0
virtual RED_RCSetAverageLuminance ( float iAverageLuminance, unsigned int iSamplesCount, const RED::State & iState ) = 0
virtual RED_RCSetCompressedPixels ( unsigned char * iPixel, RED::FORMAT iFormat, RED::TARGET iTarget, int iWidth, int iHeight, const RED::State & iState ) = 0
virtual RED_RCSetCompressedPixels ( RED::TARGET iTarget, const RED::State & iState ) = 0
virtual RED_RCSetFloatPixels ( CHANNEL iChannel, const RED::Object * iImage, const RED::State & iState ) = 0
virtual RED_RCSetFromPixelShader ( RED::FORMAT iFormat, const RED::ShaderProgramID & iPixelShaderId, RED::Object * iResMgr, const RED::Object * iSourceImage, const RED::Vector< RED::RenderShaderParameter > & iParams, const RED::State & iState ) = 0
virtual RED_RCSetLocalPixels ( const unsigned char * iPixel, RED::FORMAT iFormat, int iWidth, int iHeight ) = 0
virtual RED_RCSetLogAverageLuminance ( float iLogAverageLuminance, unsigned int iSamplesCount, const RED::State & iState ) = 0
virtual RED_RCSetMaxLuminance ( float iMaxLuminance, const RED::State & iState ) = 0
virtual RED_RCSetMinLuminance ( float iMinLuminance, const RED::State & iState ) = 0
virtual RED_RCSetNotRenderImage ( const RED::State & iState ) = 0
virtual RED_RCSetPixelChannel ( CHANNEL iDestChannel, const RED::Object * iSourceImage, CHANNEL iSourceChannel, const RED::State & iState ) = 0
virtual RED_RCSetPixels ( RED::TARGET iTarget, const RED::State & iState ) = 0
virtual RED_RCSetPixels ( const unsigned char * iPixel, RED::FORMAT iFormat, RED::TARGET iTarget, int iWidth, int iHeight, const RED::State & iState ) = 0
virtual RED_RCSetRenderDepthImage ( RED::Object * iVRL, int iWidth, int iHeight, int iXAnchor, int iYAnchor, const RED::State & iState ) = 0
virtual RED_RCSetRenderImage ( RED::Object * iVRL, int iWidth, int iHeight, int iXAnchor, int iYAnchor, RED::TARGET iTarget, const RED::State & iState ) = 0

Public static functions:

static RED::CIDGetClassID ( )

Detailed description:

This interface gives access to the 1D or 2D image's properties.

The IImage2D interface proposes services for the specific management of 1D or 2D bitmap images.

For an in-depth coverage of the images in REDsdk, please read: REDsdk textures and images (see 2D images for specific documentation about 2D images).

Functions documentation

public virtual void RED::IImage2D::ClearLocalPixels() = 0

Removes the contents of the local pixel storage.

This method clears the local storage. Memory is released.

public virtual RED_RC RED::IImage2D::GetAverageLuminance(float &oAverageLuminance,
unsigned int &oSamplesCount,
intiStateNumber = -1
)const = 0

Gets the image average luminance.

The average luminance of an image is a useful information for a majority of tone mapping operators. This call lets you retrieve this information from an image before tone mapping it.

Luminance is computed using the CIE standard luminance definition.

Note that this method is meaningful only for images in RED::FMT_FLOAT_RGB(A), RED::FMT_HALF_FLOAT_RGB(A) or RED::FMT_FLOAT_RGBA_AA format which have been rendered by viewpoints having tone mapping enabled.

The method also returns the number of samples taken to compute the average luminance. Most of the time the samples count is equal to the number of pixels in the image. But, depending on the rendering options (RED::OPTIONS_TONE_MAPPING_IGNORE_BACKGROUND for example), it can be different and is useful to consolidate luminance information in tiled rendering.

Parameters:

oAverageLuminance:the returned image average luminance.
oSamplesCount:the number of samples taken to compute the returned average luminance.
iStateNumber:queried state number.

Returns:

RED_OK when the modification succeeded,
RED_BAD_PARAM if the method received an invalid parameter,
RED_ALLOC_FAILURE if an internal memory allocation did fail.
public virtual RED::FORMAT RED::IImage2D::GetLocalFormat() const = 0

Gets the actual format of our local storage.

Returns:

The current format of our local storage.
public virtual int RED::IImage2D::GetLocalHeight() const = 0

Gets the height of the actual local storage.

Returns:

The pixel height of our local storage.
public virtual const unsigned char * RED::IImage2D::GetLocalPixels() const = 0

Retrieves the current pixel storage contents.

This storage can be used for any purpose. It remains valid until another RED::IImage2D::GetPixels operation overwrites it.

Returns:

The address of the image's internal pixel storage.
public virtual unsigned char * RED::IImage2D::GetLocalPixels() = 0

Retrieves the current pixel storage contents.

This storage can be used for any purpose. It remains valid until another RED::IImage2D::GetPixels operation overwrites it.

The local pixel array can be modified.

Returns:

The address of our internal pixel storage.
public virtual void RED::IImage2D::GetLocalSize(int &oWidth,
int &oHeight
)const = 0

Gets the actual dimensions of our local storage.

Parameters:

oWidth:Pixel width of our local storage.
oHeight:Pixel height of our local storage.
public virtual int RED::IImage2D::GetLocalWidth() const = 0

Gets the width of the actual local storage.

Returns:

The pixel width of our local storage.
public virtual RED_RC RED::IImage2D::GetLogAverageLuminance(float &oLogAverageLuminance,
unsigned int &oSamplesCount,
intiStateNumber = -1
)const = 0

Gets the image log average luminance.

The log average luminance of an image is a useful information for a majority of tone mapping operators. This call lets you retrieve this information from an image before tone mapping it.

Log average luminance is computed using:

Lavg = exp( 1/N * Sum_xy( ln( L(x, y) ) )

where N is the number of pixels in the image and (x, y) the coordinates of a given pixel.

Luminance is computed using the CIE standard luminance definition.

Note that this method is meaningful only for images in RED::FMT_FLOAT_RGB(A), RED::FMT_HALF_FLOAT_RGB(A) or RED::FMT_FLOAT_RGBA_AA format which have been rendered by viewpoints having tone mapping enabled.

Parameters:

oLogAverageLuminance:the returned image log average luminance.
oSamplesCount:the number of samples taken to compute the returned log average luminance.
iStateNumber:queried state number.

Returns:

RED_OK when the modification succeeded,
RED_BAD_PARAM if the method received an invalid parameter,
RED_ALLOC_FAILURE if an internal memory allocation did fail.
public virtual RED_RC RED::IImage2D::GetMaxLuminance(float &oMaxLuminance,
intiStateNumber = -1
)const = 0

Gets the maximum image luminance.

Luminance is computed using the CIE standard luminance definition.

Note that this method is meaningful only for images in RED::FMT_FLOAT_RGB(A), RED::FMT_HALF_FLOAT_RGB(A) or RED::FMT_FLOAT_RGBA_AA format which have been rendered by viewpoints having tone mapping enabled.

Parameters:

oMaxLuminance:the returned maximun image luminance.
iStateNumber:queried state number.

Returns:

RED_OK when the modification succeeded,
RED_BAD_PARAM if the method received an invalid parameter,
RED_ALLOC_FAILURE if an internal memory allocation did fail.
public virtual RED_RC RED::IImage2D::GetMinLuminance(float &oMinLuminance,
intiStateNumber = -1
)const = 0

Gets the minimum image luminance.

Luminance is computed using the CIE standard luminance definition.

Note that this method is meaningful only for images in RED::FMT_FLOAT_RGB(A), RED::FMT_HALF_FLOAT_RGB(A) or RED::FMT_FLOAT_RGBA_AA format which have been rendered by viewpoints having tone mapping enabled.

Parameters:

oMinLuminance:the returned minimun image luminance.
iStateNumber:queried state number.

Returns:

RED_OK when the modification succeeded,
RED_BAD_PARAM if the method received an invalid parameter,
RED_ALLOC_FAILURE if an internal memory allocation did fail.
public virtual RED_RC RED::IImage2D::GetPixels(intiStateNumber = -1) const = 0

Retrieves pixels from the GPU texture of the image.

This call performs a readback of the image pixels from the GPU to the CPU. This is a synchronous call that stalls the rendering pipeline.

The resulting pixel field is stored in the transient pixel storage of the image. It remains valid until another pixel read operation overwrites it.

Images are returned in their actual format on the GPU. This format may differ from the original format that was used to upload the texture pixel array initially on the GPU if image manipulation operations have occurred since then.

Compressed images pixels are returned in their compressed form. Read byte field has sizes defined according to the compressed format:

RED::FMT_RGB_DXT18 bytes per 4x4 image pixel block
RED::FMT_RGBA_DXT18 bytes per 4x4 image pixel block
RED::FMT_RGBA_DXT316 bytes per 4x4 image pixel block
RED::FMT_RGBA_DXT516 bytes per 4x4 image pixel block

Note that a compressed image is always considered to have dimensions equal to or greater than 4 for the purpose of it's pixel memory footprint.

See Managing image pixels for more details about this method.

Parameters:

iStateNumber:Queried state number.

Returns:

RED_OK when the modification succeeded,
RED_WORKFLOW_ERROR if a transaction error was found,
RED_ALLOC_FAILURE if an internal memory allocation did fail,
RED_FAIL if a graphic driver error occurred.
public virtual RED_RC RED::IImage2D::GetRenderImage(RED::Object *&oVRL,
int &oWidth,
int &oHeight,
int &oXAnchor,
int &oYAnchor,
TARGET &oTarget,
intiStateNumber = -1
)const = 0

Gets the render image parameters for this image.

This method returns the parameters that have been used to configure a render image in RED::IImage2D::SetRenderImage.

Parameters:

oVRL:REDViewpointRenderList data source of our texture image.
oWidth:Pixel width of the render image.
oHeight:Pixel height of the render image.
oXAnchor:Coordinate in the VRL of the bottom left image pixel.
oYAnchor:Coordinate in the VRL of the bottom left image pixel.
oTarget:Texture target of the render image.
iStateNumber:Queried state number.

Returns:

RED_OK when the call succeeded,
RED_BAD_PARAM if the method received an invalid parameter.
public virtual RED_RC RED::IImage2D::IsRenderDepthImage(bool &oDepth,
intiStateNumber = -1
)const = 0

Is the image a render depth image?

Parameters:

oDepth:Returned true if the image is bound to the depth buffer of a VRL.
iStateNumber:Queried state number.

Returns:

RED_OK when the call succeeded,
RED_BAD_PARAM if the method received an invalid parameter.
public virtual RED_RC RED::IImage2D::IsRenderImage(bool &oRender,
intiStateNumber = -1
)const = 0

Is the image a render image?

Parameters:

oRender:Returned true if the image is bound to a VRL.
iStateNumber:Queried state number.

Returns:

RED_OK when the call succeeded,
RED_BAD_PARAM if the method received an invalid parameter.
public virtual RED_RC RED::IImage2D::NormalMap(RED::FORMATiFormat,
RED::TARGETiTarget,
floatiScaling,
const RED::Object *iSourceImage,
const RED::State &iState
) = 0

Generates a normal map from an image.

Sets the image contents as a normal map. We compute the normal map from iSource, that must be a RGBA or a FLOAT image. If we receive a colored image, it'll be internally turned in grey levels before the normal map calculation. The alpha channel of the source is ignored.

We apply a bump scaling to control the overall bumpiness of the result. This is the iScaling parameter. It may be negative to reverse the bumps.

this is set to use iTarget if it has no valid target prior to the call. Note that if this has already a target, it must be equal to iTarget and it must be compatible with iFormat.

task

Task: Creating a bump map from any image

REDsdk implements bump mapping through the support of normal maps. To convert any bump map to a normal map, simply do:

RED::Object* image2d;
RC_TEST( iresmgr->CreateImage2D( image2d, iresmgr->GetState() ) );
RC_TEST( RED::ImageTools::Load( image2d, "./my_bump_map.hdr", RED::FMT_RGB, false, false, RED::TGT_TEX_2D, iresmgr->GetState() ) );

RED::IImage2D* i2d = image2d->As< RED::IImage2D >();
RC_TEST( i2d->NormalMap( RED::FMT_RGB, RED::TGT_TEX_2D, 3.f, image2d, iresmgr->GetState() ) );

Parameters:

iFormat:this format after the operation. Possible formats are RGB, RGBA, or compressed versions of those.
iTarget:this target after the operation.
iScaling:Scaling factor, that will modify the texture bumpiness. Negative values can be used to reverse the bumps.
iSourceImage:Source image. May be set to this.
iState:Current transaction parameter.

Returns:

RED_OK when the modification succeeded,
RED_WORKFLOW_ERROR if a transaction error was found,
RED_WORKFLOW_ERROR if a software tracer image is being processed,
RED_SCG_READ_ONLY_IMAGE if this can't be modified,
RED_ALLOC_FAILURE if an internal memory allocation did fail,
RED_FAIL if a graphic driver error occurred.
public virtual RED_RC RED::IImage2D::SetAverageLuminance(floatiAverageLuminance,
unsigned intiSamplesCount,
const RED::State &iState
) = 0

Sets the average luminance of the image.

See the RED::IImage2D::GetAverageLuminance method documentation for details.

Parameters:

iAverageLuminance:image average luminance.
iSamplesCount:number of samples taken to compute the average luminance.
iState:current transaction parameter.

Returns:

RED_OK on success,
RED_FAIL otherwise.
public virtual RED_RC RED::IImage2D::SetCompressedPixels(unsigned char *iPixel,
RED::FORMATiFormat,
RED::TARGETiTarget,
intiWidth,
intiHeight,
const RED::State &iState
) = 0

Uploads compressed image pixels on the GPU.

This method is similar to RED::IImage2D::SetPixels, except that its source pixels must be already in compressed form.

Note that the call will silently uncompress the input pixel array on INTEL chipsets as a texture corruption issue may show up when texture mipmaps are enabled. The texture format query will return the uncompressed version of the image format supplied in iFormat.

Parameters:

iPixel:Compressed pixel array.
iFormat:Image format. Must be one of the compressed formats.
iTarget:Image target.
iWidth:Image pixel width. Must be POTD.
iHeight:Image pixel height. Must be POTD.
iState:Current transaction parameter.

Returns:

RED_OK if the operation has succeeded,
RED_WORKFLOW_ERROR if a transaction error was found,
RED_WORKFLOW_ERROR if we have incompatible targets,
RED_WORKFLOW_ERROR if a software tracer image is being processed,
RED_SCG_READ_ONLY_IMAGE if this can't be modified,
RED_ALLOC_FAILURE if an internal memory allocation did fail,
RED_FAIL if a graphic driver error occurred.
public virtual RED_RC RED::IImage2D::SetCompressedPixels(RED::TARGETiTarget,
const RED::State &iState
) = 0

Uploads compressed image contents on the GPU.

This call is identical to RED::IImage::SetCompressedPixels, except that the source pixel array is taken from the image local storage.

Parameters:

iTarget:Image target.
iState:Current transaction parameter.

Returns:

RED_OK if the operation has succeeded,
RED_WORKFLOW_ERROR if a transaction error was found,
RED_WORKFLOW_ERROR if the image already has a target that differs from iTarget,
RED_WORKFLOW_ERROR if a software tracer image is being processed,
RED_SCG_READ_ONLY_IMAGE if this can't be modified,
RED_ALLOC_FAILURE if an internal memory allocation has failed,
RED_WORKFLOW_ERROR if the image has local pixels in non-compressed format: in this case, RED::IImage2D::SetPixels should be called,
RED_FAIL if a graphic driver error has occurred.
public virtual RED_RC RED::IImage2D::SetFloatPixels(CHANNELiChannel,
const RED::Object *iImage,
const RED::State &iState
) = 0

Sets the image as a float image.

This method extracts one channel of the specified source image. Extracted pixels are used to redefine the contents of our texture using a (F) pixel pattern. The result is a FLOAT image. If the image is not a floating point image before the call (such as a RGBA image for example), then the result is normalized in [0.0f,1.0f] for each pixel.

The call fails if we already have a valid rendering target that in not a RED::TGT_TEX_RECT.

Parameters:

iChannel:Source channel in iImage.
iImage:Source image.
iState:Current transaction parameter.

Returns:

RED_OK when the modification succeeded,
RED_WORKFLOW_ERROR if a transaction error was found,
RED_WORKFLOW_ERROR if we have incompatible targets,
RED_WORKFLOW_ERROR if a software tracer image is being processed,
RED_SCG_READ_ONLY_IMAGE if this can't be modified,
RED_ALLOC_FAILURE if an internal memory allocation did fail,
RED_FAIL if a graphic driver error occurred.
public virtual RED_RC RED::IImage2D::SetFromPixelShader(RED::FORMATiFormat,
const RED::ShaderProgramID &iPixelShaderId,
RED::Object *iResMgr,
const RED::Object *iSourceImage,
const RED::Vector< RED::RenderShaderParameter > &iParams,
const RED::State &iState
) = 0

Uses a pixel shader program to modify the image.

This method can be used for any image processing operations. It uses a pixel shader program that is applied to every texel of the target image and whose color is written to this contents.

The rendering is made using a quad that covers the whole texture. The pixel shader receives the (u,v) coordinates within the source texture through the 'fragment.texcoord[0]' interpolator. (u,v) coordinates are either bound to [0,1]x[0,1] or to [0,width]x[0,height] if the texture has a RED::TGT_TEX_RECT rendering target.

this is set to use the target of iSourceImage if it has no valid target prior to the call. Note that if this has already a target, this target must be compatible with iFormat.

The method uses the 'texture[0]' texture channel to bind iSource to the pixel shader. All other channels may be freely configured using iParams.

If iSource has no valid pixel contents, the operation does nothing. The operation sets the dimensions of this to those of iSource.

Parameters:

iFormat:Working buffer format for the operation. Defines the format of the pixels in the final texture.
iPixelShaderId:Pixel shader program id. A shader must have been loaded using the RED::IResourceManager API before we can get a valid ID for it.
iResMgr:The cluster's resource manager.
iSourceImage:Source image. May be set to this.
iParams:List of pixel shader parameters. Note that most references are ignored during the shader parameter binding, as they don't make any sense in the context of a 2D image rendering.
iState:Current transaction parameter.

Returns:

RED_OK when the modification has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter: no source image, invalid pixel shader id, wrong format, etc... RED_WORKFLOW_ERROR if a transaction error was found,
RED_WORKFLOW_ERROR if we have incompatible targets,
RED_WORKFLOW_ERROR if a software tracer image is being processed,
RED_SCG_READ_ONLY_IMAGE if this can't be modified,
RED_ALLOC_FAILURE if an internal memory allocation did fail,
RED_FAIL if a graphic driver error has occurred.
public virtual RED_RC RED::IImage2D::SetLocalPixels(const unsigned char *iPixel,
RED::FORMATiFormat,
intiWidth,
intiHeight
) = 0

Sets the contents of the local pixel storage.

This method can be used to specify the contents of the local pixel storage. The provided pixel array is internally duplicated.

The local pixel storage can be uploaded on the GPU through the regular REDImage2D::SetPixels, when no pixel array is provided.

Parameters:

iPixel:Pixel array. If set to NULL, the call internally allocates a pixel storage array matching the provided dimensions and format that is not initialized.
iFormat:Image format.
iWidth:Image pixel width.
iHeight:Image pixel height.

Returns:

RED_OK when the modification succeeded,
RED_BAD_PARAM if the method received an invalid parameter,
RED_ALLOC_FAILURE if an internal memory allocation did fail.
public virtual RED_RC RED::IImage2D::SetLogAverageLuminance(floatiLogAverageLuminance,
unsigned intiSamplesCount,
const RED::State &iState
) = 0

Sets the log average luminance of the image.

See the RED::IImage2D::GetLogAverageLuminance method documentation for details.

Parameters:

iLogAverageLuminance:image log average luminance.
iSamplesCount:number of samples taken to compute the log average luminance.
iState:current transaction parameter.

Returns:

RED_OK on success,
RED_FAIL otherwise.
public virtual RED_RC RED::IImage2D::SetMaxLuminance(floatiMaxLuminance,
const RED::State &iState
) = 0

Sets the maximum luminance of the image.

See the RED::IImage2D::GetMaxLuminance method documentation for details.

Parameters:

iMaxLuminance:maximum image luminance.
iState:current transaction parameter.

Returns:

RED_OK on success,
RED_FAIL otherwise.
public virtual RED_RC RED::IImage2D::SetMinLuminance(floatiMinLuminance,
const RED::State &iState
) = 0

Sets the minimum luminance of the image.

See the RED::IImage2D::GetMinLuminance method documentation for details.

Parameters:

iMinLuminance:minimum image luminance.
iState:current transaction parameter.

Returns:

RED_OK on success,
RED_FAIL otherwise.
public virtual RED_RC RED::IImage2D::SetNotRenderImage(const RED::State &iState) = 0

Disarms a render image.

This call can be issued to prevent a render image to be calculated anymore. Another call to RED::IImage2D::SetRenderImage must occur to rearm the render image calculation.

Parameters:

iState:Current transaction parameter.

Returns:

RED_OK when the modification succeeded,
RED_BAD_PARAM if the method received an invalid parameter,
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.
public virtual RED_RC RED::IImage2D::SetPixelChannel(CHANNELiDestChannel,
const RED::Object *iSourceImage,
CHANNELiSourceChannel,
const RED::State &iState
) = 0

Overwrites a single channel of the image.

This method extracts one channel of iImage that is copied in the chosen channel of this. The copy occurs at the dimensions of this so that iSourceImage contents may be stretched during the operation if it has different dimensions.

this is set to use the target of iSourceImage if it has no valid target prior to the call.

Parameters:

iDestChannel:Target channel in this.
iSourceImage:Source image.
iSourceChannel:Source channel in iImage.
iState:Current transaction parameter.

Returns:

RED_OK when the modification succeeded,
RED_WORKFLOW_ERROR if a transaction error was found,
RED_WORKFLOW_ERROR if we have incompatible targets,
RED_WORKFLOW_ERROR if a software tracer image is being processed,
RED_SCG_READ_ONLY_IMAGE if this can't be modified,
RED_ALLOC_FAILURE if an internal memory allocation did fail,
RED_FAIL if a graphic driver error occurred.
public virtual RED_RC RED::IImage2D::SetPixels(RED::TARGETiTarget,
const RED::State &iState
) = 0

Uploads the image contents on the GPU.

This call is identical to RED::IImage2D::SetPixels, except that the source pixel array is taken from the image local storage.

Parameters:

iTarget:Image target.
iState:Current transaction parameter.

Returns:

RED_OK if the operation has succeeded,
RED_WORKFLOW_ERROR if a transaction error was found,
RED_WORKFLOW_ERROR if the image already has a target that differs from iTarget,
RED_WORKFLOW_ERROR if a software tracer image is being processed,
RED_SCG_READ_ONLY_IMAGE if this can't be modified,
RED_ALLOC_FAILURE if an internal memory allocation has failed,
RED_FAIL if the image does not have any valid local pixel data to upload,
RED_WORKFLOW_ERROR if the image has local pixels in compressed format: in this case, RED::IImage2D::SetCompressedPixels should be called,
RED_DRV_FAIL if a graphic driver error has occurred.
public virtual RED_RC RED::IImage2D::SetPixels(const unsigned char *iPixel,
RED::FORMATiFormat,
RED::TARGETiTarget,
intiWidth,
intiHeight,
const RED::State &iState
) = 0

Uploads image pixels on the GPU.

The target of a texture is defined once for all. If the dimensions are not matching the target, the image is being resized to fit the wished target.

The call fails if we already have a valid rendering target that differs from the target in iTarget.

The pixel array defined in iPixel must be in uncompressed format. The operation may compress the image, based on the value of iFormat, but the source data must be uncompressed.

Low end INTEL graphic chipsets do not support floating point textures that are automatically converted into equivalent 8 bits formats with clamped values:

See Managing image pixels for more details about this method.

Parameters:

iPixel:Uncompressed pixel array.
iFormat:Image format.
iTarget:Image target.
iWidth:Image pixel width.
iHeight:Image pixel height.
iState:Current transaction parameter.

Returns:

RED_OK if the modification has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_BAD_PARAM if the texture has a floating point format and if it does not have a RED::TGT_TEX_RECT target,
RED_WORKFLOW_ERROR if a transaction error was found,
RED_WORKFLOW_ERROR if we have incompatible targets,
RED_WORKFLOW_ERROR if a software tracer image is being processed,
RED_SCG_READ_ONLY_IMAGE if this can't be modified,
RED_ALLOC_FAILURE if an internal memory allocation did fail,
RED_FAIL if a graphic driver error occurred.
public virtual RED_RC RED::IImage2D::SetRenderDepthImage(RED::Object *iVRL,
intiWidth,
intiHeight,
intiXAnchor,
intiYAnchor,
const RED::State &iState
) = 0

Sets the image as a render depth buffer image.

Define the image as a render image as in RED::IImage2D::SetRenderImage. The image is generated from the depth buffer of the specified VRL.

Note that a depth render image must be a RED::TGT_TEX_RECT target image.

Parameters:

iVRL:Source of the render image contents.
iWidth:Pixel width of the render image.
iHeight:Pixel height of the render image.
iXAnchor:Coordinate of the lower left render image pixel in the VRL offscreen buffer.
iYAnchor:Coordinate of the lower left render image pixel in the VRL offscreen buffer.
iState:Current transaction parameter.

Returns:

RED_OK when the modification succeeded,
RED_BAD_PARAM if the method received an invalid parameter,
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.
public virtual RED_RC RED::IImage2D::SetRenderImage(RED::Object *iVRL,
intiWidth,
intiHeight,
intiXAnchor,
intiYAnchor,
RED::TARGETiTarget,
const RED::State &iState
) = 0

Sets this image as a render image target.

Defines this image as a "render image". A render image is the result of an offscreen rendering performed by a viewpoint render list (VRL).

A REDWindow contains one or many VRLs. Each VRL target a specific offscreen buffer. The default VRL of a window always target the framebuffer, whereas auxiliary VRLs target offscreen rendering buffers.

To perform a "render to texture" operation, an auxiliary VRL must be created in a window. This VRL must be loaded with the viewpoints and scene data to be rendered. Then, this method must be called, and the VRL source of the image contents has to be defined as the value of iVRL.

The VRL dimensions and image dimensions don't necessarily need to match. We specify through this call the VRL's rendering buffer area that'll be used as source of the texture's contents.

The render image sources its contents from a rectangle defined at [iXAnchor,iYAnchor] lower left corner in the VRL, whose dimensions are [iWidth,iHeight] therefore defining an image whose dimensions are [iWidth,iHeight].

When a window is being resized, the following happens:

  • The default VRL of the window is resized.
  • Auxiliary VRLs of the window are NOT resized.
  • Render images are NOT resized.

Therefore, render images must be manually resized. There's no valid automatic behaviors, as user needs may imply an image size update or not.

A render image is not updated when it's source VRL is not activated. The RED::IViewpointRenderList::Activate method controls the activation of a VRL and consequently the update of all related render images.

A render image has the same pixel format as the VRL it's linked with.

Only RED::TGT_TEX_2D target render images may be used as data sources for the ray-tracer (for example as transparency source specified in a state shader).

task

Task: Setting a render image

RED::Object* render_image;

// Create the render image.
RC_TEST( iresmgr->CreateImage2D( render_image, iresmgr->GetState() ) );

// Set the render image to the vrl.
RED::IImage2D* irender_image;
irender_image = render_image->As< RED::IImage2D >();
RC_TEST( irender_image->SetRenderImage( vrl, width, height, 0, 0, RED::TGT_TEX_RECT, iresmgr->GetState() ) );

Parameters:

iVRL:Source of the render image contents.
iWidth:Pixel width of the render image.
iHeight:Pixel height of the render image.
iXAnchor:Coordinate of the lower left render image pixel in the VRL offscreen buffer.
iYAnchor:Coordinate of the lower left render image pixel in the VRL offscreen buffer.
iTarget:Binding texture target of the render image.
iState:Current transaction parameter.

Returns:

RED_OK when the modification succeeded,
RED_BAD_PARAM if the method received an invalid parameter,
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.