PostProcess

Functions

SET_CID

PostProcess

~PostProcess

PostProcess

RED_RC

operator=

bool

IsNeutral

bool

IsCurveNeutral

bool

IsColorOperationsNeutral

RED_RC

Reset

RED_RC

SetToneMapping

TONEMAPPING_OPERATOR

GetToneMapping

void

SetAutoKey

bool

IsAutoKey

RED_RC

SetKey

float

GetKey

RED_RC

SetExposure

float

GetExposure

RED_RC

SetBurnFactor

float

GetBurnFactor

RED_RC

SetGamma

float

GetGamma

RED_RC

SetCurve

RED_RC

GetCurve

RED_RC

ResetCurve

RED_RC

GetCurveRamp

RED_RC

SetWhiteReference

const Color &

GetWhiteReference

RED_RC

SetSharpen

float

GetSharpen

RED_RC

SetSharpenKernelSize

int

GetSharpenKernelSize

RED_RC

SetGlow

float

GetGlow

RED_RC

SetGlowThreshold

float

GetGlowThreshold

RED_RC

SetGlowKernelSize

int

GetGlowKernelSize

RED_RC

SetBlur

float

GetBlur

RED_RC

SetBlurKernelSize

int

GetBlurKernelSize

RED_RC

SetDOF

void

GetDOF

RED_RC

SetDOFKernelSize

int

GetDOFKernelSize

RED_RC

SetDepthLine

void

GetDepthLine

RED_RC

SetDepthLineWidth

float

GetDepthLineWidth

RED_RC

SetDepthLineColor

const Color &

GetDepthLineColor

RED_RC

SetBrightness

float

GetBrightness

RED_RC

SetContrast

float

GetContrast

RED_RC

SetLegacyBrightnessContrast

bool

HasLegacyBrightnessContrast

RED_RC

SetHSL

void

GetHSL

RED_RC

SetLevels

void

GetLevels

RED_RC

SetVignette

float

GetVignette

RED_RC

SetVignetteSize

float

GetVignetteSize

RED_RC

SetVignetteSmoothness

float

GetVignetteSmoothness

RED_RC

SetVignetteRoundness

float

GetVignetteRoundness

RED_RC

SetVignetteColor

const Color &

GetVignetteColor

RED_RC

SetLUT

void

GetLUT

RED_RC

LoadLUT

RED_RC

GetLUTImage

RED_RC

ProcessToneMapping

RED_RC

ProcessToneMappingAA

RED_RC

ProcessSharpen

RED_RC

ProcessGlowPass1

RED_RC

ProcessGlowPass2

RED_RC

ProcessGlowPass3

RED_RC

ProcessBlurPass1

RED_RC

ProcessBlurPass2

RED_RC

ProcessDOFPass1

RED_RC

ProcessDOFPass2

RED_RC

ProcessColorOperations

RED_RC

ProcessDepthLine

RED_RC

ProcessVignette

RED_RC

ProcessLUT

RED_RC

OverrideLuminance

void

GetLuminanceOverride

bool

IsLuminanceOverriden

void

ResetLuminanceOverride

void

GetLuminanceInformation

RED_RC

SetLuminanceInformation

Detailed Description

class PostProcess : public RED::Object

This class defines methods to setup and apply various post processing operations to images.

@related Post Processing, Tonemapping Explained, function RED::IViewpoint::GetPostProcessSettings, GI Cache and Tone Mapping for Panorama, Applying Tone Mapping on a Completed Image, Enabling Tone Mapping

Each viewpoint in REDsdk can have a PostProcess instance set on. This will turn on post processing of images rendered using those viewpoints. Post processing includes:

  • tone mapping,

  • color curve manipulation,

  • white balance,

  • sharpen filtering,

  • glow filtering,

  • gaussian blur filtering,

  • depth of field,

  • brightness, contrast adjustments,

  • HSL modifications,

  • levels adjustments,

  • gamma correction,

  • vignette.

When running in hardware or hybrid rendering modes, post processing operations are performed using the GPU and therefore have a lot smaller cost than when ran entirely in software.

There are several differences to consider on tonemapping the contents of a RED::IViewpointRenderList:

  • Tonemapping is applied once to all cameras of a VRL when rendered using RED::IWindow::FrameDrawing. Due to the nature of the GPU rendering pipeline with cameras rendered additively to compose the result, we don’t have the capability to tonemap individual cameras on the GPU. Therefore, the VRL is drawn and tonemapping is applied afterwards for the whole VRL, using the last of the viewpoint’s RED::PostProcess settings found which is not neutral.

  • Tonemapping is performed for each camera separately when rendered using RED::IWindow::FrameTracing. Each camera image is tonemapped, and cameras images are alpha blended together as for any CPU camera assembly. Note that the tonemapping can still be performed by the GPU for an immediate response in this configuration, for each camera.

Using RED::IViewpointRenderList::SetViewpointSoftImages acts as rendering with a RED::IWindow::FrameTracing call.

Calling RED::IViewpointRenderList::SetViewpointSoftMatrix if necessary when calling RED::IViewpointRenderList::SetViewpointSoftImages to use effects where depth is involved (DOF, Depth line).

The post process class is NOT managed by RED::State transactions. Therefore it should be manipulated only from the rendering thread. It can be changed anytime from that thread and from that thread only between two draws without having to open a transaction. This can be used to implement dynamic tonemapping loops that can be used to modify an image while it’s rendered or after the rendering has finished.

Public Functions

SET_CID (CID_class_REDPostProcess) IMPLEMENT_AS()
PostProcess(RED::Object *iResourceManager)

Constructor.

By default, values are set to:

  • tone mapping is RED::TMO_NEUTRAL

  • exposure is 1.0

  • gamma is 1.0

  • curve is identity (straight line)

  • white reference is (1.0,1.0,1.0)

  • auto key is on

  • sharpen is 0.0

  • glow is 0.0

  • blur is 0.0

  • DOF is 0.0

  • brightness and contrast are 0.0

  • hue, saturation and lightness are 0.0

  • levels black are 0.0 and white are 1.0.

