class RED::IImage

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

#include <REDIImage.h>

Inherits: IREDObject.

Public functions:

virtual RED_RC	Clear ( const RED::Color & iClearColor, const RED::State & iState ) = 0
virtual RED_RC	ColorBalance ( const RED::Color & iColorGain, const RED::Color & iColorOffset, const RED::State & iState ) = 0
virtual RED_RC	GetAnisotropy ( float & oAniso, int iStateNumber = -1 ) const = 0
virtual RED_RC	GetBorderColor ( RED::Color & oBorderColor, int iStateNumber = -1 ) const = 0
virtual RED_RC	GetFilterModes ( FILTER_MODE & oMinFilter, FILTER_MODE & oMagFilter, int iStateNumber = -1 ) const = 0
virtual RED_RC	GetFormat ( RED::FORMAT & oFormat, int iStateNumber = -1 ) const = 0
virtual RED_RC	GetImageByteSize ( RED::uint64 & oSize, int iWidth, int iHeight, RED::FORMAT iFormat ) const = 0
virtual RED_RC	GetIndirectMipmapMode ( bool & oMipmapMode, int iStateNumber = -1 ) const = 0
virtual float	GetLocalAnisotropy ( ) const = 0
virtual const RED::Color &	GetLocalBorderColor ( ) const = 0
virtual void	GetLocalFilterModes ( RED::FILTER_MODE & oMinFilter, RED::FILTER_MODE & oMagFilter ) const = 0
virtual bool	GetLocalMipmapMode ( ) const = 0
virtual RED::TARGET	GetLocalTarget ( ) const = 0
virtual void	GetLocalWrapModes ( RED::WRAP_MODE & oWrapU, RED::WRAP_MODE & oWrapV ) const = 0
virtual RED_RC	GetMetalInfo ( void *& oMtlTexture ) const = 0
virtual RED_RC	GetMipmapMode ( bool & oMipmapMode, int iStateNumber = -1 ) const = 0
virtual RED_RC	GetOpenGLInfo ( unsigned int & oTextureID ) const = 0
virtual RED_RC	GetPixelSize ( unsigned int & oSize, RED::FORMAT iFormat ) const = 0
virtual void	GetPixelStorage ( bool & oGPUStorage, bool & oCPUStorage ) const = 0
virtual RED_RC	GetSize ( int & oWidth, int & oHeight, int iStateNumber = -1 ) const = 0
virtual RED_RC	GetSize3D ( int & oWidth, int & oHeight, int & oDepth, int iStateNumber = -1 ) const = 0
virtual RED_RC	GetTarget ( TARGET & oTexTarget, int iStateNumber = -1 ) const = 0
virtual RED_RC	GetWrapModes ( WRAP_MODE & oWrapU, WRAP_MODE & oWrapV, int iStateNumber = -1 ) const = 0
virtual RED_RC	GreyScale ( RED::FORMAT iTargetFormat, GREY_OPERATION iGreyOp, const RED::Object * iSourceImage, const RED::State & iState ) = 0
virtual RED_RC	ImageCopyPixels ( const RED::Object * iImage, const RED::State & iState ) = 0
virtual RED_RC	Invert ( const RED::Object * iSourceImage, const RED::State & iState ) = 0
virtual RED_RC	IsPOTD ( bool & oPOTD, int iStateNumber = -1 ) const = 0
virtual RED_RC	SetAnisotropy ( float iAniso, const RED::State & iState ) = 0
virtual RED_RC	SetBorderColor ( const RED::Color & iBorderColor, const RED::State & iState ) = 0
virtual RED_RC	SetClosestPOTDSize ( const RED::State & iState ) = 0
virtual RED_RC	SetFilterModes ( FILTER_MODE iMinFilter, FILTER_MODE iMagFilter, const RED::State & iState ) = 0
virtual RED_RC	SetIndirectMipmapMode ( bool iMipmapMode, const RED::State & iState ) = 0
virtual void	SetLocalAnisotropy ( float iAnisotropy ) = 0
virtual void	SetLocalBorderColor ( const RED::Color & iBorderColor ) = 0
virtual void	SetLocalFilterModes ( RED::FILTER_MODE iMinFilter, RED::FILTER_MODE iMagFilter ) = 0
virtual void	SetLocalMipmapMode ( bool iMipmapMode ) = 0
virtual void	SetLocalTarget ( RED::TARGET iTarget ) = 0
virtual void	SetLocalWrapModes ( RED::WRAP_MODE iWrapU, RED::WRAP_MODE iWrapV ) = 0
virtual RED_RC	SetMipmapMode ( bool iMipmapMode, const RED::State & iState ) = 0
virtual RED_RC	SetPixelStorage ( bool iGPUStorage, bool iCPUStorage ) = 0
virtual RED_RC	SetSize ( int iWidth, int iHeight, const RED::State & iState ) = 0
virtual RED_RC	SetTarget ( RED::TARGET iTarget, const RED::State & iState ) = 0
virtual RED_RC	SetWrapModes ( WRAP_MODE iWrapU, WRAP_MODE iWrapV, const RED::State & iState ) = 0

