IImageCube

Functions

	SET_CID
RED_RC	SetFacePixels
RED_RC	SetFacePixels
RED_RC	SetCompressedFacePixels
RED_RC	SetCompressedFacePixels
RED_RC	ClearLocalFacePixels
RED_RC	ClearLocalPixels
RED_RC	CreateEnvironmentMap
RED_RC	GetFacePixels
RED_RC	AutoCubeUpdate
RED_RC	IsAutoCubeUpdate
RED_RC	GetAutoCubeLayerSet
RED_RC	GetAutoCubeSize
RED_RC	GetAutoCubeViewpoint
RED_RC	GetAutoCubeFormat
RED_RC	GetAutoCubeCenter
RED_RC	GetAutoCubeNearFar
unsigned char *	GetLocalFacePixels
const unsigned char *	GetLocalFacePixels
int	GetLocalSize
FORMAT	GetLocalFormat
RED_RC	SetLocalFacePixels

Detailed Description

class IImageCube : public RED::IREDObject

This interface gives access to cube images properties.

@related Cube Images, class RED::IImage, Creating Panorama, Environmental Mapping

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

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: \ref bk_images (see \ref bk_im_cube_images for specific documentation about cube images).

Public Functions

SET_CID(CID_class_REDIImageCube)

virtual RED_RC 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 tk_creating_a_cube_image

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.

virtual RED_RC 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

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.

virtual RED_RC 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

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.

virtual RED_RC 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.

virtual RED_RC 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.

virtual RED_RC 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.

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

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.

A tutorial about environment map is available here: \ref wf_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.

virtual RED_RC 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.

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

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: \ref wf_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.

virtual RED_RC 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.

virtual RED_RC 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.

virtual RED_RC 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.

virtual RED_RC 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.

virtual RED_RC 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.

virtual RED_RC 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.

virtual RED_RC 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.

virtual unsigned char *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.

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

virtual int GetLocalSize() const = 0

Gets the actual dimensions of our local cube face storage.

Returns

The size of a cube face in our local storage.

virtual FORMAT GetLocalFormat() const = 0

Gets the actual format of our local storage.

Returns

The current format of our local storage.

virtual RED_RC 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.