Which leads to a neutral RED::PostProcess instance (see RED::PostProcess::IsNeutral).

Parameters

iResourceManager – Pointer to the cluster’s resource manager.

virtual ~PostProcess()

Destructor.

PostProcess(const PostProcess &iSource)

Copy constructor.

Parameters

iSource – Source for the copy.

RED_RC operator=(const RED::PostProcess &iOther)

Copy operator.

Parameters

iOther – reference to the object to copy from.

Returns

RED_OK if the operation has succedede,

RED_ALLOC_FAILURE if a memory allocation has failed.

bool IsNeutral() const

Returns true if the post process setup is neutral, false otherwise.

The post process operator is neutral if an input color is returned unchanged by a call to RED::PostProcess::Process, or by the equivalent GPU processing.

Returns

true if the post process setup is neutral, false otherwise.

bool IsCurveNeutral() const

Returns true if the curve is neutral.

The post process operator is neutral if an input color is returned unchanged by a call to RED::PostProcess::Process, or by the equivalent GPU processing.

Returns

true if the curve setup is neutral, false otherwise.

bool IsColorOperationsNeutral() const

Returns true if the color operations does not change the input color.

Color operations are:

  • brightness / contrast;

  • HSL modifications;

  • curve correction;

  • white balance;

  • levels;

  • gamma.

Returns

true if the curve setup is neutral, false otherwise.

RED_RC Reset()

Resets the post process object to its initial state.

In its initial state, a RED::PostProcess instance is neutral.

Returns

RED_OK if the operation has succeeded,

RED_ALLOC_FAILURE if an internal allocation has failed,

Any RED_DRV* if a GPU driver error has occurred.

RED_RC SetToneMapping(RED::TONEMAPPING_OPERATOR iToneMappingOperator)

Sets the tone mapping operator to be applied.

HDR images need to be processed in order to be displayed onto a screen. By default, REDsdk uses clamping (RED::TMO_CLAMP) to constrain colors to be in the displayable range. But this operator does not preserve local image properties (like contrast) and does not account for human visual system specificities.

This method lets you choose among available tone mapping operators the one that best fill your image reproduction requirements.

Here are some explanations about each mode:

  • RED::TMO_CLAMP: the default mode; simply clamps values outside from [0, 1].

  • RED::TMO_PHOTOGRAPHIC: always gives a correctly exposed image by default, but sometimes, at the price of un-natural amplifications of dark areas (the darkest areas of the image look over-exposed). The purpose of this method is to give good results in any situation.

  • RED::TMO_NEUTRAL: does nothing.

  • RED::TMO_EXPOSURE: multiply the input color by a single scalar value. The user has to set the value manually, either to something greater than one (to increase light exposition) or smaller than one (to reduce light exposition) to get the expected image.

  • RED::TMO_EXPONENTIAL: Applies a color correction based on the average luminance in an image.

Each mode may use some informations gathered from the image or not:

\task tk_enabling_tone_mapping

Parameters

iToneMappingOperator – The tone mapping operator to be applied to the image.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid input parameter,

RED_FAIL otherwise.

inline RED::TONEMAPPING_OPERATOR GetToneMapping() const

Gets the current tone mapping operator.

See RED::PostProcess::SetToneMapping method documentation for further details about tone mapping with REDsdk.

Returns

the current tone mapping operator.

inline void SetAutoKey(bool iAutoKey)

Enables or disables automatic calculation of the tonemapping key.

The key is the tonemapping factor used to rescale all intensities in the visible range. By default, the engine automatically sets the key based on the luminance measured in the image. If iAutoKey is set to false, the value of the key can be defined by RED::PostProcess::SetKey.

Parameters

iAutoKey – Set it to ‘true’ (default) to have the engine calculate the key based on the image luminance, set it to ‘false’ to manually specify the key value to use.

inline bool IsAutoKey() const

Retrieves the auto key flag.

Returns

The auto key setup for the tonemapper.

RED_RC SetKey(float iKey)

Defines the tonemapping key.

This method will have an effect only if the automatic key calculation is turned off using RED::PostProcess::SetAutoKey( false ). It lets the user specify the value of the key to use for the tonemapping.

The default key value is 1.0.

Parameters

iKey – The new key value.

Returns

RED_OK if the method has succeeded,

RED_BAD_PARAM if the method has received an invalid parameter.

inline float GetKey() const

Retrieves the tonemapping key.

Returns

The value of the tonemapping key used if the automatic key calculation is turned off.

RED_RC SetExposure(float iExposure)

Sets the exposure scaling factor to be applied to the processed image.

The exposure is a multiplicative term applied to the colors of processed image during tone mapping. Hence, tone mapping needs to be turned on for the exposure to be taken into account.

Increase the exposure to light up your tone mapped image, or decrease it if you want to make it darker.

Parameters

