class ART::IObserver

Observer interface for planetary exploration. More...

#include <ARTIObserver.h>

Inherits: IREDObject.

Public functions:

virtual RED_RC	ExtractLuminanceInformation ( float & oLuminanceAverage, float & oLuminanceLogAverage, float & oLuminanceMax ) const = 0
virtual RED::Object *	GetClosestCelestialBody ( ) const = 0
virtual double	GetFocusDistance ( ) const = 0
virtual double	GetFOV ( ) const = 0
virtual void	GetGPSPosition ( double oPosition[3] ) const = 0
virtual void	GetNearFar ( double & oDNear, double & oDFar ) const = 0
virtual void	GetNearFarBackground ( double & oDNear, double & oDFar ) const = 0
virtual RED::Object *	GetParentCelestialBody ( ) const = 0
virtual const RED::Matrix &	GetParentCelestialBodyTransform ( ) const = 0
virtual void	GetPosition ( double oPosition[3] ) const = 0
virtual RED::Vector3	GetPosition ( ) const = 0
virtual RED_RC	GetPrimaryRay ( double oE[3], double oP[3], double iX, double iY, double iZ = 1.0 ) const = 0
virtual RED::Vector3	GetRight ( ) const = 0
virtual void	GetRight ( double oRight[3] ) const = 0
virtual void	GetSight ( double oSight[3] ) const = 0
virtual RED::Vector3	GetSight ( ) const = 0
virtual void	GetSphericalPosition ( double oPosition[3] ) const = 0
virtual RED::Object *	GetToneMappingCamera ( ) const = 0
virtual void	GetTop ( double oTop[3] ) const = 0
virtual RED::Vector3	GetTop ( ) const = 0
virtual const RED::Matrix &	GetViewMatrix ( ) const = 0
virtual bool	IsNearFarOverride ( ) const = 0
virtual bool	IsNearFarOverrideBackground ( ) const = 0
virtual RED_RC	OverrideNearFar ( double iNear, double iFar ) = 0
virtual RED_RC	OverrideNearFarBackground ( double iNear, double iFar ) = 0
virtual void	ResetNearFarOverride ( ) = 0
virtual void	ResetNearFarOverrideBackground ( ) = 0
virtual RED_RC	SetFocusDistance ( double iFocusDistance ) = 0
virtual RED_RC	SetFOV ( double iFOV ) = 0
virtual RED_RC	SetFromCamera ( const RED::Object * iCamera ) = 0
virtual RED_RC	SetParentCelestialBody ( RED::Object * iParent ) = 0
virtual RED_RC	SetViewMatrix ( const RED::Matrix & iViewMatrix ) = 0

Detailed description:

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.

Functions documentation

public static RED::CID ART::IObserver::GetClassID

(

)

public virtual RED_RC ART::IObserver::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.

public virtual RED::Object * ART::IObserver::GetClosestCelestialBody

(

) const = 0

Returns:

The closest celestial body to our observer.

public virtual double ART::IObserver::GetFocusDistance

(

) const = 0

Returns:

The observer focus distance.

public virtual double ART::IObserver::GetFOV

(

) const = 0

Returns:

The observer half horizontal field of view (radians).

public virtual void ART::IObserver::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.

public virtual void ART::IObserver::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.

public virtual void ART::IObserver::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.

public virtual RED::Object * ART::IObserver::GetParentCelestialBody

(

) const = 0

Returns:

The parent celestial body in which our coordinates are defined.

public virtual const RED::Matrix & ART::IObserver::GetParentCelestialBodyTransform

(

) const = 0

Returns:

Helper to retrieve the parent celestial body transformation matrix.

public virtual void ART::IObserver::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.

public virtual RED::Vector3 ART::IObserver::GetPosition

(

) const = 0

Returns:

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

public virtual RED_RC ART::IObserver::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.

public virtual RED::Vector3 ART::IObserver::GetRight

(

) const = 0

Returns:

The camera right vector relative to parent celestial body.

public virtual void ART::IObserver::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.

public virtual void ART::IObserver::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.

public virtual RED::Vector3 ART::IObserver::GetSight

(

) const = 0

Returns:

The camera sight vector relative to parent celestial body.

public virtual void ART::IObserver::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 ).

public virtual RED::Object * ART::IObserver::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.

public virtual void ART::IObserver::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.

public virtual RED::Vector3 ART::IObserver::GetTop

(

) const = 0

Returns:

The camera top vector relative to parent celestial body.

public virtual const RED::Matrix & ART::IObserver::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.

public virtual bool ART::IObserver::IsNearFarOverride

(

) const = 0

Returns:

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

public virtual bool ART::IObserver::IsNearFarOverrideBackground

(

) const = 0

Returns:

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

public virtual RED_RC ART::IObserver::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.

public virtual RED_RC ART::IObserver::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.

public virtual void ART::IObserver::ResetNearFarOverride

(

) = 0

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

public virtual void ART::IObserver::ResetNearFarOverrideBackground

(

) = 0

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

public virtual RED_RC ART::IObserver::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.

public virtual RED_RC ART::IObserver::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.

public virtual RED_RC ART::IObserver::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.

public virtual RED_RC ART::IObserver::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.

public virtual RED_RC ART::IObserver::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.

class ART::IObserver

Public functions:

Public static functions:

Detailed description:

Functions documentation