IImage3D

Functions

CID	GetClassID
RED_RC	SetPixels
RED_RC	SetPixels
RED_RC	GetPixels
RED_RC	GetWrapModes
RED_RC	SetWrapModes
unsigned char *	GetLocalPixels
const unsigned char *	GetLocalPixels
void	GetLocalSize
int	GetLocalWidth
int	GetLocalHeight
int	GetLocalDepth
FORMAT	GetLocalFormat
RED_RC	SetLocalPixels
void	ClearLocalPixels
RED_RC	GetImage3DByteSize

Detailed Description

class IImage3D : public RED::IREDObject

This interface gives access to the 3D image’s properties.

@related 3D Images , class RED::IImage, Volume View

The IImage3D interface is used for the definition of 3D images. A 3D image is a simple block of pixels arranged in video memory to represent a volume in space.

3D images do not support mipmaps. Any mipmapping call will be ignored. A 3D image has its filters forced to RED::FM_NEAREST the first time its pixels are being set.

Both POTD and NPOTD 3D images are sampled using normalized texture coordinates in [0,1] x [0,1] x [0,1].

There are several software fallback paths with 3D images. Please refer to the product documentation for a list of all known pitfalls.

For an in-depth coverage of the images in REDsdk, please read: \ref bk_images (see \ref bk_im_3D_images for specific documentation about 3D images).

Public Functions

virtual RED_RC SetPixels(unsigned char *iPixel, RED::FORMAT iFormat, RED::TARGET iTarget, int iWidth, int iHeight, int iDepth, 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.

Image filters are set to NEAREST on the first pixel contents upload.

See \ref bk_im_managing_image_pixels for more details about this method.

Parameters

• iPixel – Uncompressed pixel array.

• iFormat – Image format. Compressed image formats are not supported by 3D images.

• iTarget – Image target. Must be RED::TGT_TEX_3D.

• iWidth – Image pixel width.

• iHeight – Image pixel height.

• iDepth – Image pixel depth.

• iState – Current transaction parameter.

Returns

RED_OK if the operation has succeeded,

RED_BAD_PARAM if the method has received an invalid parameter,

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_ALLOC_FAILURE if an internal memory allocation has failed,

RED_FAIL if a graphic driver error has occurred.

virtual RED_RC SetPixels(RED::TARGET iTarget, const RED::State &iState) = 0

Uploads the image contents on the GPU.

This call is identical to RED::IImage3D::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 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_ALLOC_FAILURE if an internal memory allocation has failed,

RED_FAIL if a graphic driver error has occurred.

virtual RED_RC GetPixels(int iStateNumber = -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 that time.

See \ref bk_im_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.

virtual RED_RC GetWrapModes(RED::WRAP_MODE &oWrapS, RED::WRAP_MODE &oWrapT, RED::WRAP_MODE &oWrapR, int iStateNumber = -1) const = 0

Returns the texture wrapping modes.

Parameters

• oWrapS – S texture axis wrap mode.

• oWrapT – T texture axis wrap mode.

• oWrapR – R texture axis wrap mode.

• iStateNumber – Queried state number.

Returns

RED_OK when the call succeeded,

RED_BAD_PARAM if the method received an invalid parameter,

RED_WORKFLOW_ERROR if the texture has no GPU target yet,

RED_FAIL when a graphic driver error occurred.

virtual RED_RC SetWrapModes(RED::WRAP_MODE iWrapS, RED::WRAP_MODE iWrapT, RED::WRAP_MODE iWrapR, const RED::State &iState) = 0

Defines the texture wrapping modes.

Parameters

• iWrapS – S texture axis wrap mode.

• iWrapT – T texture axis wrap mode.

• iWrapR – R texture axis wrap mode.

• iState – Current transaction parameter.

Returns

RED_OK when the modification succeeded,

RED_WORKFLOW_ERROR if a transaction error was found,

RED_WORKFLOW_ERROR if the texture has no GPU target yet,

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 unsigned char *GetLocalPixels() = 0

Retrieves the current pixel storage contents.

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.

Returns

The address of our internal pixel storage.

virtual const unsigned char *GetLocalPixels() const = 0

Retrieves the current pixel storage contents.

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

Returns

The address of the image’s internal pixel storage.

virtual void GetLocalSize(int &oWidth, int &oHeight, int &oDepth) 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.

• oDepth – Pixel depth of our local storage.

virtual int GetLocalWidth() const = 0

Gets the width of the actual local storage.

Returns

The pixel width of our local storage.

virtual int GetLocalHeight() const = 0

Gets the height of the actual local storage.

Returns

The pixel height of our local storage.

virtual int GetLocalDepth() const = 0

Gets the depth of our actual local storage.

Returns

The pixel depth of our local storage.

virtual RED::FORMAT GetLocalFormat() const = 0

Gets the actual format of our local storage.

Returns

The current format of our local storage.

virtual RED_RC SetLocalPixels(unsigned char *iPixel, RED::FORMAT iFormat, int iWidth, int iHeight, int iDepth) = 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 REDImage3D::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.

• iDepth – Image pixel depth.

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.

virtual void ClearLocalPixels() = 0

Removes the contents of the local pixel storage.

This method clears the local storage. Memory is released.

virtual RED_RC GetImage3DByteSize(RED::uint64 &oSize, int iWidth, int iHeight, int iDepth, RED::FORMAT iFormat) const = 0

Gets the byte size needed to encode pixels of a 3D image.

The method is similar to RED::IImage::GetImageByteSize, and works for 3D images. Note that image compression is not supported by 3D images.

Parameters

• oSize – Byte size needed for the image.

• iWidth – Image pixel width.

• iHeight – Image pixel height.

• iDepth – Image pixel depth.

• iFormat – Image format.

Returns

RED_OK when the call has succeeded,

RED_BAD_PARAM if the method has received an invalid parameter,

RED_WORKFLOW_ERROR if the texture has no GPU target yet,

RED_FAIL when a graphic driver error has occurred.

Public Static Functions

static inline RED::CID GetClassID()