Merge SkyMaterial Latest changes

materialsLibrary/src/sky/skyMaterial.ts

@@ -3,6 +3,7 @@ import { MaterialDefines, PushMaterial, serialize, serializeAsVector3, Vector3,
 import "./sky.fragment";
 import "./sky.vertex";
 
+/** @hidden */
 class SkyMaterialDefines extends MaterialDefines {
     public CLIPPLANE = false;
     public CLIPPLANE2 = false;
@@ -19,60 +20,131 @@ class SkyMaterialDefines extends MaterialDefines {
     }
 }
 
+/**
+ * This is the sky material which allows to create dynamic and texture free effects for skyboxes.
+ * @see https://doc.babylonjs.com/extensions/sky
+ */
 export class SkyMaterial extends PushMaterial {
-    // Public members
+    /**
+     * Defines the overall luminance of sky in interval ]0, 1[.
+     */
     @serialize()
     public luminance: number = 1.0;
 
+     /**
+     * Defines the amount (scattering) of haze as opposed to molecules in atmosphere.
+     */
     @serialize()
     public turbidity: number = 10.0;
 
+    /**
+     * Defines the sky appearance (light intensity).
+     */
     @serialize()
     public rayleigh: number = 2.0;
 
+    /**
+     * Defines the mieCoefficient in interval [0, 0.1] which affects the property .mieDirectionalG.
+     */
     @serialize()
     public mieCoefficient: number = 0.005;
 
+    /**
+     * Defines the amount of haze particles following the Mie scattering theory.
+     */
     @serialize()
     public mieDirectionalG: number = 0.8;
 
+    /**
+     * Defines the distance of the sun according to the active scene camera.
+     */
     @serialize()
     public distance: number = 500;
 
+    /**
+     * Defines the sun inclination, in interval [-0.5, 0.5]. When the inclination is not 0, the sun is said
+     * "inclined".
+     */
     @serialize()
     public inclination: number = 0.49;
 
+    /**
+     * Defines the solar azimuth in interval [0, 1]. The azimuth is the angle in the horizontal plan between
+     * an object direction and a reference direction.
+     */
     @serialize()
     public azimuth: number = 0.25;
 
+    /**
+     * Defines the sun position in the sky on (x,y,z). If the property .useSunPosition is set to false, then
+     * the property is overriden by the inclination and the azimuth and can be read at any moment.
+     */
     @serializeAsVector3()
     public sunPosition: Vector3 = new Vector3(0, 100, 0);
 
+    /**
+     * Defines if the sun position should be computed (inclination and azimuth) according to the given
+     * .sunPosition property.
+     */
     @serialize()
     public useSunPosition: boolean = false;
 
+    /**
+     * Defines an offset vector used to get a horizon offset.
+     * @example skyMaterial.cameraOffset.y = camera.globalPosition.y // Set horizon relative to 0 on the Y axis
+     */
+    @serialize()
+    public cameraOffset: Vector3 = Vector3.Zero();
+
     // Private members
     private _cameraPosition: Vector3 = Vector3.Zero();
 
     private _renderId: number;
 
+    /**
+     * Instantiates a new sky material.
+     * This material allows to create dynamic and texture free
+     * effects for skyboxes by taking care of the atmosphere state.
+     * @see https://doc.babylonjs.com/extensions/sky
+     * @param name Define the name of the material in the scene
+     * @param scene Define the scene the material belong to
+     */
     constructor(name: string, scene: Scene) {
         super(name, scene);
     }
 
+    /**
+     * Specifies if the material will require alpha blending
+     * @returns a boolean specifying if alpha blending is needed
+     */
     public needAlphaBlending(): boolean {
         return (this.alpha < 1.0);
     }
 
+    /**
+     * Specifies if this material should be rendered in alpha test mode
+     * @returns false as the sky material doesn't need alpha testing.
+     */
     public needAlphaTesting(): boolean {
         return false;
     }
 
+    /**
+     * Get the texture used for alpha test purpose.
+     * @returns null as the sky material has no texture.
+     */
     public getAlphaTestTexture(): Nullable<BaseTexture> {
         return null;
     }
 
-    // Methods
+    /**
+     * Get if the submesh is ready to be used and all its information available.
+     * Child classes can use it to update shaders
+     * @param mesh defines the mesh to check
+     * @param subMesh defines which submesh to check
+     * @param useInstances specifies that instances should be used
+     * @returns a boolean indicating that the submesh is ready or not
+     */
     public isReadyForSubMesh(mesh: AbstractMesh, subMesh: SubMesh, useInstances?: boolean): boolean {
         if (this.isFrozen) {
             if (this._wasPreviouslyReady && subMesh.effect) {
@@ -125,7 +197,7 @@ export class SkyMaterial extends PushMaterial {
                 ["world", "viewProjection", "view",
                     "vFogInfos", "vFogColor", "pointSize", "vClipPlane", "vClipPlane2", "vClipPlane3", "vClipPlane4",
                     "luminance", "turbidity", "rayleigh", "mieCoefficient", "mieDirectionalG", "sunPosition",
-                    "cameraPosition"
+                    "cameraPosition", "cameraOffset"
                 ],
                 [],
                 join, fallbacks, this.onCompiled, this.onError), defines);
@@ -141,6 +213,12 @@ export class SkyMaterial extends PushMaterial {
         return true;
     }
 
+    /**
+     * Binds the submesh to this material by preparing the effect and shader to draw
+     * @param world defines the world transformation matrix
+     * @param mesh defines the mesh containing the submesh
+     * @param subMesh defines the submesh to bind the material to
+     */
     public bindForSubMesh(world: Matrix, mesh: Mesh, subMesh: SubMesh): void {
         var scene = this.getScene();
 
@@ -187,6 +265,8 @@ export class SkyMaterial extends PushMaterial {
             this._activeEffect.setVector3("cameraPosition", this._cameraPosition);
         }
 
+        this._activeEffect.setVector3("cameraOffset", this.cameraOffset);
+
         if (this.luminance > 0) {
             this._activeEffect.setFloat("luminance", this.luminance);
         }
@@ -210,29 +290,57 @@ export class SkyMaterial extends PushMaterial {
         this._afterBind(mesh, this._activeEffect);
     }
 
+    /**
+     * Get the list of animatables in the material.
+     * @returns the list of animatables object used in the material
+     */
     public getAnimatables(): IAnimatable[] {
         return [];
     }
 
+    /**
+     * Disposes the material
+     * @param forceDisposeEffect specifies if effects should be forcefully disposed
+     */
     public dispose(forceDisposeEffect?: boolean): void {
         super.dispose(forceDisposeEffect);
     }
 
+    /**
+     * Makes a duplicate of the material, and gives it a new name
+     * @param name defines the new name for the duplicated material
+     * @returns the cloned material
+     */
     public clone(name: string): SkyMaterial {
         return SerializationHelper.Clone<SkyMaterial>(() => new SkyMaterial(name, this.getScene()), this);
     }
 
+    /**
+     * Serializes this material in a JSON representation
+     * @returns the serialized material object
+     */
     public serialize(): any {
         var serializationObject = SerializationHelper.Serialize(this);
         serializationObject.customType  = "BABYLON.SkyMaterial";
         return serializationObject;
     }
 
+    /**
+     * Gets the current class name of the material e.g. "SkyMaterial"
+     * Mainly use in serialization.
+     * @returns the class name
+     */
     public getClassName(): string {
         return "SkyMaterial";
     }
 
-    // Statics
+    /**
+     * Creates a sky material from parsed material data
+     * @param source defines the JSON representation of the material
+     * @param scene defines the hosting scene
+     * @param rootUrl defines the root URL to use to load textures and relative dependencies
+     * @returns a new sky material
+     */
     public static Parse(source: any, scene: Scene, rootUrl: string): SkyMaterial {
         return SerializationHelper.Parse(() => new SkyMaterial(source.name, scene), source, scene, rootUrl);
     }

src/Engines/engine.ts

@@ -4344,14 +4344,8 @@ declare type RenderTargetTexture = import("Materials/Textures/renderTargetTextur
                         // Add Back
                         customFallback = true;
                         excludeLoaders.push(loader);
-<<<<<<< HEAD:src/Engines/engine.ts
-                        Logger.Warn((loader.constructor as any).name + " failed when trying to load " + texture.url + ", falling back to the next supported loader");
-                        this.createTexture(urlArg, noMipmap, texture.invertY, scene, samplingMode, null, onError, buffer, texture, undefined, undefined, excludeLoaders);
-                        return;
-=======
                         Tools.Warn((loader.constructor as any).name + " failed when trying to load " + texture.url + ", falling back to the next supported loader");
                         this.createTexture(urlArg, noMipmap, texture.invertY, scene, samplingMode, null, null, buffer, texture, undefined, undefined, excludeLoaders);
->>>>>>> upstream/master:src/Engine/babylon.engine.ts
                     }
                 }