Detailed description:

This interface gives access to base images properties.

The RED::IImage is the base interface for all kinds of images that can be used by the engine for both CPU and GPU rendering needs. 2D, 3D, CUBE, Composite and Readback images each have their own interfaces exposing their specific features:

RED::IImage2D for all 1D and 2D images.
RED::IImage3D for all 3D images.
RED::IImageComposite for composite images.
RED::IImageReadback for direct rendering buffer access.
RED::IImageCube for all cube mapping images.

An image corresponds to one texture on the GPU if the engine runs in hardware or hybrid mode and possibly to one texture on the CPU if the engine runs in hybrid or software mode. It stores all the texture configuration parameters. Pixels fields of the image are defined by specific image types and interfaces, according to the data to be stored and to the way to calculate it.

An image can't be created on its own. It must be created through one of the resource manager creation methods:

RED::IResourceManager::CreateImage2D: for 1D images, POTD 2D images and NPOTD 2D images.
RED::IResourceManager::CreateImage3D: for 3D images
RED::IResourceManager::CreateImageComposite: for images generated by a shader.
RED::IResourceManager::CreateImageReadback: for images whose contents is sourced from a GPU buffer.
RED::IResourceManager::CreateImageCube: for CUBE images.

These methods will fail while no windows have been created in the cluster. The resource manager needs at least one window to be created before being able to setup the GPU, before image creation is made possible.

An image must have a valid target defined for all operations to succeed. If the target of an image is not defined, most calls will return a RED_WORKFLOW_ERROR return code, indicating that the target must be specified first.

The target of an image can't be modified for its entire life. A 2D image, (RED::TGT_TEX_2D) for example that represents an image which is POTD (Power Of Two Dimensioned) must remain a POTD image using the RED::TGT_TEX_2D target until it's destroyed.

An image target is defined at the time the image receives pixels or using RED::IImage::SetTarget.

Images are particular state sensitive objects. They exist in one single exemplary on the GPU, and therefore all image operations are synchronous on the GPU, stall the rendering pipeline and are considered as workflow errors if the GPU or the CPU is busy at the time the operation occurs (rendering an image with the GPU or during a software tracer pass).

Therefore, an image has one single size for example, whatever may be the queried state number for it. On the other hand, a RED::IImage2D render image has a size that is state sensitive, as its contents will be defined on the fly for each rendered frame.

POTD: Power-Of-Two-Dimensioned. NPOTD: Non-Power-Of-Two-Dimensioned.

Image defaults for POTD images:

No texture target.
Mipmaps disabled (enabling is possible for 1D and 2D images).
Indirect lighting mipmaps disabled (enabling is possible for 1D and 2D images).
Texture repeat along (u,v,w).
Minification filter set to nearest.
Magnification filter set to linear.
Anisotropy set to 0.

Image defaults for NPOTD images:

No texture target.
Mipmaps disabled (enabling mipmaps is not possible).
Texture clamp along (u,v).
Minification and magnification filters set to nearest.
Anisotropy set to 0.

Image defaults for 3D images:

No texture target.
Mipmaps disabled (enabling mipmaps is not possible).
Texture clamp along (u,v,w) or (s,t,r).
Minification and magnification filters set to nearest.
Anisotropy set to 0.

Image defaults for CUBE images:

No texture target.
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.

Note that a 2D image that receives a NPOTD pixel array but that is turned on the fly into a RED::TGT_TEX_2D texture still get the NPOTD texture defaults.

An image using the RED::TGT_TEX_1D or RED::TGT_TEX_2D targets will use UV coordinates in the [0,1] x [0,1] range for accessing the texture's contents whereas a RED::TGT_TEX_RECT will use UVs in the [0,w] x [0,h] range for accessing the texture's contents, where the texture pixel dimensions are ( w, h ).

