IObserver

Functions

SET_CID

Object *

GetParentCelestialBody

RED_RC

SetParentCelestialBody

const Matrix &

GetParentCelestialBodyTransform

void

GetSight

Vector3

GetSight

void

GetTop

Vector3

GetTop

void

GetRight

Vector3

GetRight

void

GetPosition

Vector3

GetPosition

void

GetSphericalPosition

void

GetGPSPosition

const Matrix &

GetViewMatrix

RED_RC

SetViewMatrix

void

GetNearFar

void

GetNearFarBackground

double

GetFOV

RED_RC

SetFOV

double

GetFocusDistance

RED_RC

SetFocusDistance

RED_RC

SetFromCamera

Object *

GetToneMappingCamera

RED_RC

ExtractLuminanceInformation

Object *

GetClosestCelestialBody

RED_RC

OverrideNearFar

void

ResetNearFarOverride

bool

IsNearFarOverride

RED_RC

OverrideNearFarBackground

void

ResetNearFarOverrideBackground

bool

IsNearFarOverrideBackground

RED_RC

GetPrimaryRay

Detailed Description

class IObserver : public RED::IREDObject

Observer interface for planetary exploration.

One observer instance must be created from the ART::Factory using the CID_ARTObserver identifier. The observer is a singleton.

The observer coordinates are defined in a parent celestial body coordinate system. By default, the observer has no parent and is using absolute coordinates.

Public Functions

SET_CID(CID_class_ARTIObserver)
virtual RED::Object *GetParentCelestialBody() const = 0
Returns

The parent celestial body in which our coordinates are defined.

virtual RED_RC SetParentCelestialBody(RED::Object *iParent) = 0

Change the celestial body parent of the observer.

The observer’s axis system is redefined relatively to the new specified parent.

Parameters

iParent – New parent celestial body. Can be NULL to set no parent body.

Returns

RED_OK if the operation has succeeded,

RED_BAD_PARAM if the method has received an invalid parameter,

RED_FAIL otherwise.

virtual const RED::Matrix &GetParentCelestialBodyTransform() const = 0
Returns

Helper to retrieve the parent celestial body transformation matrix.

virtual void GetSight(double oSight[3]) const = 0

Access the observer’s camera sight vector in the main referential of the parent celestial body.

Parameters

oSight – The camera sight vector. Relative to parent celestial body.

virtual RED::Vector3 GetSight() const = 0
Returns

The camera sight vector relative to parent celestial body.

virtual void GetTop(double oTop[3]) const = 0

Access the observer’s camera top vector in the main referential of the parent celestial body.

Parameters

oTop – The camera top vector. Relative to parent celestial body.

virtual RED::Vector3 GetTop() const = 0
Returns

The camera top vector relative to parent celestial body.

virtual void GetRight(double oRight[3]) const = 0

Access the observer’s camera right vector in the main referential of the parent celestial body.

Parameters

oRight – The camera right vector. Relative to parent celestial body.

virtual RED::Vector3 GetRight() const = 0
Returns

The camera right vector relative to parent celestial body.

virtual void GetPosition(double oPosition[3]) const = 0

Access the observer’s camera position in the main referential of the parent celestial body.

Parameters

oPosition – The observer’s camera position. Relative to parent celestial body.

virtual RED::Vector3 GetPosition() const = 0
Returns

The observer’s camera position relative to parent celestial body.

virtual void GetSphericalPosition(double oPosition[3]) const = 0

Access the observer’s camera spherical position on its celestial body.

theta and phi are polar coordinates returned in radians:

  • theta is 0 at the southern pole, up to pi at the northern pole.

  • phi is 0 along the x axis, ranging up to 2 * pi rotating aroung the z axis.

Parameters

oPosition – The observer’s camera position ( altitude, theta, phi ).

virtual void GetGPSPosition(double oPosition[3]) const = 0

Access the observer’s camera GPS position on its celestial body.

Latitude is 0° at equator, -90° southern pole, +90° northern pole. Longitude is 0° at Greenwich meridian, ranging -180° west to +180° east.

Parameters

oPosition – The observer’s camera position ( altitude, latitude, longitude ). Latitude and longitude are in degrees.

virtual const RED::Matrix &GetViewMatrix() const = 0

Access the observer’s camera viewing matrix in the main referential of the parent celestial body.

Returns

A reference to the observer’s camera viewing matrix. Relative to parent celestial body current referential.

virtual RED_RC SetViewMatrix(const RED::Matrix &iViewMatrix) = 0

Set the observer’s camera viewing matrix in the main referential of the parent celestial body.

Parameters

iViewMatrix – The viewing matrix [ right, top, -sight, eye ]. Relative to parent celestial body current referential.

Returns

RED_OK if the method has succeeded,

RED_SCG_INVALID_CAMERA_AXIS if iViewMatrix is not an ortho basis matrix or if iViewMatrix is not right handed. RED_FAIL otherwise.

virtual void GetNearFar(double &oDNear, double &oDFar) const = 0

