ImageTools

Types

IMAGE_FILE_FORMAT

Fields

IFF_JPEG

IFF_PNG

IFF_HDR

IFF_TGA

IFF_COUNT

Functions

RED_RC

Save

RED_RC

Save

RED_RC

Load

RED_RC

Load

RED_RC

Resize

RED_RC

CopyFrom

RED_RC

ConvertFormat

RED_RC

ConvertMetallicToRealisticMaterial

RED_RC

GetMeanColor

RED_RC

RegisterCustomLoadCallback

RED_RC

UnregisterCustomLoadCallback

RED_RC

ClearCustomLoadCallback

Detailed Description

class ImageTools : public RED::Object

Image saving and loading API.

@related HOOPS Luminate Textures and Images, How to Load and Save Image to File?, Converting PBR Metallic Data to the Realistic Material

The RED::ImageTools class defines the I/O methods to save or load images through commonly used image file formats.

Currently supported formats are JPEG, PNG, TGA and HDR.

All the API methods take a “vertical flip” flag to reverse the order of the image lines (either at loading or at saving time). This is because while most image formats expect the image origin to be in the top left corner, OpenGL (and so REDsdk) considers the image origin to be in the bottom left corner.

Public Types

enum IMAGE_FILE_FORMAT

Lists all the supported image file formats.

Values:

enumerator IFF_JPEG

Lossy compression in RED::FMT_RGB format.

enumerator IFF_PNG

Lossless compression in RED::FMT_RGB or RED::FMT_RGBA format.

enumerator IFF_HDR

Radiance’s picture format (RED::FMT_FLOAT_RGB) with lossless compression.

enumerator IFF_TGA

Lossless compression in RED::FMT_RGB or RED::FMT_RGBA format.

enumerator IFF_COUNT

Public Static Functions

static RED_RC Save(RED::Object *iImage, bool iLocalStorage, RED::IStream &iOutput, IMAGE_FILE_FORMAT iImageFormat, bool iDiscardAlpha, bool iVerticalFlip, float iQuality)

Saves an image to a stream. The stream can be either a memory or a file stream.

If the output stream is not opened, the method opens it in RED::AM_WRITE mode. The stream cursor is left at the last write position when leaving the method and the stream is not closed.

Depending on the image file format, the alpha component of the source image can be saved or not:

  • the JPEG format can’t handle the alpha component and therefore it’s discarded (iDiscardAlpha is true whatever the value set by the caller).

  • the same goes for HDR which also discards automatically any alpha component in the input image.

  • the PNG format can handle the alpha component and follows the value of the iDiscardAlpha flag set by the caller.

  • the TGA format can handle the alpha component and follows the value of the iDiscardAlpha flag set by the caller.

An automatic conversion process of the input image can occur if the pixel format does not match the ones supported by the selected image file format. For example, a RED::FMT_FLOAT_RGB image will be first converted to RED::FMT_RGB before being saved to a JPEG file.

A summary of all the conversions is given in the table below:

Input pixel format

Conversion for JPEG, PNG and TGA

Conversion for HDR

RED::FMT_RGBA

R, G, B, A

R, G, B

RED::FMT_RGB

R, G, B

R, G, B

RED::FMT_FLOAT

[F]*255, [F]*255, [F]*255

F, F, F

RED::FMT_FLOAT_RGBA

[FR]*255, [FG]*255, [FB]*255, [FA]*255

FR, FG, FB

RED::FMT_FLOAT_RGB

[FR]*255, [FG]*255, [FB]*255

FR, FG, FB

RED::FMT_L8

L8, L8, L8

L8, L8, L8

RED::FMT_A8

0, 0, 0, A8

0, 0, 0

RED::FMT_RGBA_DXT1

fail

fail

RED::FMT_RGBA_DXT3

fail

fail

RED::FMT_RGBA_DXT5

fail

fail

RED::FMT_RGB_DXT1

fail

fail

RED::FMT_HALF_FLOAT

[HF]*255, [HF]*255, [HF]*255

HF, HF, HF

RED::FMT_HALF_FLOAT_RGBA

[HFR]*255, [HFG]*255, [HFB]*255, [HFA]*255

