code doc and cleanup

Viewer/src/configuration/types/default.ts

@@ -1,5 +1,9 @@
 import { ViewerConfiguration } from './../configuration';
 
+/**
+ * The default configuration of the viewer, including templates (canvas, overly, loading screen)
+ * This configuration doesn't hold specific parameters, and only defines objects that are needed for the viewer to fully work correctly.
+ */
 export let defaultConfiguration: ViewerConfiguration = {
     version: "3.2.0-alpha4",
     templates: {
@@ -97,10 +101,5 @@ export let defaultConfiguration: ViewerConfiguration = {
         antialiasing: true
     },
     scene: {
-        /*imageProcessingConfiguration: {
-            exposure: 1.4,
-            contrast: 1.66,
-            toneMappingEnabled: true
-        }*/
     }
 }

Viewer/src/configuration/types/environmentMap.ts

@@ -1,5 +1,8 @@
 import { ViewerConfiguration } from './../configuration';
 
+/**
+ * Lab-oriented default .env support
+ */
 export const environmentMapConfiguration: ViewerConfiguration = {
     lab: {
         assetsRootURL: '/assets/environment/',

Viewer/src/configuration/types/extended.ts

@@ -1,6 +1,10 @@
 import { ViewerConfiguration } from './../configuration';
 import { Tools } from 'babylonjs';
 
+/**
+ * The viewer's "extended" configuration.
+ * This configuration defines specific obejcts and parameters that we think make any model look good.
+ */
 export let extendedConfiguration: ViewerConfiguration = {
     version: "3.2.0",
     extends: "default",

Viewer/src/configuration/types/index.ts

@@ -6,6 +6,14 @@ import { shadowDirectionalLightConfiguration, shadowSpotlLightConfiguration } fr
 import { environmentMapConfiguration } from './environmentMap';
 import * as deepmerge from '../../../assets/deepmerge.min.js';
 
+/**
+ * Get the configuration type you need to use as the base for your viewer.
+ * The types can either be a single string, or comma separated types that will extend each other. for example:
+ * 
+ * "default, environmentMap" will first load the default configuration and will extend it using the environmentMap configuration.
+ * 
+ * @param types a comma-separated string of the type(s) or configuration to load. 
+ */
 let getConfigurationType = function (types: string): ViewerConfiguration {
     let config: ViewerConfiguration = {};
     let typesSeparated = types.split(",");

Viewer/src/configuration/types/shadowLight.ts

@@ -1,5 +1,8 @@
 import { ViewerConfiguration } from './../configuration';
 
+/**
+ * Defines a default directional shadow light for normalized objects (!)
+ */
 export const shadowDirectionalLightConfiguration: ViewerConfiguration = {
     model: {
         receiveShadows: true,
@@ -30,6 +33,9 @@ export const shadowDirectionalLightConfiguration: ViewerConfiguration = {
     }
 }
 
+/**
+ * Defines a default shadow-enabled spot light for normalized objects.
+ */
 export const shadowSpotlLightConfiguration: ViewerConfiguration = {
     model: {
         receiveShadows: true,

Viewer/src/labs/environmentSerializer.ts

@@ -2,9 +2,9 @@ import { Vector3, Tools } from "babylonjs";
 import { TextureCube, PixelFormat, PixelType } from './texture';
 
 /**
-	 * Spherical polynomial coefficients (counter part to spherical harmonic coefficients used in shader irradiance calculation)
-	 * @ignoreChildren
-	 */
+ * Spherical polynomial coefficients (counter part to spherical harmonic coefficients used in shader irradiance calculation)
+ * @ignoreChildren
+ */
 export interface SphericalPolynomalCoefficients {
     x: Vector3;
     y: Vector3;

Viewer/src/labs/viewerLabs.ts

@@ -5,6 +5,11 @@ import { Tools, Quaternion } from 'babylonjs';
 import { ViewerConfiguration } from "../configuration/configuration";
 import { TextureUtils } from "./texture";
 
+/**
+ * The ViewerLabs class will hold functions that are not (!) backwards compatible.
+ * The APIs in all labs-related classes and configuration  might change.
+ * Once stable, lab features will be moved to the publis API and configuration object.
+ */
 export class ViewerLabs {
 
     constructor(private _sceneManager: SceneManager) { }

Viewer/src/loader/modelLoader.ts

@@ -32,6 +32,11 @@ export class ModelLoader {
         this._plugins = [];
     }
 
+    /**
+     * Adds a new plugin to the loader process.
+     * 
+     * @param plugin the plugin name or the plugin itself
+     */
     public addPlugin(plugin: ILoaderPlugin | string) {
         let actualPlugin: ILoaderPlugin = {};
         if (typeof plugin === 'string') {

Viewer/src/loader/plugins/applyMaterialConfig.ts

@@ -4,7 +4,9 @@ import { ViewerModel } from "../..";
 import { Tools, ISceneLoaderPlugin, ISceneLoaderPluginAsync, Material } from "babylonjs";
 import { IGLTFLoaderData, GLTF2 } from "babylonjs-loaders";
 
-
+/**
+ * Force-apply material configuration right after a material was loaded.
+ */
 export class ApplyMaterialConfigPlugin implements ILoaderPlugin {
 
     private _model: ViewerModel;

Viewer/src/loader/plugins/extendedMaterialLoaderPlugin.ts

@@ -3,6 +3,10 @@ import { telemetryManager } from "../../telemetryManager";
 import { ViewerModel } from "../..";
 import { Color3, Texture, BaseTexture, Tools, ISceneLoaderPlugin, ISceneLoaderPluginAsync, Material, PBRMaterial, Engine } from "babylonjs";
 
+/**
+ * A (PBR) material will be extended using this function.
+ * This function will hold extra default configuration for the viewer, if not implemented in Babylon itself.
+ */
 export class ExtendedMaterialLoaderPlugin implements ILoaderPlugin {
 
     public onMaterialLoaded(baseMaterial: Material) {

Viewer/src/loader/plugins/index.ts

@@ -6,6 +6,12 @@ import { ExtendedMaterialLoaderPlugin } from './extendedMaterialLoaderPlugin';
 
 const pluginCache: { [key: string]: ILoaderPlugin } = {};
 
+/**
+ * Get a loader plugin according to its name.
+ * The plugin will be cached and will be reused if called for again.
+ * 
+ * @param name the name of the plugin
+ */
 export function getLoaderPluginByName(name: string) {
     if (!pluginCache[name]) {
         switch (name) {

Viewer/src/loader/plugins/loaderPlugin.ts

@@ -2,6 +2,11 @@ import { ViewerModel } from "../../model/viewerModel";
 import { IGLTFLoaderExtension, IGLTFLoaderData } from "babylonjs-loaders";
 import { AbstractMesh, ISceneLoaderPlugin, ISceneLoaderPluginAsync, SceneLoaderProgressEvent, BaseTexture, Material } from "babylonjs";
 
+/**
+ * This interface defines the structure of a loader plugin.
+ * Any of those functions will be called if (!) the loader supports those callbacks.
+ * Any loader supports onInit, onLoaded, onError and onProgress.
+ */
 export interface ILoaderPlugin {
     onInit?: (loader: ISceneLoaderPlugin | ISceneLoaderPluginAsync, model: ViewerModel) => void;
     onLoaded?: (model: ViewerModel) => void;

Viewer/src/loader/plugins/msftLodLoaderPlugin.ts

@@ -4,7 +4,9 @@ import { ViewerModel } from "../..";
 import { Tools, ISceneLoaderPlugin, ISceneLoaderPluginAsync } from "babylonjs";
 import { IGLTFLoaderExtension, GLTF2 } from "babylonjs-loaders";
 
-
+/**
+ * A loder plugin to use MSFT_lod extension correctly (glTF)
+ */
 export class MSFTLodLoaderPlugin implements ILoaderPlugin {
 
     private _model: ViewerModel;

Viewer/src/loader/plugins/telemetryLoaderPlugin.ts

@@ -17,7 +17,7 @@ export class TelemetryLoaderPlugin implements ILoaderPlugin {
     }
 
     public onLoaded(model: ViewerModel) {
-        telemetryManager.broadcast("Load First LOD Complete", model.getViewer(), {
+        telemetryManager.broadcast("Model Loaded", model.getViewer(), {
             model: model,
             loadTime: Tools.Now - this._loadStart
         });

Viewer/src/model/modelAnimation.ts

@@ -191,11 +191,6 @@ export class GroupModelAnimation implements IModelAnimation {
      * In correlation to an arry, this would be ".length"
      */
     public get frames(): number {
-        /*let animationFrames = this._animationGroup.targetedAnimations.map(ta => {
-            let keys = ta.animation.getKeys();
-            return keys[keys.length - 1].frame;
-        });
-        return Math.max.apply(null, animationFrames);*/
         return this._animationGroup.to - this._animationGroup.from;
     }
 
@@ -206,19 +201,6 @@ export class GroupModelAnimation implements IModelAnimation {
      * In correlation to an array, this would be the current index
      */
     public get currentFrame(): number {
-        // get the first currentFrame found
-        /*for (let i = 0; i < this._animationGroup.animatables.length; ++i) {
-            let animatable: Animatable = this._animationGroup.animatables[i];
-            let animations = animatable.getAnimations();
-            if (!animations || !animations.length) {
-                continue;
-            }
-            for (let idx = 0; idx < animations.length; ++idx) {
-                if (animations[idx].currentFrame) {
-                    return animations[idx].currentFrame;
-                }
-            }
-        }*/
         if (this._animationGroup.targetedAnimations[0] && this._animationGroup.targetedAnimations[0].animation.runtimeAnimations[0]) {
             return this._animationGroup.targetedAnimations[0].animation.runtimeAnimations[0].currentFrame - this._animationGroup.from;
         } else {

Viewer/src/model/viewerModel.ts

@@ -8,6 +8,9 @@ import { AbstractViewer } from "..";
 import { extendClassWithConfig } from "../helper";
 
 
+/**
+ * The current state of the model
+ */
 export enum ModelState {
     INIT,
     LOADING,

Viewer/src/optimizer/custom/extended.ts

@@ -1,6 +1,11 @@
 import { AbstractViewer } from '../../viewer/viewer';
 import { Scalar, DefaultRenderingPipeline } from 'babylonjs';
 
+/**
+ * A custom upgrade-oriented function configuration for the scene optimizer.
+ * 
+ * @param viewer the viewer to optimize
+ */
 export function extendedUpgrade(viewer: AbstractViewer): boolean {
     let defaultPipeline = <DefaultRenderingPipeline>viewer.sceneManager.defaultRenderingPipeline;
     // if (!this.Scene.BackgroundHelper) {
@@ -47,6 +52,11 @@ export function extendedUpgrade(viewer: AbstractViewer): boolean {
     return true;
 }
 
+/**
+ * A custom degrade-oriented function configuration for the scene optimizer.
+ * 
+ * @param viewer the viewer to optimize
+ */
 export function extendedDegrade(viewer: AbstractViewer): boolean {
     let defaultPipeline = <DefaultRenderingPipeline>viewer.sceneManager.defaultRenderingPipeline;
 

Viewer/src/optimizer/custom/index.ts

@@ -3,6 +3,11 @@ import { extendedUpgrade, extendedDegrade } from "./extended";
 
 const cache: { [key: string]: (viewer: AbstractViewer) => boolean } = {};
 
+/**
+ * 
+ * @param name the name of the custom optimizer configuration
+ * @param upgrade set to true if you want to upgrade optimizer and false if you want to degrade
+ */
 export function getCustomOptimizerByName(name: string, upgrade?: boolean) {
     if (!cache[name]) {
         switch (name) {

Viewer/src/telemetryManager.ts

@@ -118,6 +118,9 @@ export class TelemetryManager {
         return this._currentSessionId;
     }
 
+    /**
+     * Disposes the telemetry manager
+     */
     public dispose() {
         this.onEventBroadcastedObservable.clear();
         delete this.onEventBroadcastedObservable;

Viewer/src/templateManager.ts

@@ -7,10 +7,28 @@ import * as deepmerge from '../assets/deepmerge.min.js';
  * A single template configuration object
  */
 export interface ITemplateConfiguration {
+    /**
+     * can be either the id of the template's html element or a URL.
+     * See - http://doc.babylonjs.com/extensions/the_templating_system#location-vs-html
+     */
     location?: string; // #template-id OR http://example.com/loading.html
+    /**
+     * If no location is provided you can provide here the raw html of this template.
+     * See http://doc.babylonjs.com/extensions/the_templating_system#location-vs-html
+     */
     html?: string; // raw html string
     id?: string;
+    /**
+     * Parameters that will be delivered to the template and will render it accordingly.
+     */
     params?: { [key: string]: string | number | boolean | object };
+    /**
+     * Events to attach to this template.
+     * event name is the key. the value can either be a boolean (attach to the parent element)
+     * or a map of html id elements.
+     * 
+     * See - http://doc.babylonjs.com/extensions/the_templating_system#event-binding
+     */
     events?: {
         // pointer events
         pointerdown?: boolean | { [id: string]: boolean; };
@@ -27,6 +45,7 @@ export interface ITemplateConfiguration {
         dragstart?: boolean | { [id: string]: boolean; };
         drop?: boolean | { [id: string]: boolean; };
 
+
         [key: string]: boolean | { [id: string]: boolean; } | undefined;
     }
 }
@@ -371,6 +390,8 @@ export class Template {
      * The parameters are provided to Handlebars which in turn generates the template.
      * This function will update the template with the new parameters
      * 
+     * Note that when updating parameters the events will be registered again (after being cleared).
+     * 
      * @param params the new template parameters
      */
     public updateParams(params: { [key: string]: string | number | boolean | object }, append: boolean = true) {

Viewer/src/viewer/sceneManager.ts

@@ -360,7 +360,7 @@ export class SceneManager {
      * @param newConfiguration the delta that should be configured. This includes only the changes
      * @param globalConfiguration The global configuration object, after the new configuration was merged into it
      */
-    public updateConfiguration(newConfiguration: Partial<ViewerConfiguration>, globalConfiguration: ViewerConfiguration, model?: ViewerModel) {
+    public updateConfiguration(newConfiguration: Partial<ViewerConfiguration>, globalConfiguration: ViewerConfiguration) {
 
 
         if (newConfiguration.lab) {
@@ -385,15 +385,15 @@ export class SceneManager {
         }*/
 
         // lights
-        this._configureLights(newConfiguration.lights, model);
+        this._configureLights(newConfiguration.lights);
 
         // environment
         if (newConfiguration.skybox !== undefined || newConfiguration.ground !== undefined) {
-            this._configureEnvironment(newConfiguration.skybox, newConfiguration.ground, model);
+            this._configureEnvironment(newConfiguration.skybox, newConfiguration.ground);
         }
 
         // camera
-        this._configureCamera(newConfiguration.camera, model);
+        this._configureCamera(newConfiguration.camera);
 
         if (newConfiguration.lab) {
             if (newConfiguration.lab.environmentMap) {
@@ -736,7 +736,7 @@ export class SceneManager {
      * @param cameraConfig the new camera configuration
      * @param model optionally use the model to configure the camera.
      */
-    protected _configureCamera(cameraConfig: ICameraConfiguration = {}, model?: ViewerModel) {
+    protected _configureCamera(cameraConfig: ICameraConfiguration = {}) {
         if (!this.scene.activeCamera) {
             let attachControl = true;
             if (this._viewer.configuration.scene && this._viewer.configuration.scene.disableCameraControl) {
@@ -799,8 +799,7 @@ export class SceneManager {
         this.onCameraConfiguredObservable.notifyObservers({
             sceneManager: this,
             object: this.camera,
-            newConfiguration: cameraConfig,
-            model
+            newConfiguration: cameraConfig
         });
     }
 
@@ -815,7 +814,7 @@ export class SceneManager {
         this.camera.radius = (this._viewer.configuration.camera && this._viewer.configuration.camera.radius) || this.camera.radius;
     }
 
-    protected _configureEnvironment(skyboxConifguration?: ISkyboxConfiguration | boolean, groundConfiguration?: IGroundConfiguration | boolean, model?: ViewerModel) {
+    protected _configureEnvironment(skyboxConifguration?: ISkyboxConfiguration | boolean, groundConfiguration?: IGroundConfiguration | boolean) {
         if (!skyboxConifguration && !groundConfiguration) {
             if (this.environmentHelper) {
                 this.environmentHelper.dispose();
@@ -992,8 +991,7 @@ export class SceneManager {
             newConfiguration: {
                 skybox: skyboxConifguration,
                 ground: groundConfiguration
-            },
-            model
+            }
         });
     }
 
@@ -1003,7 +1001,7 @@ export class SceneManager {
      * @param lightsConfiguration the (new) light(s) configuration
      * @param model optionally use the model to configure the camera.
      */
-    protected _configureLights(lightsConfiguration: { [name: string]: ILightConfiguration | boolean } = {}, model?: ViewerModel) {
+    protected _configureLights(lightsConfiguration: { [name: string]: ILightConfiguration | boolean } = {}) {
 
         // sanity check!
         if (!Object.keys(lightsConfiguration).length) {
@@ -1123,7 +1121,7 @@ export class SceneManager {
                     });
 
                     //if (model) {
-                    this._updateShadowRenderList(shadowGenerator, model);
+                    this._updateShadowRenderList(shadowGenerator);
                     //}
                 } else if (shadowGenerator) {
                     shadowGenerator.dispose();
@@ -1144,8 +1142,7 @@ export class SceneManager {
         this.onLightsConfiguredObservable.notifyObservers({
             sceneManager: this,
             object: this.scene.lights,
-            newConfiguration: lightsConfiguration,
-            model
+            newConfiguration: lightsConfiguration
         });
     }
 

Viewer/src/viewer/viewer.ts

@@ -134,6 +134,9 @@ export abstract class AbstractViewer {
      */
     protected _configurationLoader: ConfigurationLoader;
 
+    /**
+     * Is the viewer already initialized. for internal use.
+     */
     protected _isInit: boolean;
 
     constructor(public containerElement: HTMLElement, initialConfiguration: ViewerConfiguration = {}) {
@@ -334,13 +337,14 @@ export abstract class AbstractViewer {
      * Only provided information will be updated, old configuration values will be kept.
      * If this.configuration was manually changed, you can trigger this function with no parameters, 
      * and the entire configuration will be updated. 
-     * @param newConfiguration 
+     * @param newConfiguration the partial configuration to update
+     * 
      */
-    public updateConfiguration(newConfiguration: Partial<ViewerConfiguration> = this._configuration, mode?: ViewerModel) {
+    public updateConfiguration(newConfiguration: Partial<ViewerConfiguration> = this._configuration) {
         // update this.configuration with the new data
         this._configuration = deepmerge(this._configuration || {}, newConfiguration);
 
-        this.sceneManager.updateConfiguration(newConfiguration, this._configuration, mode);
+        this.sceneManager.updateConfiguration(newConfiguration, this._configuration);
 
         // observers in configuration
         if (newConfiguration.observers) {
@@ -397,27 +401,21 @@ export abstract class AbstractViewer {
 
         //observers
         this.onEngineInitObservable.clear();
-        delete this.onEngineInitObservable;
         this.onInitDoneObservable.clear();
-        delete this.onInitDoneObservable;
         this.onLoaderInitObservable.clear();
-        delete this.onLoaderInitObservable;
         this.onModelLoadedObservable.clear();
-        delete this.onModelLoadedObservable;
         this.onModelLoadErrorObservable.clear();
-        delete this.onModelLoadErrorObservable;
         this.onModelLoadProgressObservable.clear();
-        delete this.onModelLoadProgressObservable;
         this.onSceneInitObservable.clear();
-        delete this.onSceneInitObservable;
         this.onFrameRenderedObservable.clear();
-        delete this.onFrameRenderedObservable;
+        this.onModelAddedObservable.clear();
+        this.onModelRemovedObservable.clear();
 
         if (this.sceneManager.scene.activeCamera) {
             this.sceneManager.scene.activeCamera.detachControl(this.canvas);
         }
 
-        this._fpsTimeout && clearTimeout(this._fpsTimeout);
+        this._fpsTimeoutInterval && clearInterval(this._fpsTimeoutInterval);
 
 
         this.sceneManager.dispose();
@@ -515,10 +513,9 @@ export abstract class AbstractViewer {
     }
 
     private _isLoading: boolean;
-    private _nextLoading: Function;
 
     /**
-     * Initialize a model loading. The returns object (a ViewerModel object) will be loaded in the background.
+     * Initialize a model loading. The returned object (a ViewerModel object) will be loaded in the background.
      * The difference between this and loadModel is that loadModel will fulfill the promise when the model finished loading.
      * 
      * @param modelConfig model configuration to use when loading the model.
@@ -570,7 +567,9 @@ export abstract class AbstractViewer {
     }
 
     /**
-     * load a model using the provided configuration
+     * load a model using the provided configuration.
+     * This function, as opposed to initModel, will return a promise that resolves when the model is loaded, and rejects with error.
+     * If you want to attach to the observables of the model, use initModle instead.
      * 
      * @param modelConfig the model configuration or URL to load.
      * @param clearScene Should the scene be cleared before loading the model
@@ -599,7 +598,8 @@ export abstract class AbstractViewer {
         })
     }
 
-    private _fpsTimeout: number;
+    private _fpsTimeoutInterval: number;
+
 
     protected _initTelemetryEvents() {
         telemetryManager.broadcast("Engine Capabilities", this, this.engine.getCaps());
@@ -616,7 +616,7 @@ export abstract class AbstractViewer {
 
         trackFPS();
         // Track the FPS again after 60 seconds
-        this._fpsTimeout = window.setTimeout(trackFPS, 60 * 1000);
+        this._fpsTimeoutInterval = window.setInterval(trackFPS, 60 * 1000);
     }
 
     /**