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.