IImage
Functions
void |
|
void |
|
void |
|
bool |
|
void |
|
void |
|
void |
|
void |
|
void |
|
const Color & |
|
void |
|
float |
Detailed Description
-
class IImage : public RED::IREDObject
This interface gives access to base images properties.
@related HOOPS Luminate Textures and Images, class RED::IImage2D, class RED::IImage3D, class RED::IImageCube, class RED::IImageComposite, class RED::IImageReadback
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: \ref bk_images.
Public Functions
-
virtual RED_RC 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.
-
virtual RED_RC 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.
-
virtual RED_RC 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.
-
virtual RED_RC 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.
-
virtual RED_RC 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.
-
virtual RED_RC 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.
-
virtual RED_RC 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.
-
virtual RED_RC 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.
-
virtual RED_RC 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.
-
virtual RED_RC 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.
-
virtual RED_RC 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.
-
virtual RED_RC 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.
-
virtual RED_RC 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.
-
virtual RED_RC 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.
-
virtual RED_RC 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.
-
virtual RED_RC 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
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.
-
virtual RED_RC 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.
-
virtual RED_RC 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.
-
virtual RED_RC 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.
-
virtual RED_RC 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.
-
virtual RED_RC 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.
-
virtual RED_RC 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.
-
virtual RED_RC 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.
-
virtual RED_RC 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
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.
-
virtual RED_RC 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.
-
virtual RED_RC 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
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.
-
virtual RED_RC 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.
-
virtual RED_RC 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.
-
virtual RED_RC 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.
-
virtual void 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.
-
virtual RED_RC 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.
-
virtual void 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.
-
virtual RED::TARGET 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.
-
virtual void 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.
-
virtual bool 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.
-
virtual void 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.
-
virtual void 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.
-
virtual void 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.
-
virtual void 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.
-
virtual void 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.
-
virtual const RED::Color &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.
-
virtual void 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.
-
virtual float 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.
