Merge pull request #1022 from sebavan/PBRCodeDoc

PBR Code JAVADoc

materialsLibrary/dist/babylon.pbrMaterial.js

@@ -110,59 +110,212 @@ var BABYLON;
         }
         return PBRMaterialDefines;
     })(BABYLON.MaterialDefines);
+    /**
+     * The Physically based material of BJS.
+     *
+     * This offers the main features of a standard PBR material.
+     * For more information, please refer to the documentation :
+     * http://doc.babylonjs.com/extensions/Physically_Based_Rendering
+     */
     var PBRMaterial = (function (_super) {
         __extends(PBRMaterial, _super);
+        /**
+         * Instantiates a new PBRMaterial instance.
+         *
+         * @param name The material name
+         * @param scene The scene the material will be use in.
+         */
         function PBRMaterial(name, scene) {
             var _this = this;
             _super.call(this, name, scene);
+            /**
+             * Intensity of the direct lights e.g. the four lights available in your scene.
+             * This impacts both the direct diffuse and specular highlights.
+             */
             this.directIntensity = 1.0;
+            /**
+             * Intensity of the emissive part of the material.
+             * This helps controlling the emissive effect without modifying the emissive color.
+             */
             this.emissiveIntensity = 1.0;
+            /**
+             * Intensity of the environment e.g. how much the environment will light the object
+             * either through harmonics for rough material or through the refelction for shiny ones.
+             */
             this.environmentIntensity = 1.0;
+            /**
+             * This is a special control allowing the reduction of the specular highlights coming from the
+             * four lights of the scene. Those highlights may not be needed in full environment lighting.
+             */
             this.specularIntensity = 1.0;
             this._lightingInfos = new BABYLON.Vector4(this.directIntensity, this.emissiveIntensity, this.environmentIntensity, this.specularIntensity);
+            /**
+             * Debug Control allowing disabling the bump map on this material.
+             */
+            this.disableBumpMap = false;
+            /**
+             * Debug Control helping enforcing or dropping the darkness of shadows.
+             * 1.0 means the shadows have their normal darkness, 0.0 means the shadows are not visible.
+             */
             this.overloadedShadowIntensity = 1.0;
+            /**
+             * Debug Control helping dropping the shading effect coming from the diffuse lighting.
+             * 1.0 means the shade have their normal impact, 0.0 means no shading at all.
+             */
             this.overloadedShadeIntensity = 1.0;
             this._overloadedShadowInfos = new BABYLON.Vector4(this.overloadedShadowIntensity, this.overloadedShadeIntensity, 0.0, 0.0);
+            /**
+             * The camera exposure used on this material.
+             * This property is here and not in the camera to allow controlling exposure without full screen post process.
+             * This corresponds to a photographic exposure.
+             */
             this.cameraExposure = 1.0;
+            /**
+             * The camera contrast used on this material.
+             * This property is here and not in the camera to allow controlling contrast without full screen post process.
+             */
             this.cameraContrast = 1.0;
             this._cameraInfos = new BABYLON.Vector4(1.0, 1.0, 0.0, 0.0);
             this._microsurfaceTextureLods = new BABYLON.Vector2(0.0, 0.0);
+            /**
+             * Debug Control allowing to overload the ambient color.
+             * This as to be use with the overloadedAmbientIntensity parameter.
+             */
+            this.overloadedAmbient = BABYLON.Color3.White();
+            /**
+             * Debug Control indicating how much the overloaded ambient color is used against the default one.
+             */
             this.overloadedAmbientIntensity = 0.0;
+            /**
+             * Debug Control allowing to overload the albedo color.
+             * This as to be use with the overloadedAlbedoIntensity parameter.
+             */
+            this.overloadedAlbedo = BABYLON.Color3.White();
+            /**
+             * Debug Control indicating how much the overloaded albedo color is used against the default one.
+             */
             this.overloadedAlbedoIntensity = 0.0;
+            /**
+             * Debug Control allowing to overload the reflectivity color.
+             * This as to be use with the overloadedReflectivityIntensity parameter.
+             */
+            this.overloadedReflectivity = BABYLON.Color3.White();
+            /**
+             * Debug Control indicating how much the overloaded reflectivity color is used against the default one.
+             */
             this.overloadedReflectivityIntensity = 0.0;
+            /**
+             * Debug Control allowing to overload the emissive color.
+             * This as to be use with the overloadedEmissiveIntensity parameter.
+             */
+            this.overloadedEmissive = BABYLON.Color3.White();
+            /**
+             * Debug Control indicating how much the overloaded emissive color is used against the default one.
+             */
             this.overloadedEmissiveIntensity = 0.0;
             this._overloadedIntensity = new BABYLON.Vector4(this.overloadedAmbientIntensity, this.overloadedAlbedoIntensity, this.overloadedReflectivityIntensity, this.overloadedEmissiveIntensity);
-            this.overloadedAmbient = BABYLON.Color3.White();
-            this.overloadedAlbedo = BABYLON.Color3.White();
-            this.overloadedReflectivity = BABYLON.Color3.White();
-            this.overloadedEmissive = BABYLON.Color3.White();
+            /**
+             * Debug Control allowing to overload the reflection color.
+             * This as to be use with the overloadedReflectionIntensity parameter.
+             */
             this.overloadedReflection = BABYLON.Color3.White();
+            /**
+             * Debug Control indicating how much the overloaded reflection color is used against the default one.
+             */
+            this.overloadedReflectionIntensity = 0.0;
+            /**
+             * Debug Control allowing to overload the microsurface.
+             * This as to be use with the overloadedMicroSurfaceIntensity parameter.
+             */
             this.overloadedMicroSurface = 0.0;
+            /**
+             * Debug Control indicating how much the overloaded microsurface is used against the default one.
+             */
             this.overloadedMicroSurfaceIntensity = 0.0;
-            this.overloadedReflectionIntensity = 0.0;
             this._overloadedMicroSurface = new BABYLON.Vector3(this.overloadedMicroSurface, this.overloadedMicroSurfaceIntensity, this.overloadedReflectionIntensity);
-            this.disableBumpMap = false;
             this.ambientColor = new BABYLON.Color3(0, 0, 0);
+            /**
+             * AKA Diffuse Color in other nomenclature.
+             */
             this.albedoColor = new BABYLON.Color3(1, 1, 1);
+            /**
+             * AKA Specular Color in other nomenclature.
+             */
             this.reflectivityColor = new BABYLON.Color3(1, 1, 1);
             this.reflectionColor = new BABYLON.Color3(0.5, 0.5, 0.5);
             this.emissiveColor = new BABYLON.Color3(0, 0, 0);
-            this.microSurface = 0.5;
+            /**
+             * AKA Glossiness in other nomenclature.
+             */
+            this.microSurface = 0.9;
+            /**
+             * source material index of refraction (IOR)' / 'destination material IOR.
+             */
             this.indexOfRefraction = 0.66;
+            /**
+             * Controls if refraction needs to be inverted on Y. This could be usefull for procedural texture.
+             */
             this.invertRefractionY = false;
+            /**
+             * This parameters will make the material used its opacity to control how much it is refracting aginst not.
+             * Materials half opaque for instance using refraction could benefit from this control.
+             */
             this.linkRefractionWithTransparency = false;
+            /**
+             * The emissive and albedo are linked to never be more than one (Energy conservation).
+             */
             this.linkEmissiveWithAlbedo = false;
             this.useLightmapAsShadowmap = false;
+            /**
+             * In this mode, the emissive informtaion will always be added to the lighting once.
+             * A light for instance can be thought as emissive.
+             */
             this.useEmissiveAsIllumination = false;
+            /**
+             * Secifies that the alpha is coming form the albedo channel alpha channel.
+             */
             this.useAlphaFromAlbedoTexture = false;
+            /**
+             * Specifies that the material will keeps the specular highlights over a transparent surface (only the most limunous ones).
+             * A car glass is a good exemple of that. When sun reflects on it you can not see what is behind.
+             */
             this.useSpecularOverAlpha = true;
+            /**
+             * Specifies if the reflectivity texture contains the glossiness information in its alpha channel.
+             */
             this.useMicroSurfaceFromReflectivityMapAlpha = false;
+            /**
+             * In case the reflectivity map does not contain the microsurface information in its alpha channel,
+             * The material will try to infer what glossiness each pixel should be.
+             */
             this.useAutoMicroSurfaceFromReflectivityMap = false;
+            /**
+             * Allows to work with scalar in linear mode. This is definitely a matter of preferences and tools used during
+             * the creation of the material.
+             */
             this.useScalarInLinearSpace = false;
+            /**
+             * BJS is using an harcoded light falloff based on a manually sets up range.
+             * In PBR, one way to represents the fallof is to use the inverse squared root algorythm.
+             * This parameter can help you switch back to the BJS mode in order to create scenes using both materials.
+             */
             this.usePhysicalLightFalloff = true;
+            /**
+             * Specifies that the material will keeps the reflection highlights over a transparent surface (only the most limunous ones).
+             * A car glass is a good exemple of that. When the street lights reflects on it you can not see what is behind.
+             */
             this.useRadianceOverAlpha = true;
+            /**
+             * Allows using the bump map in parallax mode.
+             */
             this.useParallax = false;
+            /**
+             * Allows using the bump map in parallax occlusion mode.
+             */
             this.useParallaxOcclusion = false;
+            /**
+             * Controls the scale bias of the parallax mode.
+             */
             this.parallaxScaleBias = 0.05;
             this.disableLighting = false;
             this._renderTargets = new BABYLON.SmartArray(16);
@@ -911,6 +1064,9 @@ var BABYLON;
         ], PBRMaterial.prototype, "specularIntensity");
         __decorate([
             BABYLON.serialize()
+        ], PBRMaterial.prototype, "disableBumpMap");
+        __decorate([
+            BABYLON.serialize()
         ], PBRMaterial.prototype, "overloadedShadowIntensity");
         __decorate([
             BABYLON.serialize()
@@ -922,44 +1078,41 @@ var BABYLON;
             BABYLON.serialize()
         ], PBRMaterial.prototype, "cameraContrast");
         __decorate([
-            BABYLON.serialize()
-        ], PBRMaterial.prototype, "overloadedAmbientIntensity");
-        __decorate([
-            BABYLON.serialize()
-        ], PBRMaterial.prototype, "overloadedAlbedoIntensity");
-        __decorate([
-            BABYLON.serialize()
-        ], PBRMaterial.prototype, "overloadedReflectivityIntensity");
-        __decorate([
-            BABYLON.serialize()
-        ], PBRMaterial.prototype, "overloadedEmissiveIntensity");
-        __decorate([
             BABYLON.serializeAsColor3()
         ], PBRMaterial.prototype, "overloadedAmbient");
         __decorate([
+            BABYLON.serialize()
+        ], PBRMaterial.prototype, "overloadedAmbientIntensity");
+        __decorate([
             BABYLON.serializeAsColor3()
         ], PBRMaterial.prototype, "overloadedAlbedo");
         __decorate([
+            BABYLON.serialize()
+        ], PBRMaterial.prototype, "overloadedAlbedoIntensity");
+        __decorate([
             BABYLON.serializeAsColor3()
         ], PBRMaterial.prototype, "overloadedReflectivity");
         __decorate([
+            BABYLON.serialize()
+        ], PBRMaterial.prototype, "overloadedReflectivityIntensity");
+        __decorate([
             BABYLON.serializeAsColor3()
         ], PBRMaterial.prototype, "overloadedEmissive");
         __decorate([
+            BABYLON.serialize()
+        ], PBRMaterial.prototype, "overloadedEmissiveIntensity");
+        __decorate([
             BABYLON.serializeAsColor3()
         ], PBRMaterial.prototype, "overloadedReflection");
         __decorate([
             BABYLON.serialize()
-        ], PBRMaterial.prototype, "overloadedMicroSurface");
-        __decorate([
-            BABYLON.serialize()
-        ], PBRMaterial.prototype, "overloadedMicroSurfaceIntensity");
+        ], PBRMaterial.prototype, "overloadedReflectionIntensity");
         __decorate([
             BABYLON.serialize()
-        ], PBRMaterial.prototype, "overloadedReflectionIntensity");
+        ], PBRMaterial.prototype, "overloadedMicroSurface");
         __decorate([
             BABYLON.serialize()
-        ], PBRMaterial.prototype, "disableBumpMap");
+        ], PBRMaterial.prototype, "overloadedMicroSurfaceIntensity");
         __decorate([
             BABYLON.serializeAsTexture()
         ], PBRMaterial.prototype, "albedoTexture");

