class ART::IWorld

Global planetary system interface. More...

#include <ARTIWorld.h>

Inherits: IREDObject.

Public functions:

virtual RED_RCAddCelestialBody ( RED::Object * iBody ) = 0
virtual RED_RCAddCustomShape ( RED::Object * iShape, bool iDefaultMaterial = true ) = 0
virtual RED_RCClearCelestialBodies ( ) = 0
virtual RED_RCFocusObserverOnGeometry ( RED::Object * iGeometry ) = 0
virtual intGetCelestialBodiesCount ( ) const = 0
virtual RED::Object *GetCelestialBody ( int iNumber ) const = 0
virtual voidGetErrorTrackingCallback ( RED::REDSDK_ERROR_CALLBACK & oCallback, void *& oUser ) const = 0
virtual doubleGetGlobalElapsedTime ( ) const = 0
virtual doubleGetGlobalTimeOverride ( ) const = 0
virtual doubleGetLastFrameTime ( ) const = 0
virtual RED::Object *GetPlanet ( ART::PLANET_ID iID ) const = 0
virtual doubleGetSimulationElapsedTime ( ) const = 0
virtual doubleGetSimulationLastFrameTime ( ) const = 0
virtual doubleGetSimulationTimeScale ( ) const = 0
virtual RED::Object *GetStar ( ART::STAR_ID iID ) const = 0
virtual doubleGetTimeNow ( ) const = 0
virtual RED_RCGetWindowSize ( int & oWidth, int & oHeight ) const = 0
virtual boolIsOculusRendering ( ) const = 0
virtual boolIsOpenVRRendering ( ) const = 0
virtual boolIsStarted ( ) const = 0
virtual voidOverrideGlobalTime ( double iElapsed ) = 0
virtual RED_RCPick ( bool & oIsPick, double oPick[3], int iX, int iY ) const = 0
virtual RED_RCPickCustomShapes ( bool & oIsPick, RED::ShapePath & oShapePath, int iX, int iY ) const = 0
virtual RED_RCPickGeometry ( bool & oIsPick, double oPick[3], RED::Object *& oGeometry, RED::ShapePath & oShapePath, int iX, int iY ) const = 0
virtual RED_RCRemoveCustomShape ( RED::Object * iShape ) = 0
virtual RED_RCResizeWindow ( int iNewWidth, int iNewHeight ) = 0
virtual RED_RCSave ( const RED::String & iPath, const RED::Matrix * iOrigin = NULL, ART::ProgressCallback iProgress = NULL, void * iParam = NULL ) = 0
virtual voidSetErrorTrackingCallback ( RED::REDSDK_ERROR_CALLBACK iCallback, void * iUser ) = 0
virtual voidSetSimulationTimeScale ( double iTimeScale ) = 0
virtual RED_RCSetupEarthSystem ( ) = 0
virtual RED_RCSetupSolarSystem ( ) = 0
virtual RED_RCShutdown ( ) = 0
virtual RED_RCStart ( RED::Object * iWindow, ART::ProgressCallback iProgress = NULL, void * iParam = NULL ) = 0
virtual RED_RCStartOculusRendering ( ) = 0
virtual RED_RCStartOpenVRRendering ( ) = 0
virtual RED_RCStopOculusRendering ( ) = 0
virtual RED_RCStopOpenVRRendering ( ) = 0
virtual RED_RCUpdate ( ) = 0

Public static functions:

static RED::CIDGetClassID ( )

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

Adds a new celestial body to the world.

Parameters:

iBody:The celestial body to add.

Returns:

RED_OK if the operation has succeeded,
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,
booliDefaultMaterial = 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.

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_OK if the function has succeeded,
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.

Releases all registered celestial bodies in the world.

This method will destroy all registered celestial bodies in the world.

Returns:

RED_OK if the operation has succeeded,
RED_WORKFLOW_ERROR if the world simulation has begun.

Focuses the observer on a given geometry.

The geometry and the observer must be situated on the same planet.

Parameters:

iGeometry:the geometry to focus.

Returns:

RED_OK if the operation has succeeded,
RED_FAIL otherwise.
public virtual int ART::IWorld::GetCelestialBodiesCount() const = 0

Returns:

The number of celestial bodies in our system.
public virtual RED::Object * ART::IWorld::GetCelestialBody(intiNumber) const = 0

Accesses to a registered celestial body.

Parameters:

iNumber:Celestial body number in world list.

Returns:

The corresponding object address. NULL if iNumber is not a valid body number.
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:

The total time spent since the world timer has been started in milliseconds.
public virtual double ART::IWorld::GetGlobalTimeOverride() const = 0

Returns:

The global time override value. This value can be negative is time is not overriden.
public virtual double ART::IWorld::GetLastFrameTime() const = 0

Returns:

The time spent during the last simulation update, in milliseconds.
public virtual RED::Object * ART::IWorld::GetPlanet(ART::PLANET_IDiID) 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:

The corresponding object address, NULL, if no body has the iID identifier.
public virtual double ART::IWorld::GetSimulationElapsedTime() const = 0

Returns:

The simulation elapsed time in milliseconds. This time includes the user time scale.
public virtual double ART::IWorld::GetSimulationLastFrameTime() const = 0

Returns:

The duration of the last update, including the user time scale.
public virtual double ART::IWorld::GetSimulationTimeScale() const = 0

Returns:

The current time scale.
public virtual RED::Object * ART::IWorld::GetStar(ART::STAR_IDiID) 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:

The corresponding object address, NULL, if no body has the iID identifier.
public virtual double ART::IWorld::GetTimeNow() const = 0

Returns:

The time now in milliseconds. Can be compared to the global elapsed time.
public virtual RED_RC ART::IWorld::GetWindowSize(int &oWidth,
int &oHeight
)const = 0

Gets the simulation window size.

Parameters:

oWidth:Returned window width.
oHeight:Returned window height.

Returns:

RED_OK if the method has succeeded,
Other RED_RCs from REDsdk operations involved in the resize operation.
public virtual bool ART::IWorld::IsOculusRendering() const = 0

Tests if we are in the Oculus rendering mode.

Returns:

whether we are in the Oculus rendering mode or not.
public virtual bool ART::IWorld::IsOpenVRRendering() const = 0

Tests if we are in the OpenVR rendering mode.

Returns:

whether we are in the OpenVR rendering mode or not.
public virtual bool ART::IWorld::IsStarted() const = 0

Returns:

true if the world simulation is started, false otherwise.
public virtual void ART::IWorld::OverrideGlobalTime(doubleiElapsed) = 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,
doubleoPick[3],
intiX,
intiY
)const = 0

Picks the world model from a given set of window coordinates.

The first found picked position is returned.

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.

Returns:

RED_OK if the operation has succeeded,
Any other RED_RC from RED::IWindow::FramePicking.
public virtual RED_RC ART::IWorld::PickCustomShapes(bool &oIsPick,
RED::ShapePath &oShapePath,
intiX,
intiY
)const = 0

Picks the custom shapes.

Parameters:

oIsPick:True if we have picked something.
oShapePath:The resulting picking results, in the coordinate system of the considered custom shapes.
iX:Window picking coordinates.
iY:Window picling coordinates.

Returns:

RED_OK if the method has succeeded,
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,
doubleoPick[3],
RED::Object *&oGeometry,
RED::ShapePath &oShapePath,
intiX,
intiY
)const = 0

Picks the geometries of the world from a given set of window coordinates.

The nearest picked position is returned.

Parameters:

oIsPick:Set to true if we have picked a geometry, false otherwise.
oPick:The 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:

RED_OK if the operation has succeeded,
Any other RED_RC from RED::IWindow::FramePicking.

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_OK if the function has succeeded,
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::ResizeWindow(intiNewWidth,
intiNewHeight
) = 0

Resizes the window that runs the simulation.

Effects are visible in the next ART::IWorld::Update.

Parameters:

iNewWidth:The new window width.
iNewHeight:The new window height.

Returns:

RED_OK if the method has succeeded,
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::ProgressCallbackiProgress = 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:

RED_OK if the operation has succeeded,
RED_FAIL otherwise.
public virtual void ART::IWorld::SetErrorTrackingCallback(RED::REDSDK_ERROR_CALLBACKiCallback,
void *iUser
) = 0

Sets up an error tracking callback.

Parameters:

iCallback:The error handling callback.
iUser:User parameter.
public virtual void ART::IWorld::SetSimulationTimeScale(doubleiTimeScale) = 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.

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_OK if the operation has succeeded,
RED_ALLOC_FAILURE if a memory allocation has failed,
RED_FAIL otherwise.

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_OK if the opeation has succeeded,
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:

RED_OK if the operation has succeeded,
Any other RED_RC code resulting of simulation shutdown operations.
public virtual RED_RC ART::IWorld::Start(RED::Object *iWindow,
ART::ProgressCallbackiProgress = 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_OK if the method has succeeded,
RED_BAD_PARAM if iWindow is invalid,
Any other RED_RC code resulting of simulation startup operations.

Starts the Oculus rendering mode.

Returns:

RED_OK if the operation has succeeded,
RED_FAIL otherwise.

Starts the OpenVR rendering mode.

Returns:

RED_OK if the operation has succeeded,
RED_FAIL otherwise.

Stops the Oculus rendering mode.

Returns:

RED_OK if the operation has succeeded,
RED_FAIL otherwise.

Stops the OpenVR rendering mode.

Returns:

RED_OK if the operation has succeeded,
RED_FAIL otherwise.
public virtual RED_RC ART::IWorld::Update() = 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.

Returns:

RED_OK if the method has succeeded,
Any other RED_RC code resulting of simulation startup operations.