The X Toolkit API

X.renderer3D

/**
* Create a 3D renderer inside a given DOM Element.
*
* @constructor
* @extends X.renderer
*/

var r = new X.renderer3D();

/**
* The animation frame ID.
*
* @type {!number}
* @protected
*/

r._AnimationFrameID = $_ANIMATIONFRAMEID;

/**
* A hash map of shader attribute pointers.
*
* @type {!goog.structs.Map}
* @protected
*/

r._attributePointers = $_ATTRIBUTEPOINTERS;

/**
* The camera of this renderer.
*
* @type {?X.camera}
* @protected
*/

r._camera = $_CAMERA;

/**
* The Canvas of this renderer.
*
* @type {?Element}
* @public
*/

r._canvas = $_CANVAS;

/**
* The center of the global bounding box in 3D space.
*
* @type {!Array}
* @protected
*/

r._center = $_CENTER;

/**
* The className of this class.
*
* @type {string}
* @protected
*/

r._classname = $_CLASSNAME;

/**
* A hash map of color buffers of this renderer. Each buffer is associated
* with a displayable object using its unique id.
*
* @type {!goog.structs.Map}
* @protected
*/

r._colorBuffers = $_COLORBUFFERS;

/**
* The configuration of this renderer.
*
* @enum {boolean}
*/

r._config = $_CONFIG;

/**
* The HTML container of this renderer, E.g. a .
*
* @type {!Element|HTMLBodyElement}
* @protected
*/

r._container = $_CONTAINER;

/**
* The rendering context of this renderer.
*
* @type {?Object}
* @protected
*/

r._context = $_CONTEXT;

/**
* The 'dirty' flag of this object.
*
* @type {boolean}
* @protected
*/

r._dirty = $_DIRTY;

/**
* The height of this renderer.
*
* @type {!number}
* @public
*/

r._height = $_HEIGHT;

/**
* The uniqueId of this instance. Each class instance in XTK has a uniqueId.
*
* @type {number}
* @protected
*/

r._id = $_ID;

/**
* The interactor of this renderer.
*
* @type {?X.interactor}
* @protected
*/

r._interactor = $_INTERACTOR;

/**
* The loader associated with this renderer.
*
* @type {?X.loader}
* @protected
*/

r._loader = $_LOADER;

/**
* A flag to show if the initial loading was completed.
*
* @type {boolean}
* @protected
*/

r._loadingCompleted = $_LOADINGCOMPLETED;

/**
* A locked flag for synchronizing.
*
* @type {boolean}
* @protected
*/

r._locked = $_LOCKED;

/**
* The maximum X value of the global bounding box.
*
* @type {?number}
* @protected
*/

r._maxX = $_MAXX;

/**
* The maximum Y value of the global bounding box.
*
* @type {?number}
* @protected
*/

r._maxY = $_MAXY;

/**
* The maximum Z value of the global bounding box.
*
* @type {?number}
* @protected
*/

r._maxZ = $_MAXZ;

/**
* The minimum X value of the global bounding box.
*
* @type {?number}
* @protected
*/

r._minX = $_MINX;

/**
* The minimum Y value of the global bounding box.
*
* @type {?number}
* @protected
*/

r._minY = $_MINY;

/**
* The minimum Z value of the global bounding box.
*
* @type {?number}
* @protected
*/

r._minZ = $_MINZ;

/**
* A hash map of normal buffers of this renderer. Each buffer is associated
* with a displayable object using its unique id.
*
* @type {!goog.structs.Map}
* @protected
*/

r._normalBuffers = $_NORMALBUFFERS;

/**
* An X.array containing the displayable objects of this renderer. The object
* reflects the rendering order for the associated objects.
*
* @type {!X.array}
* @protected
*/

r._objects = $_OBJECTS;

/**
* A flag to indicate that the onShowtime callback is about to be called.
*
* @type {boolean}
* @protected
*/

r._onShowtime = $_ONSHOWTIME;

/**
* The frame buffer which is used for picking.
*
* @type {Object}
* @protected
*/

r._pickFrameBuffer = $_PICKFRAMEBUFFER;

/**
* The progressBar of this renderer.
*
* @type {?X.progressbar}
* @protected
*/

r._progressBar = $_PROGRESSBAR;

/**
* A hash map of scalar buffers of this renderer. Each buffer is associated
* with a displayable object using its unique id.
*
* @type {!goog.structs.Map}
* @protected
*/

r._scalarBuffers = $_SCALARBUFFERS;

