class RED::IImageCube

This interface gives access to cube images properties. More...

#include <REDIImageCube.h>

Inherits: IREDObject.

Public functions:

virtual RED_RC	AutoCubeUpdate ( RED::Vector3 * iCenter, RED::FORMAT iFormat, int iSize, RED::Object * iViewpoint, float iDNear, float iDFar, const RED::LayerSet & iLayerSet, bool iUpdateFace0, bool iUpdateFace1, bool iUpdateFace2, bool iUpdateFace3, bool iUpdateFace4, bool iUpdateFace5, const RED::State & iState ) = 0
virtual RED_RC	ClearLocalFacePixels ( int iFace ) = 0
virtual RED_RC	ClearLocalPixels ( ) = 0
virtual RED_RC	CreateEnvironmentMap ( RED::FORMAT iDestFormat, const RED::ENV_TYPE & iEnvType, int iSize, unsigned char * iPixel, int iWidth, int iHeight, RED::FORMAT iFormat, RED::WRAP_MODE iWrapU, RED::WRAP_MODE iWrapV, const RED::Color & iBorder, const RED::Matrix & iAxisTransform, const RED::Matrix & iUVTransform, const RED::State & iState ) = 0
virtual RED_RC	GetAutoCubeCenter ( bool & oAutoCenter, RED::Vector3 & oCenter, int iStateNumber = -1 ) const = 0
virtual RED_RC	GetAutoCubeFormat ( RED::FORMAT & oFormat, int iStateNumber = -1 ) const = 0
virtual RED_RC	GetAutoCubeLayerSet ( RED::LayerSet & oLayerSet, int iStateNumber = -1 ) const = 0
virtual RED_RC	GetAutoCubeNearFar ( float & oDNear, float & oDFar, int iStateNumber = -1 ) const = 0
virtual RED_RC	GetAutoCubeSize ( int & oSize, int iStateNumber = -1 ) const = 0
virtual RED_RC	GetAutoCubeViewpoint ( RED::Object ** oViewpoint, int iStateNumber = -1 ) const = 0
virtual RED_RC	GetFacePixels ( int iFaceNumber, int iStateNumber = -1 ) const = 0
virtual const unsigned char *	GetLocalFacePixels ( int iFaceNumber ) const = 0
virtual unsigned char *	GetLocalFacePixels ( int iFaceNumber ) = 0
virtual FORMAT	GetLocalFormat ( ) const = 0
virtual int	GetLocalSize ( ) const = 0
virtual RED_RC	IsAutoCubeUpdate ( bool & oUpdate, int iStateNumber = -1 ) const = 0
virtual RED_RC	SetCompressedFacePixels ( int iFaceNumber, const RED::State & iState ) = 0
virtual RED_RC	SetCompressedFacePixels ( int iFaceNumber, unsigned char * iPixel, int iSize, RED::FORMAT iFormat, const RED::State & iState ) = 0
virtual RED_RC	SetFacePixels ( int iFaceNumber, unsigned char * iPixel, int iSize, RED::FORMAT iFormat, const RED::State & iState ) = 0
virtual RED_RC	SetFacePixels ( int iFaceNumber, const RED::State & iState ) = 0
virtual RED_RC	SetLocalFacePixels ( int iFaceNumber, unsigned char * iPixel, RED::FORMAT iFormat, int iSize ) = 0

Detailed description:

This interface gives access to cube images properties.

The RED::IImageCube is used to access to GPU cube images properties. Cube images are built with 6 faces, described in this order:

X positive texture: Face 0,
X negative texture: Face 1,
Y positive texture: Face 2,
Y negative texture: Face 3,
Z positive texture: Face 4,
Z negative texture: Face 5.

The faces camera axis are described below:

Face	Sight	Top	Right
0	+X	-Y	-Z
1	-X	-Y	+Z
2	+Y	+Z	+X
3	-Y	-Z	+X
4	+Z	-Y	+X
5	-Z	-Y	-X

The six faces of the cube and their camera axis.

Cube images have a specific target RED::TGT_TEX_CUBE, and must be built with POTD dimensions. The target of a cube image is automatically set on the first upload of its pixels contents.

Cube textures can use floating point formats. In this case, any GPU representation will be silently turned into an equivalent non floating point format, as GPUs do not accept floating point cube textures. The CPU representation of the texture will remain defined using the specified floating point source data.

Image defaults for CUBE images:

No texture target (set during the first image content definition).
Mipmaps disabled (enabling mipmaps is not possible).
Texture clamp to edge along (s,t).
Minification and magnification filters set to linear.
Anisotropy set to 0.

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

Functions documentation

public static RED::CID RED::IImageCube::GetClassID

(

)