Note that all floating point formats textures (RED::FMT_FLOAT, RED::FMT_FLOAT_RGB, RED::FMT_FLOAT_RGBA, RED::FMT_HALF_FLOAT, RED::FMT_HALF_FLOAT_RGB and RED::FMT_HALF_FLOAT_RGBA) must use the RED::TGT_TEX_RECT texture format or the RED::TGT_TEX_CUBE format (CPU rendering only).

Indirect mipmapping is a Red engine extension to the traditional way images are handled by a GPU. We distinguish the usage of mipmaps when the texture image is seen directly by the camera and when it's seen through a ray-bounce, such as a reflection or a refraction processed by the GPU (this is not related to the software ray-tracer). Basically, enabling mipmaps enhance the quality of the filtering of the texture map and produces better results. In an indirect rendering workflow, enabling mipmaps may cause small artifacts to appear on edges of textured geometries. Refer to the product documentation for illustrations of this fact. Therefore, based on the applicative context, it may be wishful or not to enable indirect mipmaps.

Note that anisotropic filtering is effective in both direct and indirect lighting configurations. Also note that indirect mipmaps are effective only when mipmaps are enabled.

For an in-depth coverage of the images in REDsdk, please read: REDsdk textures and images.

Functions documentation

public static RED::CID RED::IImage::GetClassID

(

)

public virtual RED_RC RED::IImage::Clear	(	const RED::Color &	iClearColor,
		const RED::State &	iState
	)	= 0

Clears the image pixels.

Parameters:

iClearColor:	Color to use for the image clearance.
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 has failed,
RED_SCG_READ_ONLY_IMAGE if this can't be modified,
RED_FAIL if a graphic driver error has occurred.

public virtual RED_RC RED::IImage::ColorBalance	(	const RED::Color &	iColorGain,
		const RED::Color &	iColorOffset,
		const RED::State &	iState
	)	= 0

Modifies the image pixels.

This method performs a per pixel image operation: Each pixel's color is multiplied by iColorGain and added to iColorOffset. Saturation occurs for all clamped image formats (RGB, RGBA, BGRA, L8 and ALPHA).

Single channel formats (L8 and ALPHA) use the alpha channels of iColorGain and iColorOffset.

Color balance is not supported for 3D images.

Parameters:

iColorGain:	Per pixel image color modulation.
iColorOffset:	Per pixel image color addition.
iState:	Current transaction parameter.

Returns:

RED_OK if the modification has 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 the texture is a 3D image,
RED_WORKFLOW_ERROR if a software tracer image is being processed,
RED_ALLOC_FAILURE if an internal memory allocation has failed,
RED_SCG_READ_ONLY_IMAGE if this can't be modified,
RED_FAIL if a graphic driver error has occurred.

public virtual RED_RC RED::IImage::GetAnisotropy	(	float &	oAniso,
		int	iStateNumber = -1
	)	const = 0

Gets the anisotropic filter size.

Parameters:

oAniso:	Anisotropic filter size value. Returned to image default (1.0) if the image has no target.
iStateNumber:	Queried state number.

Returns:

RED_OK when the call succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_FAIL if a graphic driver error has occurred.

public virtual RED_RC RED::IImage::GetBorderColor	(	RED::Color &	oBorderColor,
		int	iStateNumber = -1
	)	const = 0

Gets the image border color.

Parameters:

oBorderColor:	The returned image border color. Returned to image default if the image has no target.
iStateNumber:	Queried state number.

Returns:

RED_OK if the call has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_FAIL if a graphic driver error has occurred.

public virtual RED_RC RED::IImage::GetFilterModes	(	FILTER_MODE &	oMinFilter,
		FILTER_MODE &	oMagFilter,
		int	iStateNumber = -1
	)	const = 0

Gets the texture minification & magnification filters.

Parameters:

oMinFilter:	Minification filter value. Returned to RED::FM_LINEAR if the image has no target.
oMagFilter:	Magnification filter value. Returned to RED::FM_LINEAR if the image has no target.
iStateNumber:	Queried state number.

Returns:

RED_OK if the call has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_FAIL if a graphic driver error has occurred.

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

Returns the pixel format of the image.

Retrieves the current pixel format of the image. SetFormat() methods are found on the RED::IImage sub-classes, as some restrictions may apply to the image format changes based on the kind of image we have.

Parameters:

oFormat:	Image pixel format. The returned image format is RED::FMT_NODATA if the texture has no target yet or if it has not received any data yet.
iStateNumber:	Queried state number.

Returns:

RED_OK if the call has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_FAIL when a graphic driver error has occurred.

public virtual RED_RC RED::IImage::GetImageByteSize	(	RED::uint64 &	oSize,
		int	iWidth,
		int	iHeight,
		RED::FORMAT	iFormat
	)	const = 0

Gets the byte size needed to encode pixels of an image.

This method returns the byte size needed to encode all pixels of an image whose dimensions and format are those provided to the method.

Compressed image formats are considered by this call in the resulting needed byte size.

Note that compressed image are always considered with dimensions greater than or equal to 4 for the size of their pixel data block.

A similar method exists for 3D images. See RED::IImage3D::GetImage3DByteSize.

Parameters:

oSize:	Byte size needed for the image.
iWidth:	Image pixel width.
iHeight:	Image pixel height.
iFormat:	Image format.

Returns:

RED_OK if 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 RED_RC RED::IImage::GetIndirectMipmapMode	(	bool &	oMipmapMode,
		int	iStateNumber = -1
	)	const = 0

Returns the indirect image mipmap mode.

Only 1D, 2D or CUBE images may have mipmaps.

Parameters:

oMipmapMode:	Returned to true if the image has indirect mipmaps. Returned false if the image has no target.
iStateNumber:	Queried state number.

Returns:

RED_OK when the call succeeded,
RED_BAD_PARAM if the method received an invalid parameter,
RED_FAIL if a graphic driver error has occurred.

public virtual float RED::IImage::GetLocalAnisotropy

(

) const = 0

Returns the local storage anisotropy.

Returns the value currently stored for the local anisotropy. By default, the method will return 1.0f unless the local anisotropy has been set manually or the image has been loaded with the RED::StreamingPolicy::SetLocalImages policy enabled.

Returns:

The local storage anisotropy.

public virtual const RED::Color & RED::IImage::GetLocalBorderColor

(

) const = 0

Returns the local storage border color.

Returns the value currently stored for the local border color. By default, the method will return RED::Color::BLACK unless the local border color has been set manually or the image has been loaded with the RED::StreamingPolicy::SetLocalImages policy enabled.

Returns:

The local storage border color.

public virtual void RED::IImage::GetLocalFilterModes	(	RED::FILTER_MODE &	oMinFilter,
		RED::FILTER_MODE &	oMagFilter
	)	const = 0

Returns the local storage filter modes.

Returns the value currently stored for the local filter modes. By default, the method will return RED::WM_NEAREST for each filter mode unless the local filter modes have been set manually or the image has been loaded with the RED::StreamingPolicy::SetLocalImages policy enabled.

Parameters:

oMinFilter:	Minification filter value.
oMagFilter:	Magnification filter value.

public virtual bool RED::IImage::GetLocalMipmapMode

(

) const = 0

Returns the local storage mipmap mode.

Returns the value currently stored for the local mipmap mode. By default, it'll return false unless the local mipmap mode has been set manually or the image has been loaded with the RED::StreamingPolicy::SetLocalImages policy enabled.

public virtual RED::TARGET RED::IImage::GetLocalTarget

(

) const = 0

Returns the local target value.

Returns the value currently stored for the local target. By default, RED::TGT_NONE will be returned unless the target has been manually set or the image has been loaded with the RED::StreamingPolicy::SetLocalImages policy enabled.

Returns:

The local target value.

public virtual void RED::IImage::GetLocalWrapModes	(	RED::WRAP_MODE &	oWrapU,
		RED::WRAP_MODE &	oWrapV
	)	const = 0

Returns the local storage wrap modes.

Returns the value currently stored for the local wrap modes. By default, the method will return RED::WM_CLAMP for each wrap mode unless the local wrap modes have been set manually or the image has been loaded with the RED::StreamingPolicy::SetLocalImages policy enabled.

Parameters:

oWrapU:	u texture axis wrap mode.
oWrapV:	v texture axis wrap mode.

public virtual RED_RC RED::IImage::GetMetalInfo

(

void *&

oMtlTexture

) const = 0

Access Metal texture informations associated to the image.

As a REDsdk image is associated to a Metal texture - assuming that REDsdk runs using hardware acceleration - we may need to access the id<MTLTexture> internally used by REDsdk to work with the texture. This id<MTLTexture> may be used in external Metal calls. Otherwise, using the ID value returned by this method will produce undefined results.

Please note that the returned value may be 0 if the texture has not been created by the engine yet on the GPU. This can be the case of a new image that has no contents for instance.

Parameters:

oMtlTexture:

