class ART::IPlanet

Celestial body interface for planets. More...

#include <ARTIPlanet.h>

Inherits: IREDObject.

Public functions:

virtual RED_RCAddGeometry ( RED::Object * iGeometry, double iLatitude, double iLongitude, double iOrientation, double iScale ) = 0
virtual RED_RCAddGeometry ( RED::Object * iGeometry, const RED::Matrix & iCoordinates ) = 0
virtual RED::Object *GetAtlas ( ) const = 0
virtual const RED::Matrix &GetAxisSystem ( ) const = 0
virtual const RED::Matrix &GetAxisSystemOverride ( ) const = 0
virtual const double *GetEllipticPath ( ) const = 0
virtual RED::Object *GetEnvironment ( ) const = 0
virtual const RED::Matrix &GetEnvironmentMatrix ( ) const = 0
virtual doubleGetEnvironmentMaximalHeight ( ) const = 0
virtual RED_RCGetGeometry ( RED::Object *& oGeometry, int iIndex ) const = 0
virtual const RED::Matrix &GetInclination ( ) const = 0
virtual RED_RCGetLandscapeHeight ( double oPos[3], double oNor[3], double iPos[3] ) const = 0
virtual const RED::String &GetName ( ) const = 0
virtual const RED::Matrix &GetObliquity ( ) const = 0
virtual doubleGetOrbitalPeriod ( ) const = 0
virtual RED::Object *GetParent ( ) const = 0
virtual ART::PLANET_IDGetPID ( ) const = 0
virtual voidGetPosition ( double oPosition[3] ) const = 0
virtual doubleGetRadius ( ) const = 0
virtual doubleGetRotationAngleOverride ( ) const = 0
virtual doubleGetRotationPeriod ( ) const = 0
virtual doubleGetStartupOrbitalAngle ( ) const = 0
virtual doubleGetStartupRotationAngle ( ) const = 0
virtual RED_RCGetTangentAxisSystem ( RED::Matrix & oMatrix, const double iPosition[3] ) const = 0
virtual boolHasAxisSystemOverride ( ) const = 0
virtual voidOverrideAxisSystem ( const RED::Matrix & iAxisSystem ) = 0
virtual voidOverrideRotationAngle ( double iAngle ) = 0
virtual RED_RCRefreshGeometry ( RED::Object * iGeometry ) = 0
virtual RED_RCRefreshGeometryTransform ( RED::Object * iGeometry, const RED::Matrix & iCoordinates ) = 0
virtual RED_RCRemoveGeometry ( RED::Object * iGeometry ) = 0
virtual voidResetAxisSystemOverride ( ) = 0
virtual voidResetRotationAngleOverride ( ) = 0
virtual RED_RCSetAtlas ( RED::Object * iAtlas ) = 0
virtual RED_RCSetEllipticPath ( double iOrbit[2] ) = 0
virtual RED_RCSetEnvironment ( RED::Object * iEnvironment, const RED::Matrix & iMatrix, double iMaxHeight ) = 0
virtual RED_RCSetInclination ( const RED::Matrix & iMatrix ) = 0
virtual RED_RCSetName ( const RED::String & iName ) = 0
virtual RED_RCSetObliquity ( const RED::Matrix & iMatrix ) = 0
virtual RED_RCSetOrbitalPeriod ( double iOrbitalPeriod ) = 0
virtual RED_RCSetParent ( RED::Object * iParent ) = 0
virtual RED_RCSetRadius ( double iRadius ) = 0
virtual RED_RCSetRotationPeriod ( double iRotationPeriod ) = 0
virtual RED_RCSetStartupOrbitalAngle ( double iOrbitalAngle ) = 0
virtual RED_RCSetStartupRotationAngle ( double iRotationAngle ) = 0

Public static functions:

static RED::CIDGetClassID ( )

Detailed description:

Celestial body interface for planets.

Planets are created from the ART::Factory using the CID_ARTPlanet identifier, or accessed from the ART::IWorld interface. A planet's parameters must be setup once before the world simulation is launched, and can't be modified after that.

A planet must have a parent celestial body to be displayed. It can be either another planet (if a satellite) or a star.

Functions documentation

public virtual RED_RC ART::IPlanet::AddGeometry(RED::Object *iGeometry,
doubleiLatitude,
doubleiLongitude,
doubleiOrientation,
doubleiScale
) = 0

Adds a geometry to the planet using latitude and longitude cordinates.

The geometry is automatically replaced on the landscape ground level if its ART::IGeometry::SetAutomaticSetOnGround flag is enabled.

Parameters:

iGeometry:geometry to add.
iLatitude:latitude at which the geometry is added in [0,PI].
iLongitude:longitude at which the geometry is added in [0,2PI].
iOrientation:local orientation of the geometry in [0,2PI].
iScale:local scale of the geometry.