/**
* The compiled shader program of this renderer.
*
* @type {?Object}
* @protected
*/

r._shaderProgram = $_SHADERPROGRAM;

/**
* The shader pair for this renderer.
*
* @type {?X.shaders}
* @protected
*/

r._shaders = $_SHADERS;

/**
* A hash map of texture position buffers of this renderer. Each buffer is
* associated with a displayable object using its unique id.
*
* @type {!goog.structs.Map}
* @protected
*/

r._texturePositionBuffers = $_TEXTUREPOSITIONBUFFERS;

/**
* A hash map of different textures assigned to this renderer. The maximum
* number of textures is limited to 32 by WebGL.
*
* @type {!goog.structs.Map}
* @protected
*/

r._textures = $_TEXTURES;

/**
* An array containing the topLevel objects (which do not have parents) of
* this renderer.
*
* @type {!Array}
* @protected
*/

r._topLevelObjects = $_TOPLEVELOBJECTS;

/**
* A hash map of shader uniform locations.
*
* @type {!goog.structs.Map}
* @protected
*/

r._uniformLocations = $_UNIFORMLOCATIONS;

/**
* A hash map of vertex buffers of this renderer. Each buffer is associated
* with a displayable object using its unique id.
*
* @type {!goog.structs.Map}
* @protected
*/

r._vertexBuffers = $_VERTEXBUFFERS;

/**
* The width of this renderer.
*
* @type {!number}
* @public
*/

r._width = $_WIDTH;

/**
* Get the camera of this renderer. The camera is null until this renderer is
* initialized.
*
* @return {?X.camera} The camera.
*/

var _camera = r.camera;

/**
* Get the className of this object.
*
* @return {string} The className of this object.
* @public
*/

var _classname = r.classname;

/**
* Access the configuration of this renderer. Possible settings and there
* default values are:
*
* 
*  config.PROGRESSBAR_ENABLED: true
*  config.PICKING_ENABLED: true
*  config.ORDERING_ENABLED: true
*  config.STATISTICS_ENABLED: false
*  config.INTERMEDIATE_RENDERING: false
* 
*
* @return {Object} The configuration.
*/

var _config = r.config;

/**
* Get the container of this renderer.
*
* @return {!Element|HTMLBodyElement} The container of this renderer.
* @public
*/

var _container = r.container;

/**
* Set the container for this renderer. This has to happen before
* X.renderer.init() is called.
*
* @param {!string|Element|HTMLBodyElement} container Either an ID to a DOM
*          container or the DOM element itself.
* @throws {Error} An error, if the given container is invalid.
* @public
*/

r.container = $CONTAINER;

/**
* Get the id of this instance.
*
* @return {string} The className of this object.
* @public
*/

var _id = r.id;

/**
* Get the interactor of this renderer. The interactor is null until this
* renderer is initialized.
*
* @return {?X.interactor} The interactor.
*/

var _interactor = r.interactor;

/**
* Check if the initial loading of all objects was completed. This value gets
* set immediately after the onShowtime function is executed.
*
* @return {boolean} TRUE if all objects were completely loaded, FALSE else
*         wise.
*/

var _loadingCompleted = r.loadingCompleted;

/**
* Add a new object to this renderer. The renderer has to be initialized before
* doing so. A X.renderer.render() call has to be initiated to display added
* objects.
*
* @param {!X.object} object The object to add to this renderer.
* @throws {Error} An exception if something goes wrong.
*/

r.add($OBJECT);

/**
* Add a pair of shaders to this renderer. The renderer has to be initialized
* before adding the shaders.
*
* @param {!X.shaders} shaders The X.shaders pair to add to this renderer.
* @public
*/

r.addShaders($SHADERS);

/**
* Destroy this renderer.
*
* @public
*/

r.destroy();

/**
* Calculate the distance to the eye (camera) for one X.object.
*
* @param {!X.object} object The X.object to use for calculation.
* @return {number} The distance to the eye.
*/

var distanceToEye_ = r.distanceToEye_($OBJECT);

/**
* Recursively loop through a hierarchy tree of objects and print it.
*
* @param {!X.object} object The starting point object.
* @param {number} level The current level in the scene hierarchy.
* @protected
*/

r.generateTree_($OBJECT, $LEVEL);

/**
* Get the existing X.object with the given id.
*
* @param {!number} id The object's id.
* @return {?X.object} The requested X.object or null if it was not found.
* @throws {Error} If the given id was invalid.
* @public
*/

var get = r.get($ID);

/**
* Hides the loading progress bar.
*
* @protected
*/