public virtual RED_RC RED::IImageCube::AutoCubeUpdate	(	RED::Vector3 *	iCenter,
		RED::FORMAT	iFormat,
		int	iSize,
		RED::Object *	iViewpoint,
		float	iDNear,
		float	iDFar,
		const RED::LayerSet &	iLayerSet,
		bool	iUpdateFace0,
		bool	iUpdateFace1,
		bool	iUpdateFace2,
		bool	iUpdateFace3,
		bool	iUpdateFace4,
		bool	iUpdateFace5,
		const RED::State &	iState
	)	= 0

Automatic cube map calculation.

This method updates the cube map at the startup of the first frame after iState has been closed. The engine defines a camera at a given position and sets 6 rendering passes automatically around this position. Each rendering pass result is then used as new content for a cube face. The scene graph rendered for each pass is sourced from iViewpoint.

The position is either defined by iCenter when the value of the method parameter is not NULL or is automatically calculated based on the center position of all objects that are using the cubemap in their rendering. Note that if the engine has to define the central position around which all faces of the cube map are defined, then it'll leverage objects bounding spheres whenever possible.

This method sets the target of the cube image to RED::TGT_TEX_CUBE.

An instance of cube update is available here: Environmental mapping

Parameters:

iCenter:	Must be set to NULL for an automatic definition of the cube map central point, or must be set to a valid RED::Vector3 to override the central point's location.
iFormat:	Requested image format. Must be one of RED::FMT_RGB, RED::FMT_RGBA, RED::FMT_FLOAT_RGB, RED::FMT_FLOAT_RGBA, RED::FMT_HALF_FLOAT_RGB or RED::FMT_HALF_FLOAT_RGBA. Floating point formats require a native hardware floating point support.
iSize:	Pixel size of the cube face. Must be POTD.
iViewpoint:	Camera source of the cube image data.
iDNear:	Near clip distance for the rendering of all faces. iDNear must be greater than zero and less than iDFar.
iDFar:	Far clip distance for the rendering of all faces. iDFar must be greater than iDNear.
iLayerSet:	RED::LayerSet to use for the calculation of all faces.
iUpdateFace0:	true or false to update this face (+X) or not.
iUpdateFace1:	true or false to update this face (-X) or not.
iUpdateFace2:	true or false to update this face (+Y) or not.
iUpdateFace3:	true or false to update this face (-Y) or not.
iUpdateFace4:	true or false to update this face (+Z) or not.
iUpdateFace5:	true or false to update this face (-Z) or not.
iState:	Current transaction.

Returns:

RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
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 if a graphic driver error has occurred.

public virtual RED_RC RED::IImageCube::ClearLocalFacePixels

(

int

iFace

) = 0

Removes the contents of a cube image face in the local pixel storage.

This method clears a part of the cube map in the local storage. Memory is released.

Parameters:

iFace:

index of the face to be cleared.

Returns:

RED_OK on success,
RED_BAD_PARAM on invalid face index,
RED_FAIL otherwise.

public virtual RED_RC RED::IImageCube::ClearLocalPixels

(

) = 0

Removes the contents of the local pixel storage.

This method clears the local storage. Memory is released.

Returns:

RED_OK on success,
RED_FAIL otherwise.

public virtual RED_RC RED::IImageCube::CreateEnvironmentMap	(	RED::FORMAT	iDestFormat,
		const RED::ENV_TYPE &	iEnvType,
		int	iSize,
		unsigned char *	iPixel,
		int	iWidth,
		int	iHeight,
		RED::FORMAT	iFormat,
		RED::WRAP_MODE	iWrapU,
		RED::WRAP_MODE	iWrapV,
		const RED::Color &	iBorder,
		const RED::Matrix &	iAxisTransform,
		const RED::Matrix &	iUVTransform,
		const RED::State &	iState
	)	= 0

Creates a cube map containing a texture mapping of the provided input image.

This method computes the projection of the given texture pixel field onto a cube and stores it. The result can be used in an environmental shader. See the RED::ENV_TYPE enumeration for all details on the different possible mappings.

This operation sets the target of the cube image to RED::TGT_TEX_CUBE.

Latitude belongs to [0;pi]. Origin is at the bottom of the image.
Longitude belongs to [0;2pi]. Origin is at the left of the image and correspond to the X positive direction. Rotation is positive, this leads to a 2D map visually inverted compared to its background mapping in the 3D world.

The latitude/longitude image and its mapping information

A tutorial about environment map is available here: Environmental mapping

Parameters:

iDestFormat:	Format of the created cube map.
iEnvType:	Type of the environment to project.
iSize:	Size in pixels of the cube map faces (must be power of two).
iPixel:	Pixel byte field.
iWidth:	Pixel width of the source byte field.
iHeight:	Pixel height of the source byte field.
iFormat:	Pixel format of iPixel. Note that we only accept RGB and RGBA formats.
iWrapU:	Pixel U wrap mode of the source image.
iWrapV:	Pixel V wrap mode of the source image.
iBorder:	Border color of the source image.
iAxisTransform:	Additional transformation applied to the cube orientation.
iUVTransform:	Additional transformation applied to UVs used for texture sampling.
iState:	Current transaction parameter.

