class RED::ImageTools

Image saving and loading API. More...

#include <REDImageTools.h>

Inherits: Object.

Public static functions:

static RED_RCLoad ( RED::Object * oImage, RED::IStream & iInput, IMAGE_FILE_FORMAT iImageFormat, RED::FORMAT iPixelFormat, bool iVerticalFlip, bool iLocal, RED::TARGET iTarget, const RED::State & iState )
static RED_RCLoad ( RED::Object * oImage, const RED::String & iFilePath, RED::FORMAT iPixelFormat, bool iVerticalFlip, bool iLocal, RED::TARGET iTarget, const RED::State & iState )
static RED_RCSave ( RED::Object * iImage, bool iLocalStorage, RED::IStream & iOutput, IMAGE_FILE_FORMAT iImageFormat, bool iDiscardAlpha, bool iVerticalFlip, float iQuality )
static RED_RCSave ( RED::Object * iImage, bool iLocalStorage, const RED::String & iFilePath, bool iDiscardAlpha, bool iVerticalFlip, float iQuality )

Public enumerations:

enumIMAGE_FILE_FORMAT { IFF_JPEG =  0, IFF_PNG =  1, IFF_HDR =  2, IFF_TGA =  3, IFF_COUNT =  4 }

Detailed description:

Image saving and loading API.

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.

Functions documentation

