Merge pull request #5213 from sebavan/master

More Doc around textures

src/Materials/Textures/babylon.internalTexture.ts

@@ -87,11 +87,11 @@ module BABYLON {
          */
         public samples: number;
         /**
-         * Gets the type of the texture
+         * Gets the type of the texture (int, float...)
          */
         public type: number;
         /**
-         * Gets the format of the texture 
+         * Gets the format of the texture (RGB, RGBA...)
          */
         public format: number;
         /**

src/Materials/Textures/babylon.mirrorTexture.ts

@@ -1,18 +1,22 @@
 module BABYLON {
+    /**
+     * Mirror texture can be used to simulate the view from a mirror in a scene.
+     * It will dynamically be rendered every frame to adapt to the camera point of view.
+     * You can then easily use it as a reflectionTexture on a flat surface.
+     * In case the surface is not a plane, please consider relying on reflection probes.
+     * @see https://doc.babylonjs.com/how_to/reflect#mirrors
+     */
     export class MirrorTexture extends RenderTargetTexture {
+        /**
+         * Define the reflection plane we want to use. The mirrorPlane is usually set to the constructed reflector. 
+         * It is possible to directly set the mirrorPlane by directly using a BABYLON.Plane(a, b, c, d) where a, b and c give the plane normal vector (a, b, c) and d is a scalar displacement from the mirrorPlane to the origin. However in all but the very simplest of situations it is more straight forward to set it to the reflector as stated in the doc.
+         * @see https://doc.babylonjs.com/how_to/reflect#mirrors
+         */
         public mirrorPlane = new Plane(0, 1, 0, 1);
 
-        private _transformMatrix = Matrix.Zero();
-        private _mirrorMatrix = Matrix.Zero();
-        private _savedViewMatrix: Matrix;
-
-        private _blurX: Nullable<BlurPostProcess>;
-        private _blurY: Nullable<BlurPostProcess>;
-        private _adaptiveBlurKernel = 0;
-        private _blurKernelX = 0;
-        private _blurKernelY = 0;
-        private _blurRatio = 1.0;
-
+        /**
+         * Define the blur ratio used to blur the reflection if needed.
+         */
         public set blurRatio(value: number) {
             if (this._blurRatio === value) {
                 return;
@@ -26,16 +30,28 @@
             return this._blurRatio;
         }
 
+        /**
+         * Define the adaptive blur kernel used to blur the reflection if needed.
+         * This will autocompute the closest best match for the `blurKernel`
+         */
         public set adaptiveBlurKernel(value: number) {
             this._adaptiveBlurKernel = value;
             this._autoComputeBlurKernel();
         }
 
+        /**
+         * Define the blur kernel used to blur the reflection if needed.
+         * Please consider using `adaptiveBlurKernel` as it could find the closest best value for you.
+         */
         public set blurKernel(value: number) {
             this.blurKernelX = value;
             this.blurKernelY = value;
         }
 
+        /**
+         * Define the blur kernel on the X Axis used to blur the reflection if needed.
+         * Please consider using `adaptiveBlurKernel` as it could find the closest best value for you.
+         */
         public set blurKernelX(value: number) {
             if (this._blurKernelX === value) {
                 return;
@@ -49,6 +65,10 @@
             return this._blurKernelX;
         }
 
+        /**
+         * Define the blur kernel on the Y Axis used to blur the reflection if needed.
+         * Please consider using `adaptiveBlurKernel` as it could find the closest best value for you.
+         */
         public set blurKernelY(value: number) {
             if (this._blurKernelY === value) {
                 return;
@@ -83,11 +103,39 @@
                 this._autoComputeBlurKernel();
             }
         }
+
         private _updateGammaSpace(){
             this.gammaSpace = !this.scene.imageProcessingConfiguration.isEnabled || !this.scene.imageProcessingConfiguration.applyByPostProcess;
         }
 
         private _imageProcessingConfigChangeObserver:Nullable<Observer<ImageProcessingConfiguration>>;
+
+        private _transformMatrix = Matrix.Zero();
+        private _mirrorMatrix = Matrix.Zero();
+        private _savedViewMatrix: Matrix;
+
+        private _blurX: Nullable<BlurPostProcess>;
+        private _blurY: Nullable<BlurPostProcess>;
+        private _adaptiveBlurKernel = 0;
+        private _blurKernelX = 0;
+        private _blurKernelY = 0;
+        private _blurRatio = 1.0;
+
+        /**
+         * Instantiates a Mirror Texture.
+         * Mirror texture can be used to simulate the view from a mirror in a scene.
+         * It will dynamically be rendered every frame to adapt to the camera point of view.
+         * You can then easily use it as a reflectionTexture on a flat surface.
+         * In case the surface is not a plane, please consider relying on reflection probes.
+         * @see https://doc.babylonjs.com/how_to/reflect#mirrors
+         * @param name 
+         * @param size 
+         * @param scene 
+         * @param generateMipMaps 
+         * @param type 
+         * @param samplingMode 
+         * @param generateDepthBuffer 
+         */
         constructor(name: string, size: number | { width: number, height: number } | { ratio: number }, private scene: Scene, generateMipMaps?: boolean, type: number = Engine.TEXTURETYPE_UNSIGNED_INT, samplingMode = Texture.BILINEAR_SAMPLINGMODE, generateDepthBuffer = true) {
             super(name, size, scene, generateMipMaps, true, type, false, samplingMode, generateDepthBuffer);
 
@@ -160,6 +208,10 @@
             }
         }
 
+        /**
+         * Clone the mirror texture.
+         * @returns the cloned texture
+         */
         public clone(): MirrorTexture {
             let scene = this.getScene();
 
@@ -191,6 +243,10 @@
             return newTexture;
         }
 
+        /**
+         * Serialize the texture to a JSON representation you could use in Parse later on
+         * @returns the serialized JSON representation
+         */
         public serialize(): any {
             if (!this.name) {
                 return null;
@@ -203,6 +259,9 @@
             return serializationObject;
         }
 
+        /**
+         * Dispose the texture and release its associated resources.
+         */
         public dispose(){
             super.dispose();
             this.scene.imageProcessingConfiguration.onUpdateParameters.remove(this._imageProcessingConfigChangeObserver);

src/Materials/Textures/babylon.multiRenderTarget.ts

@@ -1,34 +1,83 @@
 module BABYLON {
+    /**
+     * Creation options of the multi render target texture.
+     */
     export interface IMultiRenderTargetOptions {
+        /**
+         * Define if the texture needs to create mip maps after render.
+         */
         generateMipMaps?: boolean,
+        /**
+         * Define the types of all the draw buffers we want to create
+         */
         types?: number[],
+        /**
+         * Define the sampling modes of all the draw buffers we want to create
+         */
         samplingModes?: number[],
+        /**
+         * Define if a depth buffer is required
+         */
         generateDepthBuffer?: boolean,
+        /**
+         * Define if a stencil buffer is required
+         */
         generateStencilBuffer?: boolean,
+        /**
+         * Define if a depth texture is required instead of a depth buffer
+         */
         generateDepthTexture?: boolean,
+        /**
+         * Define the number of desired draw buffers
+         */
         textureCount?: number,
+        /**
+         * Define if aspect ratio should be adapted to the texture or stay the scene one
+         */
         doNotChangeAspectRatio?: boolean,
+        /**
+         * Define the default type of the buffers we are creating
+         */
         defaultType?: number
     };
+
+    /**
+     * A multi render target, like a render target provides the ability to render to a texture.
+     * Unlike the render target, it can render to several draw buffers in one draw.
+     * This is specially interesting in deferred rendering or for any effects requiring more than
+     * just one color from a single pass.
+     */
     export class MultiRenderTarget extends RenderTargetTexture {
 
         private _internalTextures: InternalTexture[];
         private _textures: Texture[];
+        private _multiRenderTargetOptions: IMultiRenderTargetOptions;
 
+        /**
+         * Get if draw buffers are currently supported by the used hardware and browser.
+         */
         public get isSupported(): boolean {
             return this._engine.webGLVersion > 1 || this._engine.getCaps().drawBuffersExtension;
         }
 
-        private _multiRenderTargetOptions: IMultiRenderTargetOptions;
-
+        /**
+         * Get the list of textures generated by the multi render target.
+         */
         public get textures(): Texture[] {
             return this._textures;
         }
 
+        /**
+         * Get the depth texture generated by the multi render target if options.generateDepthTexture has been set
+         */
         public get depthTexture(): Texture {
             return this._textures[this._textures.length - 1];
         }
 
+        /**
+         * Set the wrapping mode on U of all the textures we are rendering to.
+         * Can be any of the Texture. (CLAMP_ADDRESSMODE, MIRROR_ADDRESSMODE or WRAP_ADDRESSMODE)
+         */
         public set wrapU(wrap: number) {
             if (this._textures) {
                 for (var i = 0; i < this._textures.length; i++) {
@@ -37,6 +86,10 @@ module BABYLON {
             }
         }
 
+        /**
+         * Set the wrapping mode on V of all the textures we are rendering to.
+         * Can be any of the Texture. (CLAMP_ADDRESSMODE, MIRROR_ADDRESSMODE or WRAP_ADDRESSMODE)
+         */
         public set wrapV(wrap: number) {
             if (this._textures) {
                 for (var i = 0; i < this._textures.length; i++) {
@@ -45,6 +98,18 @@ module BABYLON {
             }
         }
 
+        /**
+         * Instantiate a new multi render target texture.
+         * A multi render target, like a render target provides the ability to render to a texture.
+         * Unlike the render target, it can render to several draw buffers in one draw.
+         * This is specially interesting in deferred rendering or for any effects requiring more than
+         * just one color from a single pass.
+         * @param name Define the name of the texture
+         * @param size Define the size of the buffers to render to
+         * @param count Define the number of target we are rendering into
+         * @param scene Define the scene the texture belongs to
+         * @param options Define the options used to create the multi render target
+         */
         constructor(name: string, size: any, count: number, scene: Scene, options?: IMultiRenderTargetOptions) {
             var generateMipMaps = options && options.generateMipMaps ? options.generateMipMaps : false;
             var generateDepthTexture = options && options.generateDepthTexture ? options.generateDepthTexture : false;
@@ -124,6 +189,9 @@ module BABYLON {
             this._texture = this._internalTextures[0];
         }
 
+        /**
+         * Define the number of samples used if MSAA is enabled.
+         */
         public get samples(): number {
             return this._samples;
         }
@@ -136,6 +204,11 @@ module BABYLON {
             this._samples = this._engine.updateMultipleRenderTargetTextureSampleCount(this._internalTextures, value);
         }
 
+        /**
+         * Resize all the textures in the multi render target.
+         * Be carrefull as it will recreate all the data in the new texture.
+         * @param size Define the new size
+         */
         public resize(size: any) {
             this.releaseInternalTextures();
             this._internalTextures = this._engine.createMultipleRenderTarget(size, this._multiRenderTargetOptions);
@@ -148,12 +221,18 @@ module BABYLON {
             });
         }
 
+        /**
+         * Dispose the render targets and their associated resources
+         */
         public dispose(): void {
             this.releaseInternalTextures();
 
             super.dispose();
         }
 
+        /**
+         * Release all the underlying texture used as draw buffers.
+         */
         public releaseInternalTextures(): void {
             if (!this._internalTextures) {
                 return;

src/Materials/Textures/babylon.rawTexture.ts

@@ -1,6 +1,27 @@
 module BABYLON {
+    /**
+     * Raw texture can help creating a texture directly from an array of data.
+     * This can be super useful if you either get the data from an uncompressed source or
+     * if you wish to create your texture pixel by pixel.
+     */
     export class RawTexture extends Texture {
         private _engine: Engine;
+
+        /**
+         * Instantiates a new RawTexture.
+         * Raw texture can help creating a texture directly from an array of data.
+         * This can be super useful if you either get the data from an uncompressed source or
+         * if you wish to create your texture pixel by pixel.
+         * @param data define the array of data to use to create the texture
+         * @param width define the width of the texture
+         * @param height define the height of the texture
+         * @param format define the format of the data (RGB, RGBA... Engine.TEXTUREFORMAT_xxx)
+         * @param scene  define the scene the texture belongs to
+         * @param generateMipMaps define whether mip maps should be generated or not
+         * @param invertY define if the data should be flipped on Y when uploaded to the GPU
+         * @param samplingMode define the texture sampling mode (Texture.xxx_SAMPLINGMODE)
+         * @param type define the format of the data (int, float... Engine.TEXTURETYPE_xxx)
+         */
         constructor(data: ArrayBufferView, width: number, height: number, public format: number, scene: Scene, generateMipMaps: boolean = true, invertY: boolean = false, samplingMode: number = Texture.TRILINEAR_SAMPLINGMODE, type: number = Engine.TEXTURETYPE_UNSIGNED_INT) {
             super(null, scene, !generateMipMaps, invertY);
             this._engine = scene.getEngine();
@@ -10,33 +31,102 @@
             this.wrapV = Texture.CLAMP_ADDRESSMODE;
         }
 
+        /**
+         * Updates the texture underlying data.
+         * @param data Define the new data of the texture
+         */
         public update(data: ArrayBufferView): void {
             this._engine.updateRawTexture(this._texture, data, this._texture!.format, this._texture!.invertY, undefined, this._texture!.type);
         }
 
-        // Statics
+        /**
+         * Creates a luminance texture from some data.
+         * @param data Define the texture data
+         * @param width Define the width of the texture
+         * @param height Define the height of the texture
+         * @param scene Define the scene the texture belongs to
+         * @param generateMipMaps Define whether or not to create mip maps for the texture
+         * @param invertY define if the data should be flipped on Y when uploaded to the GPU
+         * @param samplingMode define the texture sampling mode (Texture.xxx_SAMPLINGMODE)
+         * @returns the luminance texture
+         */
         public static CreateLuminanceTexture(data: ArrayBufferView, width: number, height: number, scene: Scene, generateMipMaps: boolean = true, invertY: boolean = false, samplingMode: number = Texture.TRILINEAR_SAMPLINGMODE): RawTexture {
             return new RawTexture(data, width, height, Engine.TEXTUREFORMAT_LUMINANCE, scene, generateMipMaps, invertY, samplingMode);
         }
 
+        /**
+         * Creates a luminance alpha texture from some data.
+         * @param data Define the texture data
+         * @param width Define the width of the texture
+         * @param height Define the height of the texture
+         * @param scene Define the scene the texture belongs to
+         * @param generateMipMaps Define whether or not to create mip maps for the texture
+         * @param invertY define if the data should be flipped on Y when uploaded to the GPU
+         * @param samplingMode define the texture sampling mode (Texture.xxx_SAMPLINGMODE)
+         * @returns the luminance alpha texture
+         */
         public static CreateLuminanceAlphaTexture(data: ArrayBufferView, width: number, height: number, scene: Scene, generateMipMaps: boolean = true, invertY: boolean = false, samplingMode: number = Texture.TRILINEAR_SAMPLINGMODE): RawTexture {
             return new RawTexture(data, width, height, Engine.TEXTUREFORMAT_LUMINANCE_ALPHA, scene, generateMipMaps, invertY, samplingMode);
         }
 
+        /**
+         * Creates an alpha texture from some data.
+         * @param data Define the texture data
+         * @param width Define the width of the texture
+         * @param height Define the height of the texture
+         * @param scene Define the scene the texture belongs to
+         * @param generateMipMaps Define whether or not to create mip maps for the texture
+         * @param invertY define if the data should be flipped on Y when uploaded to the GPU
+         * @param samplingMode define the texture sampling mode (Texture.xxx_SAMPLINGMODE)
+         * @returns the alpha texture
+         */
         public static CreateAlphaTexture(data: ArrayBufferView, width: number, height: number, scene: Scene, generateMipMaps: boolean = true, invertY: boolean = false, samplingMode: number = Texture.TRILINEAR_SAMPLINGMODE): RawTexture {
             return new RawTexture(data, width, height, Engine.TEXTUREFORMAT_ALPHA, scene, generateMipMaps, invertY, samplingMode);
         }
 
+        /**
+         * Creates a RGB texture from some data.
+         * @param data Define the texture data
+         * @param width Define the width of the texture
+         * @param height Define the height of the texture
+         * @param scene Define the scene the texture belongs to
+         * @param generateMipMaps Define whether or not to create mip maps for the texture
+         * @param invertY define if the data should be flipped on Y when uploaded to the GPU
+         * @param samplingMode define the texture sampling mode (Texture.xxx_SAMPLINGMODE)
+         * @returns the RGB alpha texture
+         */
         public static CreateRGBTexture(data: ArrayBufferView, width: number, height: number, scene: Scene, generateMipMaps: boolean = true, invertY: boolean = false, samplingMode: number = Texture.TRILINEAR_SAMPLINGMODE, type: number = Engine.TEXTURETYPE_UNSIGNED_INT): RawTexture {
             return new RawTexture(data, width, height, Engine.TEXTUREFORMAT_RGB, scene, generateMipMaps, invertY, samplingMode, type);
         }
 
+        /**
+         * Creates a RGBA texture from some data.
+         * @param data Define the texture data
+         * @param width Define the width of the texture
+         * @param height Define the height of the texture
+         * @param scene Define the scene the texture belongs to
+         * @param generateMipMaps Define whether or not to create mip maps for the texture
+         * @param invertY define if the data should be flipped on Y when uploaded to the GPU
+         * @param samplingMode define the texture sampling mode (Texture.xxx_SAMPLINGMODE)
+         * @returns the RGBA texture
+         */
         public static CreateRGBATexture(data: ArrayBufferView, width: number, height: number, scene: Scene, generateMipMaps: boolean = true, invertY: boolean = false, samplingMode: number = Texture.TRILINEAR_SAMPLINGMODE, type: number = Engine.TEXTURETYPE_UNSIGNED_INT): RawTexture {
             return new RawTexture(data, width, height, Engine.TEXTUREFORMAT_RGBA, scene, generateMipMaps, invertY, samplingMode, type);
         }
 
+        /**
+         * Creates a R texture from some data.
+         * @param data Define the texture data
+         * @param width Define the width of the texture
+         * @param height Define the height of the texture
+         * @param scene Define the scene the texture belongs to
+         * @param generateMipMaps Define whether or not to create mip maps for the texture
+         * @param invertY define if the data should be flipped on Y when uploaded to the GPU
+         * @param samplingMode define the texture sampling mode (Texture.xxx_SAMPLINGMODE)
+         * @returns the R texture
+         */
         public static CreateRTexture(data: ArrayBufferView, width: number, height: number, scene: Scene, generateMipMaps: boolean = true, invertY: boolean = false, samplingMode: number = Texture.TRILINEAR_SAMPLINGMODE, type: number = Engine.TEXTURETYPE_FLOAT): RawTexture {
             return new RawTexture(data, width, height, Engine.TEXTUREFORMAT_R, scene, generateMipMaps, invertY, samplingMode, type);
-        }        
+        }
     }
 }