Returns:

RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_BAD_PARAM if iFormat is not a RGB or RGBA format,
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 if a graphic driver error has occurred.

public virtual RED_RC RED::IImageCube::GetAutoCubeCenter	(	bool &	oAutoCenter,
		RED::Vector3 &	oCenter,
		int	iStateNumber = -1
	)	const = 0

Gets the cube center in auto-update mode.

This method returns the cube center value that was set for the RED::IImageCube::AutoCubeUpdate method. There are two possible modes: auto centered cube or manually set centered cube.

Parameters:

oAutoCenter:	true if the cube is automatically centered by the engine before being updated, false if the center position has been defined by the RED::IImageCube::AutoCubeUpdate call.
oCenter:	Center position when manually defined. The value here is not defined if the cube is automatically updated.
iStateNumber:	Queried transaction number.

Returns:

RED_OK if the query has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.

public virtual RED_RC RED::IImageCube::GetAutoCubeFormat	(	RED::FORMAT &	oFormat,
		int	iStateNumber = -1
	)	const = 0

Gets the cube format in auto-update mode.

Parameters:

oFormat:	The wished format of the cube after update.
iStateNumber:	Queried transaction number.

Returns:

RED_OK if the query has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.

public virtual RED_RC RED::IImageCube::GetAutoCubeLayerSet	(	RED::LayerSet &	oLayerSet,
		int	iStateNumber = -1
	)	const = 0

Returns the RED::LayerSet used for the automatic update of all cube faces.

Parameters:

oLayerSet:	The RED::LayerSet used for the rendering of the face.
iStateNumber:	Queried transaction number.

Returns:

RED_OK if the query has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.

public virtual RED_RC RED::IImageCube::GetAutoCubeNearFar	(	float &	oDNear,
		float &	oDFar,
		int	iStateNumber = -1
	)	const = 0

Gets the cube near/far clip distances for the rendering.

Parameters:

oDNear:	Near clip distance.
oDFar:	Far clip distance.
iStateNumber:	Queried transaction number.

Returns:

RED_OK if the query has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.

public virtual RED_RC RED::IImageCube::GetAutoCubeSize	(	int &	oSize,
		int	iStateNumber = -1
	)	const = 0

Gets the requested cube face size in auto-update mode.

Parameters:

oSize:	Pixel size of a cube face.
iStateNumber:	Queried transaction number.

Returns:

RED_OK if the query has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.

public virtual RED_RC RED::IImageCube::GetAutoCubeViewpoint	(	RED::Object **	oViewpoint,
		int	iStateNumber = -1
	)	const = 0

Gets the auto update source scene.

Parameters:

oViewpoint:	The source viewpoint.
iStateNumber:	Queried transaction number.

Returns:

RED_OK if the query has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.

public virtual RED_RC RED::IImageCube::GetFacePixels	(	int	iFaceNumber,
		int	iStateNumber = -1
	)	const = 0

Retrieves a face of 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 for the specified face. 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_DXT1	8 bytes per 4x4 image pixel block
RED::FMT_RGBA_DXT1	8 bytes per 4x4 image pixel block
RED::FMT_RGBA_DXT3	16 bytes per 4x4 image pixel block
RED::FMT_RGBA_DXT5	16 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.

Parameters:

iFaceNumber:	Number of the read face.
iStateNumber:	Queried state number.

Returns:

RED_OK when the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_WORKFLOW_ERROR if a transaction error has been found,
RED_ALLOC_FAILURE if an internal memory allocation has failed,
RED_FAIL if a graphic driver error has occurred.

public virtual const unsigned char * RED::IImageCube::GetLocalFacePixels

(

int

iFaceNumber

) const = 0

Retrieves the current pixel storage contents for a cube face.

This storage can be used for any purpose. It remains valid until another pixel readback operation overwrites it.

Parameters:

iFaceNumber:

Queried face number.

Returns:

The address of the image's internal pixel storage for the specified cube face. NULL if the specified face number is wrong.

public virtual unsigned char * RED::IImageCube::GetLocalFacePixels

(

int

iFaceNumber

) = 0

Retrieves the current pixel storage contents for a cube face.

This storage can be used for any purpose. It remains valid until another pixel readback operation overwrites it.

The local pixel array can be modified.

Parameters:

iFaceNumber:

Queried face number.

Returns:

The address of the image's internal pixel storage for the specified cube face. NULL if the specified face number is wrong.

public virtual FORMAT RED::IImageCube::GetLocalFormat

