Magnum::DartIntegration::World class

DART physics world.

Usage
Reference
- Constructors, destructors, conversion operators
- Public functions

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.

Public functions

auto refresh() -> World&: Refresh/regenerate meshes for all bodies in DART world.
auto step() -> 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

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.