The Fatum context
Visualization using Fatum is centered around a context. This context is responsible for handling everything related to your visualization. It is the main entry point for the user.
Creating a context
The easy way
Fatum provides a utility function to help you setup a context.
Fatum.createFatumContext(canvas)
will create and setup a context on the canvas you provide.
Other handlers
Furthermore, Fatum provides other utility function for your context :
Fatum.setRenderingObserver(context)
will assurerenderFrame()
is called when animating. See 'rendering' for more information.Fatum.setMouseMoveHandler(canvas, context)
will setup listeners to move the visualization using the mouse.
The hard way
If you need specific options for the context creation, you may wish to setup the context yourself.
A Fatum context can be created using its js constructor Fatum.Fatum()
.
This will create a visualization context that you will be able to use.
However, the context is not yet ready to display anything.
- First, you should have a working WebGL context created by Emscripten using
Fatum.createContext()
. - Second, you need to initialize its WebGL internal context by calling its
initGL()
method. This will allow the context to render to your canvas. - Third, do not forget to initialize the Camera viewport using
setViewport
. See the camera section for more details. - Finally, you should activate wichever layers you need to be rendered.
Here it is in code :
var canvas = /* get your canvas */;
Fatum.createContext(canvas, true, true, {/* webgl context options */});
var fatum = new Fatum.Fatum();
fatum.initGL();
var camera = fatum.camera();
camera.setViewport([0,0,canvas.width,canvas.height]);
Managing visual elements
The Fatum context allow you to add Marks and Connections to the visualization.
To add a Mark, call addMark()
.
To add a Connection, call addConnection(m1,m2)
. This will connect the two given Marks.
Once you have added some elements, you can acces them in two ways :
- Using their
id
(retrieved through theid()
method). To retrieve a Mark or a Connection using its id, usemark(id)
andconnection(id)
. /!\ Beware that ids are not necesarily contiguous. - Using their current index in the visualization. You can get the number of elements using
numberOfMarks()
andnumberOfConnections()
. Then, use thegetMark(index)
andgetConnection(index)
to access each element. Contrary to theid
, the indices are contiguous, but a given element can change its index at any time. This is not a reliable way to retrive a specific Mark, for that you should use itsid
. Access using indices is more suited for global iteration.
When creating a Mark, its properties are populated with default values. These values can be changed using the defaultMark()
method. This method returns a placeholder mark that stores default values. Its proeprties can be modified just like a Mark.
For more information about the Marks and Connections, see the corresponding sections.
Rendering
Fatum cannot know when to render by itself. You need to call the rendering function in order to refresh the visualization. Two methods are available to refresh the visualization :
renderFrame()
is the main way to refresh the visualization. It will handle the current animation and state of the visualization.renderFrame(interpolationRatio)
should be used more sparingly. It allows you to control the interpolation between the two buffers during animation. However, it will not trigger animation advance.
Most of the time, a single rendering is enough. However, when an animation is launched, Fatum cannot keep rendering each step until the animation finishes. But the context will tell you when it should be refreshed. Two mechanisms exist for this purpose :
- For loop-based systems, the
needsRendering()
method will return true if you should refresh. - For callback based systems (such as Javascript), you can set a callback to be called when a refresh is needed using
setRenderingObserver()
. Note that this callback should not render directly, but only schedule a rendering usingsetTimeout
for instance.
The entities rendered are controled by a layer system. The different layers are :
- Marks
- Connections
- Axis
- Text
In order for a certain type of objects to be rendered, you need to activate its layer using layerOn(layer)
. The flags are defined in Fatum
. It is possible to deactivate a layer with layerOff(layer)
and to toggle the layer's visibility with layerToggle(layer)
.
Controling the double buffering
The fatum context holds the buffer used for double buffering. There two ways to control them :
- Using
swap()
, the buffers are exchanged, without any animation. - Using
animate()
launches an animation, which will interpolate the properties values between the two buffers and will eventualy swap them. There are two overloads :animate(int)
can be used to control the duration of the animation andanimate(int, callback)
allows to specify a function to execute when the animation is complete, allowing staged animation.
Camera
It is possible to access the Camera
using the camera()
method.
A convienence method center()
is also provided to quickly center the visualization on visible objects.
For more information about the camera, see the corresponding section.