HFR, HFG, HFB

RED::FMT_HALF_FLOAT_RGB

[HFR]*255, [HFG]*255, [HFB]*255

HFR, HFG, HFB

RED::FMT_FLOAT_RGBA_AA

pixels are converted to FMT_FLOAT_RGBA and then to the format given in that table

pixels are converted to FMT_FLOAT_RGBA and then to the format given in that table

where R, G, B, A are the respective red, green, blue and alpha 8bit components of the input image file F is the float component of the single component float input image FR, FG, FB, FA are the respective red, green, blue and alpha components of the float input image HF is the half-float component of the single component half-float input image HFR, HFG, HFB, HFA are the respective red, green, blue and alpha components of the half-float input image L8 is the L8 component of the input image A8 is the A8 component of the input image [] is the clamping operator: the input value is clamped to the [0, 1] range.

The conversion columns give the format of the output pixel after conversion.

Please note that due to IP reasons, DXT images are not saved neither load using the RED::ImageTools methods.

Note also that if a conversion occurs, the time to process the whole image can be big depending on the image resolution and the complexity of the conversion.

According to the selected image file format and the value of the iDiscardAlpha flag, the alpha component after conversion is discarded or not of the destination image. Hence, a RED::FMT_A8 image saved to a JPEG file will be totally white.

See also \ref tk_loading_and_saving_image_to_file.

Parameters
  • iImage – pointer to the image to save.

  • iLocalStorage – true to save the content of the local storage of the image, false to get pixels back from video memory.

  • iOutput – reference the destination stream.

  • iImageFormat – image file format.

  • iDiscardAlpha – true to discard the alpha component of the image, false otherwise. If the image has no alpha component, the flag has no effect.

  • iVerticalFlip – true to flip the saved image lines of pixels vertically, false to let it unchanged.

  • iQuality – quality of the image compression (in [0, 1]). This parameter is meaningful only for lossy compression image formats (like JPEG). It’s discarded for other image formats.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid parameter value,

RED_IMAGE_UNSUPPORTED_EXTENSION on an unsupported file extension,

RED_IMAGE_UNSUPPORTED_FORMAT on an unsupported pixel format for the given file extension,

RED_ALLOC_FAILURE on a memory allocation error,

RED_FAIL otherwise.

static RED_RC Save(RED::Object *iImage, bool iLocalStorage, const RED::String &iFilePath, bool iDiscardAlpha, bool iVerticalFlip, float iQuality)

Saves an image to a file. This is a helper method; for full documentation, please refer to the stream version of the Save method.

The format used to save the image is derived from the given file path extension:

  • ‘.jpg’ and ‘.jpeg’ turn into IFF_JPEG.

  • ’.png’ turns into IFF_PNG.

  • ’.hdr’ and ‘.rgbe’ turn into IFF_HDR.

  • ’.tga’ turns into IFF_TGA.

  • other formats make the method to return with RED_IMAGE_UNSUPPORTED_EXTENSION.

See also \ref tk_loading_and_saving_image_to_file.

Parameters
  • iImage – Pointer to the image to save. iImage pixels may be downloaded from the GPU.

  • iLocalStorage – true to save the content of the local storage of the image, false to get pixels back from video memory.

  • iFilePath – full path to the destination file.

  • iDiscardAlpha – true to discard the alpha component of the image, false otherwise. If the image has no alpha component, the flag has no effect.

  • iVerticalFlip – true to flip the saved image lines of pixels vertically, false to let it unchanged.

  • iQuality – quality of the image compression (in [0, 1]). This parameter is meaningful only for lossy compression image formats (like JPEG). It’s discarded for other image formats.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid parameter value,

RED_IMAGE_UNSUPPORTED_EXTENSION on an unsupported file extension,

RED_IMAGE_UNSUPPORTED_FORMAT on an unsupported pixel format for the given file extension,

RED_ALLOC_FAILURE on a memory allocation error,

RED_FAIL otherwise.

static RED_RC Load(RED::Object *oImage, RED::IStream &iInput, IMAGE_FILE_FORMAT iImageFormat, RED::FORMAT iPixelFormat, bool iVerticalFlip, bool iLocal, RED::TARGET iTarget, const RED::State &iState)