pointer to id<MTLTexture> of the image.

Returns:

RED_OK if the operation has succeeded,
RED_DRV_FAIL if a graphic driver error has occurred.

public virtual RED_RC RED::IImage::GetMipmapMode	(	bool &	oMipmapMode,
		int	iStateNumber = -1
	)	const = 0

Returns the image mipmap mode.

Only 1D, 2D or CUBE images may have mipmaps.

Parameters:

oMipmapMode:	Returned to true if the image has mipmaps. Return false if the image has no target.
iStateNumber:	Queried state number.

Returns:

RED_OK if the call has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_FAIL if a graphic driver error has occurred.

public virtual RED_RC RED::IImage::GetOpenGLInfo

(

unsigned int &

oTextureID

) const = 0

Access OpenGL texture informations associated to the image.

As a REDsdk image is associated to an OpenGL texture - assuming that REDsdk runs using hardware acceleration - we may need to access the texture ID internally used by REDsdk to work with the texture. This texture ID may be used in external OpenGL calls, in an application using an external OpenGL context, if that external context is shared with REDsdk's contexts. Otherwise, using the ID value returned by this method will produce undefined results.

Please note that the returned texture ID may be 0 if the texture has not been created by the engine yet on the GPU. This can be the case of a new image that has no contents for instance.

Parameters:

oTextureID:

OpenGL texture ID of the image.

Returns:

RED_OK if the operation has succeeded,
RED_DRV_FAIL if a graphic driver error has occurred.

public virtual RED_RC RED::IImage::GetPixelSize	(	unsigned int &	oSize,
		RED::FORMAT	iFormat
	)	const = 0

Gets the number of bytes needed to encode a pixel given an image format.

This method returns the byte size per pixel needed to store the pixel's color information. Note that if the method receives a compressed image format it returns the equivalent uncompressed format byte size.

Parameters:

oSize:	Size of the pixel in bytes.
iFormat:	Format of the image.

Returns:

public virtual void RED::IImage::GetPixelStorage	(	bool &	oGPUStorage,
		bool &	oCPUStorage
	)	const = 0

Query the data storage mode for the image.

See RED::IImage::SetPixelStorage for details.

Parameters:

oGPUStorage:	Actual GPU data storage mode for the image.
oCPUStorage:	Actual CPU data storage mode for the image.

public virtual RED_RC RED::IImage::GetSize	(	int &	oWidth,
		int &	oHeight,
		int	iStateNumber = -1
	)	const = 0

Returns the pixel width and height of the image.

Use RED::IImage::GetSize3D with a depth parameter to query the size of a 3D image.

Parameters:

oWidth:	Image pixel width. The returned width is zero if the texture has no target set.
oHeight:	Image pixel height. The returned height is zero if the texture has no target set.
iStateNumber:	Queried state number.

Returns:

RED_OK when the call succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_WORKFLOW_ERROR if the texture has no target yet,
RED_FAIL if a graphic driver error has occurred.

public virtual RED_RC RED::IImage::GetSize3D	(	int &	oWidth,
		int &	oHeight,
		int &	oDepth,
		int	iStateNumber = -1
	)	const = 0

Returns the pixel width, height and depth of the image.

Parameters:

oWidth:	Image pixel width. The returned width is zero if the texture has no target set.
oHeight:	Image pixel height. The returned height is zero if the texture has no target set.
oDepth:	Image pixel depth. The returned depth is zero if the texture has no target set.
iStateNumber:	Queried state number.

Returns:

RED_OK when the call succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_WORKFLOW_ERROR if the texture has no target yet,
RED_FAIL if a graphic driver error has occurred.

public virtual RED_RC RED::IImage::GetTarget	(	TARGET &	oTexTarget,
		int	iStateNumber = -1
	)	const = 0

Returns the texture target of an image.

1D and 2D images are using an uv space in [0,0]x[1,1]. RECT textures are using the [0,0]x[width,height] space. CUBE textures are using a vector's direction for their texel lookups.

Parameters:

oTexTarget:	Texture target.
iStateNumber:	Queried state number.

Returns:

RED_OK if the call has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_FAIL if a graphic driver error has occurred.

public virtual RED_RC RED::IImage::GetWrapModes	(	WRAP_MODE &	oWrapU,
		WRAP_MODE &	oWrapV,
		int	iStateNumber = -1
	)	const = 0

Returns the texture wrapping modes.

Parameters:

oWrapU:	u texture axis wrap mode. Returned to RED::WM_CLAMP_TO_EDGE if the image has no target.
oWrapV:	v texture axis wrap mode. Returned to RED::WM_CLAMP_TO_EDGE if the image has no target.
iStateNumber:	Queried state number.

Returns:

RED_OK if the call has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_FAIL if a graphic driver error has occurred.

public virtual RED_RC RED::IImage::GreyScale	(	RED::FORMAT	iTargetFormat,
		GREY_OPERATION	iGreyOp,
		const RED::Object *	iSourceImage,
		const RED::State &	iState
	)	= 0

Sets the image as a grey scale image.

This method redefines the contents of this with the grey levels of iImage.

The call may fail if we already have a valid rendering target that is not compatible with the requested target format.

Parameters:

iTargetFormat:	Target greyscaled image format.
iGreyOp:	The grey operation we want to perform.
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 we have incompatible targets,
RED_WORKFLOW_ERROR if a software tracer image is being processed,
RED_ALLOC_FAILURE if an internal memory allocation did fail,
RED_SCG_READ_ONLY_IMAGE if this can't be modified,
RED_FAIL if a graphic driver error occurred.

public virtual RED_RC RED::IImage::ImageCopyPixels	(	const RED::Object *	iImage,
		const RED::State &	iState
	)	= 0

GPU image to image pixel copy.

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

ImageCopyPixels is not supported for:

3D images: See RED::IImage3D.
Built-in render images: See RED::IViewpointRenderList::GetRenderImage.

Parameters:

iImage:	Pixel source to copy.
iState:	Current transaction parameter.

Returns:

RED_OK if the modification has succeeded,
RED_WORKFLOW_ERROR if a transaction error was found,
RED_WORKFLOW_ERROR if we have incompatible targets,
RED_WORKFLOW_ERROR if the texture is a 3D image,
RED_WORKFLOW_ERROR if a software tracer image is being processed,
RED_ALLOC_FAILURE if an internal memory allocation has failed,
RED_SCG_READ_ONLY_IMAGE if this can't be modified,
RED_FAIL if a graphic driver error has occurred.

public virtual RED_RC RED::IImage::Invert	(	const RED::Object *	iSourceImage,
		const RED::State &	iState
	)	= 0

Sets the image as the invert of the source image (white - source).

This method redefines the contents of this with the invert of iImage. Only RGB color components are inverted by this method. The alpha channel is set to the copy of the source alpha, without any inversion.

Parameters:

iSourceImage:	Source image. May be set to this.
iState:	Current transaction parameter.

Returns:

public virtual RED_RC RED::IImage::IsPOTD	(	bool &	oPOTD,
		int	iStateNumber = -1
	)	const = 0

Is the image a Power-Of-Two-Dimensioned image?

Returns true in oPOTD if the image dimensions are exact powers of 2.

Parameters:

oPOTD:	true if the image is a POTD false if it's a NPOTD.
iStateNumber:	Queried state number.

Returns:

RED_OK when the call 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 if a graphic driver error has occurred.

public virtual RED_RC RED::IImage::SetAnisotropy	(	float	iAniso,
		const RED::State &	iState
	)	= 0

Sets the anisotropic filter size.

The method does nothing if the texture has no specified target (see RED::IImage::SetTarget).

Some GPUs may have various limits for this value. In case of excess, the value is clamped to the maximal accepted value.

Parameters:

iAniso:	Anisotropic filter size value.
iState:	Current transaction parameter.

Returns:

RED_OK if the modification 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 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 a graphic driver error has occurred.

public virtual RED_RC RED::IImage::SetBorderColor	(	const RED::Color &	iBorderColor,
		const RED::State &	iState
	)	= 0

Sets the image border color.

The method does nothing if the texture has no specified target (see RED::IImage::SetTarget).

The border color is only used when the texture wrap mode is set to the RED::WM_CLAMP_TO_BORDER value.

Parameters:

iBorderColor:	New border color.
iState:	Current transaction parameter.

Returns:

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

public virtual RED_RC RED::IImage::SetClosestPOTDSize

(

const RED::State &

iState

) = 0

Sets the image size to the closest POTD dimensions.

Resize the image - if this appears to be a need - so that it becomes a POTD image. The target of the image is set to TEX_2D. The closest dimensions from the current image dimensions are used for the resize operation.

It's not possible to resize a 3D image using this method.

Parameters:

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 target,
RED_WORKFLOW_ERROR if the texture is a 3D image,
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::IImage::SetFilterModes	(	FILTER_MODE	iMinFilter,
		FILTER_MODE	iMagFilter,
		const RED::State &	iState
	)	= 0

