Add BAckground MAterial Documentation

dist/preview release/typedocValidationBaseline.json

@@ -4287,130 +4287,6 @@
         }
       }
     },
-    "BackgroundMaterial": {
-      "Property": {
-        "diffuseTexture": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "enableNoise": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "maxSimultaneousLights": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "opacityFresnel": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "primaryColor": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "primaryLevel": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "reflectionAmount": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "reflectionBlur": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "reflectionFalloffDistance": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "reflectionFresnel": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "reflectionReflectance0": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "reflectionReflectance90": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "reflectionTexture": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "sceneCenter": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "secondaryColor": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "secondaryLevel": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "shadowBlurScale": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "shadowLevel": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "shadowLights": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "tertiaryColor": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "tertiaryLevel": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "useRGBColor": {
-          "Comments": {
-            "MissingText": true
-          }
-        },
-        "standardReflectance0": {
-          "Naming": {
-            "NotPascalCase": true
-          }
-        },
-        "standardReflectance90": {
-          "Naming": {
-            "NotPascalCase": true
-          }
-        }
-      }
-    },
     "BaseSubMesh": {
       "Class": {
         "Comments": {

src/Materials/Background/babylon.backgroundMaterial.ts

@@ -1,6 +1,7 @@
 module BABYLON {
     /**
      * Background material defines definition.
+     * @ignore Mainly internal Use
      */
     class BackgroundMaterialDefines extends MaterialDefines implements IImageProcessingConfigurationDefines {
         /**
@@ -126,172 +127,172 @@
         /**
          * Standard reflectance value at parallel view angle.
          */
-        public static standardReflectance0 = 0.05;
+        public static StandardReflectance0 = 0.05;
 
         /**
          * Standard reflectance value at grazing angle.
          */
-        public static standardReflectance90 = 0.5;
+        public static StandardReflectance90 = 0.5;
 
+        @serializeAsColor3()
+        protected _primaryColor: Color3;
         /**
          * Key light Color (multiply against the R channel of the environement texture)
          */
-        @serializeAsColor3()
-        protected _primaryColor: Color3;
         @expandToProperty("_markAllSubMeshesAsLightsDirty")
         public primaryColor = Color3.White();
 
+        @serialize()
+        protected _primaryLevel: float;
         /**
          * Key light Level (allowing HDR output of the background)
          */
-        @serialize()
-        protected _primaryLevel: float;
         @expandToProperty("_markAllSubMeshesAsLightsDirty")
         public primaryLevel: float = 1;
+        @serializeAsColor3()
+        protected _secondaryColor: Color3;
         /**
          * Secondary light Color (multiply against the G channel of the environement texture)
          */
-        @serializeAsColor3()
-        protected _secondaryColor: Color3;
         @expandToProperty("_markAllSubMeshesAsLightsDirty")
         public secondaryColor = Color3.Gray();
 
+        @serialize()
+        protected _secondaryLevel: float;
         /**
          * Secondary light Level (allowing HDR output of the background)
          */
-        @serialize()
-        protected _secondaryLevel: float;
         @expandToProperty("_markAllSubMeshesAsLightsDirty")
         public secondaryLevel: float = 1;
 
+        @serializeAsColor3()
+        protected _tertiaryColor: Color3;
         /**
          * Tertiary light Color (multiply against the B channel of the environement texture)
          */
-        @serializeAsColor3()
-        protected _tertiaryColor: Color3;
         @expandToProperty("_markAllSubMeshesAsLightsDirty")
         public tertiaryColor = Color3.Black();
 
+        @serialize()
+        protected _tertiaryLevel: float;
         /**
          * Tertiary light Level (allowing HDR output of the background)
          */
-        @serialize()
-        protected _tertiaryLevel: float;
         @expandToProperty("_markAllSubMeshesAsLightsDirty")
         public tertiaryLevel: float = 1;
 
+        @serializeAsTexture()
+        protected _reflectionTexture: Nullable<BaseTexture>;
         /**
          * Reflection Texture used in the material.
          * Should be author in a specific way for the best result (refer to the documentation).
          */
-        @serializeAsTexture()
-        protected _reflectionTexture: Nullable<BaseTexture>;
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public reflectionTexture: Nullable<BaseTexture> = null;
 
+        @serialize()
+        protected _reflectionBlur: float;
         /**
          * Reflection Texture level of blur.
          * 
          * Can be use to reuse an existing HDR Texture and target a specific LOD to prevent authoring the 
          * texture twice.
          */
-        @serialize()
-        protected _reflectionBlur: float;
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public reflectionBlur: float = 0;
 
+        @serializeAsTexture()
+        protected _diffuseTexture: Nullable<BaseTexture>;
         /**
          * Diffuse Texture used in the material.
          * Should be author in a specific way for the best result (refer to the documentation).
          */
-        @serializeAsTexture()
-        protected _diffuseTexture: Nullable<BaseTexture>;
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public diffuseTexture: Nullable<BaseTexture> = null;
 
+        protected _shadowLights: Nullable<IShadowLight[]> = null;
         /**
          * Specify the list of lights casting shadow on the material.
          * All scene shadow lights will be included if null.
          */
-        protected _shadowLights: Nullable<IShadowLight[]> = null;
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public shadowLights: Nullable<IShadowLight[]> = null;
 
+        @serialize()
+        protected _shadowBlurScale: int;
         /**
          * For the lights having a blurred shadow generator, this can add a second blur pass in order to reach
          * soft lighting on the background.
          */
-        @serialize()
-        protected _shadowBlurScale: int;
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public shadowBlurScale: int = 1;
 
+        @serialize()
+        protected _shadowLevel: float;
         /**
          * Helps adjusting the shadow to a softer level if required.
          * 0 means black shadows and 1 means no shadows.
          */
-        @serialize()
-        protected _shadowLevel: float;
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public shadowLevel: float = 0;
 
+        @serializeAsVector3()
+        protected _sceneCenter: Vector3;
         /**
          * In case of opacity Fresnel or reflection falloff, this is use as a scene center.
          * It is usually zero but might be interesting to modify according to your setup.
          */
-        @serializeAsVector3()
-        protected _sceneCenter: Vector3;
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public sceneCenter: Vector3 = Vector3.Zero();
 
+        @serialize()
+        protected _opacityFresnel: boolean;
         /**
          * This helps specifying that the material is falling off to the sky box at grazing angle.
          * This helps ensuring a nice transition when the camera goes under the ground.
          */
-        @serialize()
-        protected _opacityFresnel: boolean;
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public opacityFresnel: boolean = true;
 
+        @serialize()
+        protected _reflectionFresnel: boolean;
         /**
          * This helps specifying that the material is falling off from diffuse to the reflection texture at grazing angle. 
          * This helps adding a mirror texture on the ground.
          */
-        @serialize()
-        protected _reflectionFresnel: boolean;
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public reflectionFresnel: boolean = false;
 
+        @serialize()
+        protected _reflectionFalloffDistance: number;
         /**
          * This helps specifying the falloff radius off the reflection texture from the sceneCenter.
          * This helps adding a nice falloff effect to the reflection if used as a mirror for instance.
          */
-        @serialize()
-        protected _reflectionFalloffDistance: number;
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public reflectionFalloffDistance: number = 0.0;
 
+        @serialize()
+        protected _reflectionAmount: number;
         /**
          * This specifies the weight of the reflection against the background in case of reflection Fresnel.
          */
-        @serialize()
-        protected _reflectionAmount: number;
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public reflectionAmount: number = 1.0;
 
+        @serialize()
+        protected _reflectionReflectance0: number;
         /**
          * This specifies the weight of the reflection at grazing angle.
          */
-        @serialize()
-        protected _reflectionReflectance0: number;
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public reflectionReflectance0: number = 0.05;
 
+        @serialize()
+        protected _reflectionReflectance90: number;
         /**
          * This specifies the weight of the reflection at a perpendicular point of view.
          */
-        @serialize()
-        protected _reflectionReflectance90: number;
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public reflectionReflectance90: number = 0.5;
 
@@ -304,37 +305,36 @@
 
             if (reflectionWeight < 0.5) {
                 reflectionWeight = reflectionWeight * 2.0;
-                this.reflectionReflectance0 = BackgroundMaterial.standardReflectance0 * reflectionWeight;
-                this.reflectionReflectance90 = BackgroundMaterial.standardReflectance90 * reflectionWeight;
+                this.reflectionReflectance0 = BackgroundMaterial.StandardReflectance0 * reflectionWeight;
+                this.reflectionReflectance90 = BackgroundMaterial.StandardReflectance90 * reflectionWeight;
             } else {
                 reflectionWeight = reflectionWeight * 2.0 - 1.0;
-                this.reflectionReflectance0 = BackgroundMaterial.standardReflectance0 + (1.0 - BackgroundMaterial.standardReflectance0) * reflectionWeight;
-                this.reflectionReflectance90 = BackgroundMaterial.standardReflectance90 + (1.0 - BackgroundMaterial.standardReflectance90) * reflectionWeight;
+                this.reflectionReflectance0 = BackgroundMaterial.StandardReflectance0 + (1.0 - BackgroundMaterial.StandardReflectance0) * reflectionWeight;
+                this.reflectionReflectance90 = BackgroundMaterial.StandardReflectance90 + (1.0 - BackgroundMaterial.StandardReflectance90) * reflectionWeight;
             }
         }
 
+        @serialize()
+        protected _useRGBColor: boolean;
         /**
          * Helps to directly use the maps channels instead of their level.
          */
-        @serialize()
-        protected _useRGBColor: boolean;
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public useRGBColor: boolean = true;
 
+        @serialize()
+        protected _enableNoise: boolean;
         /**
          * This helps reducing the banding effect that could occur on the background.
          */
-        @serialize()
-        protected _enableNoise: boolean;
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public enableNoise: boolean = false;
 
-
+        @serialize()
+        private _maxSimultaneousLights: int = 4;
         /**
          * Number of Simultaneous lights allowed on the material.
          */
-        @serialize()
-        private _maxSimultaneousLights: int = 4;
         @expandToProperty("_markAllSubMeshesAsTexturesDirty")
         public maxSimultaneousLights: int = 4;
 
@@ -503,8 +503,8 @@
         private _reflectionControls = Vector4.Zero();
 
         /**
-         * constructor
-         * @param name The name of the material
+         * Instantiates a Background Material in the given scene
+         * @param name The friendly name of the material
          * @param scene The scene to add the material to
          */
         constructor(name: string, scene: Scene) {
@@ -549,6 +549,7 @@
          * @param mesh The mesh to render
          * @param subMesh The submesh to check against
          * @param useInstances Specify wether or not the material is used with instances
+         * @returns true if all the dependencies are ready (Textures, Effects...)
          */
         public isReadyForSubMesh(mesh: AbstractMesh, subMesh: SubMesh, useInstances: boolean = false): boolean {
             if (subMesh.effect && this.isFrozen) {
@@ -978,8 +979,8 @@
 
         /**
          * Dispose the material.
-         * @forceDisposeEffect Force disposal of the associated effect.
-         * @forceDisposeTextures Force disposal of the associated textures.
+         * @param forceDisposeEffect Force disposal of the associated effect.
+         * @param forceDisposeTextures Force disposal of the associated textures.
          */
         public dispose(forceDisposeEffect: boolean = false, forceDisposeTextures: boolean = false): void {
             if (forceDisposeTextures) {
@@ -1002,7 +1003,7 @@
 
         /**
          * Clones the material.
-         * @name The cloned name.
+         * @param name The cloned name.
          * @returns The cloned material.
          */
         public clone(name: string): BackgroundMaterial {
@@ -1029,9 +1030,9 @@
 
         /**
          * Parse a JSON input to create back a background material.
-         * @param source 
-         * @param scene 
-         * @param rootUrl 
+         * @param source The JSON data to parse
+         * @param scene The scene to create the parsed material in 
+         * @param rootUrl The root url of the assets the material depends upon
          * @returns the instantiated BackgroundMaterial.
          */
         public static Parse(source: any, scene: Scene, rootUrl: string): BackgroundMaterial {