iExposure – exposure in [0, +inf[ (default is 1.0).

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid input parameter,

RED_FAIL otherwise.

inline float GetExposure() const

Returns the exposure scaling factor.

See RED::PostProcess::SetExposure for details.

Returns

the exposure scaling factor.

RED_RC SetBurnFactor(float iBurn)

Sets the percentage of burning in the tone-mapped images.

In a tone-mapped image, pixel luminances have been transformed to the unit interval [0, 1] making feasible to best display it on any device. The pixels having the biggest luminance (Lmax) in the source image are mapped to pixels having luminance = 1 in the tone mapped image.

However, sometimes it is desirable to reproduce some kind of burning into the tone-mapped image. It’s a way to reflect how some sensors can saturate (e.g the eye) under too bright light. This is the purpose of the burn factor which expresses how much of the range between [0, Lmax] will burn into the tone-mapped image.

It works as follows: pixels having their luminance in the [(1 - burn_factor) * Lmax, Lmax] range will be mapped to luminance = 1. Hence, when the burn factor is 0 (the default), only pixels with luminance = Lmax will be tone-mapped to 1. But if you increase the burn factor, pixels with less luminance will also be tone mapped to 1 (increasing the image burning effect).

The burn factor only applies to the RED::TMO_PHOTOGRAPHIC tonemapping mode.

Parameters

iBurn – burn factor in [0, 1] (default is 0).

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid input parameter,

RED_FAIL otherwise.

inline float GetBurnFactor() const

Gets the percentage of burning in the tone-mapped images.

See RED::PostProcess::SetBurnFactor for details.

Returns

the percentage of burning in the tone-mapped images.

RED_RC SetGamma(float iGamma)

Sets the gamma value for image gamma correction.

Due to the non-linear response of the monitors, gamma correction may need to be applied to image prior to displaying them onto the screen.

Gamma correction is applied as follows:

output_color = input_color ^ (1.0 / gamma)

Parameters

iGamma – amount of correction to be applied to input colors (should be in the [0, inf[ range).

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid input parameter,

RED_FAIL otherwise.

inline float GetGamma() const

Gets the current value for gamma correction.

See RED::PostProcess::SetGamma for details.

Returns

the amount of gamma correction to be applied to input colors

RED_RC SetCurve(const RED::Vector<float> &iX, const RED::Vector<float> &iValue)

Sets the curve to be applied to image colors.

A curve can be defined which transforms input intensity. This is a common and easy way to apply intensity corrections to a whole image. For example, a S-curve is efficient to increase image contrast by lowering low intensity values and boosting high ones.

The curve is set by passing curve samples. Each sample is made of its position along the x-axis as well as the curve value at that position. Both iX and iValue vector should be of equal size. No more than 65535 samples can be provided.

The curve is built back from the samples using Lagrange polynomials for interpolation.

To reset the curve to a neutral curve (a straight line), simply call the SetCurve method passing (0,0) and (1,1) as curve samples or call RED::PostProcess::ResetCurve.

Parameters
  • iX – position of the value along the x-axis of the curve.

  • iValue – value of the curve at the corresponding x coordinate.

Returns

RED_OK on success,

RED_BAD_PARAM if there are less than two curve positions in iX and iValue or if numerical values are incorrect,

RED_FAIL otherwise.

RED_RC GetCurve(RED::Vector<float> &oX, RED::Vector<float> &oValue)

Gets the curve to be applied to image colors.

See RED::PostProcess::SetCurve for details.

Parameters
  • oX – reference to the returned list of curve sample x coordinates.

  • oValue – reference to the returned list of curve sample values.

Returns

RED_OK on success,

RED_ALLOC_FAILURE on a memory allocation error,

RED_BAD_PARAM on an invalid input parameter,

RED_FAIL otherwise.

RED_RC ResetCurve()

Resets the curve to be applied to image colors.

Returns

RED_OK on success,

RED_ALLOC_FAILURE if a memory allocation fails,

Any RED_DRV* GPU driver error code in case of error.

RED_RC GetCurveRamp(RED::Object *&oRamp)

Gets the curve ramp texture.

Parameters

oRamp – A pointer to the curve ramp texture.

Returns

RED_OK if the method has succeeded,

RED_ALLOC_FAILURE if a memory allocation has failed,

Any RED_DRV* error code if an error is returned by the GPU driver.

RED_RC SetWhiteReference(const RED::Color &iWhite)

Sets the white color to be used as reference when applying white balance.

Color balance is needed to compensate for un-natural looking of images rendered under some conditions. For example, an indoor scene by night lit only by artificial light sources may look too yellow. At the opposite, an outdoor scene may look too much blue.

A kind of auto white balance (as provided by consumer cameras) can be achieved by passing the average image color to SetWhiteReference.

If not, the input color components are clamped to the [0,1] interval.

Parameters

iWhite – white reference.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid input parameter,

RED_FAIL otherwise.

inline const RED::Color &GetWhiteReference() const

Gets the current white reference value.

See RED::PostProcess::SetWhiteReference for details.

Returns

the white color to be used as reference when applying white balance.

RED_RC SetSharpen(float iSharpen)

Sets the sharpen intensity.

Sharpen is a post process enhancing the definition of edges in the image.

The sharpen filter kernel size can be changed using RED::PostProcess::SetSharpenKernelSize.

Parameters

iSharpen – sharpen intensity between 0 and 1.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid input parameter,

RED_FAIL otherwise.

inline float GetSharpen() const

Gets the current sharpening value.

See RED::PostProcess::SetSharpen for details.

Returns

the sharpen intensity.

RED_RC SetSharpenKernelSize(int iSize)

Sets the size of the kernel used during the sharpen operation.

Parameters

iSize – size of the kernel used during the sharpen operation.

Returns

RED_OK if the method has succeeded,

RED_BAD_PARAM if iSize is lower than 3 or higher than 10000.

inline int GetSharpenKernelSize() const

Gets the size of the kernel used during the sharpen operation.

Returns

The size of the kernel used during the sharpen operation.

RED_RC SetGlow(float iGlow)

Sets the glow intensity.

Glow is a post process increasing the white areas intensity in the image.

The glow filter kernel size can be changed using RED::PostProcess::SetGlowKernelSize.

Parameters

iGlow – glow intensity between 0 and 1.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid input parameter,

RED_FAIL otherwise.

inline float GetGlow() const

Gets the current glow value.

See RED::PostProcess::SetGlow for details.

Returns

the glow intensity.

RED_RC SetGlowThreshold(float iThreshold)

Sets the glow threshold.

See RED::PostProcess::SetGlow for details.

The glow threshold defines the luminance over which a pixel is enhanced.

Parameters

iThreshold – glow threshold between 0 and 1.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid input parameter,

RED_FAIL otherwise.

inline float GetGlowThreshold() const

Gets the current glow threshold.

See RED::PostProcess::SetGlowThreshold for details.

Returns

the glow threshold.

RED_RC SetGlowKernelSize(int iSize)

Sets the size of the kernel used during the glow operation.

Parameters

iSize – size of the kernel used during the glow operation.

Returns

RED_OK if the method has succeeded,

RED_BAD_PARAM if iSize is lower than 3 or higher than 10000.

inline int GetGlowKernelSize() const

Gets the size of the kernel used during the glow operation.

Returns

The size of the kernel used during the glow operation.

RED_RC SetBlur(float iBlur)

Sets the blur intensity.

This function applies a gaussian blur filter on the final image.

The blur filter kernel size can be changed using RED::PostProcess::SetBlurKernelSize.

Parameters

iBlur – blur intensity between 0 and 1.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid input parameter,

RED_FAIL otherwise.

inline float GetBlur() const

Gets the current blur values.

See RED::PostProcess::SetBlur for details.

Returns

the blur intensity.

RED_RC SetBlurKernelSize(int iSize)

Sets the size of the kernel used during the blur operation.

Parameters

iSize – size of the kernel used during the blur operation.

Returns

RED_OK if the method has succeeded,

RED_BAD_PARAM if iSize is lower than 3 or higher than 10000.

inline int GetBlurKernelSize() const

Gets the size of the kernel used during the blur operation.

Returns

The size of the kernel used during the blur operation.

RED_RC SetDOF(float iDOF, float iNearMin, float iNearMax, float iFarMin, float iFarMax)

Sets the DOF effect.

Depth Of Field is a post effect giving focus on a given distance and blurring the near and far regions, simulating the properties of real camera lenses.

The DOF filter kernel size can be changed using RED::PostProcess::SetDOFKernelSize.

iNearMin and iNearMax parameters defines the out-of-focus near-camera region whereas iFarMin and iFarMax parameters defines the out-of-focus far-camera region.

../build/doxygen/RED/xml/API_DOF.png

All the parameters values should be between near and far viewpoint distances. see RED::IViewpoint::SetNearFar.

Parameters
  • iDOF – DOF intensity between 0 and 1.

  • iNearMin – distance from the camera where sharpness starts to increase.

  • iNearMax – distance from the camera where sharpness is maximum.

  • iFarMin – distance from the camera where sharpness starts to decrease.

  • iFarMax – distance from the camera where sharpness is minimum.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid input parameter,

RED_FAIL otherwise.

inline void GetDOF(float &oDOF, float &oNearMin, float &oNearMax, float &oFarMin, float &oFarMax) const

Gets the current DOF values.

See RED::PostProcess::SetDOF for details.

Parameters
  • oDOF – returned DOF intensity between 0 and 1.

  • oNearMin – distance from the camera where sharpness starts to increase.

  • oNearMax – distance from the camera where sharpness is maximum.

  • oFarMin – distance from the camera where sharpness starts to decrease.

  • oFarMax – distance from the camera where sharpness is minimum.

RED_RC SetDOFKernelSize(int iSize)

Sets the size of the kernel used during the DOF operation.

Parameters

iSize – size of the kernel used during the DOF operation.

Returns

RED_OK if the method has succeeded,

RED_BAD_PARAM if iSize is lower than 3 or higher than 10000.

inline int GetDOFKernelSize() const

Gets the size of the kernel used during the DOF operation.

Returns

The size of the kernel used during the DOF operation.

RED_RC SetDepthLine(float iIntensity, float iDepth)

Sets the depth line effect intensity and depth.

This effect highlights a given depth value from the viewpoint. It is mostly use as a debug tool to visualize the depth values of a scene.

The highlight size and color can be set using RED::PostProcess::SetDepthLineWidth and RED::PostProcess::SetDepthLineColor.

Parameters
  • iIntensity – intensity of the post process between 0 and 1.

  • iDepth – depth at which the line is displayed.

Returns

RED_OK if the method has succeeded,

RED_BAD_PARAM if iSize is lower than 3 or higher than 10000.

inline void GetDepthLine(float &oIntensity, float &oDepth) const

Gets the intensity and depth of the depth line effect.

Parameters
  • oIntensity – returned intensity of the effect between 0 and 1.

  • oDepth – returned depth of the effect in scene unit.

RED_RC SetDepthLineWidth(float iWidth)

Sets the width of the depth line effect.

Parameters

iWidth – width of the line effect in scene unit.

Returns

RED_OK if the method has succeeded,

RED_BAD_PARAM if iSize is lower than 3 or higher than 10000.

inline float GetDepthLineWidth() const

Gets the width of the depth line effect.

Returns

the width of the line in scene unit.

RED_RC SetDepthLineColor(const RED::Color &iColor)

Sets the color of the depth line effect.

Parameters

iColor – color of the line effect.

Returns

RED_OK if the method has succeeded,

RED_BAD_PARAM if iSize is lower than 3 or higher than 10000.

inline const RED::Color &GetDepthLineColor() const

Gets the color of the depth line effect.

Returns

the color of the line effect.

RED_RC SetBrightness(float iBrightness)

Sets the image brightness.

This post effect allows to increase (iBrightness > 0) or decrease (iBrightness < 0) the image brightness.

Parameters

iBrightness – brightness value between -1 and 1.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid input parameter,

RED_FAIL otherwise.

inline float GetBrightness() const

Gets the current image brightness modifier value.

See RED::PostProcess::SetBrightness for details.

Returns

the brightness modification value.

RED_RC SetContrast(float iContrast)

Sets the image contrast.

This post effect allows to increase (iContrast > 0) or decrease (iContrast < 0) the image contrast.

Parameters

iContrast – contrast value between -1 and 1.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid input parameter,

RED_FAIL otherwise.

inline float GetContrast() const

Gets the current image contrast modifier value.

See RED::PostProcess::SetContrast for details.

Returns

the contrast modification value.

RED_RC SetLegacyBrightnessContrast(bool iLegacy = true)

Specifies if brightness and contrast calculations use legacy formulas.

Parameters

iLegacy – do we use legacy formulas?

Returns

RED_OK on success,

RED_FAIL otherwise.

inline bool HasLegacyBrightnessContrast() const

Do the brightness and contrast calculations use legacy formulas?

Returns

true if we use the legacy formulas, false otherwise.

RED_RC SetHSL(float iHue, float iSaturation, float iLightness)

Modifies the HSL values of the image.

HSL is an alternative color space to RGB. It is a cylindrical-coordinate representation of color points.

../build/doxygen/RED/xml/API_HSL.png

This post effect allows to modify the Hue, Saturation and Lightness values of the image.

Parameters
  • iHue – Hue value between -1 and 1.

  • iSaturation – Saturation value between -1 and 1.

  • iLightness – Lightness value between -1 and 1.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid input parameter,

RED_FAIL otherwise.

inline void GetHSL(float &oHue, float &oSaturation, float &oLightness) const

Gets the current HSL effect value.

See RED::PostProcess::SetHSL for details.

Parameters
  • oHue – Returned hue value.

  • oSaturation – Returned saturation value.

  • oLightness – Returned lightness value.

RED_RC SetLevels(float iInputBlack, float iInputWhite, float iOutputBlack, float iOutputWhite)

Modifies the image intensity levels.

Intensity levels allows to adjust the tonal range and color balance of the image.

Input black and white parameters remap the image intensities between these two boundaries. It clamps the values outside of the range and stretch the histogram inside of the range. Default values are 0 for black and 1 for white.

Output black and white parameters remap the input range between these two boundaries. By moving output black toward 1, the black parts of the final image will become greyish. Inverting output black and white values will result in a full color inversion. Default values are 0 for black and 1 for white.

../build/doxygen/RED/xml/API_Levels.png

Note

Input black parameter cannot be greater than input white parameter.

Parameters
  • iInputBlack – Input black value between 0 and 1.

  • iInputWhite – Input white value between 0 and 1.

  • iOutputBlack – Output black value between 0 and 1.

  • iOutputWhite – Output white value between 0 and 1.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid input parameter,

RED_FAIL otherwise.

inline void GetLevels(float &oInputBlack, float &oInputWhite, float &oOutputBlack, float &oOutputWhite) const

Gets the current greyscale levels parameters of the image.

See RED::PostProcess::SetLevels for details.

Parameters
  • oInputBlack – Returned input black value.

  • oInputWhite – Returned input white value.

  • oOutputBlack – Returned output black value.

  • oOutputWhite – Returned output white value.

RED_RC SetVignette(float iIntensity)

Sets a vignette around the image.

../build/doxygen/RED/xml/API_vignette.jpg

Multiple parameters are available:

Parameters

iIntensity – Intensity of the vignette effect between 0 and 1.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid input parameter,

RED_FAIL otherwise.

inline float GetVignette() const

Gets vignette effect intensity.

See RED::PostProcess::SetVignette for details.

Returns

the effect intensity between 0 and 1.

RED_RC SetVignetteSize(float iSize)

Sets the size of the vignette effect.

The vignette size iSize is between 0 and 1 from no vignette to a full screen vignette.

Parameters

iSize – Size of the effect between 0 and 1.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid input parameter,

RED_FAIL otherwise.

inline float GetVignetteSize() const

Gets the vignette effect size.

See RED::PostProcess::SetVignetteSize for details.

Returns

the effect size between 0 and 1.

RED_RC SetVignetteSmoothness(float iSmoothness)

Sets the smoothness of the vignette effect.

The vignette smoothness iSmoothness is between 0 and 1 from hard edge to full screen fade.

Parameters

iSmoothness – Smoothness of the effect between 0 and 1.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid input parameter,

RED_FAIL otherwise.

inline float GetVignetteSmoothness() const

Gets the vignette effect smoothness.

See RED::PostProcess::SetVignetteSmoothness for details.

Returns

the effect smoothness between 0 and 1.

RED_RC SetVignetteRoundness(float iRoundness)

Sets the roundness of the vignette effect.

Parameters

iRoundness – Roundness of the effect between 0 and 1.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid input parameter,

RED_FAIL otherwise.

inline float GetVignetteRoundness() const

Gets the vignette effect roundness.

See RED::PostProcess::SetVignetteRoundness for details.

Returns

the effect roundness between 0 and 1.

RED_RC SetVignetteColor(const RED::Color &iColor)

Sets the color of the vignette effect.

Parameters

iColorColor of the vignette.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid input parameter,

RED_FAIL otherwise.

inline const RED::Color &GetVignetteColor() const

Gets the vignette effect color.

See RED::PostProcess::SetVignetteColor for details.

Returns

the effect color.

RED_RC SetLUT(const RED::Vector<unsigned char> &iTable, unsigned int iSize)

Sets a 3D color look up table.

3D LUTs is a table of values that apply a color transform to an image.

The array iTable must be of size iSize^3 * 4. It stores Red, Green and Blue values (with Alpha = 255) for a cube of size iSize.

Red, green and blue goes from 0 to 255 along the first, second and third coordinates of the cube. Alpha is 255 everywhere and is not used during the sampling.

N being the size of the color cube, the memory index is r + N * g + N * N * b where r, g, b are the red, green and blue indices in the range 0 to N-1.

../build/doxygen/RED/xml/API_LUTCube.png

The LUT can be removed by calling this method with an empty table iTable and a size iSize of 0.

Parameters
  • iTable – Array of color values.

  • iSize – Size of the cube.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid input parameter,

RED_FAIL otherwise.

inline void GetLUT(RED::Vector<unsigned char> &oTable, unsigned int &oSize) const

Gets the current look up table.

See RED::PostProcess::SetLUT for details.

Parameters
  • oTable – Returned array of color values.

  • oSize – Returned size of the cube.

RED_RC LoadLUT(const RED::String &iFilePath)

Loads a color look up table from a file.

See RED::PostProcess::SetLUT for details.

The method loads a .cube file and sets the color LUT to the RED::PostProcess.

The 3D table is a cube. Its size is the same in all dimensions.

Parameters

iFilePath – Full path to the source file.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid input parameter,

RED_FILE_DATA_ERROR if the file can’t be loaded properly,

RED_FAIL otherwise.

RED_RC GetLUTImage(RED::Object *&oImage3D)

Gets the default look up table as a RED::IImage3D.

See RED::PostProcess::SetLUT for details.

Parameters

oImage3D – Pointer to the returned image. This image is created internally and therefore is owned by the RED::PostProcess class.

Returns

RED_OK on success,

RED_FAIL otherwise.

RED_RC ProcessToneMapping(float oColor[4], const float iColor[4], float iAverageLuminance, float iLogAverageLuminance, float iMinLuminance, float iMaxLuminance)

Processes a given color using the current tone mapping setup.

The input color must be in RED::FMT_FLOAT_RGBA format. The alpha component will be copied unchanged in the output color.

It’s safe to have both oColor and iColor memory addresses equal. The output color has its components clamped between 0.0 and 1.0.

The processing is performed entirely by the CPU and should be preferred for off-line or init time processing of data.

To process high quality pixels encored in RED::FMT_FLOAT_RGBA_AA format, please use the RED::PostProcess::ProcessToneMappingAA method instead.

Parameters
  • oColor – processed color.

  • iColor – input color to be processed.

  • iAverageLuminance – average luminance of all the pixels to be processed.

  • iLogAverageLuminance – log-average luminance of all the pixels to be processed.

  • iMinLuminance – minimum luminance amongst all the pixels to be processed.

  • iMaxLuminance – maximum luminance amongst all the pixels to be processed.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid input parameter,

RED_FAIL otherwise.

RED_RC ProcessToneMappingAA(float oColor[4], const double iColor[4], float iAverageLuminance, float iLogAverageLuminance, float iMinLuminance, float iMaxLuminance, bool iIgnoreBackground)

Processes a given color using the current tone mapping setup.

The input color must be in RED::FMT_FLOAT_RGBA_AA format. The source pixel information in iColor is decoded, processed and the results are written to oColor. The resulting color is in simple floating point format (e.g. RED::FMT_FLOAT_RGBA).

The RED::FMT_FLOAT_RGBA_AA color stores several informations, including the contribution of the background color to the result. It’s possible to apply the processing to this background color contribution or not, depending on the value of iBackgroundProcess.

To process a non anti-aliased color source, please use RED::PostProcess::Process instead of this method.

Parameters
  • oColor – Resulting color after processing.

  • iColor – input RED::FMT_FLOAT_RGBA_AA color to be processed.

  • iAverageLuminance – average luminance of all the pixels to be processed.

  • iLogAverageLuminance – log-average luminance of all the pixels to be processed.

  • iMinLuminance – minimum luminance amongst all the pixels to be processed.

  • iMaxLuminance – maximum luminance amongst all the pixels to be processed.

  • iIgnoreBackground – Do we apply the processing the to the background part of iColor? if ‘true’, the background part of the source color is not processed.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid input parameter,

RED_FAIL otherwise.

RED_RC ProcessSharpen(float oColor[4], const float *iColorBuffer, int iWidth, int iHeight, int iIndexX, int iIndexY)

Processes a given color from a color buffer using the current sharpen value.

see RED::PostProcess::SetSharpen for details about the sharpen tool.

The color buffer must be in RED::FMT_FLOAT_RGBA format. The alpha component will be copied unchanged in the output color.

The oColor adress cannot be in the iColorBuffer buffer since a call to this function must be done for each pixel of the same source buffer in order to correctly sharpen the entire image.

The processing is performed entirely by the CPU and should be preferred for off-line or init time processing of data.

Parameters
  • oColor – processed color.

  • iColorBuffer – input color buffer.

  • iWidth – width of the input color buffer.

  • iHeight – height of the input color buffer.

  • iIndexX – horizontal index of the current pixel in the input color buffer.

  • iIndexY – vertical index of the current pixel in the input color buffer.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid input parameter,

RED_FAIL otherwise.

RED_RC ProcessGlowPass1(float oColor[4], const float *iColorBuffer, int iWidth, int iHeight, int iIndexX, int iIndexY)

Processes a given color from a color buffer using the current glow value. First Pass.

see RED::PostProcess::SetGlow for details about the glow tool.

The color buffer must be in RED::FMT_FLOAT_RGBA format. The alpha component will be copied unchanged in the output color.

The oColor adress cannot be in the iColorBuffer buffer since a call to this function must be done for each pixel of the same source buffer in order to correctly apply glow to the entire image.

The processing is performed entirely by the CPU and should be preferred for off-line or init time processing of data.

The glow process is separated into three passes. Methods must be called in this order:

Parameters
  • oColor – processed color.

  • iColorBuffer – input color buffer.

  • iWidth – width of the input color buffer.

  • iHeight – height of the input color buffer.

  • iIndexX – horizontal index of the current pixel in the input color buffer.

  • iIndexY – vertical index of the current pixel in the input color buffer.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid input parameter,

RED_FAIL otherwise.

RED_RC ProcessGlowPass2(float oColor[4], const float *iColorBuffer, const float *iPass1Buffer, int iWidth, int iHeight, int iIndexX, int iIndexY)

Processes a given color from a color buffer using the current glow value. Second Pass.

see RED::PostProcess::SetGlow for details about the glow tool.

The color buffer must be in RED::FMT_FLOAT_RGBA format. The alpha component will be copied unchanged in the output color.

The oColor adress cannot be in the iColorBuffer buffer since a call to this function must be done for each pixel of the same source buffer in order to correctly apply glow to the entire image.

The processing is performed entirely by the CPU and should be preferred for off-line or init time processing of data.

The glow process is separated into three passes. Methods must be called in this order:

Parameters
  • oColor – processed color.

  • iColorBuffer – input color buffer.

  • iPass1Buffer – result buffer after calling RED::PostProcess::ProcessGlowPass1.

  • iWidth – width of the input color buffer.

  • iHeight – height of the input color buffer.

  • iIndexX – horizontal index of the current pixel in the input color buffer.

  • iIndexY – vertical index of the current pixel in the input color buffer.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid input parameter,

RED_FAIL otherwise.

RED_RC ProcessGlowPass3(float oColor[4], const float *iColorBuffer, const float *iPass2Buffer, int iWidth, int iHeight, int iIndexX, int iIndexY)

Processes a given color from a color buffer using the current glow value. Third Pass.

see RED::PostProcess::SetGlow for details about the glow tool.

The color buffer must be in RED::FMT_FLOAT_RGBA format. The alpha component will be copied unchanged in the output color.

The oColor adress cannot be in the iColorBuffer buffer since a call to this function must be done for each pixel of the same source buffer in order to correctly apply glow to the entire image.

The processing is performed entirely by the CPU and should be preferred for off-line or init time processing of data.

The glow process is separated into three passes. Methods must be called in this order:

Parameters
  • oColor – processed color.

  • iColorBuffer – input color buffer.

  • iPass2Buffer – result buffer after calling RED::PostProcess::ProcessGlowPass2.

  • iWidth – width of the input color buffer.

  • iHeight – height of the input color buffer.

  • iIndexX – horizontal index of the current pixel in the input color buffer.

  • iIndexY – vertical index of the current pixel in the input color buffer.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid input parameter,

RED_FAIL otherwise.

RED_RC ProcessBlurPass1(float oColor[4], const float *iColorBuffer, int iWidth, int iHeight, int iIndexX, int iIndexY)

Processes a given color from a color buffer using the current blur value. First Pass.

see RED::PostProcess::SetBlur for details about blur.

The color buffer must be in RED::FMT_FLOAT_RGBA format. The alpha component will be copied unchanged in the output color.

The oColor adress cannot be in the iColorBuffer buffer since a call to this function must be done for each pixel of the same source buffer in order to correctly blur the entire image.

The processing is performed entirely by the CPU and should be preferred for off-line or init time processing of data.

The blur process is separated into two passes. Methods must be called in this order:

Parameters
  • oColor – processed color.

  • iColorBuffer – input color buffer.

  • iWidth – width of the input color buffer.

  • iHeight – height of the input color buffer.

  • iIndexX – horizontal index of the current pixel in the input color buffer.

  • iIndexY – vertical index of the current pixel in the input color buffer.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid input parameter,

RED_FAIL otherwise.

RED_RC ProcessBlurPass2(float oColor[4], const float *iColorBuffer, const float *iPass1Buffer, int iWidth, int iHeight, int iIndexX, int iIndexY)

Processes a given color from a color buffer using the current blur value. Second Pass.

see RED::PostProcess::SetBlur for details about blur.

The color buffer must be in RED::FMT_FLOAT_RGBA format. The alpha component will be copied unchanged in the output color.

The oColor adress cannot be in the iColorBuffer buffer since a call to this function must be done for each pixel of the same source buffer in order to correctly blur the entire image.

The processing is performed entirely by the CPU and should be preferred for off-line or init time processing of data.

The blur process is separated into two passes. Methods must be called in this order:

Parameters
  • oColor – processed color.

  • iColorBuffer – input color buffer.

  • iPass1Buffer – result buffer after calling RED::PostProcess::ProcessBlurPass1.

  • iWidth – width of the input color buffer.

  • iHeight – height of the input color buffer.

  • iIndexX – horizontal index of the current pixel in the input color buffer.

  • iIndexY – vertical index of the current pixel in the input color buffer.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid input parameter,

RED_FAIL otherwise.

RED_RC ProcessDOFPass1(float oColor[4], const float *iColorBuffer, int iWidth, int iHeight, int iIndexX, int iIndexY)

Processes a given color from a color buffer using the current DOF value. First pass.

see RED::PostProcess::SetDOF for details about DOF.

The color buffer must be in RED::FMT_FLOAT_RGBA format. The alpha component will be copied unchanged in the output color.

The oColor adress cannot be in the iColorBuffer buffer since a call to this function must be done for each pixel of the same source buffer in order to correctly apply DOF to the entire image.

The processing is performed entirely by the CPU and should be preferred for off-line or init time processing of data.

The DOF process is separated into two passes. Methods must be called in this order:

Parameters
  • oColor – processed color.

  • iColorBuffer – input color buffer.

  • iWidth – width of the input color buffer.

  • iHeight – height of the input color buffer.

  • iIndexX – horizontal index of the current pixel in the input color buffer.

  • iIndexY – vertical index of the current pixel in the input color buffer.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid input parameter,

RED_FAIL otherwise.

RED_RC ProcessDOFPass2(float oColor[4], const float *iColorBuffer, const float *iPass1Buffer, int iWidth, int iHeight, int iIndexX, int iIndexY, float iDepth)

Processes a given color from a color buffer using the current DOF value. Second pass.

see RED::PostProcess::SetDOF for details about DOF.

The color buffer must be in RED::FMT_FLOAT_RGBA format. The alpha component will be copied unchanged in the output color.

The oColor adress cannot be in the iColorBuffer buffer since a call to this function must be done for each pixel of the same source buffer in order to correctly apply DOF to the entire image.

The processing is performed entirely by the CPU and should be preferred for off-line or init time processing of data.

Parameters
  • oColor – processed color.

  • iColorBuffer – input color buffer.

  • iPass1Buffer – result buffer after calling RED::PostProcess::ProcessDOFPass1.

  • iWidth – width of the input color buffer.

  • iHeight – height of the input color buffer.

  • iIndexX – horizontal index of the current pixel in the input color buffer.

  • iIndexY – vertical index of the current pixel in the input color buffer.

  • iDepth – depth value for the current pixel.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid input parameter,

RED_FAIL otherwise.

RED_RC ProcessColorOperations(float oColor[4], const float iColor[4])

Processes a given color from a color buffer using the current color operations value.

The color operations are (executed in this order):

  • Brightness / contrast;

  • HSL;

  • Curve correction;

  • White balance;

  • Levels and gamma.

The color buffer must be in RED::FMT_FLOAT_RGBA format. The alpha component will be copied unchanged in the output color.

The processing is performed entirely by the CPU and should be preferred for off-line or init time processing of data.

Parameters
  • oColor – processed color.

  • iColor – input color.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid input parameter,

RED_FAIL otherwise.

RED_RC ProcessDepthLine(float oColor[4], const float iColor[4], float iDepth)

Processes a given color from a color buffer using the depth line effect parameters.

The color buffer must be in RED::FMT_FLOAT_RGBA format. The alpha component will be copied unchanged in the output color.

The processing is performed entirely by the CPU and should be preferred for off-line or init time processing of data.

Parameters
  • oColor – processed color.

  • iColor – color of the current pixel.

  • iDepth – depth value for the current pixel.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid input parameter,

RED_FAIL otherwise.

RED_RC ProcessVignette(float oColor[4], const float iColor[4], int iWidth, int iHeight, int iIndexX, int iIndexY)

Processes a given color from a color buffer using the current vignette effect value.

see RED::PostProcess::SetVignette for details about vignette effect.

The color buffer must be in RED::FMT_FLOAT_RGBA format. The alpha component will be copied unchanged in the output color.

The processing is performed entirely by the CPU and should be preferred for off-line or init time processing of data.

Parameters
  • oColor – processed color.

  • iColor – input color.

  • iWidth – width of the input color buffer.

  • iHeight – height of the input color buffer.

  • iIndexX – horizontal index of the current pixel in the input color buffer.

  • iIndexY – vertical index of the current pixel in the input color buffer.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid input parameter,

RED_FAIL otherwise.

RED_RC ProcessLUT(float oColor[4], const float iColor[4])

Processes a given color from a color buffer using the current LUT.

see RED::PostProcess::SetLUT for details about LUT.

The color buffer must be in RED::FMT_FLOAT_RGBA format. The alpha component will be copied unchanged in the output color.

The processing is performed entirely by the CPU and should be preferred for off-line or init time processing of data.

Parameters
  • oColor – processed color.

  • iColor – input color.

Returns

RED_OK on success,

RED_BAD_PARAM on an invalid input parameter,

RED_FAIL otherwise.

RED_RC OverrideLuminance(float iAverageLuminance, float iLogAverageLuminance, unsigned int iSamplesCount, float iMinLuminance, float iMaxLuminance)

Overrides the luminance parameters of tonemapped images.

This method can be used to externally control the luminance of the tonemapped images. The default REDsdk behavior stores luminance informations on the color image being processed. Then, these luminance parameters are used by the tonemapper to process the image.

Using this method, luminance values are overriden, and image luminance parameters are ignored.

Refer to RED::IImage2D for the details on all luminance parameters.

The \ref wf_gi_cache_and_tone_mapping_for_panorama tutorial uses this function to set the tone mapping on all six faces of a cube.

Parameters
  • iAverageLuminance – The new value for the average luminance.

  • iLogAverageLuminance – The log value of the average luminance in the image.

  • iSamplesCount – The number of samples for the calculation of the log average luminance.

  • iMinLuminance – The minimal luminance value in the image.

  • iMaxLuminance – The maximal luminance value in the image.

Returns

RED_OK if the method has succeeded,

RED_BAD_PARAM if the method has received an invalid parameter.

inline void GetLuminanceOverride(float &oAverageLuminance, float &oLogAverageLuminance, unsigned int &oSamplesCount, float &oMinLuminance, float &oMaxLuminance) const

Returns overriden luminance parameters.

Parameters
  • oAverageLuminance – The average luminance value.

  • oLogAverageLuminance – The log value of the average luminance in the image.

  • oSamplesCount – The number of samples for the calculation of the log average luminance.

  • oMinLuminance – The minimal luminance value in the image.

  • oMaxLuminance – The maximal luminance value in the image.

inline bool IsLuminanceOverriden() const

Are we overriding the rendered image luminance values?

Returns

true if we have set a RED::PostProcess::OverrideLuminance, false if we don’t override image luminance values.

inline void ResetLuminanceOverride()

Resets the luminance override.

Calling this method cancels any effect of a previous RED::PostProcess::OverrideLuminance call.

inline void GetLuminanceInformation(float &oAverageLuminance, float &oLogAverageLuminance, unsigned int &oSamplesCount, float &oMinLuminance, float &oMaxLuminance) const

Retrieves last luminance informations available for the camera using this post process.

This method provides a direct access to the luminance informations that were calculated last during a GPU or during a CPU post-process operation. In both cases, valid luminance values can only be accessed after one draw with the post-process active. On the GPU, a RED::IWindow::FrameDrawing call must have occurred before luminance values can be retrieved through this method. Similarly, on the CPU, a RED::IWindow::FrameTracing (or similar call) must have occurred.

Due to the fact that the RED::PostProcess class is stateless, data returned by this method are set by the thread that calls the drawing method (the rendering thread). Accessing this method on another thread should be done carefully as there’s no locked access here. Data is modified by the rendering thread whenever appropriate without notice.

The \ref wf_gi_cache_and_tone_mapping_for_panorama tutorial uses this function to get the luminance values.

Parameters
  • oAverageLuminance – The average luminance value calculated last.

  • oLogAverageLuminance – The log value of the average luminance calculated last.

  • oSamplesCount – The number of samples for the calculation of the log average luminance.

  • oMinLuminance – The minimal luminance value calculated last.

  • oMaxLuminance – The maximal luminance value calculated last.

RED_RC SetLuminanceInformation(float iAverageLuminance, float iLogAverageLuminance, unsigned int iSamplesCount, float iMinLuminance, float iMaxLuminance) const

Writes luminance informations.

Write the luminance values leveraged by RED::PostProcess::GetLuminanceInfo.

Parameters
  • iAverageLuminance – The new value for the average luminance information.

  • iLogAverageLuminance – The log value of the average luminance information.

  • iSamplesCount – The number of samples for the calculation of the log average luminance.

  • iMinLuminance – The minimal luminance value information.

  • iMaxLuminance – The maximal luminance value information.

Returns

RED_OK if the method has succeeded,

RED_BAD_PARAM if the method has received an invalid parameter.