IWorld

Functions

SET_CID

RED_RC

SetupSolarSystem

RED_RC

SetupEarthSystem

int

GetCelestialBodiesCount

Object *

GetCelestialBody

Object *

GetPlanet

Object *

GetStar

RED_RC

AddCelestialBody

RED_RC

ClearCelestialBodies

RED_RC

AddCustomShape

RED_RC

RemoveCustomShape

RED_RC

EnableCustomShapes

bool

IsStarted

RED_RC

Start

RED_RC

Update

bool

IsLandscapeUpdateDone

RED_RC

Shutdown

Object *

GetWindow

RED_RC

ResizeWindow

RED_RC

GetWindowSize

void

SetOffscreenRendering

void

OverrideGlobalTime

double

GetGlobalTimeOverride

double

GetGlobalElapsedTime

double

GetLastFrameTime

double

GetTimeNow

double

GetSimulationElapsedTime

void

SetSimulationElapsedTime

double

GetSimulationLastFrameTime

void

SetSimulationTimeScale

double

GetSimulationTimeScale

RED_RC

Pick

RED_RC

PickGeometry

RED_RC

PickCloudsCovers

RED_RC

PickClouds

RED_RC

PickPrisms

RED_RC

PickCustomShapes

RED_RC

PickCustomShapes

RED_RC

StartOculusRendering

RED_RC

StopOculusRendering

bool

IsOculusRendering

RED_RC

StartOpenVRRendering

RED_RC

StopOpenVRRendering

bool

IsOpenVRRendering

RED_RC

AddEntity

RED_RC

RemoveEntity

RED_RC

ClearEntities

RED_RC

GetEntitiesCount

RED_RC

GetEntity

void

SetErrorTrackingCallback

void

GetErrorTrackingCallback

RED_RC

Save

RED_RC

FocusObserverOnGeometry

Detailed Description

class IWorld : public RED::IREDObject

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.

Public Functions

SET_CID(CID_class_ARTIWorld)
virtual RED_RC 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_OK if the opeation has succeeded,

RED_ALLOC_FAILURE if a memory allocation has failed,

RED_FAIL otherwise.

virtual RED_RC 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_OK if the operation has succeeded,

RED_ALLOC_FAILURE if a memory allocation has failed,

RED_FAIL otherwise.

virtual int GetCelestialBodiesCount() const = 0
Returns

The number of celestial bodies in our system.

virtual RED::Object *GetCelestialBody(int iNumber) 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.

virtual RED::Object *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

The corresponding object address, NULL, if no body has the iID identifier.

virtual RED::Object *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

The corresponding object address, NULL, if no body has the iID identifier.

virtual RED_RC AddCelestialBody(RED::Object *iBody) = 0

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.

virtual RED_RC ClearCelestialBodies() = 0

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.

virtual RED_RC 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_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.

virtual RED_RC 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_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.

virtual RED_RC EnableCustomShapes(bool iEnable) = 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.

virtual bool IsStarted() const = 0
Returns

true if the world simulation is started, false otherwise.

virtual RED_RC 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_OK if the method has succeeded,

RED_BAD_PARAM if iWindow is invalid,

Any other RED_RC code resulting of simulation startup operations.

virtual RED_RC 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

RED_OK if the method has succeeded,

Any other RED_RC code resulting of simulation startup operations.

virtual bool IsLandscapeUpdateDone() const = 0

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.

Returns

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

virtual RED_RC 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.

virtual RED::Object *GetWindow() const = 0
Returns

The address of the window used to run the simulation.

virtual RED_RC 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_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.

virtual RED_RC 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.

virtual void 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.

virtual void 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.

virtual double GetGlobalTimeOverride() const = 0
Returns

The global time override value. This value can be negative is time is not overriden.

virtual double GetGlobalElapsedTime() const = 0
Returns

The total time spent since the world timer has been started in milliseconds.

virtual double GetLastFrameTime() const = 0
Returns

The time spent during the last simulation update, in milliseconds.

virtual double GetTimeNow() const = 0
Returns

The time now in milliseconds. Can be compared to the global elapsed time.

virtual double GetSimulationElapsedTime() const = 0
Returns

The simulation elapsed time in milliseconds. This time includes the user time scale.

virtual void SetSimulationElapsedTime(double iElpased) = 0

Sets the simulation elapsed time in milliseconds.

virtual double GetSimulationLastFrameTime() const = 0
Returns

The duration of the last update, including the user time scale.

virtual void 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.

virtual double GetSimulationTimeScale() const = 0
Returns

The current time scale.

virtual RED_RC 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

RED_OK if the operation has succeeded,

Any other RED_RC from

RED::IWindow::FramePicking.

virtual RED_RC 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

RED_OK if the operation has succeeded,

Any other RED_RC from

RED::IWindow::FramePicking.

virtual RED_RC 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

RED_OK if the operation has succeeded,

Any other RED_RC from

RED::IWindow::FramePicking.

RED_RC 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

RED_OK if the operation has succeeded,

Any other RED_RC from

RED::IWindow::FramePicking.

RED_RC 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

RED_OK if the operation has succeeded,

Any other RED_RC from

RED::IWindow::FramePicking.

virtual RED_RC 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_OK if the method has succeeded,

RED_BAD_PARAM if the method has received an invalid parameter,

Other RED_RC values from REDsdk.

virtual RED_RC 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_OK if the method has succeeded,

RED_BAD_PARAM if the method has received an invalid parameter,

Other RED_RC values from REDsdk.

virtual RED_RC StartOculusRendering() = 0

Starts the Oculus rendering mode.

Returns

RED_OK if the operation has succeeded,

RED_FAIL otherwise.

virtual RED_RC StopOculusRendering() = 0

Stops the Oculus rendering mode.

Returns

RED_OK if the operation has succeeded,

RED_FAIL otherwise.

virtual bool IsOculusRendering() const = 0

Tests if we are in the Oculus rendering mode.

Returns

whether we are in the Oculus rendering mode or not.

virtual RED_RC StartOpenVRRendering() = 0

Starts the OpenVR rendering mode.

Returns

RED_OK if the operation has succeeded,

RED_FAIL otherwise.

virtual RED_RC StopOpenVRRendering() = 0

Stops the OpenVR rendering mode.

Returns

RED_OK if the operation has succeeded,

RED_FAIL otherwise.

virtual bool IsOpenVRRendering() const = 0

Tests if we are in the OpenVR rendering mode.

Returns

whether we are in the OpenVR rendering mode or not.

virtual RED_RC 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.

virtual RED_RC 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.

virtual RED_RC ClearEntities() = 0

Removes all the entities from the simulation.

Returns

RED_OK if the method has succeeded,

RED_FAIL otherwise.

virtual RED_RC 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.

virtual RED_RC 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

RED_OK if the method has succeeded,

RED_FAIL otherwise.

virtual void SetErrorTrackingCallback(RED::REDSDK_ERROR_CALLBACK iCallback, void *iUser) = 0

Sets up an error tracking callback.

Parameters
  • iCallback – The error handling callback.

  • iUser – User parameter.

virtual void 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.

virtual RED_RC 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

RED_OK if the operation has succeeded,

RED_FAIL otherwise.

virtual RED_RC FocusObserverOnGeometry(RED::Object *iGeometry) = 0

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.