Loads an image from a stream.

The method loads an image from a stream and fills a provided RED::Object with its content. The oImage instance must implement the RED::IImage2D and RED::IImage interfaces.

If iLocal is true, the loaded image is stored in the local storage of the RED image and is not sent to the GPU by default. It’s up to the user to decide or not to synchronize the GPU version of the image with the local one by calling SetPixels on it. If iLocal is false, the image is directly uploaded into the graphics card memory and is ready to use by the hardware. The GPU texture target is set to iTarget.

If the input stream is not opened, the method opens it in RED::AM_READ mode. The stream cursor is left at the last read position when leaving the method and the stream is not closed.

The user can specify in which pixel format the returned image must be set. Depending on the image file format, some components of the returned image may be initialized to default values.

The table below summarizes the translations which can occur between image file formats and requested pixel formats:

Image file format

Pixel format

Conversion

JPEG/PNG/TGA - RGB

RED::FMT_RGBA

R, G, B, 1

JPEG/PNG/TGA - RGB

RED::FMT_RGB

R, G, B

JPEG/PNG/TGA - RGB

RED::FMT_FLOAT

( R + G + B ) / ( 3 * 255 )

JPEG/PNG/TGA - RGB

RED::FMT_FLOAT_RGBA

R / 255, G / 255, B / 255, 1

JPEG/PNG/TGA - RGB

RED::FMT_FLOAT_RGB

R / 255, G / 255, B / 255

JPEG/PNG/TGA - RGB

RED::FMT_L8

( R + G + B ) / 3

JPEG/PNG/TGA - RGB

RED::FMT_A8

( R + G + B ) / 3

JPEG/PNG/TGA - RGB

RED::FMT_RGBA_DXT1

fail

JPEG/PNG/TGA - RGB

RED::FMT_RGBA_DXT3

fail

JPEG/PNG/TGA - RGB

RED::FMT_RGBA_DXT5

fail

JPEG/PNG/TGA - RGB

RED::FMT_RGB_DXT1

fail

JPEG/PNG/TGA - RGB

RED::FMT_HALF_FLOAT

( R + G + B ) / ( 3 * 255 )

JPEG/PNG/TGA - RGB

RED::FMT_HALF_FLOAT_RGBA

R / 255, G / 255, B / 255, 1

JPEG/PNG/TGA - RGB

RED::FMT_HALF_FLOAT_RGB

R / 255, G / 255, B / 255

JPEG/PNG/TGA - RGB

RED::FMT_FLOAT_RGBA_AA

fail

PNG/TGA - RGBA

RED::FMT_RGBA

R, G, B, A

PNG/TGA - RGBA

RED::FMT_RGB

R, G, B

PNG/TGA - RGBA

RED::FMT_FLOAT

( R + G + B ) / ( 3 * 255 )

PNG/TGA - RGBA

RED::FMT_FLOAT_RGBA

R / 255, G / 255, B / 255, A / 255

PNG/TGA - RGBA

RED::FMT_FLOAT_RGB

R / 255, G / 255, B / 255

PNG/TGA - RGBA

RED::FMT_L8

( R + G + B ) / 3

PNG/TGA - RGBA

RED::FMT_A8

( R + G + B ) / 3

PNG/TGA - RGBA

RED::FMT_RGBA_DXT1

fail

PNG/TGA - RGBA

RED::FMT_RGBA_DXT3

fail

PNG/TGA - RGBA

RED::FMT_RGBA_DXT5

fail

PNG/TGA - RGBA

RED::FMT_RGB_DXT1

fail

PNG/TGA - RGBA

RED::FMT_HALF_FLOAT

( R + G + B ) / ( 3 * 255 )

PNG/TGA - RGBA

RED::FMT_HALF_FLOAT_RGBA

R / 255, G / 255, B / 255, A / 255

PNG/TGA - RGBA

RED::FMT_HALF_FLOAT_RGB

R / 255, G / 255, B / 255

PNG/TGA - RGBA

RED::FMT_FLOAT_RGBA_AA