Returns:

RED_OK if the method has succeeded,
RED_INIT_FAILED if the world has not been started yet,
RED_FAIL otherwise.
public virtual RED_RC ART::IPlanet::AddGeometry(RED::Object *iGeometry,
const RED::Matrix &iCoordinates
) = 0

Adds a geometry to the planet using a transformation matrix.

The geometry is automatically replaced on the landscape ground level if its ART::IGeometry::SetAutomaticSetOnGround flag is enabled.

Parameters:

iGeometry:geometry to add.
iCoordinates:coordinate matrix of the object

Returns:

RED_OK if the method has succeeded,
RED_INIT_FAILED if the world has not been started yet,
RED_FAIL otherwise.
public virtual RED::Object * ART::IPlanet::GetAtlas() const = 0

Returns:

The current planet atlas.
public virtual const RED::Matrix & ART::IPlanet::GetAxisSystem() const = 0

Retrieve the planetary coordinate transformation of the planet.

Returns:

The planet transform matrix, WCS.
public virtual const RED::Matrix & ART::IPlanet::GetAxisSystemOverride() const = 0

Returns:

The current axis system override matrix, if the planet has an overriden axis system.
public virtual const double * ART::IPlanet::GetEllipticPath() const = 0

Returns:

The elliptic path of this planet's orbit (2 doubles: semi major axis and semi minor axis).
public virtual RED::Object * ART::IPlanet::GetEnvironment() const = 0

Returns:

The current environment.
public virtual const RED::Matrix & ART::IPlanet::GetEnvironmentMatrix() const = 0

Returns:

The current environment definition matrix.
public virtual double ART::IPlanet::GetEnvironmentMaximalHeight() const = 0

Returns:

The current environment maximal height.
public virtual RED_RC ART::IPlanet::GetGeometry(RED::Object *&oGeometry,
intiIndex
)const = 0

Retrieves a planet geometry by index.

Parameters:

oGeometry:output geometry.
iIndex:index of the geometry to get.

Returns:

RED_OK if the method has succeeded,
RED_INIT_FAILED if the world has not been started yet,
RED_FAIL otherwise.
public virtual const RED::Matrix & ART::IPlanet::GetInclination() const = 0

Returns:

The planet's orbit inclination matrix.
public virtual RED_RC ART::IPlanet::GetLandscapeHeight(doubleoPos[3],
doubleoNor[3],
doubleiPos[3]
)const = 0

Return the planet relief elevation at a given position, based on existing graphics.

This method returns the elevation of the planet relief under iPos. Calculations are made using existing planet graphics. All calculations are in PCS.

This method can be called from any thread, but outside of the planet graphics update time slice.

Parameters:

oPos:The landscape position at the relief altitude under iPos, in PCS.
oNor:The landscape normal at oPos, in PCS.
iPos:The source query position, in planet coordinate system (PCS).

Returns:

RED_OK if the method has succeeded,
Other RED_RCs from REDsdk calls are possible.
public virtual const RED::String & ART::IPlanet::GetName() const = 0

Returns:

The name of the planet.
public virtual const RED::Matrix & ART::IPlanet::GetObliquity() const = 0

Returns:

The planet's obliquity rotation matrix.
public virtual double ART::IPlanet::GetOrbitalPeriod() const = 0

Returns:

The planet orbital period, in milliseconds.
public virtual RED::Object * ART::IPlanet::GetParent() const = 0

Returns:

The parent planet or star around which this planet orbits.
public virtual ART::PLANET_ID ART::IPlanet::GetPID() const = 0

Returns:

The planet ID.
public virtual void ART::IPlanet::GetPosition(doubleoPosition[3]) const = 0

Access the planet position, WCS.

Parameters:

oPosition:The planet position, WCS. This is the translation in ART::IPlanet::GetAxisSystem.
public virtual double ART::IPlanet::GetRadius() const = 0

Returns:

The planet radius in meters.
public virtual double ART::IPlanet::GetRotationAngleOverride() const = 0

Returns:

The current planet rotation angle override. If the rotation angle is not overriden, the method returns -DBL_MAX.
public virtual double ART::IPlanet::GetRotationPeriod() const = 0

Returns:

The planet rotation period, in milliseconds.
public virtual double ART::IPlanet::GetStartupOrbitalAngle() const = 0

Returns:

The planet startup orbital angle, in radians.
public virtual double ART::IPlanet::GetStartupRotationAngle() const = 0

Returns:

The planet startup rotation angle, in radians.
public virtual RED_RC ART::IPlanet::GetTangentAxisSystem(RED::Matrix &oMatrix,
const doubleiPosition[3]
)const = 0