(

) const = 0

Gets the actual format of our local storage.

Returns:

The current format of our local storage.

public virtual int RED::IImageCube::GetLocalSize

(

) const = 0

Gets the actual dimensions of our local cube face storage.

Returns:

The size of a cube face in our local storage.

public virtual RED_RC RED::IImageCube::IsAutoCubeUpdate	(	bool &	oUpdate,
		int	iStateNumber = -1
	)	const = 0

Do we have an automatic update request pending?

Parameters:

oUpdate:	true if a call to RED::IImageCube::AutoCubeUpdate has occurred that has not been handled yet.
iStateNumber:	Queried transaction number.

Returns:

RED_OK if the query has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.

public virtual RED_RC RED::IImageCube::SetCompressedFacePixels	(	int	iFaceNumber,
		const RED::State &	iState
	)	= 0

Uploads compressed pixels for a given cube face.

Works as RED::IImageCube::SetCompressedFacePixels, except that the face pixels are sourced from the object's local pixel storage.

This operation sets the target of the cube image to RED::TGT_TEX_CUBE.

Parameters:

iFaceNumber:	The number of the face being written to.
iState:	Current transaction parameter.

Returns:

RED_OK when the modification has succeeded,
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 if a graphic driver error has occurred or if there was no valid pixel field in the local storage of the object.

public virtual RED_RC RED::IImageCube::SetCompressedFacePixels	(	int	iFaceNumber,
		unsigned char *	iPixel,
		int	iSize,
		RED::FORMAT	iFormat,
		const RED::State &	iState
	)	= 0

Uploads compressed pixels for a given cube face.

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

This operation sets the target of the cube image to RED::TGT_TEX_CUBE.

Parameters:

iFaceNumber:	The number of the face being written to.
iPixel:	Pixel array of the face pixels.
iSize:	Pixel size of the cube's face. (Ex: for a 512x512 face size, the value should be set to 512). Must be POTD, greater than or equal to 4.
iFormat:	Compressed pixel format of the cube's face.
iState:	Current transaction parameter.

Returns:

public virtual RED_RC RED::IImageCube::SetFacePixels	(	int	iFaceNumber,
		unsigned char *	iPixel,
		int	iSize,
		RED::FORMAT	iFormat,
		const RED::State &	iState
	)	= 0

Uploads the image of a given cube face.

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.

This operation sets the target of the cube image to RED::TGT_TEX_CUBE.

Task: Creating a cube image

RED::Object* image_cube;

// Create the image.
RC_TEST( iresmgr->CreateImageCube( image_cube, iresmgr->GetState() ) );

RED::IImageCube* icube = image_cube->As< RED::IImageCube >();

for( int face = 0; face < 6; ++face )
{
  // Set the content of each cube face.
  RC_TEST( icube->SetFacePixels( face, face_pixels[face], 512, RED::FMT_RGB, iresmgr->GetState() ) );
}

Here, we assume that we have a valid pixel array in 'face_pixels[face]', for each of the 6 faces of the cube to process.

Parameters:

iFaceNumber:	The number of the face being written to.
iPixel:	Pixel array of the face pixels.
iSize:	Pixel size of the cube's face side. Must be POTD.
iFormat:	Pixel format of the cube's face. Note that floating point pixel formats are not accepted by cube images on the GPU and are turned into non floating point formats during the image upload operation on the GPU.
iState:	Current transaction parameter.

Returns:

RED_OK when the modification has succeeded,
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 did fail,
RED_FAIL if a graphic driver error has occurred.

public virtual RED_RC RED::IImageCube::SetFacePixels	(	int	iFaceNumber,
		const RED::State &	iState
	)	= 0

Uploads the image of a given cube face.

Works as RED::IImageCube::SetFacePixels, except that the face pixels are sourced from the object's local pixel storage. The source pixel array must be uncompressed.

This operation sets the target of the cube image to RED::TGT_TEX_CUBE.

Parameters:

iFaceNumber:	The number of the face being written to.
iState:	Current transaction parameter.

Returns:

public virtual RED_RC RED::IImageCube::SetLocalFacePixels	(	int	iFaceNumber,
		unsigned char *	iPixel,
		RED::FORMAT	iFormat,
		int	iSize
	)	= 0

Sets the contents of the local pixel storage for a face of the cube.

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 RED::IImageCube::SetFacePixels, when no pixel array is provided.

Any former object contents that is not compatible with the specified one through this call is lost (different format or size).

Parameters:

iFaceNumber:	Face being modified.
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. Can't be a floating point format.
iSize:	Cube face size. Must be POTD.

Returns:

RED_OK when the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_ALLOC_FAILURE if an internal memory allocation has failed.

class RED::IImageCube

Public functions:

Public static functions:

Detailed description:

Functions documentation

Task: Creating a cube image