Merge pull request #5175 from sebavan/master

Nightly Audio

dist/preview release/babylon.max.js

@@ -9208,6 +9208,11 @@ var BABYLON;
                 document.msCancelFullScreen();
             }
         };
+        /**
+         * Sets the cors behavior on a dom element. This will add the required Tools.CorsBehavior to the element.
+         * @param url define the url we are trying
+         * @param element define the dom element where to configure the cors policy
+         */
         Tools.SetCorsBehavior = function (url, element) {
             if (url && url.indexOf("data:") === 0) {
                 return;
@@ -10535,14 +10540,14 @@ var BABYLON;
         /**
          * Create and run an async loop.
          * @param iterations the number of iterations.
-         * @param _fn the function to run each iteration
-         * @param _successCallback the callback that will be called upon succesful execution
+         * @param fn the function to run each iteration
+         * @param successCallback the callback that will be called upon succesful execution
          * @param offset starting offset.
          * @returns the created async loop object
          */
-        AsyncLoop.Run = function (iterations, _fn, _successCallback, offset) {
+        AsyncLoop.Run = function (iterations, fn, successCallback, offset) {
             if (offset === void 0) { offset = 0; }
-            var loop = new AsyncLoop(iterations, _fn, _successCallback, offset);
+            var loop = new AsyncLoop(iterations, fn, successCallback, offset);
             loop.executeNext();
             return loop;
         };
@@ -55583,6 +55588,9 @@ var BABYLON;
 
 var BABYLON;
 (function (BABYLON) {
+    /**
+     * @hidden
+     */
     var IntersectionInfo = /** @class */ (function () {
         function IntersectionInfo(bu, bv, distance) {
             this.bu = bu;
@@ -55596,7 +55604,7 @@ var BABYLON;
     BABYLON.IntersectionInfo = IntersectionInfo;
     /**
      * Information about the result of picking within a scene
-     * See https://doc.babylonjs.com/babylon101/picking_collisions
+     * @see https://doc.babylonjs.com/babylon101/picking_collisions
      */
     var PickingInfo = /** @class */ (function () {
         function PickingInfo() {
@@ -62981,15 +62989,36 @@ var BABYLON;
         enumerable: true,
         configurable: true
     });
+    /**
+     * Component responsible of rendering the bounding box of the meshes in a scene.
+     * This is usually used through the mesh.showBoundingBox or the scene.forceShowBoundingBoxes properties
+     *
+     */
     var BoundingBoxRenderer = /** @class */ (function () {
+        /**
+         * Instantiates a new bounding box renderer in a scene.
+         * @param scene the scene the  renderer renders in
+         */
         function BoundingBoxRenderer(scene) {
             /**
              * The component name helpfull to identify the component in the list of scene components.
              */
             this.name = BABYLON.SceneComponentConstants.NAME_BOUNDINGBOXRENDERER;
+            /**
+             * Color of the bounding box lines placed in front of an object
+             */
             this.frontColor = new BABYLON.Color3(1, 1, 1);
+            /**
+             * Color of the bounding box lines placed behind an object
+             */
             this.backColor = new BABYLON.Color3(0.1, 0.1, 0.1);
+            /**
+             * Defines if the renderer should show the back lines or not
+             */
             this.showBackLines = true;
+            /**
+             * @hidden
+             */
             this.renderList = new BABYLON.SmartArray(32);
             this._vertexBuffers = {};
             this.scene = scene;
@@ -63048,6 +63077,9 @@ var BABYLON;
             }
             this._createIndexBuffer();
         };
+        /**
+         * @hidden
+         */
         BoundingBoxRenderer.prototype.reset = function () {
             this.renderList.reset();
         };
@@ -63101,6 +63133,10 @@ var BABYLON;
             engine.setDepthFunctionToLessOrEqual();
             engine.setDepthWrite(true);
         };
+        /**
+         * In case of occlusion queries, we can render the occlusion bounding box through this method
+         * @param mesh Define the mesh to render the occlusion bounding box for
+         */
         BoundingBoxRenderer.prototype.renderOcclusionBoundingBox = function (mesh) {
             this._prepareRessources();
             if (!this._colorShader.isReady() || !mesh._boundingInfo) {
@@ -63128,6 +63164,9 @@ var BABYLON;
             engine.setDepthWrite(true);
             engine.setColorWrite(true);
         };
+        /**
+         * Dispose and release the resources attached to this renderer.
+         */
         BoundingBoxRenderer.prototype.dispose = function () {
             if (!this._colorShader) {
                 return;
@@ -67336,7 +67375,6 @@ var BABYLON;
             var _this = this;
             this._audioContext = null;
             this._audioContextInitialized = false;
-            this._muteButtonDisplayed = false;
             this._muteButton = null;
             /**
              * Gets whether the current host supports Web Audio and thus could create AudioContexts.
@@ -67360,7 +67398,7 @@ var BABYLON;
              * Some Browsers have strong restrictions about Audio and won t autoplay unless
              * a user interaction has happened.
              */
-            this.unlocked = false;
+            this.unlocked = true;
             /**
              * Defines if the audio engine relies on a custom unlocked button.
              * In this case, the embedded button will not be displayed.
@@ -67409,7 +67447,7 @@ var BABYLON;
                     this._initializeAudioContext();
                 }
                 else {
-                    if (!this.unlocked && !this._muteButtonDisplayed) {
+                    if (!this.unlocked && !this._muteButton) {
                         this._displayMuteButton();
                     }
                 }
@@ -67433,9 +67471,11 @@ var BABYLON;
             this._triggerRunningState();
         };
         AudioEngine.prototype._resumeAudioContext = function () {
+            var result;
             if (this._audioContext.resume) {
-                this._audioContext.resume();
+                result = this._audioContext.resume();
             }
+            return result || Promise.resolve();
         };
         AudioEngine.prototype._initializeAudioContext = function () {
             var _this = this;
@@ -67448,21 +67488,19 @@ var BABYLON;
                     this.masterGain.connect(this._audioContext.destination);
                     this._audioContextInitialized = true;
                     if (this._audioContext.state === "running") {
+                        // Do not wait for the promise to unlock.
                         this._triggerRunningState();
                     }
                     else {
-                        if (!this._muteButtonDisplayed) {
-                            this._displayMuteButton();
-                        }
-                        // 3 possible states: https://webaudio.github.io/web-audio-api/#BaseAudioContext
-                        this._audioContext.addEventListener("statechange", function () {
-                            if (_this._audioContext.state === "running") {
+                        if (this._audioContext && this._audioContext.resume) {
+                            this._resumeAudioContext().then(function () {
                                 _this._triggerRunningState();
-                            }
-                            else {
-                                _this._triggerSuspendedState();
-                            }
-                        });
+                            }).catch(function () {
+                                // Can not resume automatically
+                                // Needs user action
+                                _this.lock();
+                            });
+                        }
                     }
                 }
             }
@@ -67472,13 +67510,18 @@ var BABYLON;
             }
         };
         AudioEngine.prototype._triggerRunningState = function () {
-            this._resumeAudioContext();
-            this.unlocked = true;
-            if (this._muteButtonDisplayed) {
-                this._hideMuteButton();
-            }
-            // Notify users that the audio stack is unlocked/unmuted
-            this.onAudioUnlockedObservable.notifyObservers(this);
+            var _this = this;
+            this._resumeAudioContext()
+                .then(function () {
+                _this.unlocked = true;
+                if (_this._muteButton) {
+                    _this._hideMuteButton();
+                }
+                // Notify users that the audio stack is unlocked/unmuted
+                _this.onAudioUnlockedObservable.notifyObservers(_this);
+            }).catch(function () {
+                _this.unlocked = false;
+            });
         };
         AudioEngine.prototype._triggerSuspendedState = function () {
             this.unlocked = false;
@@ -67507,7 +67550,6 @@ var BABYLON;
             this._muteButton.addEventListener('touchend', function () {
                 _this._triggerRunningState();
             }, false);
-            this._muteButtonDisplayed = true;
             window.addEventListener("resize", this._onResize);
         };
         AudioEngine.prototype._moveButtonToTopLeft = function () {
@@ -67517,9 +67559,9 @@ var BABYLON;
             }
         };
         AudioEngine.prototype._hideMuteButton = function () {
-            if (this._muteButtonDisplayed && this._muteButton) {
+            if (this._muteButton) {
                 document.body.removeChild(this._muteButton);
-                this._muteButtonDisplayed = false;
+                this._muteButton = null;
             }
         };
         /**
@@ -67619,18 +67661,43 @@ var BABYLON;
              */
             this.useCustomAttenuation = false;
             /**
+             * Is this sound currently played.
+             */
+            this.isPlaying = false;
+            /**
+             * Is this sound currently paused.
+             */
+            this.isPaused = false;
+            /**
              * Does this sound enables spatial sound.
+             * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#creating-a-spatial-3d-sound
              */
             this.spatialSound = false;
+            /**
+             * Define the reference distance the sound should be heard perfectly.
+             * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#creating-a-spatial-3d-sound
+             */
             this.refDistance = 1;
+            /**
+             * Define the roll off factor of spatial sounds.
+             * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#creating-a-spatial-3d-sound
+             */
             this.rolloffFactor = 1;
+            /**
+             * Define the max distance the sound should be heard (intensity just became 0 at this point).
+             * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#creating-a-spatial-3d-sound
+             */
             this.maxDistance = 100;
+            /**
+             * Define the distance attenuation model the sound will follow.
+             * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#creating-a-spatial-3d-sound
+             */
             this.distanceModel = "linear";
-            this._panningModel = "equalpower";
             /**
              * Observable event when the current playing sound finishes.
              */
             this.onEndedObservable = new BABYLON.Observable();
+            this._panningModel = "equalpower";
             this._playbackRate = 1;
             this._streaming = false;
             this._startTime = 0;
@@ -67641,8 +67708,6 @@ var BABYLON;
             this._localDirection = new BABYLON.Vector3(1, 0, 0);
             this._volume = 1;
             this._isReadyToPlay = false;
-            this.isPlaying = false;
-            this.isPaused = false;
             this._isDirectional = false;
             // Used if you'd like to create a directional sound.
             // If not set, the sound will be omnidirectional
@@ -67829,6 +67894,9 @@ var BABYLON;
                 }
             }
         }
+        /**
+         * Release the sound and its associated resources
+         */
         Sound.prototype.dispose = function () {
             if (BABYLON.Engine.audioEngine.canUseWebAudio) {
                 if (this.isPlaying) {
@@ -67868,6 +67936,10 @@ var BABYLON;
                 }
             }
         };
+        /**
+         * Gets if the sounds is ready to be played or not.
+         * @returns true if ready, otherwise false
+         */
         Sound.prototype.isReady = function () {
             return this._isReadyToPlay;
         };
@@ -67887,12 +67959,20 @@ var BABYLON;
                 }
             }, function (err) { BABYLON.Tools.Error("Error while decoding audio data for: " + _this.name + " / Error: " + err); });
         };
+        /**
+         * Sets the data of the sound from an audiobuffer
+         * @param audioBuffer The audioBuffer containing the data
+         */
         Sound.prototype.setAudioBuffer = function (audioBuffer) {
             if (BABYLON.Engine.audioEngine.canUseWebAudio) {
                 this._audioBuffer = audioBuffer;
                 this._isReadyToPlay = true;
             }
         };
+        /**
+         * Updates the current sounds options such as maxdistance, loop...
+         * @param options A JSON object containing values named as the object properties
+         */
         Sound.prototype.updateOptions = function (options) {
             if (options) {
                 this.loop = options.loop || this.loop;
@@ -67945,10 +68025,20 @@ var BABYLON;
                 }
             }
         };
+        /**
+         * Switch the panning model to HRTF:
+         * Renders a stereo output of higher quality than equalpower — it uses a convolution with measured impulse responses from human subjects.
+         * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#creating-a-spatial-3d-sound
+         */
         Sound.prototype.switchPanningModelToHRTF = function () {
             this._panningModel = "HRTF";
             this._switchPanningModel();
         };
+        /**
+         * Switch the panning model to Equal Power:
+         * Represents the equal-power panning algorithm, generally regarded as simple and efficient. equalpower is the default value.
+         * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#creating-a-spatial-3d-sound
+         */
         Sound.prototype.switchPanningModelToEqualPower = function () {
             this._panningModel = "equalpower";
             this._switchPanningModel();
@@ -67958,6 +68048,10 @@ var BABYLON;
                 this._soundPanner.panningModel = this._panningModel;
             }
         };
+        /**
+         * Connect this sound to a sound track audio node like gain...
+         * @param soundTrackAudioNode the sound track audio node to connect to
+         */
         Sound.prototype.connectToSoundTrackAudioNode = function (soundTrackAudioNode) {
             if (BABYLON.Engine.audioEngine.canUseWebAudio) {
                 if (this._isOutputConnected) {
@@ -68037,12 +68131,20 @@ var BABYLON;
             enumerable: true,
             configurable: true
         });
+        /**
+         * Sets the position of the emitter if spatial sound is enabled
+         * @param newPosition Defines the new posisiton
+         */
         Sound.prototype.setPosition = function (newPosition) {
             this._position = newPosition;
             if (BABYLON.Engine.audioEngine.canUseWebAudio && this.spatialSound && this._soundPanner && !isNaN(this._position.x) && !isNaN(this._position.y) && !isNaN(this._position.z)) {
                 this._soundPanner.setPosition(this._position.x, this._position.y, this._position.z);
             }
         };
+        /**
+         * Sets the local direction of the emitter if spatial sound is enabled
+         * @param newLocalDirection Defines the new local direction
+         */
         Sound.prototype.setLocalDirectionToMesh = function (newLocalDirection) {
             this._localDirection = newLocalDirection;
             if (BABYLON.Engine.audioEngine.canUseWebAudio && this._connectedMesh && this.isPlaying) {
@@ -68058,12 +68160,18 @@ var BABYLON;
             direction.normalize();
             this._soundPanner.setOrientation(direction.x, direction.y, direction.z);
         };
+        /** @hidden */
         Sound.prototype.updateDistanceFromListener = function () {
             if (BABYLON.Engine.audioEngine.canUseWebAudio && this._connectedMesh && this.useCustomAttenuation && this._soundGain && this._scene.activeCamera) {
                 var distance = this._connectedMesh.getDistanceToCamera(this._scene.activeCamera);
                 this._soundGain.gain.value = this._customAttenuationFunction(this._volume, distance, this.maxDistance, this.refDistance, this.rolloffFactor);
             }
         };
+        /**
+         * Sets a new custom attenuation function for the sound.
+         * @param callback Defines the function used for the attenuation
+         * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#creating-your-own-custom-attenuation-function
+         */
         Sound.prototype.setAttenuationFunction = function (callback) {
             this._customAttenuationFunction = callback;
         };
@@ -68189,6 +68297,9 @@ var BABYLON;
                 this.isPlaying = false;
             }
         };
+        /**
+         * Put the sound in pause
+         */
         Sound.prototype.pause = function () {
             if (this.isPlaying) {
                 this.isPaused = true;
@@ -68206,6 +68317,11 @@ var BABYLON;
                 }
             }
         };
+        /**
+         * Sets a dedicated volume for this sounds
+         * @param newVolume Define the new volume of the sound
+         * @param time Define in how long the sound should be at this value
+         */
         Sound.prototype.setVolume = function (newVolume, time) {
             if (BABYLON.Engine.audioEngine.canUseWebAudio && this._soundGain) {
                 if (time && BABYLON.Engine.audioEngine.audioContext) {
@@ -68219,6 +68335,10 @@ var BABYLON;
             }
             this._volume = newVolume;
         };
+        /**
+         * Set the sound play back rate
+         * @param newPlaybackRate Define the playback rate the sound should be played at
+         */
         Sound.prototype.setPlaybackRate = function (newPlaybackRate) {
             this._playbackRate = newPlaybackRate;
             if (this.isPlaying) {
@@ -68230,9 +68350,18 @@ var BABYLON;
                 }
             }
         };
+        /**
+         * Gets the volume of the sound.
+         * @returns the volume of the sound
+         */
         Sound.prototype.getVolume = function () {
             return this._volume;
         };
+        /**
+         * Attach the sound to a dedicated mesh
+         * @param meshToConnectTo The mesh to connect the sound with
+         * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#attaching-a-sound-to-a-mesh
+         */
         Sound.prototype.attachToMesh = function (meshToConnectTo) {
             var _this = this;
             if (this._connectedMesh && this._registerFunc) {
@@ -68252,6 +68381,10 @@ var BABYLON;
             this._registerFunc = function (connectedMesh) { return _this._onRegisterAfterWorldMatrixUpdate(connectedMesh); };
             meshToConnectTo.registerAfterWorldMatrixUpdate(this._registerFunc);
         };
+        /**
+         * Detach the sound from the previously attached mesh
+         * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#attaching-a-sound-to-a-mesh
+         */
         Sound.prototype.detachFromMesh = function () {
             if (this._connectedMesh && this._registerFunc) {
                 this._connectedMesh.unregisterAfterWorldMatrixUpdate(this._registerFunc);
@@ -68276,6 +68409,10 @@ var BABYLON;
                 this._updateDirection();
             }
         };
+        /**
+         * Clone the current sound in the scene.
+         * @returns the new sound clone
+         */
         Sound.prototype.clone = function () {
             var _this = this;
             if (!this._streaming) {
@@ -68311,9 +68448,17 @@ var BABYLON;
                 return null;
             }
         };
+        /**
+         * Gets the current underlying audio buffer containing the data
+         * @returns the audio buffer
+         */
         Sound.prototype.getAudioBuffer = function () {
             return this._audioBuffer;
         };
+        /**
+         * Serializes the Sound in a JSON representation
+         * @returns the JSON representation of the sound
+         */
         Sound.prototype.serialize = function () {
             var serializationObject = {
                 name: this.name,
@@ -68344,6 +68489,14 @@ var BABYLON;
             }
             return serializationObject;
         };
+        /**
+         * Parse a JSON representation of a sound to innstantiate in a given scene
+         * @param parsedSound Define the JSON representation of the sound (usually coming from the serialize method)
+         * @param scene Define the scene the new parsed sound should be created in
+         * @param rootUrl Define the rooturl of the load in case we need to fetch relative dependencies
+         * @param sourceSound Define a cound place holder if do not need to instantiate a new one
+         * @returns the newly parsed sound
+         */
         Sound.Parse = function (parsedSound, scene, rootUrl, sourceSound) {
             var soundName = parsedSound.name;
             var soundUrl;
@@ -68410,8 +68563,23 @@ var BABYLON;
 
 var BABYLON;
 (function (BABYLON) {
+    /**
+     * It could be useful to isolate your music & sounds on several tracks to better manage volume on a grouped instance of sounds.
+     * It will be also used in a future release to apply effects on a specific track.
+     * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#using-sound-tracks
+     */
     var SoundTrack = /** @class */ (function () {
+        /**
+         * Creates a new sound track.
+         * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#using-sound-tracks
+         * @param scene Define the scene the sound track belongs to
+         * @param options
+         */
         function SoundTrack(scene, options) {
+            if (options === void 0) { options = {}; }
+            /**
+             * The unique identifier of the sound track in the scene.
+             */
             this.id = -1;
             this._isMainTrack = false;
             this._isInitialized = false;
@@ -68438,6 +68606,9 @@ var BABYLON;
                 this._isInitialized = true;
             }
         };
+        /**
+         * Release the sound track and its associated resources
+         */
         SoundTrack.prototype.dispose = function () {
             if (BABYLON.Engine.audioEngine && BABYLON.Engine.audioEngine.canUseWebAudio) {
                 if (this._connectedAnalyser) {
@@ -68452,6 +68623,11 @@ var BABYLON;
                 this._outputAudioNode = null;
             }
         };
+        /**
+         * Adds a sound to this sound track
+         * @param sound define the cound to add
+         * @ignoreNaming
+         */
         SoundTrack.prototype.AddSound = function (sound) {
             if (!this._isInitialized) {
                 this._initializeSoundTrackAudioGraph();
@@ -68470,17 +68646,31 @@ var BABYLON;
             this.soundCollection.push(sound);
             sound.soundTrackId = this.id;
         };
+        /**
+         * Removes a sound to this sound track
+         * @param sound define the cound to remove
+         * @ignoreNaming
+         */
         SoundTrack.prototype.RemoveSound = function (sound) {
             var index = this.soundCollection.indexOf(sound);
             if (index !== -1) {
                 this.soundCollection.splice(index, 1);
             }
         };
+        /**
+         * Set a global volume for the full sound track.
+         * @param newVolume Define the new volume of the sound track
+         */
         SoundTrack.prototype.setVolume = function (newVolume) {
             if (BABYLON.Engine.audioEngine.canUseWebAudio && this._outputAudioNode) {
                 this._outputAudioNode.gain.value = newVolume;
             }
         };
+        /**
+         * Switch the panning model to HRTF:
+         * Renders a stereo output of higher quality than equalpower — it uses a convolution with measured impulse responses from human subjects.
+         * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#creating-a-spatial-3d-sound
+         */
         SoundTrack.prototype.switchPanningModelToHRTF = function () {
             if (BABYLON.Engine.audioEngine.canUseWebAudio) {
                 for (var i = 0; i < this.soundCollection.length; i++) {
@@ -68488,6 +68678,11 @@ var BABYLON;
                 }
             }
         };
+        /**
+         * Switch the panning model to Equal Power:
+         * Represents the equal-power panning algorithm, generally regarded as simple and efficient. equalpower is the default value.
+         * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#creating-a-spatial-3d-sound
+         */
         SoundTrack.prototype.switchPanningModelToEqualPower = function () {
             if (BABYLON.Engine.audioEngine.canUseWebAudio) {
                 for (var i = 0; i < this.soundCollection.length; i++) {
@@ -68495,6 +68690,12 @@ var BABYLON;
                 }
             }
         };
+        /**
+         * Connect the sound track to an audio analyser allowing some amazing
+         * synchornization between the sounds/music and your visualization (VuMeter for instance).
+         * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#using-the-analyser
+         * @param analyser The analyser to connect to the engine
+         */
         SoundTrack.prototype.connectToAnalyser = function (analyser) {
             if (this._connectedAnalyser) {
                 this._connectedAnalyser.stopDebugCanvas();
@@ -95747,6 +95948,9 @@ var BABYLON;
                 }
             });
         };
+        /**
+         * Force relase the drag action by code.
+         */
         PointerDragBehavior.prototype.releaseDrag = function () {
             this.dragging = false;
             this.onDragEndObservable.notifyObservers({ dragPlanePoint: this.lastDragPosition, pointerId: this.currentDraggingPointerID });
@@ -95933,6 +96137,9 @@ var BABYLON;
      * A behavior that when attached to a mesh will allow the mesh to be scaled
      */
     var MultiPointerScaleBehavior = /** @class */ (function () {
+        /**
+         * Instantiate a new behavior that when attached to a mesh will allow the mesh to be scaled
+         */
         function MultiPointerScaleBehavior() {
             this._startDistance = 0;
             this._initialScale = new BABYLON.Vector3(0, 0, 0);
@@ -96036,6 +96243,9 @@ var BABYLON;
      * A behavior that when attached to a mesh will allow the mesh to be dragged around based on directions and origin of the pointer's ray
      */
     var SixDofDragBehavior = /** @class */ (function () {
+        /**
+         * Instantiates a behavior that when attached to a mesh will allow the mesh to be dragged around based on directions and origin of the pointer's ray
+         */
         function SixDofDragBehavior() {
             this._sceneRenderObserver = null;
             this._targetPosition = new BABYLON.Vector3(0, 0, 0);
@@ -104550,7 +104760,13 @@ var BABYLON;
             if (checkVerticesInsteadOfIndices === void 0) { checkVerticesInsteadOfIndices = false; }
             if (generateEdgesLines === void 0) { generateEdgesLines = true; }
             var _this = this;
+            /**
+             * Define the size of the edges with an orthographic camera
+             */
             this.edgesWidthScalerForOrthographic = 1000.0;
+            /**
+             * Define the size of the edges with a perspective camera
+             */
             this.edgesWidthScalerForPerspective = 50.0;
             this._linesPositions = new Array();
             this._linesNormals = new Array();
@@ -108543,10 +108759,9 @@ var BABYLON;
             this.zoomOnBoundingInfo(min, max, focusOnOriginXZ, onAnimationEnd);
         };
         /**
-         * Targets the given mesh and updates zoom level accordingly.
-         * @param mesh  The mesh to target.
-         * @param radius Optional. If a cached radius position already exists, overrides default.
-         * @param framingPositionY Position on mesh to center camera focus where 0 corresponds bottom of its bounding box and 1, the top
+         * Targets the bounding box info defined by its extends and updates zoom level accordingly.
+         * @param minimumWorld Determines the smaller position of the bounding box extend
+         * @param maximumWorld Determines the bigger position of the bounding box extend
          * @param focusOnOriginXZ Determines if the camera should focus on 0 in the X and Z axis instead of the mesh
          * @param onAnimationEnd Callback triggered at the end of the framing animation
          */

dist/preview release/babylon.no-module.max.js

@@ -9175,6 +9175,11 @@ var BABYLON;
                 document.msCancelFullScreen();
             }
         };
+        /**
+         * Sets the cors behavior on a dom element. This will add the required Tools.CorsBehavior to the element.
+         * @param url define the url we are trying
+         * @param element define the dom element where to configure the cors policy
+         */
         Tools.SetCorsBehavior = function (url, element) {
             if (url && url.indexOf("data:") === 0) {
                 return;
@@ -10502,14 +10507,14 @@ var BABYLON;
         /**
          * Create and run an async loop.
          * @param iterations the number of iterations.
-         * @param _fn the function to run each iteration
-         * @param _successCallback the callback that will be called upon succesful execution
+         * @param fn the function to run each iteration
+         * @param successCallback the callback that will be called upon succesful execution
          * @param offset starting offset.
          * @returns the created async loop object
          */
-        AsyncLoop.Run = function (iterations, _fn, _successCallback, offset) {
+        AsyncLoop.Run = function (iterations, fn, successCallback, offset) {
             if (offset === void 0) { offset = 0; }
-            var loop = new AsyncLoop(iterations, _fn, _successCallback, offset);
+            var loop = new AsyncLoop(iterations, fn, successCallback, offset);
             loop.executeNext();
             return loop;
         };
@@ -55550,6 +55555,9 @@ var BABYLON;
 
 var BABYLON;
 (function (BABYLON) {
+    /**
+     * @hidden
+     */
     var IntersectionInfo = /** @class */ (function () {
         function IntersectionInfo(bu, bv, distance) {
             this.bu = bu;
@@ -55563,7 +55571,7 @@ var BABYLON;
     BABYLON.IntersectionInfo = IntersectionInfo;
     /**
      * Information about the result of picking within a scene
-     * See https://doc.babylonjs.com/babylon101/picking_collisions
+     * @see https://doc.babylonjs.com/babylon101/picking_collisions
      */
     var PickingInfo = /** @class */ (function () {
         function PickingInfo() {
@@ -62948,15 +62956,36 @@ var BABYLON;
         enumerable: true,
         configurable: true
     });
+    /**
+     * Component responsible of rendering the bounding box of the meshes in a scene.
+     * This is usually used through the mesh.showBoundingBox or the scene.forceShowBoundingBoxes properties
+     *
+     */
     var BoundingBoxRenderer = /** @class */ (function () {
+        /**
+         * Instantiates a new bounding box renderer in a scene.
+         * @param scene the scene the  renderer renders in
+         */
         function BoundingBoxRenderer(scene) {
             /**
              * The component name helpfull to identify the component in the list of scene components.
              */
             this.name = BABYLON.SceneComponentConstants.NAME_BOUNDINGBOXRENDERER;
+            /**
+             * Color of the bounding box lines placed in front of an object
+             */
             this.frontColor = new BABYLON.Color3(1, 1, 1);
+            /**
+             * Color of the bounding box lines placed behind an object
+             */
             this.backColor = new BABYLON.Color3(0.1, 0.1, 0.1);
+            /**
+             * Defines if the renderer should show the back lines or not
+             */
             this.showBackLines = true;
+            /**
+             * @hidden
+             */
             this.renderList = new BABYLON.SmartArray(32);
             this._vertexBuffers = {};
             this.scene = scene;
@@ -63015,6 +63044,9 @@ var BABYLON;
             }
             this._createIndexBuffer();
         };
+        /**
+         * @hidden
+         */
         BoundingBoxRenderer.prototype.reset = function () {
             this.renderList.reset();
         };
@@ -63068,6 +63100,10 @@ var BABYLON;
             engine.setDepthFunctionToLessOrEqual();
             engine.setDepthWrite(true);
         };
+        /**
+         * In case of occlusion queries, we can render the occlusion bounding box through this method
+         * @param mesh Define the mesh to render the occlusion bounding box for
+         */
         BoundingBoxRenderer.prototype.renderOcclusionBoundingBox = function (mesh) {
             this._prepareRessources();
             if (!this._colorShader.isReady() || !mesh._boundingInfo) {
@@ -63095,6 +63131,9 @@ var BABYLON;
             engine.setDepthWrite(true);
             engine.setColorWrite(true);
         };
+        /**
+         * Dispose and release the resources attached to this renderer.
+         */
         BoundingBoxRenderer.prototype.dispose = function () {
             if (!this._colorShader) {
                 return;
@@ -67303,7 +67342,6 @@ var BABYLON;
             var _this = this;
             this._audioContext = null;
             this._audioContextInitialized = false;
-            this._muteButtonDisplayed = false;
             this._muteButton = null;
             /**
              * Gets whether the current host supports Web Audio and thus could create AudioContexts.
@@ -67327,7 +67365,7 @@ var BABYLON;
              * Some Browsers have strong restrictions about Audio and won t autoplay unless
              * a user interaction has happened.
              */
-            this.unlocked = false;
+            this.unlocked = true;
             /**
              * Defines if the audio engine relies on a custom unlocked button.
              * In this case, the embedded button will not be displayed.
@@ -67376,7 +67414,7 @@ var BABYLON;
                     this._initializeAudioContext();
                 }
                 else {
-                    if (!this.unlocked && !this._muteButtonDisplayed) {
+                    if (!this.unlocked && !this._muteButton) {
                         this._displayMuteButton();
                     }
                 }
@@ -67400,9 +67438,11 @@ var BABYLON;
             this._triggerRunningState();
         };
         AudioEngine.prototype._resumeAudioContext = function () {
+            var result;
             if (this._audioContext.resume) {
-                this._audioContext.resume();
+                result = this._audioContext.resume();
             }
+            return result || Promise.resolve();
         };
         AudioEngine.prototype._initializeAudioContext = function () {
             var _this = this;
@@ -67415,21 +67455,19 @@ var BABYLON;
                     this.masterGain.connect(this._audioContext.destination);
                     this._audioContextInitialized = true;
                     if (this._audioContext.state === "running") {
+                        // Do not wait for the promise to unlock.
                         this._triggerRunningState();
                     }
                     else {
-                        if (!this._muteButtonDisplayed) {
-                            this._displayMuteButton();
-                        }
-                        // 3 possible states: https://webaudio.github.io/web-audio-api/#BaseAudioContext
-                        this._audioContext.addEventListener("statechange", function () {
-                            if (_this._audioContext.state === "running") {
+                        if (this._audioContext && this._audioContext.resume) {
+                            this._resumeAudioContext().then(function () {
                                 _this._triggerRunningState();
-                            }
-                            else {
-                                _this._triggerSuspendedState();
-                            }
-                        });
+                            }).catch(function () {
+                                // Can not resume automatically
+                                // Needs user action
+                                _this.lock();
+                            });
+                        }
                     }
                 }
             }
@@ -67439,13 +67477,18 @@ var BABYLON;
             }
         };
         AudioEngine.prototype._triggerRunningState = function () {
-            this._resumeAudioContext();
-            this.unlocked = true;
-            if (this._muteButtonDisplayed) {
-                this._hideMuteButton();
-            }
-            // Notify users that the audio stack is unlocked/unmuted
-            this.onAudioUnlockedObservable.notifyObservers(this);
+            var _this = this;
+            this._resumeAudioContext()
+                .then(function () {
+                _this.unlocked = true;
+                if (_this._muteButton) {
+                    _this._hideMuteButton();
+                }
+                // Notify users that the audio stack is unlocked/unmuted
+                _this.onAudioUnlockedObservable.notifyObservers(_this);
+            }).catch(function () {
+                _this.unlocked = false;
+            });
         };
         AudioEngine.prototype._triggerSuspendedState = function () {
             this.unlocked = false;
@@ -67474,7 +67517,6 @@ var BABYLON;
             this._muteButton.addEventListener('touchend', function () {
                 _this._triggerRunningState();
             }, false);
-            this._muteButtonDisplayed = true;
             window.addEventListener("resize", this._onResize);
         };
         AudioEngine.prototype._moveButtonToTopLeft = function () {
@@ -67484,9 +67526,9 @@ var BABYLON;
             }
         };
         AudioEngine.prototype._hideMuteButton = function () {
-            if (this._muteButtonDisplayed && this._muteButton) {
+            if (this._muteButton) {
                 document.body.removeChild(this._muteButton);
-                this._muteButtonDisplayed = false;
+                this._muteButton = null;
             }
         };
         /**
@@ -67586,18 +67628,43 @@ var BABYLON;
              */
             this.useCustomAttenuation = false;
             /**
+             * Is this sound currently played.
+             */
+            this.isPlaying = false;
+            /**
+             * Is this sound currently paused.
+             */
+            this.isPaused = false;
+            /**
              * Does this sound enables spatial sound.
+             * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#creating-a-spatial-3d-sound
              */
             this.spatialSound = false;
+            /**
+             * Define the reference distance the sound should be heard perfectly.
+             * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#creating-a-spatial-3d-sound
+             */
             this.refDistance = 1;
+            /**
+             * Define the roll off factor of spatial sounds.
+             * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#creating-a-spatial-3d-sound
+             */
             this.rolloffFactor = 1;
+            /**
+             * Define the max distance the sound should be heard (intensity just became 0 at this point).
+             * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#creating-a-spatial-3d-sound
+             */
             this.maxDistance = 100;
+            /**
+             * Define the distance attenuation model the sound will follow.
+             * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#creating-a-spatial-3d-sound
+             */
             this.distanceModel = "linear";
-            this._panningModel = "equalpower";
             /**
              * Observable event when the current playing sound finishes.
              */
             this.onEndedObservable = new BABYLON.Observable();
+            this._panningModel = "equalpower";
             this._playbackRate = 1;
             this._streaming = false;
             this._startTime = 0;
@@ -67608,8 +67675,6 @@ var BABYLON;
             this._localDirection = new BABYLON.Vector3(1, 0, 0);
             this._volume = 1;
             this._isReadyToPlay = false;
-            this.isPlaying = false;
-            this.isPaused = false;
             this._isDirectional = false;
             // Used if you'd like to create a directional sound.
             // If not set, the sound will be omnidirectional
@@ -67796,6 +67861,9 @@ var BABYLON;
                 }
             }
         }
+        /**
+         * Release the sound and its associated resources
+         */
         Sound.prototype.dispose = function () {
             if (BABYLON.Engine.audioEngine.canUseWebAudio) {
                 if (this.isPlaying) {
@@ -67835,6 +67903,10 @@ var BABYLON;
                 }
             }
         };
+        /**
+         * Gets if the sounds is ready to be played or not.
+         * @returns true if ready, otherwise false
+         */
         Sound.prototype.isReady = function () {
             return this._isReadyToPlay;
         };
@@ -67854,12 +67926,20 @@ var BABYLON;
                 }
             }, function (err) { BABYLON.Tools.Error("Error while decoding audio data for: " + _this.name + " / Error: " + err); });
         };
+        /**
+         * Sets the data of the sound from an audiobuffer
+         * @param audioBuffer The audioBuffer containing the data
+         */
         Sound.prototype.setAudioBuffer = function (audioBuffer) {
             if (BABYLON.Engine.audioEngine.canUseWebAudio) {
                 this._audioBuffer = audioBuffer;
                 this._isReadyToPlay = true;
             }
         };
+        /**
+         * Updates the current sounds options such as maxdistance, loop...
+         * @param options A JSON object containing values named as the object properties
+         */
         Sound.prototype.updateOptions = function (options) {
             if (options) {
                 this.loop = options.loop || this.loop;
@@ -67912,10 +67992,20 @@ var BABYLON;
                 }
             }
         };
+        /**
+         * Switch the panning model to HRTF:
+         * Renders a stereo output of higher quality than equalpower — it uses a convolution with measured impulse responses from human subjects.
+         * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#creating-a-spatial-3d-sound
+         */
         Sound.prototype.switchPanningModelToHRTF = function () {
             this._panningModel = "HRTF";
             this._switchPanningModel();
         };
+        /**
+         * Switch the panning model to Equal Power:
+         * Represents the equal-power panning algorithm, generally regarded as simple and efficient. equalpower is the default value.
+         * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#creating-a-spatial-3d-sound
+         */
         Sound.prototype.switchPanningModelToEqualPower = function () {
             this._panningModel = "equalpower";
             this._switchPanningModel();
@@ -67925,6 +68015,10 @@ var BABYLON;
                 this._soundPanner.panningModel = this._panningModel;
             }
         };
+        /**
+         * Connect this sound to a sound track audio node like gain...
+         * @param soundTrackAudioNode the sound track audio node to connect to
+         */
         Sound.prototype.connectToSoundTrackAudioNode = function (soundTrackAudioNode) {
             if (BABYLON.Engine.audioEngine.canUseWebAudio) {
                 if (this._isOutputConnected) {
@@ -68004,12 +68098,20 @@ var BABYLON;
             enumerable: true,
             configurable: true
         });
+        /**
+         * Sets the position of the emitter if spatial sound is enabled
+         * @param newPosition Defines the new posisiton
+         */
         Sound.prototype.setPosition = function (newPosition) {
             this._position = newPosition;
             if (BABYLON.Engine.audioEngine.canUseWebAudio && this.spatialSound && this._soundPanner && !isNaN(this._position.x) && !isNaN(this._position.y) && !isNaN(this._position.z)) {
                 this._soundPanner.setPosition(this._position.x, this._position.y, this._position.z);
             }
         };
+        /**
+         * Sets the local direction of the emitter if spatial sound is enabled
+         * @param newLocalDirection Defines the new local direction
+         */
         Sound.prototype.setLocalDirectionToMesh = function (newLocalDirection) {
             this._localDirection = newLocalDirection;
             if (BABYLON.Engine.audioEngine.canUseWebAudio && this._connectedMesh && this.isPlaying) {
@@ -68025,12 +68127,18 @@ var BABYLON;
             direction.normalize();
             this._soundPanner.setOrientation(direction.x, direction.y, direction.z);
         };
+        /** @hidden */
         Sound.prototype.updateDistanceFromListener = function () {
             if (BABYLON.Engine.audioEngine.canUseWebAudio && this._connectedMesh && this.useCustomAttenuation && this._soundGain && this._scene.activeCamera) {
                 var distance = this._connectedMesh.getDistanceToCamera(this._scene.activeCamera);
                 this._soundGain.gain.value = this._customAttenuationFunction(this._volume, distance, this.maxDistance, this.refDistance, this.rolloffFactor);
             }
         };
+        /**
+         * Sets a new custom attenuation function for the sound.
+         * @param callback Defines the function used for the attenuation
+         * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#creating-your-own-custom-attenuation-function
+         */
         Sound.prototype.setAttenuationFunction = function (callback) {
             this._customAttenuationFunction = callback;
         };
@@ -68156,6 +68264,9 @@ var BABYLON;
                 this.isPlaying = false;
             }
         };
+        /**
+         * Put the sound in pause
+         */
         Sound.prototype.pause = function () {
             if (this.isPlaying) {
                 this.isPaused = true;
@@ -68173,6 +68284,11 @@ var BABYLON;
                 }
             }
         };
+        /**
+         * Sets a dedicated volume for this sounds
+         * @param newVolume Define the new volume of the sound
+         * @param time Define in how long the sound should be at this value
+         */
         Sound.prototype.setVolume = function (newVolume, time) {
             if (BABYLON.Engine.audioEngine.canUseWebAudio && this._soundGain) {
                 if (time && BABYLON.Engine.audioEngine.audioContext) {
@@ -68186,6 +68302,10 @@ var BABYLON;
             }
             this._volume = newVolume;
         };
+        /**
+         * Set the sound play back rate
+         * @param newPlaybackRate Define the playback rate the sound should be played at
+         */
         Sound.prototype.setPlaybackRate = function (newPlaybackRate) {
             this._playbackRate = newPlaybackRate;
             if (this.isPlaying) {
@@ -68197,9 +68317,18 @@ var BABYLON;
                 }
             }
         };
+        /**
+         * Gets the volume of the sound.
+         * @returns the volume of the sound
+         */
         Sound.prototype.getVolume = function () {
             return this._volume;
         };
+        /**
+         * Attach the sound to a dedicated mesh
+         * @param meshToConnectTo The mesh to connect the sound with
+         * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#attaching-a-sound-to-a-mesh
+         */
         Sound.prototype.attachToMesh = function (meshToConnectTo) {
             var _this = this;
             if (this._connectedMesh && this._registerFunc) {
@@ -68219,6 +68348,10 @@ var BABYLON;
             this._registerFunc = function (connectedMesh) { return _this._onRegisterAfterWorldMatrixUpdate(connectedMesh); };
             meshToConnectTo.registerAfterWorldMatrixUpdate(this._registerFunc);
         };
+        /**
+         * Detach the sound from the previously attached mesh
+         * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#attaching-a-sound-to-a-mesh
+         */
         Sound.prototype.detachFromMesh = function () {
             if (this._connectedMesh && this._registerFunc) {
                 this._connectedMesh.unregisterAfterWorldMatrixUpdate(this._registerFunc);
@@ -68243,6 +68376,10 @@ var BABYLON;
                 this._updateDirection();
             }
         };
+        /**
+         * Clone the current sound in the scene.
+         * @returns the new sound clone
+         */
         Sound.prototype.clone = function () {
             var _this = this;
             if (!this._streaming) {
@@ -68278,9 +68415,17 @@ var BABYLON;
                 return null;
             }
         };
+        /**
+         * Gets the current underlying audio buffer containing the data
+         * @returns the audio buffer
+         */
         Sound.prototype.getAudioBuffer = function () {
             return this._audioBuffer;
         };
+        /**
+         * Serializes the Sound in a JSON representation
+         * @returns the JSON representation of the sound
+         */
         Sound.prototype.serialize = function () {
             var serializationObject = {
                 name: this.name,
@@ -68311,6 +68456,14 @@ var BABYLON;
             }
             return serializationObject;
         };
+        /**
+         * Parse a JSON representation of a sound to innstantiate in a given scene
+         * @param parsedSound Define the JSON representation of the sound (usually coming from the serialize method)
+         * @param scene Define the scene the new parsed sound should be created in
+         * @param rootUrl Define the rooturl of the load in case we need to fetch relative dependencies
+         * @param sourceSound Define a cound place holder if do not need to instantiate a new one
+         * @returns the newly parsed sound
+         */
         Sound.Parse = function (parsedSound, scene, rootUrl, sourceSound) {
             var soundName = parsedSound.name;
             var soundUrl;
@@ -68377,8 +68530,23 @@ var BABYLON;
 
 var BABYLON;
 (function (BABYLON) {
+    /**
+     * It could be useful to isolate your music & sounds on several tracks to better manage volume on a grouped instance of sounds.
+     * It will be also used in a future release to apply effects on a specific track.
+     * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#using-sound-tracks
+     */
     var SoundTrack = /** @class */ (function () {
+        /**
+         * Creates a new sound track.
+         * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#using-sound-tracks
+         * @param scene Define the scene the sound track belongs to
+         * @param options
+         */
         function SoundTrack(scene, options) {
+            if (options === void 0) { options = {}; }
+            /**
+             * The unique identifier of the sound track in the scene.
+             */
             this.id = -1;
             this._isMainTrack = false;
             this._isInitialized = false;
@@ -68405,6 +68573,9 @@ var BABYLON;
                 this._isInitialized = true;
             }
         };
+        /**
+         * Release the sound track and its associated resources
+         */
         SoundTrack.prototype.dispose = function () {
             if (BABYLON.Engine.audioEngine && BABYLON.Engine.audioEngine.canUseWebAudio) {
                 if (this._connectedAnalyser) {
@@ -68419,6 +68590,11 @@ var BABYLON;
                 this._outputAudioNode = null;
             }
         };
+        /**
+         * Adds a sound to this sound track
+         * @param sound define the cound to add
+         * @ignoreNaming
+         */
         SoundTrack.prototype.AddSound = function (sound) {
             if (!this._isInitialized) {
                 this._initializeSoundTrackAudioGraph();
@@ -68437,17 +68613,31 @@ var BABYLON;
             this.soundCollection.push(sound);
             sound.soundTrackId = this.id;
         };
+        /**
+         * Removes a sound to this sound track
+         * @param sound define the cound to remove
+         * @ignoreNaming
+         */
         SoundTrack.prototype.RemoveSound = function (sound) {
             var index = this.soundCollection.indexOf(sound);
             if (index !== -1) {
                 this.soundCollection.splice(index, 1);
             }
         };
+        /**
+         * Set a global volume for the full sound track.
+         * @param newVolume Define the new volume of the sound track
+         */
         SoundTrack.prototype.setVolume = function (newVolume) {
             if (BABYLON.Engine.audioEngine.canUseWebAudio && this._outputAudioNode) {
                 this._outputAudioNode.gain.value = newVolume;
             }
         };
+        /**
+         * Switch the panning model to HRTF:
+         * Renders a stereo output of higher quality than equalpower — it uses a convolution with measured impulse responses from human subjects.
+         * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#creating-a-spatial-3d-sound
+         */
         SoundTrack.prototype.switchPanningModelToHRTF = function () {
             if (BABYLON.Engine.audioEngine.canUseWebAudio) {
                 for (var i = 0; i < this.soundCollection.length; i++) {
@@ -68455,6 +68645,11 @@ var BABYLON;
                 }
             }
         };
+        /**
+         * Switch the panning model to Equal Power:
+         * Represents the equal-power panning algorithm, generally regarded as simple and efficient. equalpower is the default value.
+         * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#creating-a-spatial-3d-sound
+         */
         SoundTrack.prototype.switchPanningModelToEqualPower = function () {
             if (BABYLON.Engine.audioEngine.canUseWebAudio) {
                 for (var i = 0; i < this.soundCollection.length; i++) {
@@ -68462,6 +68657,12 @@ var BABYLON;
                 }
             }
         };
+        /**
+         * Connect the sound track to an audio analyser allowing some amazing
+         * synchornization between the sounds/music and your visualization (VuMeter for instance).
+         * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#using-the-analyser
+         * @param analyser The analyser to connect to the engine
+         */
         SoundTrack.prototype.connectToAnalyser = function (analyser) {
             if (this._connectedAnalyser) {
                 this._connectedAnalyser.stopDebugCanvas();
@@ -95714,6 +95915,9 @@ var BABYLON;
                 }
             });
         };
+        /**
+         * Force relase the drag action by code.
+         */
         PointerDragBehavior.prototype.releaseDrag = function () {
             this.dragging = false;
             this.onDragEndObservable.notifyObservers({ dragPlanePoint: this.lastDragPosition, pointerId: this.currentDraggingPointerID });
@@ -95900,6 +96104,9 @@ var BABYLON;
      * A behavior that when attached to a mesh will allow the mesh to be scaled
      */
     var MultiPointerScaleBehavior = /** @class */ (function () {
+        /**
+         * Instantiate a new behavior that when attached to a mesh will allow the mesh to be scaled
+         */
         function MultiPointerScaleBehavior() {
             this._startDistance = 0;
             this._initialScale = new BABYLON.Vector3(0, 0, 0);
@@ -96003,6 +96210,9 @@ var BABYLON;
      * A behavior that when attached to a mesh will allow the mesh to be dragged around based on directions and origin of the pointer's ray
      */
     var SixDofDragBehavior = /** @class */ (function () {
+        /**
+         * Instantiates a behavior that when attached to a mesh will allow the mesh to be dragged around based on directions and origin of the pointer's ray
+         */
         function SixDofDragBehavior() {
             this._sceneRenderObserver = null;
             this._targetPosition = new BABYLON.Vector3(0, 0, 0);
@@ -104517,7 +104727,13 @@ var BABYLON;
             if (checkVerticesInsteadOfIndices === void 0) { checkVerticesInsteadOfIndices = false; }
             if (generateEdgesLines === void 0) { generateEdgesLines = true; }
             var _this = this;
+            /**
+             * Define the size of the edges with an orthographic camera
+             */
             this.edgesWidthScalerForOrthographic = 1000.0;
+            /**
+             * Define the size of the edges with a perspective camera
+             */
             this.edgesWidthScalerForPerspective = 50.0;
             this._linesPositions = new Array();
             this._linesNormals = new Array();
@@ -108510,10 +108726,9 @@ var BABYLON;
             this.zoomOnBoundingInfo(min, max, focusOnOriginXZ, onAnimationEnd);
         };
         /**
-         * Targets the given mesh and updates zoom level accordingly.
-         * @param mesh  The mesh to target.
-         * @param radius Optional. If a cached radius position already exists, overrides default.
-         * @param framingPositionY Position on mesh to center camera focus where 0 corresponds bottom of its bounding box and 1, the top
+         * Targets the bounding box info defined by its extends and updates zoom level accordingly.
+         * @param minimumWorld Determines the smaller position of the bounding box extend
+         * @param maximumWorld Determines the bigger position of the bounding box extend
          * @param focusOnOriginXZ Determines if the camera should focus on 0 in the X and Z axis instead of the mesh
          * @param onAnimationEnd Callback triggered at the end of the framing animation
          */

dist/preview release/es6.js

@@ -9175,6 +9175,11 @@ var BABYLON;
                 document.msCancelFullScreen();
             }
         };
+        /**
+         * Sets the cors behavior on a dom element. This will add the required Tools.CorsBehavior to the element.
+         * @param url define the url we are trying
+         * @param element define the dom element where to configure the cors policy
+         */
         Tools.SetCorsBehavior = function (url, element) {
             if (url && url.indexOf("data:") === 0) {
                 return;
@@ -10502,14 +10507,14 @@ var BABYLON;
         /**
          * Create and run an async loop.
          * @param iterations the number of iterations.
-         * @param _fn the function to run each iteration
-         * @param _successCallback the callback that will be called upon succesful execution
+         * @param fn the function to run each iteration
+         * @param successCallback the callback that will be called upon succesful execution
          * @param offset starting offset.
          * @returns the created async loop object
          */
-        AsyncLoop.Run = function (iterations, _fn, _successCallback, offset) {
+        AsyncLoop.Run = function (iterations, fn, successCallback, offset) {
             if (offset === void 0) { offset = 0; }
-            var loop = new AsyncLoop(iterations, _fn, _successCallback, offset);
+            var loop = new AsyncLoop(iterations, fn, successCallback, offset);
             loop.executeNext();
             return loop;
         };
@@ -55550,6 +55555,9 @@ var BABYLON;
 
 var BABYLON;
 (function (BABYLON) {
+    /**
+     * @hidden
+     */
     var IntersectionInfo = /** @class */ (function () {
         function IntersectionInfo(bu, bv, distance) {
             this.bu = bu;
@@ -55563,7 +55571,7 @@ var BABYLON;
     BABYLON.IntersectionInfo = IntersectionInfo;
     /**
      * Information about the result of picking within a scene
-     * See https://doc.babylonjs.com/babylon101/picking_collisions
+     * @see https://doc.babylonjs.com/babylon101/picking_collisions
      */
     var PickingInfo = /** @class */ (function () {
         function PickingInfo() {
@@ -62948,15 +62956,36 @@ var BABYLON;
         enumerable: true,
         configurable: true
     });
+    /**
+     * Component responsible of rendering the bounding box of the meshes in a scene.
+     * This is usually used through the mesh.showBoundingBox or the scene.forceShowBoundingBoxes properties
+     *
+     */
     var BoundingBoxRenderer = /** @class */ (function () {
+        /**
+         * Instantiates a new bounding box renderer in a scene.
+         * @param scene the scene the  renderer renders in
+         */
         function BoundingBoxRenderer(scene) {
             /**
              * The component name helpfull to identify the component in the list of scene components.
              */
             this.name = BABYLON.SceneComponentConstants.NAME_BOUNDINGBOXRENDERER;
+            /**
+             * Color of the bounding box lines placed in front of an object
+             */
             this.frontColor = new BABYLON.Color3(1, 1, 1);
+            /**
+             * Color of the bounding box lines placed behind an object
+             */
             this.backColor = new BABYLON.Color3(0.1, 0.1, 0.1);
+            /**
+             * Defines if the renderer should show the back lines or not
+             */
             this.showBackLines = true;
+            /**
+             * @hidden
+             */
             this.renderList = new BABYLON.SmartArray(32);
             this._vertexBuffers = {};
             this.scene = scene;
@@ -63015,6 +63044,9 @@ var BABYLON;
             }
             this._createIndexBuffer();
         };
+        /**
+         * @hidden
+         */
         BoundingBoxRenderer.prototype.reset = function () {
             this.renderList.reset();
         };
@@ -63068,6 +63100,10 @@ var BABYLON;
             engine.setDepthFunctionToLessOrEqual();
             engine.setDepthWrite(true);
         };
+        /**
+         * In case of occlusion queries, we can render the occlusion bounding box through this method
+         * @param mesh Define the mesh to render the occlusion bounding box for
+         */
         BoundingBoxRenderer.prototype.renderOcclusionBoundingBox = function (mesh) {
             this._prepareRessources();
             if (!this._colorShader.isReady() || !mesh._boundingInfo) {
@@ -63095,6 +63131,9 @@ var BABYLON;
             engine.setDepthWrite(true);
             engine.setColorWrite(true);
         };
+        /**
+         * Dispose and release the resources attached to this renderer.
+         */
         BoundingBoxRenderer.prototype.dispose = function () {
             if (!this._colorShader) {
                 return;
@@ -67303,7 +67342,6 @@ var BABYLON;
             var _this = this;
             this._audioContext = null;
             this._audioContextInitialized = false;
-            this._muteButtonDisplayed = false;
             this._muteButton = null;
             /**
              * Gets whether the current host supports Web Audio and thus could create AudioContexts.
@@ -67327,7 +67365,7 @@ var BABYLON;
              * Some Browsers have strong restrictions about Audio and won t autoplay unless
              * a user interaction has happened.
              */
-            this.unlocked = false;
+            this.unlocked = true;
             /**
              * Defines if the audio engine relies on a custom unlocked button.
              * In this case, the embedded button will not be displayed.
@@ -67376,7 +67414,7 @@ var BABYLON;
                     this._initializeAudioContext();
                 }
                 else {
-                    if (!this.unlocked && !this._muteButtonDisplayed) {
+                    if (!this.unlocked && !this._muteButton) {
                         this._displayMuteButton();
                     }
                 }
@@ -67400,9 +67438,11 @@ var BABYLON;
             this._triggerRunningState();
         };
         AudioEngine.prototype._resumeAudioContext = function () {
+            var result;
             if (this._audioContext.resume) {
-                this._audioContext.resume();
+                result = this._audioContext.resume();
             }
+            return result || Promise.resolve();
         };
         AudioEngine.prototype._initializeAudioContext = function () {
             var _this = this;
@@ -67415,21 +67455,19 @@ var BABYLON;
                     this.masterGain.connect(this._audioContext.destination);
                     this._audioContextInitialized = true;
                     if (this._audioContext.state === "running") {
+                        // Do not wait for the promise to unlock.
                         this._triggerRunningState();
                     }
                     else {
-                        if (!this._muteButtonDisplayed) {
-                            this._displayMuteButton();
-                        }
-                        // 3 possible states: https://webaudio.github.io/web-audio-api/#BaseAudioContext
-                        this._audioContext.addEventListener("statechange", function () {
-                            if (_this._audioContext.state === "running") {
+                        if (this._audioContext && this._audioContext.resume) {
+                            this._resumeAudioContext().then(function () {
                                 _this._triggerRunningState();
-                            }
-                            else {
-                                _this._triggerSuspendedState();
-                            }
-                        });
+                            }).catch(function () {
+                                // Can not resume automatically
+                                // Needs user action
+                                _this.lock();
+                            });
+                        }
                     }
                 }
             }
@@ -67439,13 +67477,18 @@ var BABYLON;
             }
         };
         AudioEngine.prototype._triggerRunningState = function () {
-            this._resumeAudioContext();
-            this.unlocked = true;
-            if (this._muteButtonDisplayed) {
-                this._hideMuteButton();
-            }
-            // Notify users that the audio stack is unlocked/unmuted
-            this.onAudioUnlockedObservable.notifyObservers(this);
+            var _this = this;
+            this._resumeAudioContext()
+                .then(function () {
+                _this.unlocked = true;
+                if (_this._muteButton) {
+                    _this._hideMuteButton();
+                }
+                // Notify users that the audio stack is unlocked/unmuted
+                _this.onAudioUnlockedObservable.notifyObservers(_this);
+            }).catch(function () {
+                _this.unlocked = false;
+            });
         };
         AudioEngine.prototype._triggerSuspendedState = function () {
             this.unlocked = false;
@@ -67474,7 +67517,6 @@ var BABYLON;
             this._muteButton.addEventListener('touchend', function () {
                 _this._triggerRunningState();
             }, false);
-            this._muteButtonDisplayed = true;
             window.addEventListener("resize", this._onResize);
         };
         AudioEngine.prototype._moveButtonToTopLeft = function () {
@@ -67484,9 +67526,9 @@ var BABYLON;
             }
         };
         AudioEngine.prototype._hideMuteButton = function () {
-            if (this._muteButtonDisplayed && this._muteButton) {
+            if (this._muteButton) {
                 document.body.removeChild(this._muteButton);
-                this._muteButtonDisplayed = false;
+                this._muteButton = null;
             }
         };
         /**
@@ -67586,18 +67628,43 @@ var BABYLON;
              */
             this.useCustomAttenuation = false;
             /**
+             * Is this sound currently played.
+             */
+            this.isPlaying = false;
+            /**
+             * Is this sound currently paused.
+             */
+            this.isPaused = false;
+            /**
              * Does this sound enables spatial sound.
+             * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#creating-a-spatial-3d-sound
              */
             this.spatialSound = false;
+            /**
+             * Define the reference distance the sound should be heard perfectly.
+             * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#creating-a-spatial-3d-sound
+             */
             this.refDistance = 1;
+            /**
+             * Define the roll off factor of spatial sounds.
+             * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#creating-a-spatial-3d-sound
+             */
             this.rolloffFactor = 1;
+            /**
+             * Define the max distance the sound should be heard (intensity just became 0 at this point).
+             * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#creating-a-spatial-3d-sound
+             */
             this.maxDistance = 100;
+            /**
+             * Define the distance attenuation model the sound will follow.
+             * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#creating-a-spatial-3d-sound
+             */
             this.distanceModel = "linear";
-            this._panningModel = "equalpower";
             /**
              * Observable event when the current playing sound finishes.
              */
             this.onEndedObservable = new BABYLON.Observable();
+            this._panningModel = "equalpower";
             this._playbackRate = 1;
             this._streaming = false;
             this._startTime = 0;
@@ -67608,8 +67675,6 @@ var BABYLON;
             this._localDirection = new BABYLON.Vector3(1, 0, 0);
             this._volume = 1;
             this._isReadyToPlay = false;
-            this.isPlaying = false;
-            this.isPaused = false;
             this._isDirectional = false;
             // Used if you'd like to create a directional sound.
             // If not set, the sound will be omnidirectional
@@ -67796,6 +67861,9 @@ var BABYLON;
                 }
             }
         }
+        /**
+         * Release the sound and its associated resources
+         */
         Sound.prototype.dispose = function () {
             if (BABYLON.Engine.audioEngine.canUseWebAudio) {
                 if (this.isPlaying) {
@@ -67835,6 +67903,10 @@ var BABYLON;
                 }
             }
         };
+        /**
+         * Gets if the sounds is ready to be played or not.
+         * @returns true if ready, otherwise false
+         */
         Sound.prototype.isReady = function () {
             return this._isReadyToPlay;
         };
@@ -67854,12 +67926,20 @@ var BABYLON;
                 }
             }, function (err) { BABYLON.Tools.Error("Error while decoding audio data for: " + _this.name + " / Error: " + err); });
         };
+        /**
+         * Sets the data of the sound from an audiobuffer
+         * @param audioBuffer The audioBuffer containing the data
+         */
         Sound.prototype.setAudioBuffer = function (audioBuffer) {
             if (BABYLON.Engine.audioEngine.canUseWebAudio) {
                 this._audioBuffer = audioBuffer;
                 this._isReadyToPlay = true;
             }
         };
+        /**
+         * Updates the current sounds options such as maxdistance, loop...
+         * @param options A JSON object containing values named as the object properties
+         */
         Sound.prototype.updateOptions = function (options) {
             if (options) {
                 this.loop = options.loop || this.loop;
@@ -67912,10 +67992,20 @@ var BABYLON;
                 }
             }
         };
+        /**
+         * Switch the panning model to HRTF:
+         * Renders a stereo output of higher quality than equalpower — it uses a convolution with measured impulse responses from human subjects.
+         * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#creating-a-spatial-3d-sound
+         */
         Sound.prototype.switchPanningModelToHRTF = function () {
             this._panningModel = "HRTF";
             this._switchPanningModel();
         };
+        /**
+         * Switch the panning model to Equal Power:
+         * Represents the equal-power panning algorithm, generally regarded as simple and efficient. equalpower is the default value.
+         * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#creating-a-spatial-3d-sound
+         */
         Sound.prototype.switchPanningModelToEqualPower = function () {
             this._panningModel = "equalpower";
             this._switchPanningModel();
@@ -67925,6 +68015,10 @@ var BABYLON;
                 this._soundPanner.panningModel = this._panningModel;
             }
         };
+        /**
+         * Connect this sound to a sound track audio node like gain...
+         * @param soundTrackAudioNode the sound track audio node to connect to
+         */
         Sound.prototype.connectToSoundTrackAudioNode = function (soundTrackAudioNode) {
             if (BABYLON.Engine.audioEngine.canUseWebAudio) {
                 if (this._isOutputConnected) {
@@ -68004,12 +68098,20 @@ var BABYLON;
             enumerable: true,
             configurable: true
         });
+        /**
+         * Sets the position of the emitter if spatial sound is enabled
+         * @param newPosition Defines the new posisiton
+         */
         Sound.prototype.setPosition = function (newPosition) {
             this._position = newPosition;
             if (BABYLON.Engine.audioEngine.canUseWebAudio && this.spatialSound && this._soundPanner && !isNaN(this._position.x) && !isNaN(this._position.y) && !isNaN(this._position.z)) {
                 this._soundPanner.setPosition(this._position.x, this._position.y, this._position.z);
             }
         };
+        /**
+         * Sets the local direction of the emitter if spatial sound is enabled
+         * @param newLocalDirection Defines the new local direction
+         */
         Sound.prototype.setLocalDirectionToMesh = function (newLocalDirection) {
             this._localDirection = newLocalDirection;
             if (BABYLON.Engine.audioEngine.canUseWebAudio && this._connectedMesh && this.isPlaying) {
@@ -68025,12 +68127,18 @@ var BABYLON;
             direction.normalize();
             this._soundPanner.setOrientation(direction.x, direction.y, direction.z);
         };
+        /** @hidden */
         Sound.prototype.updateDistanceFromListener = function () {
             if (BABYLON.Engine.audioEngine.canUseWebAudio && this._connectedMesh && this.useCustomAttenuation && this._soundGain && this._scene.activeCamera) {
                 var distance = this._connectedMesh.getDistanceToCamera(this._scene.activeCamera);
                 this._soundGain.gain.value = this._customAttenuationFunction(this._volume, distance, this.maxDistance, this.refDistance, this.rolloffFactor);
             }
         };
+        /**
+         * Sets a new custom attenuation function for the sound.
+         * @param callback Defines the function used for the attenuation
+         * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#creating-your-own-custom-attenuation-function
+         */
         Sound.prototype.setAttenuationFunction = function (callback) {
             this._customAttenuationFunction = callback;
         };
@@ -68156,6 +68264,9 @@ var BABYLON;
                 this.isPlaying = false;
             }
         };
+        /**
+         * Put the sound in pause
+         */
         Sound.prototype.pause = function () {
             if (this.isPlaying) {
                 this.isPaused = true;
@@ -68173,6 +68284,11 @@ var BABYLON;
                 }
             }
         };
+        /**
+         * Sets a dedicated volume for this sounds
+         * @param newVolume Define the new volume of the sound
+         * @param time Define in how long the sound should be at this value
+         */
         Sound.prototype.setVolume = function (newVolume, time) {
             if (BABYLON.Engine.audioEngine.canUseWebAudio && this._soundGain) {
                 if (time && BABYLON.Engine.audioEngine.audioContext) {
@@ -68186,6 +68302,10 @@ var BABYLON;
             }
             this._volume = newVolume;
         };
+        /**
+         * Set the sound play back rate
+         * @param newPlaybackRate Define the playback rate the sound should be played at
+         */
         Sound.prototype.setPlaybackRate = function (newPlaybackRate) {
             this._playbackRate = newPlaybackRate;
             if (this.isPlaying) {
@@ -68197,9 +68317,18 @@ var BABYLON;
                 }
             }
         };
+        /**
+         * Gets the volume of the sound.
+         * @returns the volume of the sound
+         */
         Sound.prototype.getVolume = function () {
             return this._volume;
         };
+        /**
+         * Attach the sound to a dedicated mesh
+         * @param meshToConnectTo The mesh to connect the sound with
+         * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#attaching-a-sound-to-a-mesh
+         */
         Sound.prototype.attachToMesh = function (meshToConnectTo) {
             var _this = this;
             if (this._connectedMesh && this._registerFunc) {
@@ -68219,6 +68348,10 @@ var BABYLON;
             this._registerFunc = function (connectedMesh) { return _this._onRegisterAfterWorldMatrixUpdate(connectedMesh); };
             meshToConnectTo.registerAfterWorldMatrixUpdate(this._registerFunc);
         };
+        /**
+         * Detach the sound from the previously attached mesh
+         * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#attaching-a-sound-to-a-mesh
+         */
         Sound.prototype.detachFromMesh = function () {
             if (this._connectedMesh && this._registerFunc) {
                 this._connectedMesh.unregisterAfterWorldMatrixUpdate(this._registerFunc);
@@ -68243,6 +68376,10 @@ var BABYLON;
                 this._updateDirection();
             }
         };
+        /**
+         * Clone the current sound in the scene.
+         * @returns the new sound clone
+         */
         Sound.prototype.clone = function () {
             var _this = this;
             if (!this._streaming) {
@@ -68278,9 +68415,17 @@ var BABYLON;
                 return null;
             }
         };
+        /**
+         * Gets the current underlying audio buffer containing the data
+         * @returns the audio buffer
+         */
         Sound.prototype.getAudioBuffer = function () {
             return this._audioBuffer;
         };
+        /**
+         * Serializes the Sound in a JSON representation
+         * @returns the JSON representation of the sound
+         */
         Sound.prototype.serialize = function () {
             var serializationObject = {
                 name: this.name,
@@ -68311,6 +68456,14 @@ var BABYLON;
             }
             return serializationObject;
         };
+        /**
+         * Parse a JSON representation of a sound to innstantiate in a given scene
+         * @param parsedSound Define the JSON representation of the sound (usually coming from the serialize method)
+         * @param scene Define the scene the new parsed sound should be created in
+         * @param rootUrl Define the rooturl of the load in case we need to fetch relative dependencies
+         * @param sourceSound Define a cound place holder if do not need to instantiate a new one
+         * @returns the newly parsed sound
+         */
         Sound.Parse = function (parsedSound, scene, rootUrl, sourceSound) {
             var soundName = parsedSound.name;
             var soundUrl;
@@ -68377,8 +68530,23 @@ var BABYLON;
 
 var BABYLON;
 (function (BABYLON) {
+    /**
+     * It could be useful to isolate your music & sounds on several tracks to better manage volume on a grouped instance of sounds.
+     * It will be also used in a future release to apply effects on a specific track.
+     * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#using-sound-tracks
+     */
     var SoundTrack = /** @class */ (function () {
+        /**
+         * Creates a new sound track.
+         * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#using-sound-tracks
+         * @param scene Define the scene the sound track belongs to
+         * @param options
+         */
         function SoundTrack(scene, options) {
+            if (options === void 0) { options = {}; }
+            /**
+             * The unique identifier of the sound track in the scene.
+             */
             this.id = -1;
             this._isMainTrack = false;
             this._isInitialized = false;
@@ -68405,6 +68573,9 @@ var BABYLON;
                 this._isInitialized = true;
             }
         };
+        /**
+         * Release the sound track and its associated resources
+         */
         SoundTrack.prototype.dispose = function () {
             if (BABYLON.Engine.audioEngine && BABYLON.Engine.audioEngine.canUseWebAudio) {
                 if (this._connectedAnalyser) {
@@ -68419,6 +68590,11 @@ var BABYLON;
                 this._outputAudioNode = null;
             }
         };
+        /**
+         * Adds a sound to this sound track
+         * @param sound define the cound to add
+         * @ignoreNaming
+         */
         SoundTrack.prototype.AddSound = function (sound) {
             if (!this._isInitialized) {
                 this._initializeSoundTrackAudioGraph();
@@ -68437,17 +68613,31 @@ var BABYLON;
             this.soundCollection.push(sound);
             sound.soundTrackId = this.id;
         };
+        /**
+         * Removes a sound to this sound track
+         * @param sound define the cound to remove
+         * @ignoreNaming
+         */
         SoundTrack.prototype.RemoveSound = function (sound) {
             var index = this.soundCollection.indexOf(sound);
             if (index !== -1) {
                 this.soundCollection.splice(index, 1);
             }
         };
+        /**
+         * Set a global volume for the full sound track.
+         * @param newVolume Define the new volume of the sound track
+         */
         SoundTrack.prototype.setVolume = function (newVolume) {
             if (BABYLON.Engine.audioEngine.canUseWebAudio && this._outputAudioNode) {
                 this._outputAudioNode.gain.value = newVolume;
             }
         };
+        /**
+         * Switch the panning model to HRTF:
+         * Renders a stereo output of higher quality than equalpower — it uses a convolution with measured impulse responses from human subjects.
+         * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#creating-a-spatial-3d-sound
+         */
         SoundTrack.prototype.switchPanningModelToHRTF = function () {
             if (BABYLON.Engine.audioEngine.canUseWebAudio) {
                 for (var i = 0; i < this.soundCollection.length; i++) {
@@ -68455,6 +68645,11 @@ var BABYLON;
                 }
             }
         };
+        /**
+         * Switch the panning model to Equal Power:
+         * Represents the equal-power panning algorithm, generally regarded as simple and efficient. equalpower is the default value.
+         * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#creating-a-spatial-3d-sound
+         */
         SoundTrack.prototype.switchPanningModelToEqualPower = function () {
             if (BABYLON.Engine.audioEngine.canUseWebAudio) {
                 for (var i = 0; i < this.soundCollection.length; i++) {
@@ -68462,6 +68657,12 @@ var BABYLON;
                 }
             }
         };
+        /**
+         * Connect the sound track to an audio analyser allowing some amazing
+         * synchornization between the sounds/music and your visualization (VuMeter for instance).
+         * @see http://doc.babylonjs.com/how_to/playing_sounds_and_music#using-the-analyser
+         * @param analyser The analyser to connect to the engine
+         */
         SoundTrack.prototype.connectToAnalyser = function (analyser) {
             if (this._connectedAnalyser) {
                 this._connectedAnalyser.stopDebugCanvas();
@@ -95714,6 +95915,9 @@ var BABYLON;
                 }
             });
         };
+        /**
+         * Force relase the drag action by code.
+         */
         PointerDragBehavior.prototype.releaseDrag = function () {
             this.dragging = false;
             this.onDragEndObservable.notifyObservers({ dragPlanePoint: this.lastDragPosition, pointerId: this.currentDraggingPointerID });
@@ -95900,6 +96104,9 @@ var BABYLON;
      * A behavior that when attached to a mesh will allow the mesh to be scaled
      */
     var MultiPointerScaleBehavior = /** @class */ (function () {
+        /**
+         * Instantiate a new behavior that when attached to a mesh will allow the mesh to be scaled
+         */
         function MultiPointerScaleBehavior() {
             this._startDistance = 0;
             this._initialScale = new BABYLON.Vector3(0, 0, 0);
@@ -96003,6 +96210,9 @@ var BABYLON;
      * A behavior that when attached to a mesh will allow the mesh to be dragged around based on directions and origin of the pointer's ray
      */
     var SixDofDragBehavior = /** @class */ (function () {
+        /**
+         * Instantiates a behavior that when attached to a mesh will allow the mesh to be dragged around based on directions and origin of the pointer's ray
+         */
         function SixDofDragBehavior() {
             this._sceneRenderObserver = null;
             this._targetPosition = new BABYLON.Vector3(0, 0, 0);
@@ -104517,7 +104727,13 @@ var BABYLON;
             if (checkVerticesInsteadOfIndices === void 0) { checkVerticesInsteadOfIndices = false; }
             if (generateEdgesLines === void 0) { generateEdgesLines = true; }
             var _this = this;
+            /**
+             * Define the size of the edges with an orthographic camera
+             */
             this.edgesWidthScalerForOrthographic = 1000.0;
+            /**
+             * Define the size of the edges with a perspective camera
+             */
             this.edgesWidthScalerForPerspective = 50.0;
             this._linesPositions = new Array();
             this._linesNormals = new Array();
@@ -108510,10 +108726,9 @@ var BABYLON;
             this.zoomOnBoundingInfo(min, max, focusOnOriginXZ, onAnimationEnd);
         };
         /**
-         * Targets the given mesh and updates zoom level accordingly.
-         * @param mesh  The mesh to target.
-         * @param radius Optional. If a cached radius position already exists, overrides default.
-         * @param framingPositionY Position on mesh to center camera focus where 0 corresponds bottom of its bounding box and 1, the top
+         * Targets the bounding box info defined by its extends and updates zoom level accordingly.
+         * @param minimumWorld Determines the smaller position of the bounding box extend
+         * @param maximumWorld Determines the bigger position of the bounding box extend
          * @param focusOnOriginXZ Determines if the camera should focus on 0 in the X and Z axis instead of the mesh
          * @param onAnimationEnd Callback triggered at the end of the framing animation
          */

dist/preview release/typedocValidationBaseline.json

@@ -1,25 +1,7 @@
 {
-  "errors": 2483,
+  "errors": 2389,
   "babylon.typedoc.json": {
-    "errors": 2483,
-    "AsyncLoop": {
-      "Method": {
-        "Run": {
-          "Parameter": {
-            "_fn": {
-              "Naming": {
-                "NotCamelCase": true
-              }
-            },
-            "_successCallback": {
-              "Naming": {
-                "NotCamelCase": true
-              }
-            }
-          }
-        }
-      }
-    },
+    "errors": 2389,
     "BaseSubMesh": {
       "Class": {
         "Comments": {
@@ -331,73 +313,6 @@
         }
       }
     },
-    "BoundingBoxRenderer": {
-      "Class": {
-        "Comments": {
-          "MissingText": true
-        }
-      },
-      "Constructor": {
-        "new BoundingBoxRenderer": {
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "scene": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        }
-      },
-      "Property": {
-        "backColor": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "frontColor": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "renderList": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "showBackLines": {
-          "Comments": {
-            "MissingText": true
-          }
-        }
-      },
-      "Method": {
-        "dispose": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "renderOcclusionBoundingBox": {
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "mesh": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "reset": {
-          "Comments": {
-            "MissingText": true
-          }
-        }
-      }
-    },
     "BoundingInfo": {
       "Class": {
         "Comments": {
@@ -1360,20 +1275,6 @@
         }
       }
     },
-    "EdgesRenderer": {
-      "Property": {
-        "edgesWidthScalerForOrthographic": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "edgesWidthScalerForPerspective": {
-          "Comments": {
-            "MissingText": true
-          }
-        }
-      }
-    },
     "EngineInstrumentation": {
       "Constructor": {
         "new EngineInstrumentation": {
@@ -1527,24 +1428,6 @@
         }
       }
     },
-    "FramingBehavior": {
-      "Method": {
-        "zoomOnBoundingInfo": {
-          "Parameter": {
-            "minimumWorld": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "maximumWorld": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        }
-      }
-    },
     "FreeCameraInputsManager": {
       "Method": {
         "addGamepad": {
@@ -2260,64 +2143,6 @@
         }
       }
     },
-    "IntersectionInfo": {
-      "Class": {
-        "Comments": {
-          "MissingText": true
-        }
-      },
-      "Constructor": {
-        "new IntersectionInfo": {
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "bu": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "bv": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "distance": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        }
-      },
-      "Property": {
-        "bu": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "bv": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "distance": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "faceId": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "subMeshId": {
-          "Comments": {
-            "MissingText": true
-          }
-        }
-      }
-    },
     "KeyboardEventTypes": {
       "Class": {
         "Comments": {
@@ -3256,15 +3081,6 @@
         }
       }
     },
-    "MultiPointerScaleBehavior": {
-      "Constructor": {
-        "new MultiPointerScaleBehavior": {
-          "Comments": {
-            "MissingText": true
-          }
-        }
-      }
-    },
     "MultiRenderTarget": {
       "Class": {
         "Comments": {
@@ -4841,15 +4657,6 @@
         }
       }
     },
-    "PointerDragBehavior": {
-      "Method": {
-        "releaseDrag": {
-          "Comments": {
-            "MissingText": true
-          }
-        }
-      }
-    },
     "PointerEventTypes": {
       "Class": {
         "Comments": {
@@ -8284,15 +8091,6 @@
         }
       }
     },
-    "SixDofDragBehavior": {
-      "Constructor": {
-        "new SixDofDragBehavior": {
-          "Comments": {
-            "MissingText": true
-          }
-        }
-      }
-    },
     "Size": {
       "Class": {
         "Comments": {
@@ -8457,351 +8255,6 @@
         }
       }
     },
-    "Sound": {
-      "Property": {
-        "distanceModel": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "isPaused": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "isPlaying": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "maxDistance": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "onended": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "refDistance": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "rolloffFactor": {
-          "Comments": {
-            "MissingText": true
-          }
-        }
-      },
-      "Method": {
-        "attachToMesh": {
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "meshToConnectTo": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "clone": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "connectToSoundTrackAudioNode": {
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "soundTrackAudioNode": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "detachFromMesh": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "dispose": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "getAudioBuffer": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "getVolume": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "isReady": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "pause": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "serialize": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "setAttenuationFunction": {
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "callback": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "setAudioBuffer": {
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "audioBuffer": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "setLocalDirectionToMesh": {
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "newLocalDirection": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "setPlaybackRate": {
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "newPlaybackRate": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "setPosition": {
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "newPosition": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "setVolume": {
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "newVolume": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "time": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "switchPanningModelToEqualPower": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "switchPanningModelToHRTF": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "updateDistanceFromListener": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "updateOptions": {
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "options": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "Parse": {
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "parsedSound": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "scene": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "rootUrl": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "sourceSound": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        }
-      }
-    },
-    "SoundTrack": {
-      "Class": {
-        "Comments": {
-          "MissingText": true
-        }
-      },
-      "Constructor": {
-        "new SoundTrack": {
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "scene": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "options": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        }
-      },
-      "Property": {
-        "id": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "soundCollection": {
-          "Comments": {
-            "MissingText": true
-          }
-        }
-      },
-      "Method": {
-        "AddSound": {
-          "Naming": {
-            "NotCamelCase": true
-          },
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "sound": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "RemoveSound": {
-          "Naming": {
-            "NotCamelCase": true
-          },
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "sound": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "connectToAnalyser": {
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "analyser": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "dispose": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "setVolume": {
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "newVolume": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
-        "switchPanningModelToEqualPower": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "switchPanningModelToHRTF": {
-          "Comments": {
-            "MissingText": true
-          }
-        }
-      }
-    },
     "Sprite": {
       "Class": {
         "Comments": {
@@ -11474,23 +10927,6 @@
             }
           }
         },
-        "SetCorsBehavior": {
-          "Comments": {
-            "MissingText": true
-          },
-          "Parameter": {
-            "url": {
-              "Comments": {
-                "MissingText": true
-              }
-            },
-            "element": {
-              "Comments": {
-                "MissingText": true
-              }
-            }
-          }
-        },
         "SetImmediate": {
           "Comments": {
             "MissingText": true

dist/preview release/viewer/babylon.viewer.d.ts

@@ -168,11 +168,11 @@ declare module BabylonViewer {
                 * Mainly used for help and errors
                 * @param subScreen the name of the subScreen. Those can be defined in the configuration object
                 */
-            showOverlayScreen(subScreen: string): Promise<string> | Promise<Template>;
+            showOverlayScreen(subScreen: string): Promise<Template> | Promise<string>;
             /**
                 * Hide the overlay screen.
                 */
-            hideOverlayScreen(): Promise<string> | Promise<Template>;
+            hideOverlayScreen(): Promise<Template> | Promise<string>;
             /**
                 * show the viewer (in case it was hidden)
                 *
@@ -189,11 +189,11 @@ declare module BabylonViewer {
                 * Show the loading screen.
                 * The loading screen can be configured using the configuration object
                 */
-            showLoadingScreen(): Promise<string> | Promise<Template>;
+            showLoadingScreen(): Promise<Template> | Promise<string>;
             /**
                 * Hide the loading screen
                 */
-            hideLoadingScreen(): Promise<string> | Promise<Template>;
+            hideLoadingScreen(): Promise<Template> | Promise<string>;
             dispose(): void;
             protected _onConfigurationLoaded(configuration: ViewerConfiguration): void;
     }
@@ -924,7 +924,7 @@ declare module BabylonViewer {
       * @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): (sceneManager: SceneManager) => boolean;
+    export function getCustomOptimizerByName(name: string, upgrade?: boolean): typeof extendedUpgrade;
     export function registerCustomOptimizer(name: string, optimizer: (sceneManager: SceneManager) => boolean): void;
 }
 declare module BabylonViewer {
@@ -1558,6 +1558,20 @@ declare module BabylonViewer {
     export function addLoaderPlugin(name: string, plugin: ILoaderPlugin): void;
 }
 declare module BabylonViewer {
+    /**
+        * A custom upgrade-oriented function configuration for the scene optimizer.
+        *
+        * @param viewer the viewer to optimize
+        */
+    export function extendedUpgrade(sceneManager: SceneManager): boolean;
+    /**
+        * A custom degrade-oriented function configuration for the scene optimizer.
+        *
+        * @param viewer the viewer to optimize
+        */
+    export function extendedDegrade(sceneManager: SceneManager): boolean;
+}
+declare module BabylonViewer {
 }
 declare module BabylonViewer {
     export interface IEnvironmentMapConfiguration {

dist/preview release/viewer/babylon.viewer.module.d.ts

@@ -200,11 +200,11 @@ declare module 'babylonjs-viewer/viewer/defaultViewer' {
                 * Mainly used for help and errors
                 * @param subScreen the name of the subScreen. Those can be defined in the configuration object
                 */
-            showOverlayScreen(subScreen: string): Promise<string> | Promise<Template>;
+            showOverlayScreen(subScreen: string): Promise<Template> | Promise<string>;
             /**
                 * Hide the overlay screen.
                 */
-            hideOverlayScreen(): Promise<string> | Promise<Template>;
+            hideOverlayScreen(): Promise<Template> | Promise<string>;
             /**
                 * show the viewer (in case it was hidden)
                 *
@@ -221,11 +221,11 @@ declare module 'babylonjs-viewer/viewer/defaultViewer' {
                 * Show the loading screen.
                 * The loading screen can be configured using the configuration object
                 */
-            showLoadingScreen(): Promise<string> | Promise<Template>;
+            showLoadingScreen(): Promise<Template> | Promise<string>;
             /**
                 * Hide the loading screen
                 */
-            hideLoadingScreen(): Promise<string> | Promise<Template>;
+            hideLoadingScreen(): Promise<Template> | Promise<string>;
             dispose(): void;
             protected _onConfigurationLoaded(configuration: ViewerConfiguration): void;
     }
@@ -985,13 +985,14 @@ declare module 'babylonjs-viewer/templating/viewerTemplatePlugin' {
 }
 
 declare module 'babylonjs-viewer/optimizer/custom' {
+    import { extendedUpgrade } from "babylonjs-viewer/optimizer/custom/extended";
     import { SceneManager } from "babylonjs-viewer/managers/sceneManager";
     /**
       *
       * @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): (sceneManager: SceneManager) => boolean;
+    export function getCustomOptimizerByName(name: string, upgrade?: boolean): typeof extendedUpgrade;
     export function registerCustomOptimizer(name: string, optimizer: (sceneManager: SceneManager) => boolean): void;
 }
 
@@ -1662,6 +1663,22 @@ declare module 'babylonjs-viewer/loader/plugins' {
     export function addLoaderPlugin(name: string, plugin: ILoaderPlugin): void;
 }
 
+declare module 'babylonjs-viewer/optimizer/custom/extended' {
+    import { SceneManager } from 'babylonjs-viewer/managers/sceneManager';
+    /**
+        * A custom upgrade-oriented function configuration for the scene optimizer.
+        *
+        * @param viewer the viewer to optimize
+        */
+    export function extendedUpgrade(sceneManager: SceneManager): boolean;
+    /**
+        * A custom degrade-oriented function configuration for the scene optimizer.
+        *
+        * @param viewer the viewer to optimize
+        */
+    export function extendedDegrade(sceneManager: SceneManager): boolean;
+}
+
 declare module 'babylonjs-viewer/configuration/interfaces' {
     export * from 'babylonjs-viewer/configuration/interfaces/cameraConfiguration';
     export * from 'babylonjs-viewer/configuration/interfaces/colorGradingConfiguration';

src/Rendering/babylon.boundingBoxRenderer.ts

@@ -70,7 +70,6 @@
     /**
      * Component responsible of rendering the bounding box of the meshes in a scene.
      * This is usually used through the mesh.showBoundingBox or the scene.forceShowBoundingBoxes properties
-     * 
      */
     export class BoundingBoxRenderer implements ISceneComponent {
         /**

src/Rendering/babylon.renderingGroup.ts

@@ -1,4 +1,10 @@
 module BABYLON {
+    /**
+     * This represents the object necessary to create a rendering group.
+     * This is exclusively used and created by the rendering manager.
+     * To modify the behavior, you use the available helpers in your scene or meshes.
+     * @hidden
+     */
     export class RenderingGroup {
         private _scene: Scene;
         private _opaqueSubMeshes = new SmartArray<SubMesh>(256);

src/Rendering/babylon.renderingManager.ts

@@ -19,6 +19,11 @@
         stencil: boolean;
     }
 
+    /**
+     * This is the manager responsible of all the rendering for meshes sprites and particles.
+     * It is enable to manage the different groups as well as the different necessary sort functions.
+     * This should not be used directly aside of the few static configurations
+     */
     export class RenderingManager {
         /**
          * The max id used for rendering groups (not included)
@@ -50,6 +55,10 @@
         private _customTransparentSortCompareFn: { [id: number]: Nullable<(a: SubMesh, b: SubMesh) => number> } = {};
         private _renderingGroupInfo: Nullable<RenderingGroupInfo> = new RenderingGroupInfo();
 
+        /**
+         * Instantiates a new rendering group for a particular scene
+         * @param scene Defines the scene the groups belongs to
+         */
         constructor(scene: Scene) {
             this._scene = scene;
 
@@ -67,6 +76,10 @@
             this._depthStencilBufferAlreadyCleaned = true;
         }
 
+        /**
+         * Renders the entire managed groups. This is used by the scene or the different rennder targets.
+         * @hidden
+         */
         public render(customRenderFunction: Nullable<(opaqueSubMeshes: SmartArray<SubMesh>, transparentSubMeshes: SmartArray<SubMesh>, alphaTestSubMeshes: SmartArray<SubMesh>, depthOnlySubMeshes: SmartArray<SubMesh>) => void>,
             activeMeshes: Nullable<AbstractMesh[]>, renderParticles: boolean, renderSprites: boolean): void {
 
@@ -121,6 +134,10 @@
             }
         }
 
+        /**
+         * Resets the different information of the group to prepare a new frame
+         * @hidden
+         */
         public reset(): void {
             for (let index = RenderingManager.MIN_RENDERINGGROUPS; index < RenderingManager.MAX_RENDERINGGROUPS; index++) {
                 var renderingGroup = this._renderingGroups[index];
@@ -130,6 +147,10 @@
             }
         }
 
+        /**
+         * Dispose and release the group and its associated resources.
+         * @hidden
+         */
         public dispose(): void {
             this.freeRenderingGroups();
             this._renderingGroups.length = 0;
@@ -158,6 +179,10 @@
             }
         }
 
+        /**
+         * Add a sprite manager to the rendering manager in order to render it this frame.
+         * @param spriteManager Define the sprite manager to render
+         */
         public dispatchSprites(spriteManager: ISpriteManager) {
             var renderingGroupId = spriteManager.renderingGroupId || 0;
 
@@ -166,6 +191,10 @@
             this._renderingGroups[renderingGroupId].dispatchSprites(spriteManager);
         }
 
+        /**
+         * Add a particle system to the rendering manager in order to render it this frame.
+         * @param particleSystem Define the particle system to render
+         */
         public dispatchParticles(particleSystem: IParticleSystem) {
             var renderingGroupId = particleSystem.renderingGroupId || 0;
 
@@ -175,9 +204,10 @@
         }
 
         /**
+         * Add a submesh to the manager in order to render it this frame
          * @param subMesh The submesh to dispatch
-         * @param [mesh] Optional reference to the submeshes's mesh. Provide if you have an exiting reference to improve performance.
-         * @param [material] Optional reference to the submeshes's material. Provide if you have an exiting reference to improve performance.
+         * @param mesh Optional reference to the submeshes's mesh. Provide if you have an exiting reference to improve performance.
+         * @param material Optional reference to the submeshes's material. Provide if you have an exiting reference to improve performance.
          */
         public dispatch(subMesh: SubMesh, mesh?: AbstractMesh, material?: Nullable<Material>): void {
             if (mesh === undefined) {