Behave3d.Element
Every HTML element in the DOM tree that has behave3d functionality has an object of type Behave3d.Element attached as a property.
The name of the property is defined by Behave3d.consts.BEHAVE3D_PROPERTY and by default is "behave3d".
The object contains:
- all controllers attached to the element, and their working data,
- a queue of transforms requested by the controllers to be applied onto the element every frame,
- "physical" properties of the element, modified by the physics controllers, and updated by simulation on every frame.
The engine keeps a list of references to all elements on the page that contain a Behave3d.Element -
this is the so-called elements pool. All elements in the pool have their controllers updated and transforms applied on each drawing frame.
Note that not only elements that have controllers assigned need to have Behave3d.Element instantiated.
All elements that will be applied 3D transforms and physics need it.
Some controllers, like box() and carousel(),
apply transforms not on the element they are assigned to, but on its child nodes.
These controllers instantiate Behave3d.Element on their children automatically.
Another, not very obvious case when an element needs to have Behave3d.Element instantiated is
when a controller on another element wants to listen to this element's events,
i.e. to listen to this element's actions() controller's events.
Instantiating Behave3d.Element
-
The presence of a
behave3dattribute on an HTML element, with or without controller definitions contained, tells the behave3d engine to create aBehave3d.Element:
-
The
Behave3d()selector function automatically creates aBehave3d.Elementon the selected element if such is not already created.
Removing Behave3d.Element
If the page contains many elements with behave3d functionality that will not be used any more, this functionality can be removed, freeing memory and saving the few clock cycles spent in updating the idle controllers.
Removal is done via the .removeFromPool() method, which removes all controllers from the element,
and then removes the element from the pool and as property of the HTML element.
In case you want to remove not only the Behave3d.Element but also the HTML element (from the DOM tree),
there's the remove_element message of the actions() controller,
which, as a message, allows the removal of the element to be scheduled to happen upon a controller's event:
Note that when an HTML element is deleted from the DOM tree by external scripts,
the engine doesn't "see" this (it's expensive to check) and continues to update its Behave3d.Element.
Either call manually the .removeFromPool() method for each deleted HTML element,
or call Behave3d.updatePool(), which will check all elements in the pool
to see if the document.contains() them and will remove from the pool all deleted HTML elements.