Setting up the simulation

Creating Masses and Springs

These commands create and modify objects in the simulation. They can only be called before the simulation has started or while it is paused.

Mass * sim.createMass(const Vec & position)

Creates a mass primitive with default values located at the given position. The default values can be changed in the library, but are by default:

Mass (m): 1.0 kilograms
Delta-T (dt): 0.0001 seconds
Color (color): (255, 51, 51)
Position (pos): [given]
Velocity (vel): (0, 0, 0)
Acceleration (acc): (0, 0, 0)
Force (force): (0, 0, 0)

Returns a pointer to the mass stored by the simulation. The user can access and set values in the mass by dereferencing the pointer, but moving or deleting the underlying object is undefined behavior.

Other overloaded constructors are also available: Mass * sim.createMass(const Vec & position, double mass, bool fixed, double dt), and Mass * sim.createMass(), which defaults everything.

Spring * sim.createSpring(Mass * left, Mass * right)

Creates a spring primitive with default values connected to the specified masses. The left and right mass pointers should point to existing masses in the simulation. The default values can be changed in the library, but are by default:

Spring Constant (_k): 10000 N / m^2
Rest Length (_rest): d(m1, m2), distance between the two specified masses (in meters)
Left Mass (_left): left pointer
Right Mass (_right): right pointer

Deleting Masses and Springs

Masses and springs can be deleted from the simulation mid-run. All of these operations are safe and the user does not need to worry about springs connected to a deleted mass. However, make sure not to call delete on a single mass twice. This is undefined behavior. Under some circumstances, this will simply produce a warning, but under others, it will cause a segmentation fault and crash the program.

void deleteMass(Mass * m)

Deletes a specified mass. The mass is invalidated and any further operations on the pointer are undefined behavior. Deleting a mass which is connected to existing springs will invalidate all those springs as well, until they are modified to point to valid masses. However, the simulation can continue.

void deleteSpring(Spring * s)

Deletes a specified spring. The spring is invalidated and any further operations on the pointer are undefined behavior. This does not affect the masses a given spring is connected to.

Pushing and Pulling Data to/from the GPU

Mass and spring data can be pushed to and pulled from the GPU at any point while the simulation is paused. The basic commands are sim.get(...) and sim.set(...), which copy data to and from the GPU for a given mass or spring.

void get(Mass *m)

Copy all data from the GPU to the specified mass. This is relatively expensive, and it is preferable to use containers or getAll() if large numbers of masses need to be updated.

void get(Spring *s)

Currently does nothing. This command in theory fetches data about a given spring from the GPU, but since no operation on the GPU updates the springs, it has no effect. This can be implemented in the future if needed.

void set(Mass * m)

Copy all local data from the CPU to the corresponding mass on the GPU. Does not modify the existing mass object on the CPU.

void set(Spring *s)

Copy all local data from the CPU to the corresponding spring on the GPU. Does not modify the existing spring object on the CPU or its connected masses.

void getAll()

Copy all data from the GPU to the CPU. Updates and overwrites all CPU objects. Relatively efficient compared to large numbers of gets, and should be preferred if many objects need to be copied to the CPU.

void setAll()

Copy all data from the CPU to the GPU. Updates and overwrites all GPU objects. Relatively efficient compared to large numbers of sets, and should be preferred if many objects need to be copied to the GPU.

Examples

The following creates masses, connects them with a spring, modifies one of them, and pushes it to the GPU.

Mass * m1 = sim.createMass(Vec(0, 0, 1));
Mass * m2 = sim.createMass(Vec(0, 0, -1));
Spring * s1 = sim.createSpring(m1, m2);

m1 -> m = 2.0; // set the mass to 2.0kg

sim.set(m1); // pushes that change to the GPU