IWorld
Functions
int |
|
Object * |
|
Object * |
|
Object * |
|
bool |
|
bool |
|
Object * |
|
void |
|
void |
|
double |
|
double |
|
double |
|
double |
|
double |
|
void |
|
double |
|
void |
|
double |
|
bool |
|
bool |
|
void |
|
void |
|
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.
-
SET_CID(CID_class_ARTIWorld)
