behave3d Engine

Library Structure

Here's the basic structure of the library:

• Behave3d()

  A function used for selecting (i.e. getting a reference to) behave3d elements (instances of Behave3d.Element) and controllers (instances of descendants of Behave3d.Controller)

• Behave3d.consts

  Engine functionality switches and parameters.

• Behave3d.vars

  Engine variables.

• Behave3d.transforms

  An object containing the default values for each type of transform that controllers can request to the engine.

• Behave3d.params

  String-parsing and other methods for handling parameters.

• Behave3d.controllerAaBb

  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 controller aa_bb() is expected to have constructor Behave3d.controllerAaBb.

• Behave3d.controllers

  An object containing named references to all currently-registered controllers, so that
  Behave3d.controllers["aa_bb"] === Behave3d.controllerAaBb.

• Behave3d.Element

  Every HTML element containing behave3d functionality has an instance of this class as its behave3d property. This instance contains and manages the element's controllers. Visit the Behave3d.Element Documentation page for details.

• Behave3d.Controller

  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.StepEngine

  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 sends 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.