Get the camera near and far clipping distance.

Parameters
  • oDNear – Camera near clip distance.

  • oDFar – Camera far clip distance.

virtual void GetNearFarBackground(double &oDNear, double &oDFar) const = 0

Get the camera near and far background clipping distance.

Parameters
  • oDNear – Camera background near clip distance.

  • oDFar – Camera background far clip distance.

virtual double GetFOV() const = 0
Returns

The observer half horizontal field of view (radians).

virtual RED_RC SetFOV(double iFOV) = 0

Setup the observer’s camera half horizontal field of view.

Parameters

iFOV – Half the total horizontal field of view of the observer’s camera (radians).

Returns

RED_OK if the method has succeeded,

RED_BAD_PARAM if the method has received an invalid parameter.

virtual double GetFocusDistance() const = 0
Returns

The observer focus distance.

virtual RED_RC SetFocusDistance(double iFocusDistance) = 0

Setup the observer’s focus distance.

Parameters

iFocusDistance – the new focus distance value.

Returns

RED_OK if the method has succeeded,

RED_BAD_PARAM if the method has received an invalid parameter.

virtual RED_RC SetFromCamera(const RED::Object *iCamera) = 0

Setup the observer from a camera.

Parameters

iCamera – A camera object implementing the ART::ICamera interface.

Returns

RED_OK if the operation has succeeded,

RED_BAD_PARAM if ‘iCamera’ is not a valid camera object,

Other RED_RCs from the REDsdk API are possible.

virtual RED::Object *GetToneMappingCamera() const = 0
Returns

The REDsdk tonemapping camera. This is a standard REDsdk viewpoint object implementing the RED::IViewpoint interface. Returns NULL in case of error.

virtual RED_RC ExtractLuminanceInformation(float &oLuminanceAverage, float &oLuminanceLogAverage, float &oLuminanceMax) const = 0

Extract luminance values from the viewed scene image.

This is a costly operation that can be used to collect useful luminance informations to calibrate the tonemapping operator. It should not be called every frame. It should be called only during some synchronization points when the knowledge of real luminance values is paramount for rendering.

Retrieved parameters can then be supplied to RED::PostProcess::OverrideLuminance and are only valid for the RED::TMO_PHOTOGRAPHIC or RED::TMO_EXPONENTIAL tonemapping operator. Note that for the call to RED::PostProcess::OverrideLuminance used in that scope, the number of samples and the minimal luminance values don’t matter.

Parameters
  • oLuminanceAverage – Retrieved average luminance value.

  • oLuminanceLogAverage – Retrieved average luminance log value.

  • oLuminanceMax – Retrieved maximal luminance.

Returns

RED_OK if the operation has succeeded,

RED_FAIL in case of critical error,

Other RED_RC from REDsdk imaging API are possible.

virtual RED::Object *GetClosestCelestialBody() const = 0
Returns

The closest celestial body to our observer.

virtual RED_RC OverrideNearFar(double iNear, double iFar) = 0

Override the automatic clipping distances.

This method can be used to override near / far camera clip distances that are calculated automatically each frame. Due to the high view ranges in planetary display, always try to keep the far / near range as low as possible.

The method overrides both the scene and clouds clip distances.

Parameters
  • iNear – Near clip distance.

  • iFar – Far clip distance.

virtual void ResetNearFarOverride() = 0

Resets the near / far clip distance override set using ART::IObserver::OverrideNearFar.

virtual bool IsNearFarOverride() const = 0
Returns

true if we have a near / far clip distance override in place for the observer.

virtual RED_RC OverrideNearFarBackground(double iNear, double iFar) = 0

Override the near / far clip distances for background elements.

The method overrides the near / far clip distances that are used for the rendering of all background elements in the scenery. This includes all entities that are outside of the planet: satellites and stars for instance.

The default values for the background near / far clip are very high: 10.000 kms to 10.000.000.000 kms to handle solar system bodies.

Parameters
  • iNear – Near clip distance.

  • iFar – Far clip distance.

virtual void ResetNearFarOverrideBackground() = 0

Resets the near / far clip background distance override set using ART::IObserver::OverrideNearFarBackground.

virtual bool IsNearFarOverrideBackground() const = 0
Returns

true if we have a near / far background clip distance override in place for the observer.

virtual RED_RC GetPrimaryRay(double oE[3], double oP[3], double iX, double iY, double iZ = 1.0) const = 0

Get a primary ray through a screen pixel.

Parameters
  • oE – Ray origin. On the camera near plane at ( iX, iY ).

  • oP – Ray end. On the camera far plane at ( iX, iY ).

  • iX – Screen coordinates. Origin is the lower left image corner.

  • iY – Screen coordinates. Origin is the lower left image corner.

  • iZ – Sceen depth coordinate. Set to a value in [ 0.0, 1.0 ] to truncate the ray.

Returns

RED_OK if the method has succeeded,

RED_BAD_PARAM if the method has received an invalid parameter,

RED_FAIL otherwise.