fail

HDR - float RGB

RED::FMT_RGBA

R * 255, G * 255, B * 255, 255

HDR - float RGB

RED::FMT_RGB

R * 255, G * 255, B * 255

HDR - float RGB

RED::FMT_FLOAT

( R + G + B ) / 3

HDR - float RGB

RED::FMT_FLOAT_RGBA

R, G, B, 1

HDR - float RGB

RED::FMT_FLOAT_RGB

R, G, B

HDR - float RGB

RED::FMT_L8

255 * ( R + G + B ) / 3

HDR - float RGB

RED::FMT_A8

255 * ( R + G + B ) / 3

HDR - float RGB

RED::FMT_RGBA_DXT1

fail

HDR - float RGB

RED::FMT_RGBA_DXT3

fail

HDR - float RGB

RED::FMT_RGBA_DXT5

fail

HDR - float RGB

RED::FMT_RGB_DXT1

fail

HDR - float RGB

RED::FMT_HALF_FLOAT

( R + G + B ) / 3

HDR - float RGB

RED::FMT_HALF_FLOAT_RGBA

R, G, B, A

HDR - float RGB

RED::FMT_HALF_FLOAT_RGB

R, G, B

HDR - float RGB

RED::FMT_FLOAT_RGBA_AA

fail

where R, G, B, A are the respective red, green, blue and alpha components of the input image file

The conversion columns give the format of the output pixel after conversion.

Please note also that if a conversion occurs, the time to process the whole image can be big depending on the image resolution and the complexity of the conversion.

See also \ref tk_loading_and_saving_image_to_file.

Note

Some restrictions apply to the HDR format support: only HDR files using the ‘bit_rle_rgbe’ format and oriented along ‘-y +x’ are supported.

Parameters
  • oImage – pointer to the returned image. This image must have been properly created before the call (and must implement RED::IImage and RED::IImage2D interfaces).

  • iInput – reference to the input stream.

  • iImageFormat – image file format.

  • iPixelFormat – requested pixel format for the returned image.

  • iVerticalFlip – true to flip the loaded image lines of pixels vertically, false to let it unchanged.

  • iLocal – true to load the image in the local (CPU memory) storage of the image, false to load it directly in the graphics card memory. If iLocal is true, then the source pixel array is kept in the local storage of the image regardless of the value of iTarget. If iLocal is false, the source pixel array is loaded and then set into the image with possible formats & conversions depending on the hardware backend capabilities and value of iTarget. For instance, a non-power-of-two (NPOTD) image can be loaded and will remain as NPOTD in the local storage while it’ll be turned into a power-of-two (POTD) image if iLocal is false and iTarget is RED::TGT_TEX_2D for instance.

  • iTarget – this specifies the target of the loaded image once in the graphics card memory. Note that the target must be chosen in accordance with the requested iPixelFormat.

  • iState – current transaction.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid parameter value,

RED_IMAGE_UNSUPPORTED_FORMAT on an unsupported file extension,

RED_ALLOC_FAILURE on a memory allocation error,

RED_FAIL otherwise.

static RED_RC Load(RED::Object *oImage, const RED::String &iFilePath, RED::FORMAT iPixelFormat, bool iVerticalFlip, bool iLocal, RED::TARGET iTarget, const RED::State &iState)

Loads an image from a file. This is a helper method; for full documentation, please refer to the stream version of the Load method.

If iLocal is true, the loaded image is stored in the local storage of the RED image and is not sent to the GPU by default. It’s up to the user to decide or not to synchronize the GPU version of the image with the local one by calling SetPixels on it. If iLocal is false, the image is directly uploaded into the graphics card memory and ready to use by the hardware.

Files ending with the ‘.jpeg’ or ‘.jpg’ extensions are loaded as JPEG files. Files ending with the ‘.png’ extension are loaded as PNG files. Files ending with the ‘.hdr’ or ‘.rgbe’ extensions are loaded as HDR files. Files ending with the ‘.tga’ extensions are loaded as TGA files.

The method is not case sensitive.

See also \ref tk_loading_and_saving_image_to_file.

Note

Some restrictions apply to the HDR format support: only HDR files using the ‘bit_rle_rgbe’ format and oriented along ‘-y +x’ are supported.

Parameters
  • oImage – pointer to the returned image. This image must have been properly created before the call (and must implement RED::IImage and RED::IImage2D interfaces).

  • iFilePath – full path to the source file.

  • iPixelFormat – requested pixel format for the returned image.

  • iVerticalFlip – true to flip the loaded image lines of pixels vertically, false to let it unchanged.

  • iLocal – true to load the image in the local (CPU memory) storage of the image, false to load it directly in the graphics card memory.

  • iTarget – this specifies the target of the loaded image once in the graphics card memory. Note that the target must be chosen in accordance with the requested iPixelFormat.

  • iState – current transaction.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid parameter value,

RED_IMAGE_UNSUPPORTED_FORMAT on an unsupported file format,

RED_IMAGE_UNSUPPORTED_EXTENSION on an unsupported file extension,

RED_ALLOC_FAILURE on a memory allocation error,

RED_FAIL otherwise.

static RED_RC Resize(RED::Object *iImage, const RED::Object *iSourceImage, bool iLocalStorage, int iWidth, int iHeight)

Resizes an image by filtering its content.

The result is stored in the local storage of the returned iImage. The source image can’t be the same as the destination image.

The format of the image is not changed during the operation.

Parameters
  • iImage – pointer to the returned image. This image must have been properly created before the call (and must implement RED::IImage and RED::IImage2D interfaces).

  • iSourceImage – pointer to the image to resize.

  • iLocalStorage – true to get the content from the local storage of the image, false to get pixels back from video memory.

  • iWidth – width of the returned image after the resizing.

  • iHeight – height of the returned image after the resizing.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid parameter value,

RED_ALLOC_FAILURE on a memory allocation error,

RED_FAIL otherwise.

static RED_RC CopyFrom(RED::Object *iImage, const RED::Object *iSourceImage, bool iLocalStorage)

Copy a source content pixels into a destination image. 2D images only.

The result is stored in the local storage of the returned iImage. The source image can’t be the same as the destination image. Target, pixels, anisotropy, wrap modes, filter modes and mimmap modes are copied.

Parameters
  • iImage – pointer to the returned image. This image must have been properly created before the call (and must implement RED::IImage and RED::IImage2D interfaces).

  • iSourceImage – pointer to the source image.

  • iLocalStorage – true to get the content from the local storage of the souce image, false to get pixels back from video memory.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid parameter value, or if an image is not a 2D image,

RED_ALLOC_FAILURE on a memory allocation error,

RED_FAIL otherwise.

static RED_RC ConvertFormat(RED::Object *iImage, const RED::Object *iSourceImage, bool iLocalStorage, RED::FORMAT iFormat)

Converts an image from one format to another.

The result is stored in the local storage of the returned iImage. The source image can’t be the same as the destination image.

  • When the source format has 4 channels and the result format has 3 channels, the alpha component is lost.

  • When the source format has 3 or 4 channels and the result format has 1 channel, the channel is filled with (R + G + B) / 3.

  • When the source format has 1 channel and the result format has 3 or 4 channels, they are all filled with the same value.

Float and half float channels have normalized values between 0 and 1. Other formats have values between 0 and 255.

Parameters
  • iImage – pointer to the returned image. This image must have been properly created before the call (and must implement RED::IImage and RED::IImage2D interfaces).

  • iSourceImage – pointer to the image to convert.

  • iLocalStorage – true to get the content from the local storage of the image, false to get pixels back from video memory.

  • iFormat – format of the returned image after the conversion.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid parameter value,

RED_ALLOC_FAILURE on a memory allocation error,

RED_FAIL otherwise.

static RED_RC ConvertMetallicToRealisticMaterial(RED::Object *iDiffuseTexture, int iDiffuseTextureWidth, int iDiffuseTextureHeight, RED::Object *iReflectionTexture, int iReflectionTextureWidth, int iReflectionTextureHeight, RED::Object *iAnisotropyTexture, int iAnisotropyTextureWidth, int iAnisotropyTextureHeight, RED::Object *iIORTexture, int iIORTextureWidth, int iIORTextureHeight, RED::Object *iGlossyEnvironmentalTexture, int iGlossyEnvironmentalTextureSize, const RED::Object *iAlbedoTexture, const RED::Color &iAlbedoColor, const RED::Object *iRoughnessTexture, float iRoughnessValue, const RED::Object *iMetalnessTexture, float iMetalnessValue, const RED::Object *iAOTexture, float iAOStrength, const RED::Object *iAlphaMask, float iAlphaThreshold, bool iAlphaFromAlbedo, const RED::Object *iEnvironmentalTexture, RED::Object *iResMgr, const RED::State &iState)

Converts PBR metallic material parameters into realistic material parameters.

From a set of metallic material parameters, this function outputs ready-to-use textures to use with RED::IMaterial::SetupRealisticMaterial.

Metallic material inputs are:

  • albedo texture and color;

  • roughness texture and value;

  • metalness texture and value;

  • AO texture and strength.

Albedo, roughness and metalness textures are optional. If NULL, the associated color or value is used instead. If the texture is valid, its data is modulated by the associated color or value following the formula: result = texture * color.

AO texture is optionnal. iAOStrength controls how much of the AO is applied. A value of 0.0 means no occlusion. A value of 1.0 means full occlusion. This value affects the resulting diffuse using the formula: diffuse = lerp( color, color * iAOTexture, iAOStrength ). iAOStrength is ignored if the AO texture is NULL.

Output realistic material parameters are:

  • diffuse texture;

  • reflection texture;

  • reflection anisotropy texture;

  • IOR texture.

All the textures implement the RED::IImage2D interface except iGlossyEnvironmentalTexture which is a RED::IImageCube.

All textures are set with the wrapping mode of the first input texture found (iAlbedoTexture, iRoughnessTexture, iMetalnessTexture, iAOTexture). If no input textures are supplied, then the wrap mode is set to RED::WM_REPEAT by default.

When iAlphaMask is provided, the output reflection is discarded where the value of the mask is under iAlphaThreshold and the oIOR is set to 1. It allows to have a perfect transparency without any refraction effect where the mask is off.

The alpha mask can also be taken from the albedo alpha channel when iAlphaFromAlbedo parameter is true. In this case, no separate alpha mask texture should be provided.

In addition to the traditionnal PBR inputs, the function can convert an environmental texture used for realtime reflections. The texture is blurred according to the average roughness of the material. iEnvironmentalTexture can be provided as a cube map implementing RED::IImageCube or as a latitude / longitude environment map implementing RED::IImage2D. iGlossyEnvironmentalTexture implements the RED::IImageCube interface.

\task tk_converting_pbr_metallic_to_realistic

Note

This function works with image local storage. Make sure that the texture data are in the local storage before calling it. Also make sure to call RED::IImage2D::SetPixels before using the output images in the realistic material.

Note

The Fresnel parameter of the realistic material must be turned ON when using this function.

Note

iAlphaThreshold can be negative. If so, the comparison is inverted and the values are discarded where the mask is over the absolute value of iThreshold.

