Merge pull request #5178 from sebavan/master

Audio + Doc

src/Audio/babylon.audioEngine.ts

@@ -243,9 +243,15 @@
             }
         }
 
+        private _tryToRun = false;
         private _triggerRunningState() {
+            if (this._tryToRun) {
+                return;
+            }
+            this._tryToRun = true;
             this._resumeAudioContext()
                 .then(() => {
+                    this._tryToRun = false;
                     this.unlocked = true;
                     if (this._muteButton) {
                         this._hideMuteButton(); 
@@ -254,6 +260,7 @@
                     // Notify users that the audio stack is unlocked/unmuted
                     this.onAudioUnlockedObservable.notifyObservers(this);
                 }).catch(() => {
+                    this._tryToRun = false;
                     this.unlocked = false;
                 });
         }
@@ -287,10 +294,13 @@
 
             this._muteButton.addEventListener('mousedown', () => { 
                 this._triggerRunningState();
-            }, false);
+            }, true);
             this._muteButton.addEventListener('touchend', () => { 
                 this._triggerRunningState();
-            }, false);
+            }, true);
+            this._muteButton.addEventListener('click', () => {
+                this._triggerRunningState();
+            }, true);
 
             window.addEventListener("resize", this._onResize);
         }

src/Cameras/Inputs/babylon.arcRotateCameraPointersInput.ts

@@ -281,7 +281,7 @@ module BABYLON {
                 }
             }
 