Gets the tangent axis system for a given position.

The planetary coordinate system (PCS) has the planet center at the origin, the south pole along -Z and the north pole along +Z. The tangent coordinate system (TCS) has its center at the specified iPosition, its matrix X axis as a longitude direction toward the southern pole, its matrix Y axis as a latitude direction and its matrix Z axis along the opposite of the gravity direction (planet center to iPosition).

Parameters:

oMatrix:the matrix to convert tangent coordinates system (TCS) to planet coordinates system (PCS).
iPosition:the position at the surface of the planet.

Returns:

RED_OK if the method has succeeded,
RED_BAD_PARAM if iPosition is incorrect,
RED_FAIL otherwise.
public virtual bool ART::IPlanet::HasAxisSystemOverride() const = 0

Returns:

true if the planet has an axis system override, false otherwise.
public virtual void ART::IPlanet::OverrideAxisSystem(const RED::Matrix &iAxisSystem) = 0

Overrides the axis system of the planet.

Overrides the global positioning of the planet.

Parameters:

iAxisSystem:The new planet axis system to use.
public virtual void ART::IPlanet::OverrideRotationAngle(doubleiAngle) = 0

Override the planet rotation angle.

Parameters:

iAngle:Planet rotation angle to use. If iAngle is -DBL_MAX, this resets the rotation angle override.
public virtual RED_RC ART::IPlanet::RefreshGeometry(RED::Object *iGeometry) = 0

Refreshes a geometry on the planet.

Refreshing a geometry may be needed when some core parameters of the geometry are modified. Setting up a new GI cache or setting up ground elevation on a geometry require a refresh.

Parameters:

iGeometry:geometry to refresh.

Returns:

RED_OK if the method has succeeded,
RED_INIT_FAILED if the world has not been started yet,
RED_FAIL otherwise.
public virtual RED_RC ART::IPlanet::RefreshGeometryTransform(RED::Object *iGeometry,
const RED::Matrix &iCoordinates
) = 0

Refreshes the geometry transformation on the planet.

If the geometry has the ART::IGeometry::SetAutomaticSetOnGround flag enabled, it gets replaced automatically.

Parameters:

iGeometry:geometry to add.
iCoordinates:coordinate matrix of the object

Returns:

RED_OK if the method has succeeded,
RED_INIT_FAILED if the world has not been started yet,
RED_FAIL otherwise.
public virtual RED_RC ART::IPlanet::RemoveGeometry(RED::Object *iGeometry) = 0

Removes a geometry from the planet.

Parameters:

iGeometry:geometry to remove.

Returns:

RED_OK if the method has succeeded,
RED_INIT_FAILED if the world has not been started yet,
RED_FAIL otherwise.
public virtual void ART::IPlanet::ResetAxisSystemOverride() = 0

Cancels the override of the planet's axis system.

Resets the override of the planet rotation angle.

public virtual RED_RC ART::IPlanet::SetAtlas(RED::Object *iAtlas) = 0

Setup the planet atlas.

Setting up a non NULL atlas removes any environment set using ART::IPlanet::SetEnvironment. Get an atlas using ART::IAssetManager::LoadAtlas.

The atlas of a planet can only be changed with a world that is stopped. If the world is started, the method will return an error.

Parameters:

iAtlas:The atlas object. Can be NULL to remove the current atlas.

Returns:

RED_OK if the method has succeeded,
RED_WORKFLOW_ERROR if the ART::IWorld is started. It must be stopped to change an atlas.
public virtual RED_RC ART::IPlanet::SetEllipticPath(doubleiOrbit[2]) = 0

Setup the elliptic path of this planet's orbit.

The elliptic path of this planet's orbit defines the dimensions of the ellipse of the planet's trajectory in the (xy) plane of its orbiting matrix.

Parameters:

iOrbit:The ellipse semi major axis and semi minor axis values.

Returns:

RED_OK if the method has succeeded,
RED_BAD_PARAM if any value in iOrbit is negative or zero,
RED_WORKFLOW_ERROR if the world simulation has already begun.
public virtual RED_RC ART::IPlanet::SetEnvironment(RED::Object *iEnvironment,
const RED::Matrix &iMatrix,
doubleiMaxHeight
) = 0

Setup a planet background environment.

Setting up a non NULL background environment replaces any atlas previously set using ART::IPlanet::SetAtlas. A valid iEnvironment and its iMatrix can be loaded using ART::IAssetManager::LoadEnvironment in the case of an environment file generated by the REDart editor.

If you wish to specify your own environment, it can also be done using this method. In this case, iEnvironment must be a valid RED::IImage2D object that contains a latitude / longitude map, as a RED::TGT_TEX_RECT image.

