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_RCAddEntity ( RED::Object * iEntity ) = 0
virtual RED_RCClearCelestialBodies ( ) = 0
virtual RED_RCClearEntities ( ) = 0
virtual RED_RCEnableCustomShapes ( bool iEnable ) = 0
virtual RED_RCFocusObserverOnGeometry ( RED::Object * iGeometry ) = 0
virtual intGetCelestialBodiesCount ( ) const = 0
virtual RED::Object *GetCelestialBody ( int iNumber ) const = 0
virtual RED_RCGetEntitiesCount ( unsigned int & oCount ) const = 0
virtual RED_RCGetEntity ( RED::Object *& oEntity, unsigned int iIndex ) 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::Object *GetWindow ( ) const = 0
virtual RED_RCGetWindowSize ( int & oWidth, int & oHeight ) const = 0
virtual boolIsLandscapeUpdateDone ( ) 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, bool iPickDeferred, bool iPickTranspar, bool iPickClouds ) const = 0
RED_RCPickClouds ( bool & oIsPick, RED::String & oCloudName, int iX, int iY ) const
virtual RED_RCPickCloudsCovers ( bool & oIsPick, RED::Object *& oCloudsCover, int iX, int iY ) const = 0
virtual RED_RCPickCustomShapes ( bool & oIsPick, RED::ShapePath & oShapePath, int iX, int iY ) const = 0
virtual RED_RCPickCustomShapes ( bool & oIsPick, RED::Vector< RED::ShapePath > & oShapePath, int iX, int iY ) const = 0
virtual RED_RCPickGeometry ( bool & oIsPick, double oPick[3], double oNorm[3], RED::Object *& oGeometry, RED::ShapePath & oShapePath, int iX, int iY ) const = 0
RED_RCPickPrisms ( bool & oIsPick, RED::String & oPrismName, int iX, int iY ) const
virtual RED_RCRemoveCustomShape ( RED::Object * iShape ) = 0
virtual RED_RCRemoveEntity ( RED::Object * iEntity ) = 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 voidSetOffscreenRendering ( bool iOnOff ) = 0
virtual voidSetSimulationElapsedTime ( double iElpased ) = 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 ( bool iSkipRendering = false ) = 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.

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_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.
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:

RED_OK if the method has succeeded,
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.
public virtual RED_RC ART::IWorld::ClearEntities() = 0

Removes all the entities from the simulation.

Returns:

RED_OK if the method has succeeded,
RED_FAIL otherwise.
public virtual RED_RC ART::IWorld::EnableCustomShapes(booliEnable) = 0

Enables or disables the custom shapes.

Parameters:

iEnable:True to enable the custom shapes, false to disable them.

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.

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 RED_RC ART::IWorld::GetEntitiesCount(unsigned int &oCount) const = 0

Gets the number of entities in the world.

Parameters:

oCount:returned number of entities.

Returns:

RED_OK if the method has succeeded,
RED_FAIL otherwise.
public virtual RED_RC ART::IWorld::GetEntity(RED::Object *&oEntity,
unsigned intiIndex
)const = 0

Gets an entity by its index.

Parameters:

oEntity:returned entity as ART::IEntity.
iIndex:index of the entity.

Returns:

RED_OK if the method has succeeded,
RED_FAIL otherwise.
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::Object * ART::IWorld::GetWindow() const = 0

Returns:

The address of the window used to run the simulation.
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:

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

Returns:

true if the landscape update is finished, false if it's still in process.

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:

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,
booliPickDeferred,
booliPickTranspar,
booliPickClouds
)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:

RED_OK if the operation has succeeded,
Any other RED_RC from RED::IWindow::FramePicking.
public RED_RC ART::IWorld::PickClouds(bool &oIsPick,
RED::String &oCloudName,
intiX,
intiY
)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:

RED_OK if the operation has succeeded,
Any other RED_RC from RED::IWindow::FramePicking.
public virtual RED_RC ART::IWorld::PickCloudsCovers(bool &oIsPick,
RED::Object *&oCloudsCover,
intiX,
intiY
)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:

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 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_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::PickCustomShapes(bool &oIsPick,
RED::Vector< RED::ShapePath > &oShapePath,
intiX,
intiY
)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_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],
doubleoNorm[3],
RED::Object *&oGeometry,
RED::ShapePath &oShapePath,
intiX,
intiY
)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:

RED_OK if the operation has succeeded,
Any other RED_RC from RED::IWindow::FramePicking.
public RED_RC ART::IWorld::PickPrisms(bool &oIsPick,
RED::String &oPrismName,
intiX,
intiY
)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:

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::RemoveEntity(RED::Object *iEntity) = 0

Removes an entity from the simulation.

Parameters:

iEntity:entity to destroy as ART::IEntity.

Returns:

RED_OK if the method has succeeded,
RED_FAIL otherwise.
public virtual RED_RC ART::IWorld::ResizeWindow(intiNewWidth,
intiNewHeight
) = 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_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::SetOffscreenRendering(booliOnOff) = 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(doubleiElpased) = 0

Sets the simulation elapsed time in milliseconds.

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(booliSkipRendering = 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:

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