public static RED_RC RED::ImageTools::Load(RED::Object *oImage,
RED::IStream &iInput,
IMAGE_FILE_FORMATiImageFormat,
RED::FORMATiPixelFormat,
booliVerticalFlip,
booliLocal,
RED::TARGETiTarget,
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.

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.

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_RGBAR, G, B, 1
JPEG/PNG/TGA - RGB RED::FMT_RGBR, G, B
JPEG/PNG/TGA - RGB RED::FMT_FLOAT( R + G + B ) / ( 3 * 255 )
JPEG/PNG/TGA - RGB RED::FMT_FLOAT_RGBAR / 255, G / 255, B / 255, 1
JPEG/PNG/TGA - RGB RED::FMT_FLOAT_RGBR / 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_DXT1fail
JPEG/PNG/TGA - RGB RED::FMT_RGBA_DXT3fail
JPEG/PNG/TGA - RGB RED::FMT_RGBA_DXT5fail
JPEG/PNG/TGA - RGB RED::FMT_RGB_DXT1fail
JPEG/PNG/TGA - RGB RED::FMT_HALF_FLOAT( R + G + B ) / ( 3 * 255 )
JPEG/PNG/TGA - RGB RED::FMT_HALF_FLOAT_RGBAR / 255, G / 255, B / 255, 1
JPEG/PNG/TGA - RGB RED::FMT_HALF_FLOAT_RGBR / 255, G / 255, B / 255
JPEG/PNG/TGA - RGB RED::FMT_FLOAT_RGBA_AAfail
PNG/TGA - RGBA RED::FMT_RGBAR, G, B, A
PNG/TGA - RGBA RED::FMT_RGBR, G, B
PNG/TGA - RGBA RED::FMT_FLOAT( R + G + B ) / ( 3 * 255 )
PNG/TGA - RGBA RED::FMT_FLOAT_RGBAR / 255, G / 255, B / 255, A / 255
PNG/TGA - RGBA RED::FMT_FLOAT_RGBR / 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_DXT1fail
PNG/TGA - RGBA RED::FMT_RGBA_DXT3fail
PNG/TGA - RGBA RED::FMT_RGBA_DXT5fail
PNG/TGA - RGBA RED::FMT_RGB_DXT1fail
PNG/TGA - RGBA RED::FMT_HALF_FLOAT( R + G + B ) / ( 3 * 255 )
PNG/TGA - RGBA RED::FMT_HALF_FLOAT_RGBAR / 255, G / 255, B / 255, A / 255
PNG/TGA - RGBA RED::FMT_HALF_FLOAT_RGBR / 255, G / 255, B / 255
PNG/TGA - RGBA RED::FMT_FLOAT_RGBA_AAfail
HDR - float RGB RED::FMT_RGBAR * 255, G * 255, B * 255, 255
HDR - float RGB RED::FMT_RGBR * 255, G * 255, B * 255
HDR - float RGB RED::FMT_FLOAT( R + G + B ) / 3
HDR - float RGB RED::FMT_FLOAT_RGBAR, G, B, 1
HDR - float RGB RED::FMT_FLOAT_RGBR, G, B
HDR - float RGB RED::FMT_L8255 * ( R + G + B ) / 3
HDR - float RGB RED::FMT_A8255 * ( R + G + B ) / 3
HDR - float RGB RED::FMT_RGBA_DXT1fail
HDR - float RGB RED::FMT_RGBA_DXT3fail
HDR - float RGB RED::FMT_RGBA_DXT5fail
HDR - float RGB RED::FMT_RGB_DXT1fail
HDR - float RGB RED::FMT_HALF_FLOAT( R + G + B ) / 3
HDR - float RGB RED::FMT_HALF_FLOAT_RGBAR, G, B, A
HDR - float RGB RED::FMT_HALF_FLOAT_RGBR, G, B
HDR - float RGB RED::FMT_FLOAT_RGBA_AAfail

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:

oImagepointer to the returned image. This image must have been properly created before the call (and must implement RED::IImage and RED::IImage2D interfaces).
iInputreference to the input stream.
iImageFormatimage file format.
iPixelFormatrequested pixel format for the returned image.
iVerticalFliptrue to flip the loaded image lines of pixels vertically, false to let it unchanged.
iLocaltrue 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.
iTargetthis 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.
iStatecurrent 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.
public static RED_RC RED::ImageTools::Load(RED::Object *oImage,
const RED::String &iFilePath,
RED::FORMATiPixelFormat,
booliVerticalFlip,
booliLocal,
RED::TARGETiTarget,
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.

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.

See also How to load and save image to file?.

Parameters:

oImagepointer to the returned image. This image must have been properly created before the call (and must implement RED::IImage and RED::IImage2D interfaces).
iFilePathfull path to the source file.
iPixelFormatrequested pixel format for the returned image.
iVerticalFliptrue to flip the loaded image lines of pixels vertically, false to let it unchanged.
iLocaltrue to load the image in the local (CPU memory) storage of the image, false to load it directly in the graphics card memory.
iTargetthis 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.
iStatecurrent 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.
public static RED_RC RED::ImageTools::Save(RED::Object *iImage,
booliLocalStorage,
RED::IStream &iOutput,
IMAGE_FILE_FORMATiImageFormat,
booliDiscardAlpha,
booliVerticalFlip,
floatiQuality
)

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_RGBAR, G, B, A R, G, B
RED::FMT_RGBR, 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_L8L8, L8, L8 L8, L8, L8
RED::FMT_A80, 0, 0, A8 0, 0, 0
RED::FMT_RGBA_DXT1fail fail
RED::FMT_RGBA_DXT3fail fail
RED::FMT_RGBA_DXT5fail fail
RED::FMT_RGB_DXT1fail 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]*255HFR, HFG, HFB
RED::FMT_HALF_FLOAT_RGB[HFR]*255, [HFG]*255, [HFB]*255 HFR, HFG, HFB
RED::FMT_FLOAT_RGBA_AApixels are converted to FMT_FLOAT_RGBA and then to the format given in that tablepixels 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 How to load and save image to file?.

Parameters:

iImagepointer to the image to save.
iLocalStoragetrue to save the content of the local storage of the image, false to get pixels back from video memory.
iOutputreference the destination stream.
iImageFormatimage file format.
iDiscardAlphatrue to discard the alpha component of the image, false otherwise. If the image has no alpha component, the flag has no effect.
iVerticalFliptrue to flip the saved image lines of pixels vertically, false to let it unchanged.
iQualityquality 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.
public static RED_RC RED::ImageTools::Save(RED::Object *iImage,
booliLocalStorage,
const RED::String &iFilePath,
booliDiscardAlpha,
booliVerticalFlip,
floatiQuality
)

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:

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.
iFilePathfull path to the destination file.
iDiscardAlphatrue to discard the alpha component of the image, false otherwise. If the image has no alpha component, the flag has no effect.
iVerticalFliptrue to flip the saved image lines of pixels vertically, false to let it unchanged.
iQualityquality 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.

Enumerations documentation

Lists all the supported image file formats.

Enumerator:

IFF_JPEG

Lossy compression in RED::FMT_RGB format.

IFF_PNG

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

IFF_HDR

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

IFF_TGA

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

IFF_COUNT