Parameters
  • iDiffuseTexture – pointer to the returned diffuse image. RED::FMT_RGB format. This image must have been properly created before the call (and must implement RED::IImage and RED::IImage2D interfaces).

  • iDiffuseTextureWidth – width of the returned diffuse image.

  • iDiffuseTextureHeight – height of the returned diffuse image.

  • iReflectionTexture – pointer to the returned reflection image. RED::FMT_RGB format. This image must have been properly created before the call (and must implement RED::IImage and RED::IImage2D interfaces).

  • iReflectionTextureWidth – width of the returned reflection image.

  • iReflectionTextureHeight – height of the returned reflection image.

  • iAnisotropyTexture – pointer to the returned anisotropy image. RED::FMT_RGB format. This image must have been properly created before the call (and must implement RED::IImage and RED::IImage2D interfaces).

  • iAnisotropyTextureWidth – width of the returned anisotropy image.

  • iAnisotropyTextureHeight – height of the returned anisotropy image.

  • iIORTexture – pointer to the returned IOR image. RED::FMT_HALF_FLOAT format. This image must have been properly created before the call (and must implement RED::IImage and RED::IImage2D interfaces).

  • iIORTextureWidth – width of the returned IOR image.

  • iIORTextureHeight – height of the returned IOR image.

  • iGlossyEnvironmentalTexture – environmental texture used for realtime reflections. RED::FMT_RGB format. Can be NULL.

  • iGlossyEnvironmentalTextureSize – environmental texture cube size. Must be power of two.

  • iAlbedoTexture – albedo texture from the metallic material. Can be NULL.

  • iAlbedoColor – albedo color from the metallic material.

  • iRoughnessTexture – roughness texture from the metallic material. Can be NULL.

  • iRoughnessValue – roughness value from the metallic material.

  • iMetalnessTexture – metalness texture from the metallic material. Can be NULL.

  • iMetalnessValue – metalness value from the metallic material.

  • iAOTexture – ambient occlusion texture from the metallic material. Can be NULL.

  • iAOStrength – controls the amount of AO applied. Range from 0 (no AO) to 1(full AO).

  • iAlphaMask – alpha mask texture. Allows to “cancel” refraction effect under transparency pixels. Can be NULL.

  • iAlphaThreshold – controls the threshold value of the alpha mask under which a pixel is rejected.

  • iAlphaFromAlbedo – true to take the alpha mask from the albedo alpha channel. false to take it from iAlphaMask.

  • iEnvironmentalTexture – environmental texture. Can be NULL.

  • iResMgr – resource manager implementing RED::IResourceManager.

  • iState – current transaction parameter.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid parameter value,

RED_ALLOC_FAILURE on a memory allocation error,

RED_FAIL otherwise.

static RED_RC GetMeanColor(RED::Color &oMinColor, RED::Color &oMaxColor, RED::Color &oMeanColor, RED::Object *ioImage, bool iLocalStorage)

Calculates the mean color of an image.

This method calculates the mean color of an image. ioImage must be a valid RED::IImage2D image. It’s local pixel storage will be overwritten by the operation unless iLocalStorage is set to true.

Please note that DXT based compressed formats are ignored by the method.

Parameters
  • oMinColor – The minimal color in the image (e.g. the lowest RGBA intensity pixel as defined by RED::Color::Intensity).

  • oMaxColor – The maximal color in the image (e.g. the highest RGBA luminance pixel as defined by RED::Color::Intensity).

  • oMeanColor – The average color in the image.

  • ioImage – Source image to read from. Must implement RED::IImage2D.

  • iLocalStorage – True to read from the image local storage, false to first retrieve image pixels on the CPU.

Returns

RED_OK on success,

RED_BAD_PARAM if ioImage is not valid or not of the expected kind,

Other RED_RCs can be returned by image function tools.

static RED_RC RegisterCustomLoadCallback(bool &oRegistered, const RED::String &iFileExtension, RED::IMAGE_TOOLS_LOAD_CALLBACK iCallback)

Registers a custom callback for image loading.

When calling RED::ImageTools::Load, if a callback has been registered for the file extension, it will be called instead of the regular Load method.

Registering a new loading callback allows to handle files formats that are not supported natively by REDsdk.

The iFileExtension doesn’t include the dot (e.g. “png” or “jpg”) and the comparison is case insensitive.

Parameters
  • oRegistered – Returned true if the callback has been registered, false if this extension was already registered.

  • iFileExtension – The file extension to register.

  • iCallback – The callback function to associate to the extension.

Returns

RED_OK on success,

RED_BAD_PARAM if iCallback is NULL,

RED_ALLOC_FAILURE if an internal allocation did fail.

static RED_RC UnregisterCustomLoadCallback(const RED::String &iFileExtension)

Unregisters a custom callback for image loading.

see RED::ImageTools::RegisterCustomLoadCallback for details about custom callback.

Parameters

iFileExtension – The file extension to unregister.

Returns

RED_OK on success.

static RED_RC ClearCustomLoadCallback()

Clears all the custom callback for image loading.

see RED::ImageTools::RegisterCustomLoadCallback for details about custom callback.

Returns

RED_OK on success.