class ART::IWorld
Global planetary system interface. More...
#include <ARTIWorld.h>
Inherits: IREDObject.
Public functions:
virtual RED_RC | AddCelestialBody ( RED::Object * iBody ) = 0 |
virtual RED_RC | AddCustomShape ( RED::Object * iShape, bool iDefaultMaterial = true ) = 0 |
virtual RED_RC | AddEntity ( RED::Object * iEntity ) = 0 |
virtual RED_RC | ClearCelestialBodies ( ) = 0 |
virtual RED_RC | ClearEntities ( ) = 0 |
virtual RED_RC | EnableCustomShapes ( bool iEnable ) = 0 |
virtual RED_RC | FocusObserverOnGeometry ( RED::Object * iGeometry ) = 0 |
virtual int | GetCelestialBodiesCount ( ) const = 0 |
virtual RED::Object * | GetCelestialBody ( int iNumber ) const = 0 |
virtual RED_RC | GetEntitiesCount ( unsigned int & oCount ) const = 0 |
virtual RED_RC | GetEntity ( RED::Object *& oEntity, unsigned int iIndex ) const = 0 |
virtual void | GetErrorTrackingCallback ( RED::REDSDK_ERROR_CALLBACK & oCallback, void *& oUser ) const = 0 |
virtual double | GetGlobalElapsedTime ( ) const = 0 |
virtual double | GetGlobalTimeOverride ( ) const = 0 |
virtual double | GetLastFrameTime ( ) const = 0 |
virtual RED::Object * | GetPlanet ( ART::PLANET_ID iID ) const = 0 |
virtual double | GetSimulationElapsedTime ( ) const = 0 |
virtual double | GetSimulationLastFrameTime ( ) const = 0 |
virtual double | GetSimulationTimeScale ( ) const = 0 |
virtual RED::Object * | GetStar ( ART::STAR_ID iID ) const = 0 |
virtual double | GetTimeNow ( ) const = 0 |
virtual RED::Object * | GetWindow ( ) const = 0 |
virtual RED_RC | GetWindowSize ( int & oWidth, int & oHeight ) const = 0 |
virtual bool | IsLandscapeUpdateDone ( ) const = 0 |
virtual bool | IsOculusRendering ( ) const = 0 |
virtual bool | IsOpenVRRendering ( ) const = 0 |
virtual bool | IsStarted ( ) const = 0 |
virtual void | OverrideGlobalTime ( double iElapsed ) = 0 |
virtual RED_RC | Pick ( bool & oIsPick, double oPick[3], int iX, int iY, bool iPickDeferred, bool iPickTranspar, bool iPickClouds ) const = 0 |
RED_RC | PickClouds ( bool & oIsPick, RED::String & oCloudName, int iX, int iY ) const |
virtual RED_RC | PickCloudsCovers ( bool & oIsPick, RED::Object *& oCloudsCover, int iX, int iY ) const = 0 |
virtual RED_RC | PickCustomShapes ( bool & oIsPick, RED::ShapePath & oShapePath, int iX, int iY ) const = 0 |
virtual RED_RC | PickCustomShapes ( bool & oIsPick, RED::Vector< RED::ShapePath > & oShapePath, int iX, int iY ) const = 0 |
virtual RED_RC | PickGeometry ( bool & oIsPick, double oPick[3], double oNorm[3], RED::Object *& oGeometry, RED::ShapePath & oShapePath, int iX, int iY ) const = 0 |
RED_RC | PickPrisms ( bool & oIsPick, RED::String & oPrismName, int iX, int iY ) const |
virtual RED_RC | RemoveCustomShape ( RED::Object * iShape ) = 0 |
virtual RED_RC | RemoveEntity ( RED::Object * iEntity ) = 0 |
virtual RED_RC | ResizeWindow ( int iNewWidth, int iNewHeight ) = 0 |
virtual RED_RC | Save ( const RED::String & iPath, const RED::Matrix * iOrigin = NULL, ART::ProgressCallback iProgress = NULL, void * iParam = NULL ) = 0 |
virtual void | SetErrorTrackingCallback ( RED::REDSDK_ERROR_CALLBACK iCallback, void * iUser ) = 0 |
virtual void | SetOffscreenRendering ( bool iOnOff ) = 0 |
virtual void | SetSimulationElapsedTime ( double iElpased ) = 0 |
virtual void | SetSimulationTimeScale ( double iTimeScale ) = 0 |
virtual RED_RC | SetupEarthSystem ( ) = 0 |
virtual RED_RC | SetupSolarSystem ( ) = 0 |
virtual RED_RC | Shutdown ( ) = 0 |
virtual RED_RC | Start ( RED::Object * iWindow, ART::ProgressCallback iProgress = NULL, void * iParam = NULL ) = 0 |
virtual RED_RC | StartOculusRendering ( ) = 0 |
virtual RED_RC | StartOpenVRRendering ( ) = 0 |
virtual RED_RC | StopOculusRendering ( ) = 0 |
virtual RED_RC | StopOpenVRRendering ( ) = 0 |
virtual RED_RC | Update ( bool iSkipRendering = false ) = 0 |
Public static functions:
static RED::CID | GetClassID ( ) |
Detailed description:
Global planetary system interface.
One instance of the world class has to be created first, using the ART::Factory and the CID_ARTWorld identifier. The created object implements the ART::IWorld interface. The world is a singleton.
Functions documentation
public static RED::CID ART::IWorld::GetClassID | ( | ) |
public virtual RED_RC ART::IWorld::AddCelestialBody | ( | RED::Object * | iBody | ) = 0 |
Adds a new celestial body to the world.
Parameters:
iBody: | The celestial body to add. |
Returns:
RED_BAD_PARAM if iBody was NULL or was not a celestial body,
RED_WORKFLOW_ERROR if the world simulation has begun,
RED_ALLOC_FAILURE if a memory allocation has failed,
RED_FAIL if iBody has been added already to our world.
public virtual RED_RC ART::IWorld::AddCustomShape | ( | RED::Object * | iShape, |
bool | iDefaultMaterial = true | ||
) | = 0 |
Add a REDsdk graphics shape to the rendering pipeline.
The shape is added at the end of the rendering pipeline in a dedicated camera defined using the observer viewing matrix. This method must be called from the rendering thread. The method does nothing if iShape is already registered as a custom shape.
If iDefaultMaterial is true a default color / depth based rendering material is applied to iShape: The RED::MCL_COLOR channel of the shape's vertices define the color of the custom shape and rendered shapes are hidden by objects in front of them. This material is managed by the ART::IAssetManager and does not need to be relased by the caller.
If the added custom shape iShape have a bounding sphere, it will be considered in the calculation of the observer near and far distances. Otherwise it will be ignored and this may lead to the shape disappearing under some circumstances.
Parameters:
iShape: | The shape to add. |
iDefaultMaterial: | If true, a color based material is applied to iShape (which does not prevent iShape's children to have their own materials); if false, iShape's DAG materials are used. |
Returns:
RED_BAD_PARAM if the method has received an invalid parameter,
RED_INIT_FAILED if the method is called before the world has been initialized,
RED_ALLOC_FAILURE if a memory allocation has failed,
RED_FAIL otherwise.
public virtual RED_RC ART::IWorld::AddEntity | ( | RED::Object * | iEntity | ) = 0 |
Adds a new entity to the simulation.
Parameters:
oEntity: | returned new entity as ART::IEntity. |
Returns:
public virtual RED_RC ART::IWorld::ClearCelestialBodies | ( | ) = 0 |
Releases all registered celestial bodies in the world.
This method will destroy all registered celestial bodies in the world.
Returns:
public virtual RED_RC ART::IWorld::ClearEntities | ( | ) = 0 |
public virtual RED_RC ART::IWorld::EnableCustomShapes | ( | bool | iEnable | ) = 0 |
Enables or disables the custom shapes.
Parameters:
iEnable: | True to enable the custom shapes, false to disable them. |
Returns:
RED_INIT_FAILED if the method is called before the world has been initialized,
RED_ALLOC_FAILURE if a memory allocation has failed,
RED_FAIL otherwise.
public virtual RED_RC ART::IWorld::FocusObserverOnGeometry | ( | RED::Object * | iGeometry | ) = 0 |
public virtual int ART::IWorld::GetCelestialBodiesCount | ( | ) const = 0 |
Returns:
public virtual RED::Object * ART::IWorld::GetCelestialBody | ( | int | iNumber | ) const = 0 |
Accesses to a registered celestial body.
Parameters:
iNumber: | Celestial body number in world list. |
Returns:
public virtual RED_RC ART::IWorld::GetEntitiesCount | ( | unsigned int & | oCount | ) const = 0 |
public virtual RED_RC ART::IWorld::GetEntity | ( | RED::Object *& | oEntity, |
unsigned int | iIndex | ||
) | const = 0 |
Gets an entity by its index.
Parameters:
oEntity: | returned entity as ART::IEntity. |
iIndex: | index of the entity. |
Returns:
public virtual void ART::IWorld::GetErrorTrackingCallback | ( | RED::REDSDK_ERROR_CALLBACK & | oCallback, |
void *& | oUser | ||
) | const = 0 |
Access to the current error tracking callback.
Parameters:
oCallback: | The current callback. |
oUser: | Current user parameter. |
public virtual double ART::IWorld::GetGlobalElapsedTime | ( | ) const = 0 |
Returns:
public virtual double ART::IWorld::GetGlobalTimeOverride | ( | ) const = 0 |
Returns:
public virtual double ART::IWorld::GetLastFrameTime | ( | ) const = 0 |
Returns:
public virtual RED::Object * ART::IWorld::GetPlanet | ( | ART::PLANET_ID | iID | ) const = 0 |
Accesses to a planetary body declared in the solar or earth system.
The world must have been setup using ART::IWorld::SetupSolarSystem or ART::IWorld::SetupEarthSystem.
Parameters:
iID: | Identifier of the planet. |
Returns:
public virtual double ART::IWorld::GetSimulationElapsedTime | ( | ) const = 0 |
Returns:
public virtual double ART::IWorld::GetSimulationLastFrameTime | ( | ) const = 0 |
Returns:
public virtual double ART::IWorld::GetSimulationTimeScale | ( | ) const = 0 |
Returns:
public virtual RED::Object * ART::IWorld::GetStar | ( | ART::STAR_ID | iID | ) const = 0 |
Accesses to a star body declared in the solar or earth system.
The world must have been setup using ART::IWorld::SetupSolarSystem or ART::IWorld::SetupEarthSystem.
Parameters:
iID: | Identifier of the star. |
Returns:
public virtual double ART::IWorld::GetTimeNow | ( | ) const = 0 |
Returns:
public virtual RED::Object * ART::IWorld::GetWindow | ( | ) const = 0 |
Returns:
public virtual RED_RC ART::IWorld::GetWindowSize | ( | int & | oWidth, |
int & | oHeight | ||
) | const = 0 |
Gets the simulation window size.
Note that just after a ART::IWorld::ResizeWindow, the size has not changed yet. A loop in ART::IWorld::Update is required before a resizing order effectively takes place.
Parameters:
oWidth: | Returned window width. |
oHeight: | Returned window height. |
Returns:
Other RED_RCs from REDsdk operations involved in the resize operation.
public virtual bool ART::IWorld::IsLandscapeUpdateDone | ( | ) const = 0 |
Returns:
Landscape calculations are performed each frame until the wished quality is reached. This method returns true when the landscape meshing has been completed and will no longer change unless something happens.
public virtual bool ART::IWorld::IsOculusRendering | ( | ) const = 0 |
Tests if we are in the Oculus rendering mode.
Returns:
public virtual bool ART::IWorld::IsOpenVRRendering | ( | ) const = 0 |
Tests if we are in the OpenVR rendering mode.
Returns:
public virtual bool ART::IWorld::IsStarted | ( | ) const = 0 |
Returns:
public virtual void ART::IWorld::OverrideGlobalTime | ( | double | iElapsed | ) = 0 |
Override the world timer.
This method can be used to specify the amount of time elapsed. It overrides the real elapsed time returned by the world simulation timer otherwise.
Parameters:
iElapsed: | The amount of elapsed time in milliseconds since the world has started. If iElapsed is negative, the time is no longer overriden. |
public virtual RED_RC ART::IWorld::Pick | ( | bool & | oIsPick, |
double | oPick[3], | ||
int | iX, | ||
int | iY, | ||
bool | iPickDeferred, | ||
bool | iPickTranspar, | ||
bool | iPickClouds | ||
) | const = 0 |
Picks the world model from a given set of window coordinates.
The first found picked position is returned. The set of picked entities is specified by the method options.
Parameters:
oIsPick: | Set to true if we have picked something, false otherwise. |
oPick: | The picked position, WCS. |
iX: | Picked window coordinate. Screen origin is bottom left. |
iY: | Picked window coordinate. Screen origin is bottom left. |
iPickDeferred: | Set to true to pick all opaque entities on screen. |
iPickTranspar: | Set to true to pick the first transparent entity on screen. |
iPiclClouds: | Set to true to pick clouds. |
Returns:
public RED_RC ART::IWorld::PickClouds | ( | bool & | oIsPick, |
RED::String & | oCloudName, | ||
int | iX, | ||
int | iY | ||
) | const |
Picks clouds of the world from given window coordinates.
The picking method is based on cloud boxes enclosing clouds prisms shown in a clouds cover. Therefore, the accuracy of that picking is limited by the invisible boxes of clouds prisms surrounding the visible prism showing the cloud. The nearest picked cloud is returned. The name of the picked cloud is returned.
Parameters:
oIsPick: | Set to true if we have picked a geometry, false otherwise. |
oCloudName: | The name of the picked cloud object. |
iX: | Picked window coordinate. Screen origin is bottom left. |
iY: | Picked window coordinate. Screen origin is bottom left. |
Returns:
public virtual RED_RC ART::IWorld::PickCloudsCovers | ( | bool & | oIsPick, |
RED::Object *& | oCloudsCover, | ||
int | iX, | ||
int | iY | ||
) | const = 0 |
Picks clouds covers of the world from given window coordinates.
The nearest picked clouds cover is returned. Note that clouds covers boxes are being picked.
Parameters:
oIsPick: | Set to true if we have picked a geometry, false otherwise. |
oCloudsCover: | The picked clouds cover object. |
iX: | Picked window coordinate. Screen origin is bottom left. |
iY: | Picked window coordinate. Screen origin is bottom left. |
Returns:
public virtual RED_RC ART::IWorld::PickCustomShapes | ( | bool & | oIsPick, |
RED::ShapePath & | oShapePath, | ||
int | iX, | ||
int | iY | ||
) | const = 0 |
Picks custom shapes.
Parameters:
oIsPick: | True if we have picked something. |
oShapePath: | The first picking result, in the coordinate system of the considered custom shapes. |
iX: | Window picking coordinates. |
iY: | Window picling coordinates. |
Returns:
RED_BAD_PARAM if the method has received an invalid parameter,
Other RED_RC values from REDsdk.
public virtual RED_RC ART::IWorld::PickCustomShapes | ( | bool & | oIsPick, |
RED::Vector< RED::ShapePath > & | oShapePath, | ||
int | iX, | ||
int | iY | ||
) | const = 0 |
Picks custom shapes.
Parameters:
oIsPick: | True if we have picked something. |
oShapePaths: | The complete list of picked custom shapes, in the coordinate system of the considered custom shapes. |
iX: | Window picking coordinates. |
iY: | Window picling coordinates. |
Returns:
RED_BAD_PARAM if the method has received an invalid parameter,
Other RED_RC values from REDsdk.
public virtual RED_RC ART::IWorld::PickGeometry | ( | bool & | oIsPick, |
double | oPick[3], | ||
double | oNorm[3], | ||
RED::Object *& | oGeometry, | ||
RED::ShapePath & | oShapePath, | ||
int | iX, | ||
int | iY | ||
) | const = 0 |
Picks the geometries of the world from given window coordinates.
The nearest picked geometry is returned.
Parameters:
oIsPick: | Set to true if we have picked a geometry, false otherwise. |
oPick: | The picked position, WCS. |
oNorm: | The normal to the geometry at picked position, WCS. |
oGeometry: | The picked ART::Geometry. |
oShapePath: | The shape path of the picked geometry part. |
iX: | Picked window coordinate. Screen origin is bottom left. |
iY: | Picked window coordinate. Screen origin is bottom left. |
Returns:
public RED_RC ART::IWorld::PickPrisms | ( | bool & | oIsPick, |
RED::String & | oPrismName, | ||
int | iX, | ||
int | iY | ||
) | const |
Picks prisms of the world from given window coordinates.
The picking method is based on prisms boxes generated for a biome applied onto a landscape. Prisms boxes remain valid even if the prism is replaced by its mesh. Therefore, the accuracy of that picking is limited by the invisible boxes of prisms surrounding the visible prism mesh or prism showing the plant. The nearest found prism is returned by its name.
Parameters:
oIsPick: | Set to true if we have picked a prism , false otherwise. |
oPrismName: | The name of the picked prism object. |
iX: | Picked window coordinate. Screen origin is bottom left. |
iY: | Picked window coordinate. Screen origin is bottom left. |
Returns:
public virtual RED_RC ART::IWorld::RemoveCustomShape | ( | RED::Object * | iShape | ) = 0 |
Remove a custom shape from the rendering pipeline. The shape is not destroyed by the method.
This method must be called from the rendering thread. The method does nothing if iShape is either NULL or not found.
Parameters:
iShape: | The shape to remove. |
Returns:
RED_INIT_FAILED if the method is called before the world has been initialized,
RED_ALLOC_FAILURE if a memory allocation has failed,
RED_FAIL otherwise.
public virtual RED_RC ART::IWorld::RemoveEntity | ( | RED::Object * | iEntity | ) = 0 |
Removes an entity from the simulation.
Parameters:
iEntity: | entity to destroy as ART::IEntity. |
Returns:
public virtual RED_RC ART::IWorld::ResizeWindow | ( | int | iNewWidth, |
int | iNewHeight | ||
) | = 0 |
Resizes the window that runs the simulation.
The method internally triggers one world update. The resize occurs right after.
Parameters:
iNewWidth: | The new window width. |
iNewHeight: | The new window height. |
Returns:
RED_BAD_PARAM if a size is lower than or equal to zero,
Other RED_RCs from REDsdk operations involved in the resize operation.
public virtual RED_RC ART::IWorld::Save | ( | const RED::String & | iPath, |
const RED::Matrix * | iOrigin = NULL, | ||
ART::ProgressCallback | iProgress = NULL, | ||
void * | iParam = NULL | ||
) | = 0 |
Saves the world as a .red or .fbx file.
Parameters:
iPath: | The complete file path to save. The extensions defines the kind of file being saved. |
iOrigin: | Optional origin matrix in planet coordinates system. If we have an export area set in the planetary setup, the origin is taken from the export area. If we have no export area set, then the origin is either iOrigin when valid or the observer position. |
iProgress: | Progress indicator callback. |
iParam: | Optional progress indicator callback data. |
Returns:
public virtual void ART::IWorld::SetErrorTrackingCallback | ( | RED::REDSDK_ERROR_CALLBACK | iCallback, |
void * | iUser | ||
) | = 0 |
Sets up an error tracking callback.
Parameters:
iCallback: | The error handling callback. |
iUser: | User parameter. |
public virtual void ART::IWorld::SetOffscreenRendering | ( | bool | iOnOff | ) = 0 |
Turn on or off offscreen rendering for the window that runs the simulation.
When offscreen rendering is turned on, REDart removes all its data from the main VRL of the simulation window. The main window VRL is not desactivated however by the method. It remains "as is" and REDart no longer renders into it. When offscreen rendering is turned off, REDart renders into the main VRL of the window to produce the final image result.
The final image of the rendering can be accessed from the VRL number 1 of the window directly (regardless of whether offscreen rendering is on or off).
This method may be called before the simulation startup. When called during the course of a simulation, there's a one frame delay before it's effect can be visible.
Parameters:
iOnOff: | Set to true to turn on offscreen rendering, set to false to turn off offscreen rendering. |
public virtual void ART::IWorld::SetSimulationElapsedTime | ( | double | iElpased | ) = 0 |
Sets the simulation elapsed time in milliseconds.
public virtual void ART::IWorld::SetSimulationTimeScale | ( | double | iTimeScale | ) = 0 |
Modifies the time scale.
The time scale affects simulation times (ex: ART::IWorld::GetSimulationElapsedTime). Real time values (ex: ART::IWorld::GetGlobalElapsedTime) are not modified by the time scale.
Parameters:
iTimeScale: | New time scale to apply to the simulation time. Negative or zero values stop the progress of the simulation in time, but don't stop the simulation itself. |
public virtual RED_RC ART::IWorld::SetupEarthSystem | ( | ) = 0 |
Sets up a default Earth-like-planet-with-sun system.
This method builds a system including a planet and a star. They are both initialized to match our Earth and sun features.
Returns:
RED_ALLOC_FAILURE if a memory allocation has failed,
RED_FAIL otherwise.
public virtual RED_RC ART::IWorld::SetupSolarSystem | ( | ) = 0 |
Sets up a default solar system.
This method builds a default solar system. It's made of the Sun, Mercury, Venus, Earth, Mars, Jupiter Saturn, Uranus and Neptune. All planets are initialized.
Returns:
RED_ALLOC_FAILURE if a memory allocation has failed,
RED_FAIL otherwise.
public virtual RED_RC ART::IWorld::Shutdown | ( | ) = 0 |
Terminates the simulation.
The simulation can be restarted afterwards, calling again ART::IWorld::Start. The current REDsdk transaction is not closed by the method.
Returns:
public virtual RED_RC ART::IWorld::Start | ( | RED::Object * | iWindow, |
ART::ProgressCallback | iProgress = NULL, | ||
void * | iParam = NULL | ||
) | = 0 |
Starts the simulation.
On first start, all options are set to default. On restarting after a shutdown, options that were modified are kept unchanged. The simulation will start an internal update thread and possibly several auxiliary landscape calculation threads. A REDsdk transaction is started by the method.
Parameters:
iWindow: | The rendering window to use for the simulation display. |
iProgress: | Pointer to an optional progress indicator callback. |
iParam: | Optional parameter to the progress indicator callback. |
Returns:
RED_BAD_PARAM if iWindow is invalid,
Any other RED_RC code resulting of simulation startup operations.
public virtual RED_RC ART::IWorld::StartOculusRendering | ( | ) = 0 |
public virtual RED_RC ART::IWorld::StartOpenVRRendering | ( | ) = 0 |
public virtual RED_RC ART::IWorld::StopOculusRendering | ( | ) = 0 |
public virtual RED_RC ART::IWorld::StopOpenVRRendering | ( | ) = 0 |
public virtual RED_RC ART::IWorld::Update | ( | bool | iSkipRendering = false | ) = 0 |
Updates the simulation.
During the update method, the rendering of the REDart window (defined by ART::IWorld::Start) occurs. A REDsdk transaction is closed and re-opened for this, so a REDsdk transaction is always available after this method's execution.
iSkipRendering can be turned on when updates have to be performed as fast as possible until the IsLandscapeUpdateDone method returns true. Then calling Update again with iSkipRendering back to false will display the entire scene.
Parameters:
iSkipRendering: | Set to true to have the system do all updates, but skip the draw. |
Returns: