class RED::IImage3D

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

#include <REDIImage3D.h>

Inherits: IREDObject.

Public functions:

virtual void	ClearLocalPixels ( ) = 0
virtual RED_RC	GetImage3DByteSize ( RED::uint64 & oSize, int iWidth, int iHeight, int iDepth, RED::FORMAT iFormat ) const = 0
virtual int	GetLocalDepth ( ) const = 0
virtual RED::FORMAT	GetLocalFormat ( ) const = 0
virtual int	GetLocalHeight ( ) const = 0
virtual unsigned char *	GetLocalPixels ( ) = 0
virtual const unsigned char *	GetLocalPixels ( ) const = 0
virtual void	GetLocalSize ( int & oWidth, int & oHeight, int & oDepth ) const = 0
virtual int	GetLocalWidth ( ) const = 0
virtual RED_RC	GetPixels ( int iStateNumber = -1 ) const = 0
virtual RED_RC	GetWrapModes ( RED::WRAP_MODE & oWrapS, RED::WRAP_MODE & oWrapT, RED::WRAP_MODE & oWrapR, int iStateNumber = -1 ) const = 0
virtual RED_RC	SetLocalPixels ( unsigned char * iPixel, RED::FORMAT iFormat, int iWidth, int iHeight, int iDepth ) = 0
virtual RED_RC	SetPixels ( RED::TARGET iTarget, const RED::State & iState ) = 0
virtual RED_RC	SetPixels ( unsigned char * iPixel, RED::FORMAT iFormat, RED::TARGET iTarget, int iWidth, int iHeight, int iDepth, const RED::State & iState ) = 0
virtual RED_RC	SetWrapModes ( RED::WRAP_MODE iWrapS, RED::WRAP_MODE iWrapT, RED::WRAP_MODE iWrapR, const RED::State & iState ) = 0

Detailed description:

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

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: REDsdk textures and images (see 3D images for specific documentation about 3D images).

Functions documentation

public static RED::CID RED::IImage3D::GetClassID

(

)

public virtual void RED::IImage3D::ClearLocalPixels

(

) = 0

Removes the contents of the local pixel storage.

This method clears the local storage. Memory is released.

public virtual RED_RC RED::IImage3D::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 virtual int RED::IImage3D::GetLocalDepth

(

) const = 0

Gets the depth of our actual local storage.

Returns:

The pixel depth of our local storage.

public virtual RED::FORMAT RED::IImage3D::GetLocalFormat

(

) const = 0

Gets the actual format of our local storage.

Returns:

The current format of our local storage.

public virtual int RED::IImage3D::GetLocalHeight

(

) const = 0

Gets the height of the actual local storage.

Returns:

The pixel height of our local storage.

public virtual unsigned char * RED::IImage3D::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.

public virtual const unsigned char * RED::IImage3D::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.

public virtual void RED::IImage3D::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.

public virtual int RED::IImage3D::GetLocalWidth

(

) const = 0

Gets the width of the actual local storage.

Returns:

The pixel width of our local storage.

public virtual RED_RC RED::IImage3D::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 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::IImage3D::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.

public virtual RED_RC RED::IImage3D::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.

public virtual RED_RC RED::IImage3D::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.

public virtual RED_RC RED::IImage3D::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 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.

public virtual RED_RC RED::IImage3D::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.

class RED::IImage3D

Public functions:

Public static functions:

Detailed description:

Functions documentation