r.hideProgressBar_();

/**
* Create the canvas of this renderer inside the configured container and using
* attributes like width, height etc. Then, initialize the rendering context and
* attach all necessary objects (e.g. camera, shaders..). Finally, initialize
* the event listeners.
*
* @param {string} _contextName The name of the context to create.
* @throws {Error} An exception if there were problems during initialization.
* @protected
*/

r.init($_CONTEXTNAME);

/**
* The callback for X.event.events.HOVER events which indicate a hovering over
* the viewport.
*
* @param {!X.event.HoverEvent} event The hover event pointing to the relevant
*          screen coordinates.
* @throws {Error} An error if the given event is invalid.
* @protected
*/

r.onHover_($EVENT);

/**
* The callback for X.event.events.MODIFIED events which re-configures the
* object for rendering. This does not trigger re-rendering.
*
* @param {!X.event.ModifiedEvent} event The modified event pointing to the
*          modified object.
* @public
*/

r.onModified($EVENT);

/**
* The callback for X.event.events.PROGRESS events which indicate progress
* updates during loading.
*
* @param {!X.event.ProgressEvent} event The progress event holding the total
*          progress value.
* @public
*/

r.onProgress($EVENT);

/**
* Overload this function to execute code on each rendering call.
*
* @public
*/

r.onRender();

/**
* @protected
*/

r.onResize_();

/**
* The callback for X.event.events.SCROLL events which indicate scrolling of the
* viewport.
*
* @param {!X.event.ScrollEvent} event The scroll event indicating the scrolling
*          direction.
* @throws {Error} An error if the given event is invalid.
* @protected
*/

r.onScroll_($EVENT);

/**
* Overload this function to execute code after all initial loading (files,
* textures..) has completed and just before the first real rendering call.
*
* @public
*/

r.onShowtime();

/**
* Calculates the distance for each associated X.object and orders objects array
* accordingly from back-to-front while fully opaque objects are drawn first.
* Jumps out as early as possible if all objects are fully opaque.
*/

r.order_();

/**
* (Re-)configure the volume rendering orientation based on the current view
* matrix of the camera. We always use the slices which are best oriented to
* create the tiled textures of X.volumes.
*
* @param {X.volume} volume The X.volume to configure
*/

r.orientVolume_($VOLUME);

/**
* Picks an object at a position defined by display coordinates. If
* X.renderer3D.config['PICKING_ENABLED'] is FALSE, this function always returns
* -1.
*
* @param {!number} x The X-value of the display coordinates.
* @param {!number} y The Y-value of the display coordinates.
* @return {number} The ID of the found X.object or -1 if no X.object was found.
*/

var pick = r.pick($X, $Y);

/**
* Print the full hierarchy tree of objects.
*
* @public
*/

r.printScene();

/**
* (Re-)render all associated displayable objects of this renderer. This method
* clears the viewport and re-draws everything by looping through the tree of
* objects. The current camera is used to setup the world space.
*
* @public
*/

r.render();

/**
* Internal function to perform the actual rendering by looping through all
* associated X.objects.
*
* @param {boolean} picking If TRUE, perform picking - if FALSE render to the
*          canvas viewport.
* @param {?boolean=} invoked If TRUE, the render counts as invoked and f.e.
*          statistics are generated.
* @throws {Error} If anything goes wrong.
* @protected
*/

r.render_($PICKING, $INVOKED);

/**
* Reset the global bounding box for all objects to undefined and reset the
* center to 0,0,0. This can be useful before calling X.object.modified() on all
* objects after transforms etc. which then re-calculates the global bounding
* box.
*
* @public
*/

r.resetBoundingBox();

/**
* Resets the view according to the global bounding box of all associated
* objects, the configured camera position as well as its focus _and_ triggers
* re-rendering.
*/

r.resetViewAndRender();

/**
* Show the caption of the X.object at viewport position x,y. This performs
* object picking and shows a tooltip if an object with a caption exists at this
* position.
*
* @param {number} x The x coordinate (viewport).
* @param {number} y The y coordinate (viewport).
*/

r.showCaption_($X, $Y);

/**
* Shows the loading progress bar by modifying the DOM tree.
*
* @protected
*/

r.showProgressBar_();

/**
* Configure a displayable object within this renderer. The object can be a
* newly created one or an existing one. A X.renderer.render() call has to be
* initiated to display the object.
*
* @param {!X.object} object The displayable object to setup within this
*          renderer.
* @throws {Error} An exception if something goes wrong.
* @protected
*/

r.update_($OBJECT);