Other sources of information are the Reference Manual, the User Manual, and the Sylvester Docs for vectors and matrices.
We use standard JavaScript prototypal inheritance for the objects.
Instance variables and member functions starting with an underscore are understood to be private and for internal use only. Apart from this, we follow Java naming conventions.
We use JSDoc for inline documentation (particularly jsdoc-toolkit).
draw() and redraw()The user-supplied anonymous function in the constructor call is
bound to the member function draw(). This should not
generally be called explicitly, however. Instead,
redraw() should be called, which is overridden by the
PrairieDrawAnim child.
There are three coordinate systems used: Dw is drawing
coordinates and is used for positions and vectors, Px is
pixel coordinates and is used for line widths, arrow sizes,
etc, and Nm is normalized coordinates for referencing
locations within the viewport. The transformation from Dw to Px is
stored in the _trans instance variable. This is an affine
transformation matrix (using homogeneous
coordinates). The transformation matrix is pushed/popped from a
transformation stack by
save()/restore().
To convert from Dw to Px coordinates we use pos2Px
(for positions) and vec2Px (for vectors). The vector
transformation only uses the linear part of the affine
transformation. The inverse transforms are pos2Dw and
vec2Dw. Similarly, posNm2Dw and
posNm2Px convert normalized coordinate positions to the
other coordinate systems.
All PrairieDraw functions should leave the 2D Canvas coordinate
system unmodified, so we should do a _ctx.save() and
_ctx.restore() around any canvas coordinate
transformations.
In the code, variables are suffixed with either Dw,
Px, or Nm to indicate which coordinate
system they are in.
Drawing properties are stored in the _props instance
variable object and pushed/popped from a stack by
save()/restore(). Properties include colors
to indicate standard types of objects. Object drawing functions (like
rod(), pivot(), etc.) should set all
appropriate style and color properties from _props data
and should clear them before exit.
Options stored in the _options instance variable
object are for user-created options. These are not
push/popped by save()/restore(), as they
need to persist across multiple draw() invocations.
Calling setOption() or setProp() triggers
a redraw().
There are three times used for animation by the
PrairieDrawAnim child class: wall-time in milliseconds,
animation time in milliseconds, and animation time in seconds.
Animation is implemented using
requestAnimationFrame(), which calls
_callback() with the wall-time in milliseconds. We offset
by the _timeOffset instance variable to obtain the
current animation time in milliseconds. This allows for the animation
to be paused and restarted without skipping. The
_startFrame instance variable set to true
when animation begins, which triggers the recalculation of
_timeOffset.
The _drawTime instance variable stores the animation
time in milliseconds of the last draw() call, for use by
redraw() when the animation is not running.
The user-supplied draw(t) function is called with time
t being the animation time in seconds.