Sets the minification and magnification filters.

The method does nothing if the texture has no specified target (see RED::IImage::SetTarget).

Parameters:

iMinFilter:	Minification filter.
iMagFilter:	Magnification filter.
iState:	Current transaction parameter.

Returns:

public virtual RED_RC RED::IImage::SetIndirectMipmapMode	(	bool	iMipmapMode,
		const RED::State &	iState
	)	= 0

Enables or disables indirect mipmaps for the texture.

The order is only effective if the image has a 1D, 2D or CUBE target. It's ignored for RECT and 3D target images.

Parameters:

iMipmapMode:	New mipmap generation mode.
iState:	Current transaction parameters.

Returns:

RED_OK if the modification has succeeded,
RED_WORKFLOW_ERROR if a transaction error was found,
RED_WORKFLOW_ERROR if the texture has no target,
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 void RED::IImage::SetLocalAnisotropy

(

float

iAnisotropy

) = 0

Sets an anisotropy for the local storage.

This value is unusued except when a file is loaded with the RED::StreamingPolicy::SetLocalImages policy set to true. In this case, original image's anisotropy is stored in the image's local storage.

The local anisotropy won't be taken into consideration unless the image's own anisotropy is set again using that value.

Parameters:

iAnisotropy:

The local storage anisotropy.

public virtual void RED::IImage::SetLocalBorderColor

(

const RED::Color &

iBorderColor

) = 0

Sets a border color for the local storage.

This value is unusued except when a file is loaded with the RED::StreamingPolicy::SetLocalImages policy set to true. In this case, original image's border color is stored in the image's local storage.

The local border color won't be taken into consideration unless the image's own border color is set again using that value.

Parameters:

iBorderColor:

The local storage border color.

public virtual void RED::IImage::SetLocalFilterModes	(	RED::FILTER_MODE	iMinFilter,
		RED::FILTER_MODE	iMagFilter
	)	= 0

Sets filter modes for the local storage.

These values are unusued except when a file is loaded with the RED::StreamingPolicy::SetLocalImages policy set to true. In this case, original image's filter modes are stored in the image's local storage.

Local filter modes won't be taken into consideration unless the image's own filter modes are set again using these values.

Parameters:

iMinFilter:	Minification filter value.
iMagFilter:	Magnification filter value.

public virtual void RED::IImage::SetLocalMipmapMode

(

bool

iMipmapMode

) = 0

Sets a mipmap mode for the local storage.

This value is unusued except when a file is loaded with the RED::StreamingPolicy::SetLocalImages policy set to true. In this case, the fact that mipmaps are enabled or disabled is stored in the image's local storage.

The local mipmap mode won't be taken into consideration unless the image's mipmap mode is set again using that value.

Parameters:

iMipmapMode:

true to enable mipmaps, false to disable them.

public virtual void RED::IImage::SetLocalTarget

(

RED::TARGET

iTarget

) = 0

Sets a local target associated to the local pixel storage.

This is an optional RED::TARGET parameter that can be stored in the image's local storage. It's set with a valid target on loading a 2D image with the RED::StreamingPolicy::SetLocalImages policy set to true. In this case, the image is loaded in the local pixel storage and the target that was recorded with the texture is saved in the local target.

Otherwise, this parameter is not used. It's not taken into consideration when doing any of the RED::IImage2D::SetPixels call to upload the local storage on the GPU. The target must be respecified.

Parameters:

iTarget:

New value for the local target.

public virtual void RED::IImage::SetLocalWrapModes	(	RED::WRAP_MODE	iWrapU,
		RED::WRAP_MODE	iWrapV
	)	= 0

Sets wrap modes for the local storage.

These values are unusued except when a file is loaded with the RED::StreamingPolicy::SetLocalImages policy set to true. In this case, original image's wrap modes are stored in the image's local storage.

Local wrap modes won't be taken into consideration unless the image's own wrap modes are set again using these values.

Parameters:

iWrapU:	u texture axis wrap mode.
iWrapV:	v texture axis wrap mode.

public virtual RED_RC RED::IImage::SetMipmapMode	(	bool	iMipmapMode,
		const RED::State &	iState
	)	= 0

Enables or disables mipmaps for the texture.

The order is only effective if the image has a 1D, 2D or CUBE target. It's ignored for RECT and 3D target images.

Parameters:

iMipmapMode:	New mipmap generation mode.
iState:	Current transaction parameters.

