Base Teture Doc

src/Materials/Textures/babylon.baseTexture.ts

@@ -1,12 +1,27 @@
 module BABYLON {
+    /**
+     * Base class of all the textures in babylon.
+     * It groups all the common properties the materials, post process, lights... might need 
+     * in order to make a correct use of the texture.
+     */
     export class BaseTexture {
+        /**
+         * Default anisotropic filtering level for the application.
+         * It is set to 4 as a good tradeoff between perf and quality.
+         */
         public static DEFAULT_ANISOTROPIC_FILTERING_LEVEL = 4;
 
+        /**
+         * Define the name of the texture.
+         */
         @serialize()
         public name: string;
 
         @serialize("hasAlpha")
         private _hasAlpha = false;
+        /**
+         * Define if the texture is having a usable alpha value (can be use for transparency or glossiness for instance).
+         */
         public set hasAlpha(value: boolean) {
             if (this._hasAlpha === value) {
                 return;
@@ -20,12 +35,24 @@
             return this._hasAlpha;
         }
 
+        /**
+         * Defines if the alpha value should be determined via the rgb values.
+         * If true the luminance of the pixel might be used to find the corresponding alpha value.
+         */
         @serialize()
         public getAlphaFromRGB = false;
 
+        /**
+         * Intensity or strength of the texture.
+         * It is commonly used by materials to fine tune the intensity of the texture
+         */
         @serialize()
         public level = 1;
 
+        /**
+         * Define the UV chanel to use starting from 0 and defaulting to 0.
+         * This is part of the texture as textures usually maps to one uv set.
+         */
         @serialize()
         public coordinatesIndex = 0;
 
@@ -91,15 +118,31 @@
         @serialize()
         public wrapR = Texture.WRAP_ADDRESSMODE;
 
+        /**
+         * With compliant hardware and browser (supporting anisotropic filtering)
+         * this defines the level of anisotropic filtering in the texture.
+         * The higher the better but the slower. This defaults to 4 as it seems to be the best tradeoff.
+         */
         @serialize()
         public anisotropicFilteringLevel = BaseTexture.DEFAULT_ANISOTROPIC_FILTERING_LEVEL;
 
+        /**
+         * Define if the texture is a cube texture or if false a 2d texture.
+         */
         @serialize()
         public isCube = false;
 
+        /**
+         * Define if the texture is a 3d texture (webgl 2) or if false a 2d texture.
+         */
         @serialize()
         public is3D = false;
 
+        /**
+         * Define if the texture contains data in gamma space (most of the png/jpg aside bump).
+         * HDR texture are usually stored in linear space.
+         * This only impacts the PBR and Background materials
+         */
         @serialize()
         public gammaSpace = true;
 
@@ -110,12 +153,21 @@
             return this._texture != null && this._texture._isRGBD;
         }
 
+        /**
+         * Is Z inverted in the texture (useful in a cube texture).
+         */
         @serialize()
         public invertZ = false;
 
+        /**
+         * @hidden
+         */
         @serialize()
         public lodLevelInAlpha = false;
 
+        /**
+         * With prefiltered texture, defined the offset used during the prefiltering steps.
+         */
         @serialize()
         public get lodGenerationOffset(): number {
             if (this._texture) return this._texture._lodGenerationOffset;
@@ -126,6 +178,9 @@
             if (this._texture) this._texture._lodGenerationOffset = value;
         }
 
+        /**
+         * With prefiltered texture, defined the scale used during the prefiltering steps.
+         */
         @serialize()
         public get lodGenerationScale(): number {
             if (this._texture) return this._texture._lodGenerationScale;
@@ -136,9 +191,15 @@
             if (this._texture) this._texture._lodGenerationScale = value;
         }
 
+        /**
+         * Define if the texture is a render target.
+         */
         @serialize()
         public isRenderTarget = false;
 
+        /**
+         * Define the unique id of the texture in the scene.
+         */
         public get uid(): string {
             if (!this._uid) {
                 this._uid = Tools.RandomId();
@@ -146,14 +207,25 @@
             return this._uid;
         }
 
+        /**
+         * Return a string representation of the texture.
+         * @returns the texture as a string
+         */
         public toString(): string {
             return this.name;
         }
 
+        /**
+         * Get the class name of the texture.
+         * @returns "BaseTexture"
+         */
         public getClassName(): string {
             return "BaseTexture";
         }
 
+        /**
+         * Define the list of animation attached to the texture.
+         */
         public animations = new Array<Animation>();
 
         /**
@@ -162,6 +234,10 @@
         public onDisposeObservable = new Observable<BaseTexture>();
 
         private _onDisposeObserver: Nullable<Observer<BaseTexture>>;
+        /**
+         * Callback triggered when the texture has been disposed.
+         * Kept for back compatibility, you can use the onDisposeObservable instead.
+         */
         public set onDispose(callback: () => void) {
             if (this._onDisposeObserver) {
                 this.onDisposeObservable.remove(this._onDisposeObserver);
@@ -169,6 +245,9 @@
             this._onDisposeObserver = this.onDisposeObservable.add(callback);
         }
 
+        /**
+         * Define the current state of the loading sequence when in delayed load mode.
+         */
         public delayLoadState = Engine.DELAYLOADSTATE_NONE;
 
         private _scene: Nullable<Scene>;
@@ -177,10 +256,21 @@
         public _texture: Nullable<InternalTexture>;
         private _uid: Nullable<string>;
 
+        /**
+         * Define if the texture is preventinga material to render or not.
+         * If not and the texture is not ready, the engine will use a default black texture instead.
+         */
         public get isBlocking(): boolean {
             return true;
         }
 
+        /**
+         * Instantiates a new BaseTexture.
+         * Base class of all the textures in babylon.
+         * It groups all the common properties the materials, post process, lights... might need 
+         * in order to make a correct use of the texture.
+         * @param scene Define the scene the texture blongs to
+         */
         constructor(scene: Nullable<Scene>) {
             this._scene = scene || Engine.LastCreatedScene;
             if (this._scene) {
@@ -190,26 +280,50 @@
             this._uid = null;
         }
 
+        /**
+         * Get the scene the texture belongs to.
+         * @returns the scene or null if undefined
+         */
         public getScene(): Nullable<Scene> {
             return this._scene;
         }
 
+        /**
+         * Get the texture transform matrix used to offset tile the texture for istance.
+         * @returns the transformation matrix
+         */
         public getTextureMatrix(): Matrix {
             return Matrix.IdentityReadOnly;
         }
 
+        /**
+         * Get the texture reflection matrix used to rotate/transform the reflection.
+         * @returns the reflection matrix
+         */
         public getReflectionTextureMatrix(): Matrix {
             return Matrix.IdentityReadOnly;
         }
 
+        /**
+         * Get the underlying lower level texture from Babylon.
+         * @returns the insternal texture
+         */
         public getInternalTexture(): Nullable<InternalTexture> {
             return this._texture;
         }
 
+        /**
+         * Get if the texture is ready to be consumed (either it is ready or it is not blocking)
+         * @returns true if ready or not blocking
+         */
         public isReadyOrNotBlocking(): boolean {
             return !this.isBlocking || this.isReady();
         }
 
+        /**
+         * Get if the texture is ready to be used (downloaded, converted, mip mapped...).
+         * @returns true if fully ready
+         */
         public isReady(): boolean {
             if (this.delayLoadState === Engine.DELAYLOADSTATE_NOTLOADED) {
                 this.delayLoad();
@@ -224,6 +338,10 @@
         }
 
         private _cachedSize: ISize = Size.Zero();
+        /**
+         * Get the size of the texture.
+         * @returns the texture size.
+         */
         public getSize(): ISize {
             if (this._texture) {
                 if (this._texture.width) {
@@ -242,6 +360,11 @@
             return this._cachedSize;
         }
 
+        /**
+         * Get the base size of the texture.
+         * It can be different from the size if the texture has been resized for POT for instance
+         * @returns the base size
+         */
         public getBaseSize(): ISize {
             if (!this.isReady() || !this._texture)
                 return Size.Zero();
@@ -253,9 +376,16 @@
             return new Size(this._texture.baseWidth, this._texture.baseHeight);
         }
 
+        /**
+         * Scales the texture if is `canRescale()`
+         * @param ratio the resize factor we want to use to rescale
+         */
         public scale(ratio: number): void {
         }
 
+        /**
+         * Get if the texture can rescale.
+         */
         public get canRescale(): boolean {
             return false;
         }
@@ -286,13 +416,23 @@
 
         }
 
+        /**
+         * Triggers the load sequence in delayed load mode.
+         */
         public delayLoad(): void {
         }
 
+        /**
+         * Clones the texture.
+         * @returns the cloned texture
+         */
         public clone(): Nullable<BaseTexture> {
             return null;
         }
 
+        /**
+         * Get the texture underlying type (INT, FLOAT...)
+         */
         public get textureType(): number {
             if (!this._texture) {
                 return Engine.TEXTURETYPE_UNSIGNED_INT;
@@ -301,6 +441,9 @@
             return (this._texture.type !== undefined) ? this._texture.type : Engine.TEXTURETYPE_UNSIGNED_INT;
         }
 
+        /**
+         * Get the texture underlying format (RGB, RGBA...)
+         */
         public get textureFormat(): number {
             if (!this._texture) {
                 return Engine.TEXTUREFORMAT_RGBA;
@@ -349,6 +492,9 @@
             return engine._readTexturePixels(this._texture, width, height, -1, level, buffer);
         }
 
+        /**
+         * Release and destroy the underlying lower level texture aka internalTexture.
+         */
         public releaseInternalTexture(): void {
             if (this._texture) {
                 this._texture.dispose();
@@ -356,6 +502,11 @@
             }
         }
 
+        /**
+         * Get the polynomial representation of the texture data.
+         * This is mainly use as a fast way to recover IBL Diffuse irradiance data.
+         * @see https://learnopengl.com/PBR/IBL/Diffuse-irradiance
+         */
         public get sphericalPolynomial(): Nullable<SphericalPolynomial> {
             if (!this._texture || !CubeMapToSphericalPolynomialTools || !this.isReady()) {
                 return null;
@@ -375,6 +526,7 @@
             }
         }
 
+        /** @hidden */
         public get _lodTextureHigh(): Nullable<BaseTexture> {
             if (this._texture) {
                 return this._texture._lodTextureHigh;
@@ -382,6 +534,7 @@
             return null;
         }
 
+        /** @hidden */
         public get _lodTextureMid(): Nullable<BaseTexture> {
             if (this._texture) {
                 return this._texture._lodTextureMid;
@@ -389,6 +542,7 @@
             return null;
         }
 
+        /** @hidden */
         public get _lodTextureLow(): Nullable<BaseTexture> {
             if (this._texture) {
                 return this._texture._lodTextureLow;
@@ -396,6 +550,9 @@
             return null;
         }
 
+        /**
+         * Dispose the texture and release its associated resources.
+         */
         public dispose(): void {
             if (!this._scene) {
                 return;
@@ -425,6 +582,10 @@
             this.onDisposeObservable.clear();
         }
 
+        /**
+         * Serialize the texture into a JSON representation that can be parsed later on.
+         * @returns the JSON representation of the texture
+         */
         public serialize(): any {
             if (!this.name) {
                 return null;
@@ -438,6 +599,11 @@
             return serializationObject;
         }
 
+        /**
+         * Helper function to be called back once a list of texture contains only ready textures.
+         * @param textures Define the list of textures to wait for
+         * @param callback Define the callback triggered once the entire list will be ready
+         */
         public static WhenAllReady(textures: BaseTexture[], callback: () => void): void {
             let numRemaining = textures.length;
             if (numRemaining === 0) {