-            this._observer = this.camera.getScene().onPointerObservable.add(this._pointerInput, PointerEventTypes.POINTERDOWN | PointerEventTypes.POINTERUP | PointerEventTypes.POINTERMOVE | PointerEventTypes._POINTERDOUBLETAP);
+            this._observer = this.camera.getScene().onPointerObservable.add(this._pointerInput, PointerEventTypes.POINTERDOWN | PointerEventTypes.POINTERUP | PointerEventTypes.POINTERMOVE | PointerEventTypes.POINTERDOUBLETAP);
 
             this._onContextMenu = evt => {
                 evt.preventDefault();

src/Events/babylon.keyboardEvents.ts

@@ -1,20 +1,37 @@
 module BABYLON {
-    
+    /**
+     * Gather the list of keyboard event types as constants.
+     */
     export class KeyboardEventTypes {
-        static _KEYDOWN = 0x01;
-        static _KEYUP = 0x02;
-
-        public static get KEYDOWN(): number {
-            return KeyboardEventTypes._KEYDOWN;
-        }
-
-        public static get KEYUP(): number {
-            return KeyboardEventTypes._KEYUP;
-        }
+        /**
+         * The keydown event is fired when a key becomes active (pressed).
+         */
+        public static readonly KEYDOWN = 0x01;
+        /**
+         * The keyup event is fired when a key has been released.
+         */
+        public static readonly KEYUP = 0x02;
     }
 
+    /**
+     * This class is used to store keyboard related info for the onKeyboardObservable event.
+     */
     export class KeyboardInfo {
-        constructor(public type: number, public event: KeyboardEvent) {
+        /**
+         * Instantiates a new keyboard info.
+         * This class is used to store keyboard related info for the onKeyboardObservable event.
+         * @param type Defines the type of event (BABYLON.KeyboardEventTypes)
+         * @param event Defines the related dom event
+         */
+        constructor(
+            /**
+             * Defines the type of event (BABYLON.KeyboardEventTypes)
+             */
+            public type: number,
+            /**
+             * Defines the related dom event
+             */
+            public event: KeyboardEvent) {
         }
     }
 
@@ -23,11 +40,28 @@ module BABYLON {
      * Set the skipOnKeyboardObservable property to true if you want the engine to stop any process after this event is triggered, even not calling onKeyboardObservable
      */
     export class KeyboardInfoPre extends KeyboardInfo {
-        constructor(type: number, event: KeyboardEvent) {
+        /**
+         * Defines whether the engine should skip the next onKeyboardObservable associated to this pre.
+         */
+        public skipOnPointerObservable: boolean;
+
+        /**
+         * Instantiates a new keyboard pre info.
+         * This class is used to store keyboard related info for the onPreKeyboardObservable event.
+         * @param type Defines the type of event (BABYLON.KeyboardEventTypes)
+         * @param event Defines the related dom event
+         */
+        constructor(
+            /**
+             * Defines the type of event (BABYLON.KeyboardEventTypes)
+             */
+            public type: number,
+            /**
+             * Defines the related dom event
+             */
+            public event: KeyboardEvent) {
             super(type, event);
             this.skipOnPointerObservable = false;
         }
-
-        public skipOnPointerObservable: boolean;
-    }   
+    }
 }

src/Events/babylon.pointerEvents.ts

@@ -1,44 +1,56 @@
 module BABYLON {
+    /**
+     * Gather the list of pointer event types as constants.
+     */
     export class PointerEventTypes {
-        static _POINTERDOWN = 0x01;
-        static _POINTERUP = 0x02;
-        static _POINTERMOVE = 0x04;
-        static _POINTERWHEEL = 0x08;
-        static _POINTERPICK = 0x10;
-        static _POINTERTAP = 0x20;
-        static _POINTERDOUBLETAP = 0x40;
-
-        public static get POINTERDOWN(): number {
-            return PointerEventTypes._POINTERDOWN;
-        }
-
-        public static get POINTERUP(): number {
-            return PointerEventTypes._POINTERUP;
-        }
-
-        public static get POINTERMOVE(): number {
-            return PointerEventTypes._POINTERMOVE;
-        }
-
-        public static get POINTERWHEEL(): number {
-            return PointerEventTypes._POINTERWHEEL;
-        }
-
-        public static get POINTERPICK(): number {
-            return PointerEventTypes._POINTERPICK;
-        }
-
-        public static get POINTERTAP(): number {
-            return PointerEventTypes._POINTERTAP;
-        }
-
-        public static get POINTERDOUBLETAP(): number {
-            return PointerEventTypes._POINTERDOUBLETAP;
-        }
+        /**
+         * The pointerdown event is fired when a pointer becomes active. For mouse, it is fired when the device transitions from no buttons depressed to at least one button depressed. For touch, it is fired when physical contact is made with the digitizer. For pen, it is fired when the stylus makes physical contact with the digitizer.
+         */
+        public static readonly POINTERDOWN = 0x01;
+        /**
+         * The pointerup event is fired when a pointer is no longer active.
+         */
+        public static readonly POINTERUP = 0x02;
+        /**
+         * The pointermove event is fired when a pointer changes coordinates.
+         */
+        public static readonly POINTERMOVE = 0x04;
+        /**
+         * The pointerwheel event is fired when a mouse wheel has been rotated.
+         */
+        public static readonly POINTERWHEEL = 0x08;
+        /**
+         * The pointerpick event is fired when a mesh or sprite has been picked by the pointer.
+         */
+        public static readonly POINTERPICK = 0x10;
+        /**
+         * The pointertap event is fired when a the object has been touched and released without drag.
+         */
+        public static readonly POINTERTAP = 0x20;
+        /**
+         * The pointertap event is fired when a the object has been touched and released twice without drag.
+         */
+        public static readonly POINTERDOUBLETAP = 0x40;
     }
 
+    /**
+     * Base class of pointer info types.
+     */
     export class PointerInfoBase {
-        constructor(public type: number, public event: PointerEvent | MouseWheelEvent) {
+        /**
+         * Instantiates the base class of pointers info.
+         * @param type Defines the type of event (BABYLON.PointerEventTypes)
+         * @param event Defines the related dom event
+         */
+        constructor(
+            /**
+             * Defines the type of event (BABYLON.PointerEventTypes)
+             */
+            public type: number, 
+            /**
+             * Defines the related dom event
+             */
+            public event: PointerEvent | MouseWheelEvent) {
         }
     }
 
@@ -51,14 +63,29 @@ module BABYLON {
          * Ray from a pointer if availible (eg. 6dof controller)
          */
         public ray:Nullable<Ray> = null;
+
+        /**
+         * Defines the local position of the pointer on the canvas.
+         */
+        public localPosition: Vector2;
+
+        /**
+         * Defines whether the engine should skip the next OnPointerObservable associated to this pre.
+         */
+        public skipOnPointerObservable: boolean;
+
+        /**
+         * Instantiates a PointerInfoPre to store pointer related info to the onPrePointerObservable event.
+         * @param type Defines the type of event (BABYLON.PointerEventTypes)
+         * @param event Defines the related dom event
+         * @param localX Defines the local x coordinates of the pointer when the event occured
+         * @param localY Defines the local y coordinates of the pointer when the event occured
+         */
         constructor(type: number, event: PointerEvent | MouseWheelEvent, localX: number, localY: number) {
             super(type, event);
             this.skipOnPointerObservable = false;
             this.localPosition = new Vector2(localX, localY);
         }
-
-        public localPosition: Vector2;
-        public skipOnPointerObservable: boolean;
     }
 
     /**
@@ -66,7 +93,18 @@ module BABYLON {
      * The event member is an instance of PointerEvent for all types except PointerWheel and is of type MouseWheelEvent when type equals PointerWheel. The different event types can be found in the PointerEventTypes class.
      */
     export class PointerInfo extends PointerInfoBase {
-        constructor(type: number, event: PointerEvent | MouseWheelEvent, public pickInfo: Nullable<PickingInfo>) {
+        /**
+         * Instantiates a PointerInfo to store pointer related info to the onPointerObservable event.
+         * @param type Defines the type of event (BABYLON.PointerEventTypes)
+         * @param event Defines the related dom event
+         * @param pickInfo Defines the picking info associated to the info (if any)\
+         */
+        constructor(type: number, 
+            event: PointerEvent | MouseWheelEvent, 
+            /**
+             * Defines the picking info associated to the info (if any)\
+             */
+            public pickInfo: Nullable<PickingInfo>) {
             super(type, event);
         }
     }    

src/Instrumentation/babylon.engineInstrumentation.ts

@@ -1,6 +1,7 @@
 module BABYLON {
     /**
      * This class can be used to get instrumentation data from a Babylon engine
+     * @see http://doc.babylonjs.com/how_to/optimizing_your_scene#engineinstrumentation
      */
     export class EngineInstrumentation implements IDisposable {
         private _captureGPUFrameTime = false;
@@ -8,7 +9,7 @@ module BABYLON {
         private _gpuFrameTime = new PerfCounter();
 
         private _captureShaderCompilationTime = false;
-        private _shaderCompilationTime = new PerfCounter();        
+        private _shaderCompilationTime = new PerfCounter();
 
         // Observers
         private _onBeginFrameObserver: Nullable<Observer<Engine>> = null;
@@ -109,9 +110,22 @@ module BABYLON {
             }
         }
 
-        public constructor(public engine: Engine) {
+        /**
+         * Instantiates a new engine instrumentation.
+         * This class can be used to get instrumentation data from a Babylon engine
+         * @see http://doc.babylonjs.com/how_to/optimizing_your_scene#engineinstrumentation
+         * @param engine Defines the engine to instrument
+         */
+        public constructor(
+            /**
+             * Define the instrumented engine.
+             */
+            public engine: Engine) {
         }
 
+        /**
+         * Dispose and release associated resources.
+         */
         public dispose() {
             this.engine.onBeginFrameObservable.remove(this._onBeginFrameObserver);
             this._onBeginFrameObserver = null;

src/Instrumentation/babylon.sceneInstrumentation.ts

@@ -1,6 +1,7 @@
 module BABYLON {
     /**
      * This class can be used to get instrumentation data from a Babylon engine
+     * @see http://doc.babylonjs.com/how_to/optimizing_your_scene#sceneinstrumentation
      */
     export class SceneInstrumentation implements IDisposable {
         private _captureActiveMeshesEvaluationTime = false;
@@ -459,7 +460,17 @@ module BABYLON {
             return this.scene.getEngine()._textureCollisions;
         }
 
-        public constructor(public scene: Scene) {
+        /**
+         * Instantiates a new scene instrumentation.
+         * This class can be used to get instrumentation data from a Babylon engine
+         * @see http://doc.babylonjs.com/how_to/optimizing_your_scene#sceneinstrumentation
+         * @param scene Defines the scene to instrument
+         */
+        public constructor(
+            /**
+             * Defines the scene to instrument
+             */
+            public scene: Scene) {
             // Before render
             this._onBeforeAnimationsObserver = scene.onBeforeAnimationsObservable.add(() => {
                 if (this._captureActiveMeshesEvaluationTime) {
@@ -512,6 +523,9 @@ module BABYLON {
             });
         }
 
+        /**
+         * Dispose and release associated resources.
+         */
         public dispose() {
             this.scene.onAfterRenderObservable.remove(this._onAfterRenderObserver);
             this._onAfterRenderObserver = null;

src/Instrumentation/babylon.timeToken.ts

@@ -1,7 +1,7 @@
 module BABYLON {
     /**
      * @hidden
-     **/    
+     **/
     export class _TimeToken {
         public _startTimeQuery: Nullable<WebGLQuery>;
         public _endTimeQuery: Nullable<WebGLQuery>;

src/Layer/babylon.layer.ts

@@ -1,12 +1,51 @@
 module BABYLON {
+
+    /**
+     * This represents a full screen 2d layer.
+     * This can be usefull to display a picture in the  background of your scene for instance.
+     * @see https://www.babylonjs-playground.com/#08A2BS#1
+     */
     export class Layer {
+        /**
+         * Define the texture the layer should display.
+         */
         public texture: Nullable<Texture>;
+
+        /**
+         * Is the layer in background or foreground.
+         */
         public isBackground: boolean;
+
+        /**
+         * Define the color of the layer (instead of texture).
+         */
         public color: Color4;
+
+        /**
+         * Define the scale of the layer in order to zoom in out of the texture.
+         */
         public scale = new Vector2(1, 1);
+
+        /**
+         * Define an offset for the layer in order to shift the texture.
+         */
         public offset = new Vector2(0, 0);
+        
+        /**
+         * Define the alpha blending mode used in the layer in case the texture or color has an alpha.
+         */
         public alphaBlendingMode = Engine.ALPHA_COMBINE;
+
+        /**
+         * Define if the layer should alpha test or alpha blend with the rest of the scene.
+         * Alpha test will not mix with the background color in case of transparency.
+         * It will either use the texture color or the background depending on the alpha value of the current pixel.
+         */
         public alphaTest: boolean;
+
+        /**
+         * Define a mask to restrict the layer to only some of the scene cameras.
+         */
         public layerMask: number = 0x0FFFFFFF;
         
         private _scene: Scene;
@@ -15,15 +54,16 @@
         private _effect: Effect;
         private _alphaTestEffect: Effect;
 
-
-        // Events
-
         /**
-        * An event triggered when the layer is disposed.
-        */
+         * An event triggered when the layer is disposed.
+         */
         public onDisposeObservable = new Observable<Layer>();
 
         private _onDisposeObserver: Nullable<Observer<Layer>>;
+        /**
+         * Back compatibility with callback before the onDisposeObservable existed.
+         * The set callback will be triggered when the layer has been disposed.
+         */
         public set onDispose(callback: () => void) {
             if (this._onDisposeObserver) {
                 this.onDisposeObservable.remove(this._onDisposeObserver);
@@ -37,6 +77,10 @@
         public onBeforeRenderObservable = new Observable<Layer>();
 
         private _onBeforeRenderObserver: Nullable<Observer<Layer>>;
+        /**
+         * Back compatibility with callback before the onBeforeRenderObservable existed.
+         * The set callback will be triggered just before rendering the layer.
+         */
         public set onBeforeRender(callback: () => void) {
             if (this._onBeforeRenderObserver) {
                 this.onBeforeRenderObservable.remove(this._onBeforeRenderObserver);
@@ -57,6 +101,17 @@
             this._onAfterRenderObserver = this.onAfterRenderObservable.add(callback);
         }
 
+        /**
+         * Instantiates a new layer.
+         * This represents a full screen 2d layer.
+         * This can be usefull to display a picture in the  background of your scene for instance.
+         * @see https://www.babylonjs-playground.com/#08A2BS#1
+         * @param name Define the name of the layer in the scene
+         * @param imgUrl Define the url of the texture to display in the layer
+         * @param scene Define the scene the layer belongs to
+         * @param isBackground Defines whether the layer is displayed in front or behind the scene
+         * @param color Defines a color for the layer
+         */
         constructor(public name: string, imgUrl: Nullable<string>, scene: Nullable<Scene>, isBackground?: boolean, color?: Color4) {
             this.texture = imgUrl ? new Texture(imgUrl, scene, true) : null;
             this.isBackground = isBackground === undefined ? true : isBackground;
@@ -123,6 +178,9 @@
             this._createIndexBuffer();
         }
 
+        /**
+         * Renders the layer in the scene.
+         */
         public render(): void {
             var currentEffect = this.alphaTest ? this._alphaTestEffect : this._effect;
 
@@ -165,6 +223,9 @@
             this.onAfterRenderObservable.notifyObservers(this);
         }
 
+        /**
+         * Disposes and releases the associated ressources.
+         */
         public dispose(): void {
             var vertexBuffer = this._vertexBuffers[VertexBuffer.PositionKind];
             if (vertexBuffer) {