In that case it may be preferrable to change the axis system and to load the environment map with an identity iMatrix and to reposition the observer at the origin. Then while still using the Planet Coordinate System, everything will be set around the origin. The sun direction must be then setup taking these axis system into consideration.

Note that an iEnvironment loaded using an identity matrix is wrapped by matching the image left to right pixels along increasing polar coordinates phi angle (so rotating around the z axis from +x to +y to -x and -y), the bottom of the image (image origins in REDsdk are bottom left) is mapped to the -z coordinate while the image top is mapped to the +z coordinate. This mapping may cause an environment map to appears flipped from a plain view of that image in a 2D viewing software due to increasing phi values going left from the observer viewpoint and increasing pixel coordinates going right in a 2D map viewer on screen.

Parameters:

iEnvironment:The environment object that must have been retrieved from the ART::IAssetManager::LoadEnvironment. Can be NULL to remove the current environment.
iMatrix:The environment definition matrix. This is a matrix expressed in Planet Coordinate System. PCS.
iMaxHeight:The maximal height, above sea level, reached by data to visualize inside the environment. All viewed geometries must be in the range of this value otherwise visual artifacts can show up.

Returns:

RED_OK if the method has succeeded,
RED_WORKFLOW_ERROR if the world is started and an atlas has been set. It must be stopped to change atlas into environment. RED_BAD_PARAM if iMaxHeight was negative.
public virtual RED_RC ART::IPlanet::SetInclination(const RED::Matrix &iMatrix) = 0

Setup the orbit inclination matrix for this planet.

Defines the planet's orbiting trajectory inclination relatively to its parent body.

Parameters:

iMatrix:The orbit inclination matrix.

Returns:

RED_OK if the method has succeeded,
RED_WORKFLOW_ERROR if the world simulation has already begun.
public virtual RED_RC ART::IPlanet::SetName(const RED::String &iName) = 0

Sets the planet name.

Parameters:

iName:The string name of the planet.

Returns:

RED_OK if the method has succeeded,
RED_ALLOC_FAILURE if an internal allocation has failed.
public virtual RED_RC ART::IPlanet::SetObliquity(const RED::Matrix &iMatrix) = 0

Setup the obliquity rotation matrix for this planet.

The obliquity matrix (or axial tilt) is the rotation of the planet's rotation axis and orbit plane axis.

Parameters:

iMatrix:The obliquity rotation matrix.

Returns:

RED_OK if the method has succeeded,
RED_WORKFLOW_ERROR if the world simulation has already begun.
public virtual RED_RC ART::IPlanet::SetOrbitalPeriod(doubleiOrbitalPeriod) = 0

Setup The orbital period of the planet.

Parameters:

iOrbitalPeriod:The planet orbital period in milliseconds.

Returns:

RED_OK if the method has succeeded,
RED_BAD_PARAM if iOrbitalPeriod is negative or zero,
RED_WORKFLOW_ERROR if the world simulation has already begun.
public virtual RED_RC ART::IPlanet::SetParent(RED::Object *iParent) = 0

Setup the parent body of this planet.

Parameters:

iParent:The parent planet or star.

Returns:

RED_OK if the operation has succeeded,
RED_BAD_PARAM if iParent is not valid,
RED_WORKFLOW_ERROR if the world simulation has already begun.
public virtual RED_RC ART::IPlanet::SetRadius(doubleiRadius) = 0

Setup the radius of this planet.

Parameters:

iRadius:The planet radius, in meters.

Returns:

RED_OK if the operation has succeeded,
RED_BAD_PARAM if iRadius is negative or zero.
public virtual RED_RC ART::IPlanet::SetRotationPeriod(doubleiRotationPeriod) = 0

Setup The rotation period of the planet.

Parameters:

iRotationPeriod:The planet rotation period in milliseconds.

Returns:

RED_OK if the method has succeeded,
RED_BAD_PARAM if iOrbitalPeriod is negative or zero,
RED_WORKFLOW_ERROR if the world simulation has already begun.
public virtual RED_RC ART::IPlanet::SetStartupOrbitalAngle(doubleiOrbitalAngle) = 0

Setup The startup orbital angle of the planet.

Parameters:

iOrbitalAngle:The planet startup orbital angle in radians.

Returns:

RED_OK if the method has succeeded,
RED_WORKFLOW_ERROR if the world simulation has already begun.
public virtual RED_RC ART::IPlanet::SetStartupRotationAngle(doubleiRotationAngle) = 0

Setup the startup rotation angle of the planet.

Parameters:

iRotationAngle:The startup planet rotation angle, in radians.

Returns:

RED_OK if the method has succeeded,
RED_WORKFLOW_ERROR if the world simulation has already begun.