behave3d Engine
The behave3d library is loaded and automatically started by including the engine's script file:
This will create window.Behave3d
which contains all the library's functionality.
Library Structure
Here's the basic structure of the library:
A function used for selecting (i.e. getting a reference to) behave3d elements (instances ofBehave3d()
Behave3d.Element
) and controllers (instances of descendants ofBehave3d.Controller
)
Engine functionality switches and parameters.Behave3d.consts
Engine variables.Behave3d.vars
An object containing the default values for each type of transform that controllers can request to the engine.Behave3d.transforms
String-parsing and other methods for handling parameters.Behave3d.params
Every loaded controller will have its constructor function here. The convention is the name of the constructor function to be of camelCase and the name of the controller (as used in documentation and scripts) - lowercase with "_" between words. So, a controllerBehave3d.controllerAaBb
aa_bb()
is expected to have constructorBehave3d.controllerAaBb
.
An object containing named references to all currently-registered controllers, so thatBehave3d.controllers
Behave3d.controllers["aa_bb"] === Behave3d.controllerAaBb
.
Every HTML element containing behave3d functionality has an instance of this class as itsBehave3d.Element
behave3d
property. This instance contains and manages the element's controllers. Visit the Behave3d.Element Documentation page for details.
All controller types are defined as classes that inherit this class. It contains the base functionality of a controller. Visit the Behave3d.Controller Documentation page for details.Behave3d.Controller
Encapsulates functionality for animating variables, used by controllers. Calculates an animated variable's current position on every frame and supplies it to the controller. The controller sets initial values, animation duration and parameters for easing and inertia, and sendsBehave3d.StepEngine
start
/start_back
/etc. commands to the StepEngine.
Loading of Controllers
The behave3d library contains many controllers (with more to come), each of them being defined in a separate file.
Only the files of the controllers that will be used on a page need to be loaded, and they should be loaded after the library's engine file.
Each controller file has a command in its end, registering the controller for use:
Behave3d.registerController("rotate", Behave3d.controllerRotate);
Some controllers use and are dependant on other controllers. In these cases the dependencies should be loaded before the dependant controller.
Framerate
The behave3d library is mainly about animations, which require changes apllied at regular intervals (i.e. frames).
The library has a main update method called on every frame with either window.requestAnimationFrame()
or window.setTimeout()
,
depending on the value of Behave3d.consts.FRAME_TIMER_TYPE
.
The engine keeps a pool of references to all HTML elements on the page that have behave3d functionality. Which means that these elements either have controllers, or other elements' controllers apply transformations on them. On each frame, every element in the pool has all its controllers updated. After all elements' controllers have been updated, each element has the collected transforms applied.
Applying of Transforms
Since changes to DOM and CSS properties are slow operations,
the behave3d library doesn't let each controller apply 3D transforms by itself (by appending to style.transform
).
Instead, each instance of Behave3d.Element
has a queue of requested transforms which is applied to the element all at once every frame.
The engine rounds the values of all requested transforms and applies the new transforms only if different than the currently-applied transforms.
The following options (shown with default values) set the rounding precision (in digits after decimal point) for the different transforms' parameters:
Behave3d.consts.PRECISION_TRANSLATE = 1;
Behave3d.consts.PRECISION_ROTATE = 3;
Behave3d.consts.PRECISION_ROTATE_ANGLE = 1;
Behave3d.consts.PRECISION_SCALE = 3;
Behave3d.consts.PRECISION_OPACITY = 2;
The controllers need only to supply the correct values every frame, and don't "think" about optimizations in applying.
Synchronized Viewport and Perspective
The behave3d library tries to achieve a "true" 3D scene
where moving the camera causes the redrawing of all visible objects, so that they are "looked at" from the new position of the camera.
Which, in HTML+CSS terms, means that the perspective
properties of the elements should reflect the changes in the browser's viewport,
so that perspective's vanishing point always matches the center of the viewport.
Have a look at controllerScene's Reference for more details.