IPlanet
Functions
const String & |
|
Object * |
|
double |
|
const Matrix & |
|
const Matrix & |
|
const double * |
|
double |
|
double |
|
double |
|
double |
|
void |
|
void |
|
double |
|
void |
|
void |
|
bool |
|
const Matrix & |
|
void |
|
const Matrix & |
|
Object * |
|
Object * |
|
void |
|
double |
|
const Matrix & |
|
double |
|
const Matrix & |
|
const Matrix & |
|
void |
|
bool |
|
void |
|
bool |
|
void |
|
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.
-
SET_CID(CID_class_ARTIPlanet)