materialsLibrary/dist/dts/babylon.pbrMaterial.d.ts

@@ -1,65 +1,221 @@
 /// <reference path="../../../dist/preview release/babylon.d.ts" />
 declare module BABYLON {
+    /**
+     * The Physically based material of BJS.
+     *
+     * This offers the main features of a standard PBR material.
+     * For more information, please refer to the documentation :
+     * http://doc.babylonjs.com/extensions/Physically_Based_Rendering
+     */
     class PBRMaterial extends BABYLON.Material {
+        /**
+         * Intensity of the direct lights e.g. the four lights available in your scene.
+         * This impacts both the direct diffuse and specular highlights.
+         */
         directIntensity: number;
+        /**
+         * Intensity of the emissive part of the material.
+         * This helps controlling the emissive effect without modifying the emissive color.
+         */
         emissiveIntensity: number;
+        /**
+         * Intensity of the environment e.g. how much the environment will light the object
+         * either through harmonics for rough material or through the refelction for shiny ones.
+         */
         environmentIntensity: number;
+        /**
+         * This is a special control allowing the reduction of the specular highlights coming from the
+         * four lights of the scene. Those highlights may not be needed in full environment lighting.
+         */
         specularIntensity: number;
         private _lightingInfos;
+        /**
+         * Debug Control allowing disabling the bump map on this material.
+         */
+        disableBumpMap: boolean;
+        /**
+         * Debug Control helping enforcing or dropping the darkness of shadows.
+         * 1.0 means the shadows have their normal darkness, 0.0 means the shadows are not visible.
+         */
         overloadedShadowIntensity: number;
+        /**
+         * Debug Control helping dropping the shading effect coming from the diffuse lighting.
+         * 1.0 means the shade have their normal impact, 0.0 means no shading at all.
+         */
         overloadedShadeIntensity: number;
         private _overloadedShadowInfos;
+        /**
+         * The camera exposure used on this material.
+         * This property is here and not in the camera to allow controlling exposure without full screen post process.
+         * This corresponds to a photographic exposure.
+         */
         cameraExposure: number;
+        /**
+         * The camera contrast used on this material.
+         * This property is here and not in the camera to allow controlling contrast without full screen post process.
+         */
         cameraContrast: number;
         private _cameraInfos;
         private _microsurfaceTextureLods;
+        /**
+         * Debug Control allowing to overload the ambient color.
+         * This as to be use with the overloadedAmbientIntensity parameter.
+         */
+        overloadedAmbient: Color3;
+        /**
+         * Debug Control indicating how much the overloaded ambient color is used against the default one.
+         */
         overloadedAmbientIntensity: number;
+        /**
+         * Debug Control allowing to overload the albedo color.
+         * This as to be use with the overloadedAlbedoIntensity parameter.
+         */
+        overloadedAlbedo: Color3;
+        /**
+         * Debug Control indicating how much the overloaded albedo color is used against the default one.
+         */
         overloadedAlbedoIntensity: number;
+        /**
+         * Debug Control allowing to overload the reflectivity color.
+         * This as to be use with the overloadedReflectivityIntensity parameter.
+         */
+        overloadedReflectivity: Color3;
+        /**
+         * Debug Control indicating how much the overloaded reflectivity color is used against the default one.
+         */
         overloadedReflectivityIntensity: number;
+        /**
+         * Debug Control allowing to overload the emissive color.
+         * This as to be use with the overloadedEmissiveIntensity parameter.
+         */
+        overloadedEmissive: Color3;
+        /**
+         * Debug Control indicating how much the overloaded emissive color is used against the default one.
+         */
         overloadedEmissiveIntensity: number;
         private _overloadedIntensity;
-        overloadedAmbient: Color3;
-        overloadedAlbedo: Color3;
-        overloadedReflectivity: Color3;
-        overloadedEmissive: Color3;
+        /**
+         * Debug Control allowing to overload the reflection color.
+         * This as to be use with the overloadedReflectionIntensity parameter.
+         */
         overloadedReflection: Color3;
+        /**
+         * Debug Control indicating how much the overloaded reflection color is used against the default one.
+         */
+        overloadedReflectionIntensity: number;
+        /**
+         * Debug Control allowing to overload the microsurface.
+         * This as to be use with the overloadedMicroSurfaceIntensity parameter.
+         */
         overloadedMicroSurface: number;
+        /**
+         * Debug Control indicating how much the overloaded microsurface is used against the default one.
+         */
         overloadedMicroSurfaceIntensity: number;
-        overloadedReflectionIntensity: number;
         private _overloadedMicroSurface;
-        disableBumpMap: boolean;
+        /**
+         * AKA Diffuse Texture in standard nomenclature.
+         */
         albedoTexture: BaseTexture;
+        /**
+         * AKA Occlusion Texture in other nomenclature.
+         */
         ambientTexture: BaseTexture;
         opacityTexture: BaseTexture;
         reflectionTexture: BaseTexture;
         emissiveTexture: BaseTexture;
+        /**
+         * AKA Specular texture in other nomenclature.
+         */
         reflectivityTexture: BaseTexture;
         bumpTexture: BaseTexture;
         lightmapTexture: BaseTexture;
         refractionTexture: BaseTexture;
         ambientColor: Color3;
+        /**
+         * AKA Diffuse Color in other nomenclature.
+         */
         albedoColor: Color3;
+        /**
+         * AKA Specular Color in other nomenclature.
+         */
         reflectivityColor: Color3;
         reflectionColor: Color3;
         emissiveColor: Color3;
+        /**
+         * AKA Glossiness in other nomenclature.
+         */
         microSurface: number;
+        /**
+         * source material index of refraction (IOR)' / 'destination material IOR.
+         */
         indexOfRefraction: number;
+        /**
+         * Controls if refraction needs to be inverted on Y. This could be usefull for procedural texture.
+         */
         invertRefractionY: boolean;
         opacityFresnelParameters: FresnelParameters;
         emissiveFresnelParameters: FresnelParameters;
+        /**
+         * This parameters will make the material used its opacity to control how much it is refracting aginst not.
+         * Materials half opaque for instance using refraction could benefit from this control.
+         */
         linkRefractionWithTransparency: boolean;
+        /**
+         * The emissive and albedo are linked to never be more than one (Energy conservation).
+         */
         linkEmissiveWithAlbedo: boolean;
         useLightmapAsShadowmap: boolean;
+        /**
+         * In this mode, the emissive informtaion will always be added to the lighting once.
+         * A light for instance can be thought as emissive.
+         */
         useEmissiveAsIllumination: boolean;
+        /**
+         * Secifies that the alpha is coming form the albedo channel alpha channel.
+         */
         useAlphaFromAlbedoTexture: boolean;
+        /**
+         * Specifies that the material will keeps the specular highlights over a transparent surface (only the most limunous ones).
+         * A car glass is a good exemple of that. When sun reflects on it you can not see what is behind.
+         */
         useSpecularOverAlpha: boolean;
+        /**
+         * Specifies if the reflectivity texture contains the glossiness information in its alpha channel.
+         */
         useMicroSurfaceFromReflectivityMapAlpha: boolean;
+        /**
+         * In case the reflectivity map does not contain the microsurface information in its alpha channel,
+         * The material will try to infer what glossiness each pixel should be.
+         */
         useAutoMicroSurfaceFromReflectivityMap: boolean;
+        /**
+         * Allows to work with scalar in linear mode. This is definitely a matter of preferences and tools used during
+         * the creation of the material.
+         */
         useScalarInLinearSpace: boolean;
+        /**
+         * BJS is using an harcoded light falloff based on a manually sets up range.
+         * In PBR, one way to represents the fallof is to use the inverse squared root algorythm.
+         * This parameter can help you switch back to the BJS mode in order to create scenes using both materials.
+         */
         usePhysicalLightFalloff: boolean;
+        /**
+         * Specifies that the material will keeps the reflection highlights over a transparent surface (only the most limunous ones).
+         * A car glass is a good exemple of that. When the street lights reflects on it you can not see what is behind.
+         */
         useRadianceOverAlpha: boolean;
+        /**
+         * Allows using the bump map in parallax mode.
+         */
         useParallax: boolean;
+        /**
+         * Allows using the bump map in parallax occlusion mode.
+         */
         useParallaxOcclusion: boolean;
+        /**
+         * Controls the scale bias of the parallax mode.
+         */
         parallaxScaleBias: number;
         disableLighting: boolean;
         private _renderTargets;
@@ -70,6 +226,12 @@ declare module BABYLON {
         private _defines;
         private _cachedDefines;
         private _useLogarithmicDepth;
+        /**
+         * Instantiates a new PBRMaterial instance.
+         *
+         * @param name The material name
+         * @param scene The scene the material will be use in.
+         */
         constructor(name: string, scene: Scene);
         useLogarithmicDepth: boolean;
         needAlphaBlending(): boolean;

materialsLibrary/materials/pbr/babylon.pbrMaterial.ts

@@ -102,33 +102,79 @@ module BABYLON {
         }
     }
 
+    /**
+     * The Physically based material of BJS.
+     * 
+     * This offers the main features of a standard PBR material.
+     * For more information, please refer to the documentation : 
+     * http://doc.babylonjs.com/extensions/Physically_Based_Rendering
+     */
     export class PBRMaterial extends BABYLON.Material {
 
+        /**
+         * Intensity of the direct lights e.g. the four lights available in your scene.
+         * This impacts both the direct diffuse and specular highlights.
+         */
         @serialize()
         public directIntensity: number = 1.0;
         
+        /**
+         * Intensity of the emissive part of the material.
+         * This helps controlling the emissive effect without modifying the emissive color.
+         */
         @serialize()
         public emissiveIntensity: number = 1.0;
         
+        /**
+         * Intensity of the environment e.g. how much the environment will light the object
+         * either through harmonics for rough material or through the refelction for shiny ones.
+         */
         @serialize()
         public environmentIntensity: number = 1.0;
         
+        /**
+         * This is a special control allowing the reduction of the specular highlights coming from the 
+         * four lights of the scene. Those highlights may not be needed in full environment lighting.
+         */
         @serialize()
         public specularIntensity: number = 1.0;
 
         private _lightingInfos: Vector4 = new Vector4(this.directIntensity, this.emissiveIntensity, this.environmentIntensity, this.specularIntensity);
+        
+        /**
+         * Debug Control allowing disabling the bump map on this material.
+         */
+        @serialize()
+        public disableBumpMap: boolean = false;
 
+        /**
+         * Debug Control helping enforcing or dropping the darkness of shadows.
+         * 1.0 means the shadows have their normal darkness, 0.0 means the shadows are not visible.
+         */
         @serialize()
         public overloadedShadowIntensity: number = 1.0;
         
+        /**
+         * Debug Control helping dropping the shading effect coming from the diffuse lighting.
+         * 1.0 means the shade have their normal impact, 0.0 means no shading at all.
+         */
         @serialize()
         public overloadedShadeIntensity: number = 1.0;
         
         private _overloadedShadowInfos: Vector4 = new Vector4(this.overloadedShadowIntensity, this.overloadedShadeIntensity, 0.0, 0.0);
 
+        /**
+         * The camera exposure used on this material.
+         * This property is here and not in the camera to allow controlling exposure without full screen post process.
+         * This corresponds to a photographic exposure.
+         */
         @serialize()
         public cameraExposure: number = 1.0;
         
+        /**
+         * The camera contrast used on this material.
+         * This property is here and not in the camera to allow controlling contrast without full screen post process.
+         */
         @serialize()
         public cameraContrast: number = 1.0;
         
@@ -136,52 +182,97 @@ module BABYLON {
 
         private _microsurfaceTextureLods: Vector2 = new Vector2(0.0, 0.0);
 
+        /**
+         * Debug Control allowing to overload the ambient color.
+         * This as to be use with the overloadedAmbientIntensity parameter.
+         */
+        @serializeAsColor3()
+        public overloadedAmbient: Color3 = BABYLON.Color3.White();
+
+        /**
+         * Debug Control indicating how much the overloaded ambient color is used against the default one.
+         */
         @serialize()
         public overloadedAmbientIntensity: number = 0.0;
         
+        /**
+         * Debug Control allowing to overload the albedo color.
+         * This as to be use with the overloadedAlbedoIntensity parameter.
+         */
+        @serializeAsColor3()
+        public overloadedAlbedo: Color3 = BABYLON.Color3.White();
+        
+        /**
+         * Debug Control indicating how much the overloaded albedo color is used against the default one.
+         */
         @serialize()
         public overloadedAlbedoIntensity: number = 0.0;
         
+        /**
+         * Debug Control allowing to overload the reflectivity color.
+         * This as to be use with the overloadedReflectivityIntensity parameter.
+         */
+        @serializeAsColor3()
+        public overloadedReflectivity: Color3 = BABYLON.Color3.White();
+        
+        /**
+         * Debug Control indicating how much the overloaded reflectivity color is used against the default one.
+         */
         @serialize()
         public overloadedReflectivityIntensity: number = 0.0;
         
+        /**
+         * Debug Control allowing to overload the emissive color.
+         * This as to be use with the overloadedEmissiveIntensity parameter.
+         */
+        @serializeAsColor3()
+        public overloadedEmissive: Color3 = BABYLON.Color3.White();
+        
+        /**
+         * Debug Control indicating how much the overloaded emissive color is used against the default one.
+         */
         @serialize()
         public overloadedEmissiveIntensity: number = 0.0;
         
         private _overloadedIntensity: Vector4 = new Vector4(this.overloadedAmbientIntensity, this.overloadedAlbedoIntensity, this.overloadedReflectivityIntensity, this.overloadedEmissiveIntensity);
-
-        @serializeAsColor3()
-        public overloadedAmbient: Color3 = BABYLON.Color3.White();
-        
-        @serializeAsColor3()
-        public overloadedAlbedo: Color3 = BABYLON.Color3.White();
-        
-        @serializeAsColor3()
-        public overloadedReflectivity: Color3 = BABYLON.Color3.White();
-        
-        @serializeAsColor3()
-        public overloadedEmissive: Color3 = BABYLON.Color3.White();
         
+        /**
+         * Debug Control allowing to overload the reflection color.
+         * This as to be use with the overloadedReflectionIntensity parameter.
+         */
         @serializeAsColor3()
         public overloadedReflection: Color3 = BABYLON.Color3.White();
+        
+        /**
+         * Debug Control indicating how much the overloaded reflection color is used against the default one.
+         */
+        @serialize()
+        public overloadedReflectionIntensity: number = 0.0;
 
+        /**
+         * Debug Control allowing to overload the microsurface.
+         * This as to be use with the overloadedMicroSurfaceIntensity parameter.
+         */
         @serialize()
         public overloadedMicroSurface: number = 0.0;
         
+        /**
+         * Debug Control indicating how much the overloaded microsurface is used against the default one.
+         */
         @serialize()
         public overloadedMicroSurfaceIntensity: number = 0.0;
         
-        @serialize()
-        public overloadedReflectionIntensity: number = 0.0;
-        
         private _overloadedMicroSurface: Vector3 = new Vector3(this.overloadedMicroSurface, this.overloadedMicroSurfaceIntensity, this.overloadedReflectionIntensity);
 
-        @serialize()
-        public disableBumpMap: boolean = false;
-
+        /**
+         * AKA Diffuse Texture in standard nomenclature.
+         */
         @serializeAsTexture()
         public albedoTexture: BaseTexture;
         
+        /**
+         * AKA Occlusion Texture in other nomenclature.
+         */
         @serializeAsTexture()
         public ambientTexture: BaseTexture;
         
@@ -194,6 +285,9 @@ module BABYLON {
         @serializeAsTexture()
         public emissiveTexture: BaseTexture;
         
+        /**
+         * AKA Specular texture in other nomenclature.
+         */
         @serializeAsTexture()
         public reflectivityTexture: BaseTexture;
         
@@ -209,9 +303,15 @@ module BABYLON {
         @serializeAsColor3("ambient")
         public ambientColor = new Color3(0, 0, 0);
         
+        /**
+         * AKA Diffuse Color in other nomenclature.
+         */
         @serializeAsColor3("albedo")
         public albedoColor = new Color3(1, 1, 1);
         
+        /**
+         * AKA Specular Color in other nomenclature.
+         */
         @serializeAsColor3("reflectivity")
         public reflectivityColor = new Color3(1, 1, 1);
         
@@ -221,12 +321,21 @@ module BABYLON {
         @serializeAsColor3("emissivie")
         public emissiveColor = new Color3(0, 0, 0);
         
+        /**
+         * AKA Glossiness in other nomenclature.
+         */
         @serialize()
-        public microSurface = 0.5;
+        public microSurface = 0.9;
         
+        /**
+         * source material index of refraction (IOR)' / 'destination material IOR.
+         */
         @serialize()
         public indexOfRefraction = 0.66;
         
+        /**
+         * Controls if refraction needs to be inverted on Y. This could be usefull for procedural texture.
+         */
         @serialize()
         public invertRefractionY = false;
         
@@ -236,45 +345,92 @@ module BABYLON {
         @serializeAsFresnelParameters()
         public emissiveFresnelParameters: FresnelParameters;
 
+        /**
+         * This parameters will make the material used its opacity to control how much it is refracting aginst not.
+         * Materials half opaque for instance using refraction could benefit from this control.
+         */
         @serialize()
         public linkRefractionWithTransparency = false;
         
+        /**
+         * The emissive and albedo are linked to never be more than one (Energy conservation).
+         */
         @serialize()
         public linkEmissiveWithAlbedo = false;
         
         @serialize()
         public useLightmapAsShadowmap = false;
         
+        /**
+         * In this mode, the emissive informtaion will always be added to the lighting once.
+         * A light for instance can be thought as emissive.
+         */
         @serialize()
         public useEmissiveAsIllumination = false;
         
+        /**
+         * Secifies that the alpha is coming form the albedo channel alpha channel.
+         */
         @serialize()
         public useAlphaFromAlbedoTexture = false;
         
+        /**
+         * Specifies that the material will keeps the specular highlights over a transparent surface (only the most limunous ones).
+         * A car glass is a good exemple of that. When sun reflects on it you can not see what is behind.
+         */
         @serialize()
         public useSpecularOverAlpha = true;
         
+        /**
+         * Specifies if the reflectivity texture contains the glossiness information in its alpha channel.
+         */
         @serialize()
         public useMicroSurfaceFromReflectivityMapAlpha = false;
         
+        /**
+         * In case the reflectivity map does not contain the microsurface information in its alpha channel,
+         * The material will try to infer what glossiness each pixel should be.
+         */
         @serialize()
         public useAutoMicroSurfaceFromReflectivityMap = false;
         
+        /**
+         * Allows to work with scalar in linear mode. This is definitely a matter of preferences and tools used during
+         * the creation of the material.
+         */
         @serialize()
         public useScalarInLinearSpace = false;
         
+        /**
+         * BJS is using an harcoded light falloff based on a manually sets up range.
+         * In PBR, one way to represents the fallof is to use the inverse squared root algorythm.
+         * This parameter can help you switch back to the BJS mode in order to create scenes using both materials.
+         */
         @serialize()
         public usePhysicalLightFalloff = true;
         
+        /**
+         * Specifies that the material will keeps the reflection highlights over a transparent surface (only the most limunous ones).
+         * A car glass is a good exemple of that. When the street lights reflects on it you can not see what is behind.
+         */
         @serialize()
         public useRadianceOverAlpha = true;
         
+        /**
+         * Allows using the bump map in parallax mode.
+         */
         @serialize()
         public useParallax = false;
 
+        /**
+         * Allows using the bump map in parallax occlusion mode.
+         */
         @serialize()
         public useParallaxOcclusion = false;
 
+        /**
+         * Controls the scale bias of the parallax mode.
+         */
         @serialize()
         public parallaxScaleBias = 0.05;
         
@@ -292,6 +448,12 @@ module BABYLON {
 
         private _useLogarithmicDepth: boolean;
 
+        /**
+         * Instantiates a new PBRMaterial instance.
+         * 
+         * @param name The material name
+         * @param scene The scene the material will be use in.
+         */
         constructor(name: string, scene: Scene) {
             super(name, scene);
 

src/Materials/Textures/babylon.hdrCubeTexture.js

@@ -5,18 +5,45 @@ var __extends = (this && this.__extends) || function (d, b) {
 };
 var BABYLON;
 (function (BABYLON) {
+    /**
+     * This represents a texture coming from an HDR input.
+     *
+     * The only supported format is currently panorama picture stored in RGBE format.
+     * Example of such files can be found on HDRLib: http://hdrlib.com/
+     */
     var HDRCubeTexture = (function (_super) {
         __extends(HDRCubeTexture, _super);
+        /**
+         * Instantiates an HDRTexture from the following parameters.
+         *
+         * @param url The location of the HDR raw data (Panorama stored in RGBE format)
+         * @param scene The scene the texture will be used in
+         * @param size The cubemap desired size (the more it increases the longer the generation will be)
+         * @param noMipmap Forces to not generate the mipmap if true
+         * @param generateHarmonics Specifies wether you want to extract the polynomial harmonics during the generation process
+         * @param useInGammaSpace Specifies if the texture will be use in gamma or linear space (the PBR material requires those texture in linear space, but the standard material would require them in Gamma space)
+         * @param usePMREMGenerator Specifies wether or not to generate the CubeMap through CubeMapGen to avoid seams issue at run time.
+         */
         function HDRCubeTexture(url, scene, size, noMipmap, generateHarmonics, useInGammaSpace, usePMREMGenerator) {
             if (noMipmap === void 0) { noMipmap = false; }
             if (generateHarmonics === void 0) { generateHarmonics = true; }
             if (useInGammaSpace === void 0) { useInGammaSpace = false; }
             if (usePMREMGenerator === void 0) { usePMREMGenerator = false; }
             _super.call(this, scene);
-            this.coordinatesMode = BABYLON.Texture.CUBIC_MODE;
             this._useInGammaSpace = false;
             this._generateHarmonics = true;
+            /**
+             * The texture coordinates mode. As this texture is stored in a cube format, please modify carefully.
+             */
+            this.coordinatesMode = BABYLON.Texture.CUBIC_MODE;
+            /**
+             * The spherical polynomial data extracted from the texture.
+             */
             this.sphericalPolynomial = null;
+            /**
+             * Specifies wether the texture has been generated through the PMREMGenerator tool.
+             * This is usefull at run time to apply the good shader.
+             */
             this.isPMREM = false;
             this.name = url;
             this.url = url;
@@ -91,6 +118,7 @@ var BABYLON;
             var mipmapGenerator = null;
             if (!this._noMipmap && this._usePMREMGenerator) {
                 mipmapGenerator = function (data) {
+                    // Custom setup of the generator matching with the PBR shader values.
                     var generator = new BABYLON.Internals.PMREMGenerator(data, _this._size, _this._size, 0, 3, _this.getScene().getEngine().getCaps().textureFloat, 2048, 0.25, false, true);
                     return generator.filterCubeMap();
                 };

src/Materials/Textures/babylon.hdrcubetexture.ts

@@ -1,15 +1,12 @@
 module BABYLON {
+    
+    /**
+     * This represents a texture coming from an HDR input.
+     * 
+     * The only supported format is currently panorama picture stored in RGBE format.
+     * Example of such files can be found on HDRLib: http://hdrlib.com/
+     */
     export class HDRCubeTexture extends BaseTexture {
-        public url: string;
-        public coordinatesMode = Texture.CUBIC_MODE;
-
-        private _useInGammaSpace = false;
-        private _generateHarmonics = true;
-        private _noMipmap: boolean;
-        private _extensions: string[];
-        private _textureMatrix: Matrix;
-        private _size: number;
-        private _usePMREMGenerator: boolean;
 
         private static _facesMapping = [
             "right",
@@ -19,11 +16,47 @@ module BABYLON {
             "down",
             "back"
         ];
+        
+        private _useInGammaSpace = false;
+        private _generateHarmonics = true;
+        private _noMipmap: boolean;
+        private _extensions: string[];
+        private _textureMatrix: Matrix;
+        private _size: number;
+        private _usePMREMGenerator: boolean;
+        
+        /**
+         * The texture URL.
+         */
+        public url: string;
+        
+        /**
+         * The texture coordinates mode. As this texture is stored in a cube format, please modify carefully.
+         */
+        public coordinatesMode = Texture.CUBIC_MODE;
 
+        /**
+         * The spherical polynomial data extracted from the texture.
+         */
         public sphericalPolynomial: SphericalPolynomial = null;
 
+        /**
+         * Specifies wether the texture has been generated through the PMREMGenerator tool.
+         * This is usefull at run time to apply the good shader.
+         */
         public isPMREM = false;
 
+        /**
+         * Instantiates an HDRTexture from the following parameters.
+         * 
+         * @param url The location of the HDR raw data (Panorama stored in RGBE format)
+         * @param scene The scene the texture will be used in
+         * @param size The cubemap desired size (the more it increases the longer the generation will be)
+         * @param noMipmap Forces to not generate the mipmap if true
+         * @param generateHarmonics Specifies wether you want to extract the polynomial harmonics during the generation process
+         * @param useInGammaSpace Specifies if the texture will be use in gamma or linear space (the PBR material requires those texture in linear space, but the standard material would require them in Gamma space)
+         * @param usePMREMGenerator Specifies wether or not to generate the CubeMap through CubeMapGen to avoid seams issue at run time.
+         */
         constructor(url: string, scene: Scene, size: number, noMipmap = false, generateHarmonics = true, useInGammaSpace = false, usePMREMGenerator = false) {
             super(scene);
 
@@ -113,6 +146,7 @@ module BABYLON {
             var mipmapGenerator = null;
             if (!this._noMipmap && this._usePMREMGenerator) {
                 mipmapGenerator = (data: ArrayBufferView[]) => {
+                    // Custom setup of the generator matching with the PBR shader values.
                     var generator = new BABYLON.Internals.PMREMGenerator(data,
                         this._size,
                         this._size,

src/Tools/HDR/babylon.tools.cubemapToSphericalPolynomial.js

@@ -12,9 +12,20 @@ var BABYLON;
             return FileFaceOrientation;
         })();
         ;
+        /**
+         * Helper class dealing with the extraction of spherical polynomial dataArray
+         * from a cube map.
+         */
         var CubeMapToSphericalPolynomialTools = (function () {
             function CubeMapToSphericalPolynomialTools() {
             }
+            /**
+             * Converts a cubemap to the according Spherical Polynomial data.
+             * This extracts the first 3 orders only as they are the only one used in the lighting.
+             *
+             * @param cubeInfo The Cube map to extract the information from.
+             * @return The Spherical Polynomial data.
+             */
             CubeMapToSphericalPolynomialTools.ConvertCubeMapToSphericalPolynomial = function (cubeInfo) {
                 var sphericalHarmonics = new BABYLON.SphericalHarmonics();
                 var totalSolidAngle = 0.0;

src/Tools/HDR/babylon.tools.cubemaptosphericalpolynomial.ts

@@ -13,7 +13,11 @@ module BABYLON.Internals {
             this.worldAxisForFileY = worldAxisForFileY;
         }
     };
-
+    
+    /**
+     * Helper class dealing with the extraction of spherical polynomial dataArray
+     * from a cube map.
+     */
     export class CubeMapToSphericalPolynomialTools {
 
         private static FileFaces: FileFaceOrientation[] = [
@@ -25,6 +29,13 @@ module BABYLON.Internals {
             new FileFaceOrientation("back", new Vector3(0, 0, -1), new Vector3(-1, 0, 0), new Vector3(0, -1, 0))// -Z bottom
         ];
 
+        /**
+         * Converts a cubemap to the according Spherical Polynomial data. 
+         * This extracts the first 3 orders only as they are the only one used in the lighting.
+         * 
+         * @param cubeInfo The Cube map to extract the information from.
+         * @return The Spherical Polynomial data.
+         */
         public static ConvertCubeMapToSphericalPolynomial(cubeInfo: CubeMapInfo): SphericalPolynomial {
             var sphericalHarmonics = new SphericalHarmonics();
             var totalSolidAngle = 0.0;

src/Tools/HDR/babylon.tools.hdr.js

@@ -3,6 +3,9 @@ var BABYLON;
     var Internals;
     (function (Internals) {
         ;
+        /**
+         * This groups tools to convert HDR texture to native colors array.
+         */
         var HDRTools = (function () {
             function HDRTools() {
             }
@@ -40,7 +43,14 @@ var BABYLON;
                 }
                 return line;
             };
-            /* minimal header reading.  modify if you want to parse more information */
+            /**
+             * Reads header information from an RGBE texture stored in a native array.
+             * More information on this format are available here:
+             * https://en.wikipedia.org/wiki/RGBE_image_format
+             *
+             * @param uint8array The binary file stored in  native array.
+             * @return The header information.
+             */
             HDRTools.RGBE_ReadHeader = function (uint8array) {
                 var height = 0;
                 var width = 0;
@@ -84,6 +94,17 @@ var BABYLON;
                     dataPosition: lineIndex
                 };
             };
+            /**
+             * Returns the cubemap information (each faces texture data) extracted from an RGBE texture.
+             * This RGBE texture needs to store the information as a panorama.
+             *
+             * More information on this format are available here:
+             * https://en.wikipedia.org/wiki/RGBE_image_format
+             *
+             * @param buffer The binary file stored in an array buffer.
+             * @param size The expected size of the extracted cubemap.
+             * @return The Cube Map information.
+             */
             HDRTools.GetCubeMapTextureData = function (buffer, size) {
                 var uint8array = new Uint8Array(buffer);
                 var hdrInfo = this.RGBE_ReadHeader(uint8array);
@@ -91,6 +112,17 @@ var BABYLON;
                 var cubeMapData = Internals.PanoramaToCubeMapTools.ConvertPanoramaToCubemap(data, hdrInfo.width, hdrInfo.height, size);
                 return cubeMapData;
             };
+            /**
+             * Returns the pixels data extracted from an RGBE texture.
+             * This pixels will be stored left to right up to down in the R G B order in one array.
+             *
+             * More information on this format are available here:
+             * https://en.wikipedia.org/wiki/RGBE_image_format
+             *
+             * @param uint8array The binary file stored in an array buffer.
+             * @param hdrInfo The header information of the file.
+             * @return The pixels data in RGB right to left up to down order.
+             */
             HDRTools.RGBE_ReadPixels = function (uint8array, hdrInfo) {
                 // Keep for multi format supports.
                 return this.RGBE_ReadPixels_RLE(uint8array, hdrInfo);

src/Tools/HDR/babylon.tools.hdr.ts

@@ -1,10 +1,27 @@
 module BABYLON.Internals {
+    /**
+     * Header information of HDR texture files.
+     */
     export interface HDRInfo {
+        /**
+         * The height of the texture in pixels.
+         */
         height: number;
+        
+        /**
+         * The width of the texture in pixels.
+         */
         width: number;
+        
+        /**
+         * The index of the beginning of the data in the binary file.
+         */
         dataPosition: number;
     };
 
+    /**
+     * This groups tools to convert HDR texture to native colors array.
+     */
     export class HDRTools {
 
         private static Ldexp(mantissa: number, exponent: number): number {
@@ -54,7 +71,14 @@ module BABYLON.Internals {
             return line;
         }
 
-        /* minimal header reading.  modify if you want to parse more information */
+        /**
+         * Reads header information from an RGBE texture stored in a native array. 
+         * More information on this format are available here:
+         * https://en.wikipedia.org/wiki/RGBE_image_format
+         * 
+         * @param uint8array The binary file stored in  native array.
+         * @return The header information.
+         */
         public static RGBE_ReadHeader(uint8array: Uint8Array) : HDRInfo {
             var height: number = 0;
             var width: number = 0;
@@ -110,6 +134,17 @@ module BABYLON.Internals {
             };
         }
 
+        /**
+         * Returns the cubemap information (each faces texture data) extracted from an RGBE texture.
+         * This RGBE texture needs to store the information as a panorama.
+         *  
+         * More information on this format are available here:
+         * https://en.wikipedia.org/wiki/RGBE_image_format
+         * 
+         * @param buffer The binary file stored in an array buffer.
+         * @param size The expected size of the extracted cubemap.
+         * @return The Cube Map information.
+         */
         public static GetCubeMapTextureData(buffer: ArrayBuffer, size: number) : CubeMapInfo {
             var uint8array = new Uint8Array(buffer);
             var hdrInfo = this.RGBE_ReadHeader(uint8array);
@@ -120,11 +155,22 @@ module BABYLON.Internals {
             return cubeMapData;
         }
 
+        /**
+         * Returns the pixels data extracted from an RGBE texture. 
+         * This pixels will be stored left to right up to down in the R G B order in one array.
+         *  
+         * More information on this format are available here:
+         * https://en.wikipedia.org/wiki/RGBE_image_format
+         * 
+         * @param uint8array The binary file stored in an array buffer.
+         * @param hdrInfo The header information of the file.
+         * @return The pixels data in RGB right to left up to down order.
+         */
         public static RGBE_ReadPixels(uint8array:Uint8Array, hdrInfo:HDRInfo): Float32Array {
             // Keep for multi format supports.
             return this.RGBE_ReadPixels_RLE(uint8array, hdrInfo);
         }
-
+        
         private static RGBE_ReadPixels_RLE(uint8array:Uint8Array, hdrInfo:HDRInfo): Float32Array {
             var num_scanlines = hdrInfo.height;
             var scanline_width = hdrInfo.width;

src/Tools/HDR/babylon.tools.panoramaToCubemap.js

@@ -2,9 +2,21 @@ var BABYLON;
 (function (BABYLON) {
     var Internals;
     (function (Internals) {
+        /**
+         * Helper class usefull to convert panorama picture to their cubemap representation in 6 faces.
+         */
         var PanoramaToCubeMapTools = (function () {
             function PanoramaToCubeMapTools() {
             }
+            /**
+             * Converts a panorma stored in RGB right to left up to down format into a cubemap (6 faces).
+             *
+             * @param float32Array The source data.
+             * @param inputWidth The width of the input panorama.
+             * @param inputhHeight The height of the input panorama.
+             * @param size The willing size of the generated cubemap (each faces will be size * size pixels)
+             * @return The cubemap data
+             */
             PanoramaToCubeMapTools.ConvertPanoramaToCubemap = function (float32Array, inputWidth, inputHeight, size) {
                 if (!float32Array) {
                     throw "ConvertPanoramaToCubemap: input cannot be null";

src/Tools/HDR/babylon.tools.panoramaToCubemap.ts

@@ -1,14 +1,55 @@
 module BABYLON.Internals {
+    /**
+     * CubeMap information grouping all the data for each faces as well as the cubemap size.
+     */
     export interface CubeMapInfo {
+        /**
+         * The pixel array for the front face.
+         * This is stored in RGB, left to right, up to down format.
+         */
         front: Float32Array;
+        
+        /**
+         * The pixel array for the back face.
+         * This is stored in RGB, left to right, up to down format.
+         */
         back: Float32Array;
+        
+        /**
+         * The pixel array for the left face.
+         * This is stored in RGB, left to right, up to down format.
+         */
         left: Float32Array;
+        
+        /**
+         * The pixel array for the right face.
+         * This is stored in RGB, left to right, up to down format.
+         */
         right: Float32Array;
+        
+        /**
+         * The pixel array for the up face.
+         * This is stored in RGB, left to right, up to down format.
+         */
         up: Float32Array;
+        
+        /**
+         * The pixel array for the down face.
+         * This is stored in RGB, left to right, up to down format.
+         */
         down: Float32Array;
+        
+        /**
+         * The size of the cubemap stored.
+         * 
+         * Each faces will be size * size pixels.
+         */
         size: number;
     }
 
+    /**
+     * Helper class usefull to convert panorama picture to their cubemap representation in 6 faces.
+     */
     export class PanoramaToCubeMapTools {
 
         private static FACE_FRONT = [
@@ -48,6 +89,15 @@ module BABYLON.Internals {
             new Vector3(1.0, -1.0, -1.0)
         ];
 
+        /**
+         * Converts a panorma stored in RGB right to left up to down format into a cubemap (6 faces).
+         * 
+         * @param float32Array The source data.
+         * @param inputWidth The width of the input panorama.
+         * @param inputhHeight The height of the input panorama.
+         * @param size The willing size of the generated cubemap (each faces will be size * size pixels)
+         * @return The cubemap data 
+         */
         public static ConvertPanoramaToCubemap(float32Array: Float32Array, inputWidth: number, inputHeight: number, size: number): CubeMapInfo {
             if (!float32Array) {
                 throw "ConvertPanoramaToCubemap: input cannot be null";

src/Tools/HDR/babylon.tools.pmremgenerator.js

@@ -8,6 +8,9 @@ var BABYLON;
 (function (BABYLON) {
     var Internals;
     (function (Internals) {
+        /**
+         * The bounding box information used during the conversion process.
+         */
         var CMGBoundinBox = (function () {
             function CMGBoundinBox() {
                 this.min = new BABYLON.Vector3(0, 0, 0);
@@ -54,7 +57,30 @@ var BABYLON;
             CMGBoundinBox.MIN = Number.MIN_VALUE;
             return CMGBoundinBox;
         })();
+        /**
+         * Helper class to PreProcess a cubemap in order to generate mipmap according to the level of blur
+         * required by the glossinees of a material.
+         *
+         * This only supports the cosine drop power as well as Warp fixup generation method.
+         *
+         * This is using the process from CubeMapGen described here:
+         * https://seblagarde.wordpress.com/2012/06/10/amd-cubemapgen-for-physically-based-rendering/
+         */
         var PMREMGenerator = (function () {
+            /**
+             * Constructor of the generator.
+             *
+             * @param input The different faces data from the original cubemap in the order X+ X- Y+ Y- Z+ Z-
+             * @param inputSize The size of the cubemap faces
+             * @param outputSize The size of the output cubemap faces
+             * @param maxNumMipLevels The max number of mip map to generate (0 means all)
+             * @param numChannels The number of channels stored in the cubemap (3 for RBGE for instance)
+             * @param isFloat Specifies if the input texture is in float or int (hdr is usually in float)
+             * @param specularPower The max specular level of the desired cubemap
+             * @param cosinePowerDropPerMip The amount of drop the specular power will follow on each mip
+             * @param excludeBase Specifies wether to process the level 0 (original level) or not
+             * @param fixup Specifies wether to apply the edge fixup algorythm or not
+             */
             function PMREMGenerator(input, inputSize, outputSize, maxNumMipLevels, numChannels, isFloat, specularPower, cosinePowerDropPerMip, excludeBase, fixup) {
                 this.input = input;
                 this.inputSize = inputSize;
@@ -69,6 +95,11 @@ var BABYLON;
                 this._outputSurface = [];
                 this._numMipLevels = 0;
             }
+            /**
+             * Launches the filter process and return the result.
+             *
+             * @return the filter cubemap in the form mip0 [faces1..6] .. mipN [faces1..6]
+             */
             PMREMGenerator.prototype.filterCubeMap = function () {
                 // Init cubemap processor
                 this.init();

src/Tools/HDR/babylon.tools.pmremgenerator.ts

@@ -6,6 +6,10 @@
 //_______________________________________________________________
 
 namespace BABYLON.Internals {
+    
+    /**
+     * The bounding box information used during the conversion process.
+     */
     class CMGBoundinBox {
         private static MAX = Number.MAX_VALUE;
         private static MIN = Number.MIN_VALUE;
@@ -63,6 +67,15 @@ namespace BABYLON.Internals {
         }
     }
 
+    /**
+     * Helper class to PreProcess a cubemap in order to generate mipmap according to the level of blur
+     * required by the glossinees of a material.
+     * 
+     * This only supports the cosine drop power as well as Warp fixup generation method.
+     * 
+     * This is using the process from CubeMapGen described here:
+     * https://seblagarde.wordpress.com/2012/06/10/amd-cubemapgen-for-physically-based-rendering/
+     */
     export class PMREMGenerator {
         private static CP_MAX_MIPLEVELS = 16;
 
@@ -232,6 +245,20 @@ namespace BABYLON.Internals {
         private _filterLUT: ArrayBufferView[];
         private _numMipLevels: number = 0;
 
+        /**
+         * Constructor of the generator.
+         * 
+         * @param input The different faces data from the original cubemap in the order X+ X- Y+ Y- Z+ Z-
+         * @param inputSize The size of the cubemap faces
+         * @param outputSize The size of the output cubemap faces
+         * @param maxNumMipLevels The max number of mip map to generate (0 means all)
+         * @param numChannels The number of channels stored in the cubemap (3 for RBGE for instance)
+         * @param isFloat Specifies if the input texture is in float or int (hdr is usually in float)
+         * @param specularPower The max specular level of the desired cubemap
+         * @param cosinePowerDropPerMip The amount of drop the specular power will follow on each mip
+         * @param excludeBase Specifies wether to process the level 0 (original level) or not
+         * @param fixup Specifies wether to apply the edge fixup algorythm or not
+         */
         constructor(public input: ArrayBufferView[],
             public inputSize: number,
             public outputSize: number,
@@ -245,6 +272,11 @@ namespace BABYLON.Internals {
 
         }
 
+        /**
+         * Launches the filter process and return the result.
+         * 
+         * @return the filter cubemap in the form mip0 [faces1..6] .. mipN [faces1..6]
+         */
         public filterCubeMap(): ArrayBufferView[][] {
             // Init cubemap processor
             this.init();