Magnum::DartIntegration::World class
#include <Magnum/DartIntegration/World.h>

DART physics world.

Parses a dart::simulation::World for easy usage in Magnum. It basically parses all the dart::dynamics::Skeleton objects in the DART world and keeps track of a list of DartIntegration::Object instances. It automatically captures any change that occurs in the DART world. After each refresh() the user has access to deleted shapes via unusedObjects() and can get updated shapes (material or mesh) via updatedShapeObjects().

Usage

Common usage is to create a dart::simulation::World and then instantiate this class by passing a parent SceneGraph::Object and the DART world to its constructor:

dart::simulation::WorldPtr dartWorld = createWorldInDart();
addDartSkeletonsToDartWorld();
SceneGraph::Scene<SceneGraph::MatrixTransformation3D> scene;
SceneGraph::Object<SceneGraph::MatrixTransformation3D> object{&scene};

/* object should never be a SceneGraph::Scene */
DartIntegration::World world{object, *dartWorld};

Only the DART world can affect the transformation of the Magnum world and not the other way around. Of course, one can change things directly in the DART world and observe the changes in Magnum world. To update the world and get the updated shapes you can do the following:

/* Simulate with time step of 0.001 seconds */
world.world().setTimeStep(0.001);

for(UnsignedInt i = 0; i < simulationSteps; ++i) {
    world.step();

    /* Update graphics at ~60Hz (15*0.001 ~= 60Hz) */
    if(i % 15 == 0) {
        world.refresh();

        /* Get unused/deleted shapes */
        std::vector<std::unique_ptr<DartIntegration::Object>>& unusedObjects =
            world.unusedObjects();

        /* The user is expected to handle unused objects. One possible handling
           would be to remove them from the parent scene. */
        deleteObjectsFromScene(unusedObjects);

        /* Get updated shapes -- ones that either the materials or the meshes
          have changed */
        std::vector<std::reference_wrapper<DartIntegration::Object>>
            updatedObjects = world.updatedShapeObjects();

        updateMeshesAndMaterials(updatedObjects);

        /* Clear list of updated objects */
        world.clearUpdatedShapeObjects();
    }
}

Constructors, destructors, conversion operators

template<class T> World(T& object, dart::simulation::World& world) explicit: Constructor.
template<class T> World(PluginManager::Manager<Trade::AbstractImporter>& importerManager, T& object, dart::simulation::World& world) explicit: Construct with an external importer plugin manager.

Public functions

auto refresh() -> World&: Refresh/regenerate meshes for all bodies in DART world.
auto step(bool resetCommand = true) -> World&: Do a DART world step.
auto unusedObjects() -> std::vector<std::unique_ptr<Object>>&: Get unused objects.
auto objects() -> std::vector<std::reference_wrapper<Object>>: All objects managed by the world.
auto shapeObjects() -> std::vector<std::reference_wrapper<Object>>: All objects that have shapes.
auto bodyObjects() -> std::vector<std::reference_wrapper<Object>>: All objects that do not have shapes.
auto updatedShapeObjects() -> std::vector<std::reference_wrapper<Object>>: All objects that have updated shapes.
auto clearUpdatedShapeObjects() -> World&: Clear list of updated shape objects.
auto objectFromDartFrame(dart::dynamics::Frame* frame) -> Object&: Get object instance corresponding to a DART frame.
auto world() -> dart::simulation::World&: Underlying DART world object.

Function documentation

template<class T>
Magnum::DartIntegration::World::World(T& object, dart::simulation::World& world) explicit

Constructor.

Parameters
object	Parent object
world	DART world instance

This constructor creates a private instance of Trade::AbstractImporter plugin manager for importing model data. If you plan to use importer plugins elsewhere in your application, it's advised to keep the plugin manager on the app side and construct the world using World(PluginManager::Manager<Trade::AbstractImporter>&, T&, dart::simulation::World&) instead.

template<class T>
Magnum::DartIntegration::World::World(PluginManager::Manager<Trade::AbstractImporter>& importerManager, T& object, dart::simulation::World& world) explicit

Construct with an external importer plugin manager.

Parameters
importerManager	Importer plugin manager
object	Parent object
world	DART world instance

The importerManager is expected to be in scope for the whole lifetime of the World instance.

World& Magnum::DartIntegration::World::step(bool resetCommand = true)

Do a DART world step.

The resetCommand parameter is passed to dart::simulation::World::step().

std::vector<std::unique_ptr<Object>>& Magnum::DartIntegration::World::unusedObjects()

Get unused objects.

Returns all objects that were not updated during the last refresh() call. This list gets cleared during the next refresh() call, which means also all Object instances in the list get deleted. In case you need to handle the Object instance deletion yourself, you're free to do anything with the returned list — move instances out, release them, erase the elements etc.

std::vector<std::reference_wrapper<Object>> Magnum::DartIntegration::World::updatedShapeObjects()

All objects that have updated shapes.

This list gets appended to after every refresh() call, you can use it to update your rendering structures. Be sure to call clearUpdatedShapeObjects() once you have your rendering structures updated to avoid updating objects that didn't change again.

World& Magnum::DartIntegration::World::clearUpdatedShapeObjects()

Clear list of updated shape objects.

Returns	Reference to self (for method chaining)

See updatedShapeObjects() for more information.

Object& Magnum::DartIntegration::World::objectFromDartFrame(dart::dynamics::Frame* frame)

Get object instance corresponding to a DART frame.

Returns Object instance associated with a DART Frame / BodyNode / ShapeNode. Expects that the DART frame is part of the world.