Returns:

RED_OK if the modification has succeeded,
RED_WORKFLOW_ERROR if a transaction error was found,
RED_WORKFLOW_ERROR if the texture has no target,
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 a graphic driver error has occurred.

public virtual RED_RC RED::IImage::SetPixelStorage	(	bool	iGPUStorage,
		bool	iCPUStorage
	)	= 0

Enable or disable CPU or GPU pixel data storage for the image.

This method is only effective when REDsdk runs in hybrid mode (see RED::OPTIONS_RAY_ENABLE_SOFT_TRACER). It can be used to prevent images that are created to be loaded on the GPU or on the CPU. If done so, then the image should be only used in relevant workflows, otherwise, it may cause errors or appear black.

Disabling the GPU pixel storage of an image avoids having it to consume GPU memory and disabling the CPU pixel storage of an image avoids having it to consume CPU memory.

By default, image GPU and CPU storages are enabled. Changing a storage mode after having used the image will provoke errors, so this method should only be called for images after their creation, before use.

Note that CPU and GPU storage refer to how the image is being stored by the engine, so this differs from the local storage that remain another storage that can be used to locally manipulate image pixels.

The image pixel storage mode setting is not copied to a RED::IResourceManager::CloneImage.

Parameters:

iGPUStorage:	true (default) to have images uploaded on the GPU, false otherwise.
iCPUStorage:	true (default) to have images uploaded on the CPU, false otherwise.

Returns:

RED_OK if the method has succeeded,
RED_BAD_PARAM if both storages are set to 'false': One of them must be enabled at least.

public virtual RED_RC RED::IImage::SetSize	(	int	iWidth,
		int	iHeight,
		const RED::State &	iState
	)	= 0

Sets the pixel width and height of an image.

Stretches the image contents to the new specified size. If the image has no contents yet, the operation is pointless. If the image has a POTD target (TEX_1D, TEX_2D or TEX_CUBE), then the target dimensions must be POTD also.

It's not possible to resize a 3D image using this method.

Parameters:

iWidth:	New image width.
iHeight:	New image height.
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 the texture has no target,
RED_WORKFLOW_ERROR if the texture is a 3D image,
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 a graphic driver error has occurred.

public virtual RED_RC RED::IImage::SetTarget	(	RED::TARGET	iTarget,
		const RED::State &	iState
	)	= 0

Defines the image's texture target.

This method sets the specified iTarget as being the texture's target for the image. Once set, an image's texture target can't be changed. The target defines the way the image pixels will be sampled by the graphic hardware or by the software ray-tracer.

The texture target of the image must have been defined before any other operation on the image. Usually, it's automatically defined while defining the pixels of the texture image. If not, this method can be used to set the texture target beforehand, so that texturing parameters can be changed.

Several images types have fixed targets. Images created using:

RED::IResourceManager::CreateImage2D can use any of the three following targets: RED::TGT_TEX_1D, RED::TGT_TEX_2D or RED::TGT_TEX_RECT.
RED::IResourceManager::CreateImageComposite must use the RED::TGT_TEX_RECT target.
RED::IResourceManager::CreateImageCube must use the RED::TGT_TEX_CUBE target.
RED::IResourceManager::CreateImage3D must use the RED::TGT_TEX_3D target.

Parameters:

iTarget:	The texture target to set.
iState:	Current transaction parameter.

Returns:

RED_OK if the modification has succeeded,
RED_WORKFLOW_ERROR if a transaction error was found,
RED_WORKFLOW_ERROR if the texture already have a target or if the specified target is invalid for the image,
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 a graphic driver error has occurred.

public virtual RED_RC RED::IImage::SetWrapModes	(	WRAP_MODE	iWrapU,
		WRAP_MODE	iWrapV,
		const RED::State &	iState
	)	= 0

Defines the texture wrapping modes.

The method does nothing if the texture has no specified target (see RED::IImage::SetTarget).

Note that the RED::IImage3D exposes its own RED::IImage3D::SetWrapModes method that handles the 3rd axis wrap mode.

Parameters:

iWrapU:	u texture axis wrap mode.
iWrapV:	v texture axis wrap mode.
iState:	Current transaction parameter.

Returns:

RED_OK if the modification has succeeded,
RED_BAD_PARAM if the method has received a wrong target / wrap mode combination,
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 has failed,
RED_FAIL if a graphic driver error has occurred.

class RED::IImage

Public functions:

Public static functions:

Detailed description:

Functions documentation