class RED::ImageTools

Clears all the custom callback for image loading.

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

Returns:

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:

Returns:

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: Converting PBR metallic data to the realistic material

REDsdk provides a helper function to convert data from a PBR metallic workflow into its realistic material.

Here is how to use it:

// Create the images.
RED::Object *diffuse, *reflection, *anisotropy, *ior;
RC_TEST( iresmgr->CreateImage2D( diffuse, iresmgr->GetState() ) );
RC_TEST( iresmgr->CreateImage2D( reflection, iresmgr->GetState() ) );
RC_TEST( iresmgr->CreateImage2D( anisotropy, iresmgr->GetState() ) );
RC_TEST( iresmgr->CreateImage2D( ior, iresmgr->GetState() ) );

RED::Object *albedo, *roughness, *metalness, *normal;
RC_TEST( iresmgr->CreateImage2D( albedo, iresmgr->GetState() ) );
RC_TEST( iresmgr->CreateImage2D( roughness, iresmgr->GetState() ) );
RC_TEST( iresmgr->CreateImage2D( metalness, iresmgr->GetState() ) );
RC_TEST( iresmgr->CreateImage2D( normal, iresmgr->GetState() ) );

// Load the images. Use the local storage.
RC_TEST( RED::ImageTools::Load( albedo, "albedo.png", RED::FMT_RGB, true, true, RED::TGT_TEX_2D, iresmgr->GetState() ) );
RC_TEST( RED::ImageTools::Load( roughness, "roughness.png", RED::FMT_FLOAT, true, true, RED::TGT_TEX_2D, iresmgr->GetState() ) );
RC_TEST( RED::ImageTools::Load( metalness, "metalness.png", RED::FMT_FLOAT, true, true, RED::TGT_TEX_2D, iresmgr->GetState() ) );
RC_TEST( RED::ImageTools::Load( normal, "normal.png", RED::FMT_RGB, true, true, RED::TGT_TEX_2D, iresmgr->GetState() ) );

// Convert metallic workflow images into realistic material data.
RC_TEST( RED::ImageTools::ConvertMetallicToRealisticMaterial( diffuse, 2048, 2048,        // Returned diffuse
                                                              reflection, 2048, 2048,     // Returned reflection
                                                              anisotropy, 2048, 2048,     // Returned anisotropy
                                                              ior, 2048, 2048,            // Returned IOR
                                                              NULL, 0,                    // No environment map.
                                                              albedo, RED::Color::WHITE,  // PBR Albedo
                                                              roughness, 1.f,             // PBR roughness
                                                              metalness, 1.f,             // PBR metallic
                                                              NULL, 1.f,                  // No PBR ambient occlusion
                                                              NULL, 0.5f, false,          // No alpha mask
                                                              NULL,                       // No environment texture
                                                              resmgr, iresmgr->GetState() ) );

// The convert function works in local storage, don't forget RED::IImage2D::SetPixels.
RC_TEST( diffuse->As< RED::IImage2D >()->SetPixels( RED::TGT_TEX_2D, iresmgr->GetState() ) );
RC_TEST( reflection->As< RED::IImage2D >()->SetPixels( RED::TGT_TEX_2D, iresmgr->GetState() ) );
RC_TEST( anisotropy->As< RED::IImage2D >()->SetPixels( RED::TGT_TEX_2D, iresmgr->GetState() ) );
RC_TEST( ior->As< RED::IImage2D >()->SetPixels( RED::TGT_TEX_2D, iresmgr->GetState() ) );
RC_TEST( normal->As< RED::IImage2D >()->SetPixels( RED::TGT_TEX_2D, iresmgr->GetState() ) );

// Use the textures in the realistic material: diffuse, reflection, anisotropy and normal.
// Use the returned IOR and set Fresnel on.
RC_TEST( imaterial->SetupRealisticMaterial(
  false,                                                                // Double sided
  true,                                                                 // Fresnel
  RED::Color::RED, diffuse, RED::Matrix::IDENTITY, RED::MCL_TEX0,       // Diffusion
  RED::Color::WHITE, reflection, RED::Matrix::IDENTITY, RED::MCL_TEX0,  // Reflection
  RED::Color::WHITE, FLT_MAX,                                           // Reflection fog
  false, false, NULL, RED::Matrix::IDENTITY,                            // Environment
  RED::Color::BLACK, NULL, RED::Matrix::IDENTITY, RED::MCL_TEX0,        // Transmission
  0.0f, NULL, RED::Matrix::IDENTITY, RED::MCL_TEX0,                     // Transmission glossiness
  1.0f, ior, RED::Matrix::IDENTITY, RED::MCL_TEX0,                      // IOR
  RED::Color::WHITE, 1.0f,                                              // Transmission scattering
  false, false,                                                         // Caustics
  RED::Color::BLACK, anisotropy, RED::Matrix::IDENTITY, RED::MCL_TEX0,  // Reflection anisotropy
  0.0f, NULL, RED::Matrix::IDENTITY, RED::MCL_TEX0,                     // Reflection anisotropy orientation
  normal, RED::Matrix::IDENTITY, RED::MCL_TEX0, RED::MCL_USER0,         // Bump
  0.0f, 0.0f, NULL, RED::Matrix::IDENTITY, RED::MCL_TEX0,               // Displacement
  NULL, &RED::LayerSet::ALL_LAYERS,                                     // Layersets
  resmgr, iresmgr->GetState() ) );                                      // Engine stuff

In this sample, neither AO texture nor environment texture are used. They can be set to NULL.

Parameters:

Returns:

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:

Returns:

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:

Returns:

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 How to load and save image to file?.

Parameters:

Returns:

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:

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 How to load and save image to file?.

Parameters:

Returns:

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:

Returns:

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:

Returns:

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 How to load and save image to file?.

Parameters:

Returns:

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:

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 How to load and save image to file?.

Parameters:

Returns:

Unregisters a custom callback for image loading.

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

Parameters:

Returns:

List of custom loading callbacks.

Lists all the supported image file formats.

Enumerator: