IPlanet
Functions
Detailed Description
-
class
IPlanet: public RED::IREDObject 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.
Public Functions
-
SET_CID(CID_class_ARTIPlanet)
-
virtual RED_RC
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.
-
virtual RED::Object *
GetParent() const = 0 Returns: The parent planet or star around which this planet orbits.
-
virtual RED_RC
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.
-
virtual double
GetRadius() const = 0 Returns: The planet radius in meters.
-
virtual RED_RC
SetRadius(double iRadius) = 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.
-
virtual const RED::Matrix &
GetInclination() const = 0 Returns: The planet’s orbit inclination matrix.
-
virtual RED_RC
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.
-
virtual const RED::Matrix &
GetObliquity() const = 0 Returns: The planet’s obliquity rotation matrix.
-
virtual RED_RC
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.
-
virtual const double *
GetEllipticPath() const = 0 Returns: The elliptic path of this planet’s orbit (2 doubles: semi major axis and semi minor axis).
-
virtual RED_RC
SetEllipticPath(double iOrbit[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.
-
virtual double
GetOrbitalPeriod() const = 0 Returns: The planet orbital period, in milliseconds.
-
virtual RED_RC
SetOrbitalPeriod(double iOrbitalPeriod) = 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.
-
virtual double
GetStartupOrbitalAngle() const = 0 Returns: The planet startup orbital angle, in radians.
-
virtual RED_RC
SetStartupOrbitalAngle(double iOrbitalAngle) = 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.
-
virtual double
GetRotationPeriod() const = 0 Returns: The planet rotation period, in milliseconds.
-
virtual RED_RC
SetRotationPeriod(double iRotationPeriod) = 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.
-
virtual double
GetStartupRotationAngle() const = 0 Returns: The planet startup rotation angle, in radians.
-
virtual RED_RC
SetStartupRotationAngle(double iRotationAngle) = 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.
-
virtual void
OverrideRotationAngle(double iAngle) = 0 Override the planet rotation angle.
Parameters: iAngle – Planet rotation angle to use. If iAngle is -DBL_MAX, this resets the rotation angle override.
-
virtual void
ResetRotationAngleOverride() = 0 Resets the override of the planet rotation angle.
-
virtual double
GetRotationAngleOverride() const = 0 Returns: The current planet rotation angle override. If the rotation angle is not overriden, the method returns -DBL_MAX.
-
virtual RED_RC
GetTangentAxisSystem(RED::Matrix &oMatrix, const double iPosition[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 latitude direction toward the southern pole, its matrix Y axis as a longitude 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.
-
virtual void
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.
-
virtual void
ResetAxisSystemOverride() = 0 Cancels the override of the planet’s axis system.
-
virtual bool
HasAxisSystemOverride() const = 0 Returns: true if the planet has an axis system override, false otherwise.
-
virtual const RED::Matrix &
GetAxisSystemOverride() const = 0 Returns: The current axis system override matrix, if the planet has an overriden axis system.
-
virtual void
SetOffsetMatrix(const RED::Matrix &iOffsetMatrix) = 0 Adds an offset matrix applied at the end of the planet transform chain.
The offset matrix is not included in the global transform of the planet children.
The matrix returned by ART::IPlanet::GetAxisSystem includes the offset matrix. ART::IPlanet::GetRawAxisSystem can be used to get the axis system without the offset matrix.
Parameters: iOffsetMatrix – the offset matrix.
-
virtual const RED::Matrix &
GetOffsetMatrix() const = 0 Returns: The current offset matrix applied to the planet axis system.
-
virtual RED_RC
ConvertPlanetToTangentAxisSystem(double oVectorTCS[3], const double iPosition[3], const double iVectorPCS[3]) const = 0 Converts a vector from planet coordinates system (PCS) to tangent coordinates system (TCS).
Parameters: - oVectorTCS – returned converted vector in TCS.
- iPosition – the position at the surface of the planet.
- iVectorPCS – vector in PCS to convert in TCS.
Returns: RED_OK if the method has succeeded,
RED_BAD_PARAM if iPosition is incorrect,
RED_FAIL otherwise.
-
virtual RED_RC
ConvertTangentToPlanetAxisSystem(double oVectorPCS[3], const double iPosition[3], const double iVectorTCS[3]) const = 0 Converts a vector from tangent coordinates system (TCS) to planet coordinates system (PCS).
Parameters: - oVectorPCS – returned converted vector in PCS.
- iPosition – the position at the surface of the planet.
- iVectorTCS – vector in TCS to convert in PCS.
Returns: RED_OK if the method has succeeded,
RED_BAD_PARAM if iPosition is incorrect,
RED_FAIL otherwise.
-
virtual RED_RC
GetStarDirection(double oDirection[3]) const = 0 Gets the direction of the star around which the planet rotates.
Parameters: oDirection – returned star direction in PCS. Returns: RED_OK if the method has succeeded, RED_FAIL otherwise.
-
virtual RED_RC
ComputeOffsetMatrixForStarDirection(const double iDirection[3]) = 0 Computes an offset matrix so that the star is in a given direction.
This method calls ART::IPlanet::SetOffsetMatrix.
Parameters: iDirection – target star direction in PCS. Returns: RED_OK if the method has succeeded, RED_FAIL otherwise.
-
virtual RED_RC
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.
-
virtual RED_RC
SetEnvironment(RED::Object *iEnvironment, double iScale, const RED::Matrix &iMatrix, double iMaxHeight) = 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.
- iScale – Intensity scaling applied to the environment image. Set to 1.0 for no influence.
- 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.
-
virtual void
GetEnvironmentSize(int &oWidth, int &oHeight) const = 0 Access the current environment dimensions.
Parameters: - oWidth – Pixel width of the environment image.
- oHeight – Pixel height of the environment image.
-
virtual double
GetEnvironmentScale() const = 0 Returns: The intensity scale applied to the current environment.
-
virtual const RED::Matrix &
GetEnvironmentMatrix() const = 0 Returns: The current environment definition matrix.
-
virtual double
GetEnvironmentMaximalHeight() const = 0 Returns: The current environment maximal height.
-
virtual const RED::Matrix &
GetAxisSystem() const = 0 Retrieve the planetary coordinate transformation of the planet.
Returns: The planet transform matrix, WCS.
-
virtual const RED::Matrix &
GetRawAxisSystem() const = 0 Retrieve the planetary coordinate transformation of the planet without the custom offset matrix.
The returned matrix doesn’t include the custom offset matrix set with ART::IPlanet::SetOffsetMatrix.
Returns: The planet transform matrix, WCS.
-
virtual void
GetPosition(double oPosition[3]) const = 0 Access the planet position, WCS.
Parameters: oPosition – The planet position, WCS. This is the translation in ART::IPlanet::GetAxisSystem.
-
virtual RED_RC
GetLandscapeVisibleHeight(double oPos[3], double oNor[3], double iPos[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.
Since results are based on existing, visible, graphics, for a given position, the results may vary if the observer moves.
This method can be called during the user command 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.
-
virtual RED_RC
GetLandscapeRealHeight(double oPos[3], double iPos[3], bool iWithGroundAreas, bool iWithGeometries, bool iFirstSoil, int iGeometryMaxPriority = INT_MAX) const = 0 Return the planet relief elevation at a given position, based on real landscape elevation.
This method returns the elevation of the planet relief under iPos. Calculations are made using exact landscape specifications. All calculations are in PCS.
Compared to the GetLandscapeVisibleHeight method, this version uses the real landscape specification, so the amount of calculations being performed may outweight the version based on existing landscape. Using this method there’s no local neighborhood mesh analysis, therefore the vertex normal is not available.
This method can be called during the user command time slice.
Parameters: - oPos – The landscape position at the relief altitude under iPos, in PCS.
- iPos – The source query position, in planet coordinate system (PCS).
- iWithGroundAreas – True to include all ground areas (decals, water bodies) in the result.
- iWithGeometries – True to include all geometries (cities, networks) in the result.
- iFirstSoil – If true, only the first level soils in the atlas are sampled.
- iGeometryMaxPriority – If iWithGeometries is true, all geometries with priorities <= iGeometryMaxPriority are rendered. By default (INT_MAX) all geometries are rendered.
Returns: RED_OK if the method has succeeded,
Other RED_RCs from REDsdk calls are possible.
-
virtual RED_RC
AddGeometry(RED::Object *iGeometry, double iLatitude, double iLongitude, double iOrientation, double iScale) = 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.
-
virtual RED_RC
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.
-
virtual RED_RC
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.
-
virtual RED_RC
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.
-
virtual RED_RC
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.
-
virtual RED_RC
GetGeometry(RED::Object *&oGeometry, int iIndex) 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.
-
virtual bool
IsGeometriesLazyGroundUpdates() const = 0 Returns: true if geometry ground updates are lazy and deferred.
-
virtual void
SetGeometriesLazyGroundUpdates(bool iLazy) = 0 Setup the geometry ground update mode.
If disabled, all geometry changes that modify the landscape are immediately handled. If enabled, all events are stacked until they can be handled when this lazy mode is turned off again or flushed.
Parameters: iLazy – True to enable deferred ground updates, false to handle these right away.
-
virtual bool
IsGeometriesGroundUpdatesFlush() const = 0 Returns: true if we have ordered a flush of geometry ground update orders, false otherwise.
-
virtual void
SetGeometriesGroundUpdatesFlush(bool iOnOff) = 0 Request a flush of all pending geometry ground updates orders. Lasts for one world update loop. Does nothing if lazy ground updates are off.
-
virtual RED_RC
GetWindDirection(RED::Vector3 &oDirection) const = 0 Gets the direction of the wind.
Parameters: oDirection – returned wind direction in PCS. Returns: RED_OK if the method has succeeded, RED_FAIL otherwise.
-
virtual RED_RC
SetWindDirection(const RED::Vector3 &iDirection) = 0 Sets the direction of the wind.
Parameters: iDirection – wind direction in PCS. Returns: RED_OK if the method has succeeded, RED_FAIL otherwise.
-
virtual RED_RC
GetWindPower(double &oPower) = 0 Gets the power of the wind.
Parameters: oPower – returned wind power between 0 and 1. Returns: RED_OK if the method has succeeded, RED_FAIL otherwise.
-
virtual RED_RC
SetWindPower(double iPower) = 0 Sets the power of the wind.
Parameters: iPower – wind power between 0 and 1. Returns: RED_OK if the method has succeeded, RED_FAIL otherwise.
-
virtual RED_RC
GetWindTurbulenceSpeed(double &oSpeed) = 0 Gets the turbulence speed of the wind.
Parameters: oSpeed – returned wind turbulence speed between 0 and 1. Returns: RED_OK if the method has succeeded, RED_FAIL otherwise.
-
virtual RED_RC
SetWindTurbulenceSpeed(double iSpeed) = 0 Sets the turbulence speed of the wind.
Parameters: iSpeed – wind turbulence speed between 0 and 1. Returns: RED_OK if the method has succeeded, RED_FAIL otherwise.
-
