Babylon.js/src/Particles/babylon.IParticleSystem.ts

module BABYLON {
    /**
     * Interface representing a particle system in Babylon.js.
     * This groups the common functionalities that needs to be implemented in order to create a particle system.
     * A particle system represents a way to manage particles from their emission to their animation and rendering.
     */
    export interface IParticleSystem {
        /**
         * List of animations used by the particle system.
         */
        animations: Animation[];
        /**
         * The id of the Particle system.
         */
        id: string;
        /**
         * The name of the Particle system.
         */
        name: string;
        /**
         * The emitter represents the Mesh or position we are attaching the particle system to.
         */
        emitter: Nullable<AbstractMesh | Vector3>;
        /**
         * Gets or sets a boolean indicating if the particles must be rendered as billboard or aligned with the direction
         */
        isBillboardBased: boolean;        
        /**
         * The rendering group used by the Particle system to chose when to render.
         */
        renderingGroupId: number;
        /**
         * The layer mask we are rendering the particles through.
         */
        layerMask: number;

         /**
         * The overall motion speed (0.01 is default update speed, faster updates = faster animation)
         */
        updateSpeed: number;        

        /**
         * The amount of time the particle system is running (depends of the overall update speed).
         */
        targetStopDuration: number;        

        /**
         * The texture used to render each particle. (this can be a spritesheet)
         */
        particleTexture: Nullable<Texture>;   
        
        /**
         * Blend mode use to render the particle, it can be either ParticleSystem.BLENDMODE_ONEONE, ParticleSystem.BLENDMODE_STANDARD or ParticleSystem.BLENDMODE_ADD.
         */
        blendMode: number;   
        
        /**
         * Minimum life time of emitting particles.
         */
        minLifeTime: number;
        /**
         * Maximum life time of emitting particles.
         */
        maxLifeTime: number;    

        /**
         * Minimum Size of emitting particles.
         */
        minSize: number;
        /**
         * Maximum Size of emitting particles.
         */
        maxSize: number;     
        
        /**
         * Minimum scale of emitting particles on X axis.
         */
        minScaleX: number;
        /**
         * Maximum scale of emitting particles on X axis.
         */
        maxScaleX: number;        

        /**
         * Minimum scale of emitting particles on Y axis.
         */
        minScaleY: number;
        /**
         * Maximum scale of emitting particles on Y axis.
         */
        maxScaleY: number;             
        
        /**
         * Random color of each particle after it has been emitted, between color1 and color2 vectors.
         */
        color1: Color4;
        /**
         * Random color of each particle after it has been emitted, between color1 and color2 vectors.
         */
        color2: Color4;  
        
        /**
         * Color the particle will have at the end of its lifetime.
         */
        colorDead: Color4;
        
        /**
         * The maximum number of particles to emit per frame until we reach the activeParticleCount value
         */
        emitRate: number;
        
        /**
         * You can use gravity if you want to give an orientation to your particles.
         */
        gravity: Vector3;    

        /**
         * Minimum power of emitting particles.
         */
        minEmitPower: number;
        /**
         * Maximum power of emitting particles.
         */
        maxEmitPower: number;        
        /**
         * Minimum angular speed of emitting particles (Z-axis rotation for each particle).
         */
        minAngularSpeed: number;
        /**
         * Maximum angular speed of emitting particles (Z-axis rotation for each particle).
         */
        maxAngularSpeed: number;
        /**
         * Gets or sets the minimal initial rotation in radians.         
         */
        minInitialRotation: number;
        /**
         * Gets or sets the maximal initial rotation in radians.         
         */
        maxInitialRotation: number;         
        /**
         * The particle emitter type defines the emitter used by the particle system.
         * It can be for example box, sphere, or cone...
         */
        particleEmitterType: Nullable<IParticleEmitterType>;  
        /**
         * Defines the delay in milliseconds before starting the system (0 by default)
         */
        startDelay: number;        
        /** 
         * Gets or sets a value indicating how many cycles (or frames) must be executed before first rendering (this value has to be set before starting the system). Default is 0 
         */
        preWarmCycles: number;   
        /** 
         * Gets or sets a value indicating the time step multiplier to use in pre-warm mode (default is 1) 
         */
        preWarmStepOffset: number;     
        
        /**
         * If using a spritesheet (isAnimationSheetEnabled) defines the speed of the sprite loop (default is 1 meaning the animation will play once during the entire particle lifetime)
         */
        spriteCellChangeSpeed: number;
        /**
         * If using a spritesheet (isAnimationSheetEnabled) defines the first sprite cell to display
         */
        startSpriteCellID: number;
        /**
         * If using a spritesheet (isAnimationSheetEnabled) defines the last sprite cell to display
         */
        endSpriteCellID: number;
        /**
         * If using a spritesheet (isAnimationSheetEnabled), defines the sprite cell width to use
         */
        spriteCellWidth: number;
        /**
         * If using a spritesheet (isAnimationSheetEnabled), defines the sprite cell height to use
         */
        spriteCellHeight: number;           
        /**
         * This allows the system to random pick the start cell ID between startSpriteCellID and endSpriteCellID
         */
        spriteRandomStartCell: boolean;        
        
        /**
         * Gets or sets a boolean indicating if a spritesheet is used to animate the particles texture
         */
        isAnimationSheetEnabled: boolean;

        /** Gets or sets a Vector2 used to move the pivot (by default (0,0)) */
        translationPivot: Vector2;

        /**
         * Gets or sets a texture used to add random noise to particle positions
         */
        noiseTexture: Nullable<BaseTexture>;

        /** Gets or sets the strength to apply to the noise value (default is (10, 10, 10)) */
        noiseStrength: Vector3;        
        
        /**
         * Gets or sets the billboard mode to use when isBillboardBased = true.
         * Value can be: ParticleSystem.BILLBOARDMODE_ALL, ParticleSystem.BILLBOARDMODE_Y, ParticleSystem.BILLBOARDMODE_STRETCHED
         */
        billboardMode: number;

        /** Gets or sets a value indicating the damping to apply if the limit velocity factor is reached */
        limitVelocityDamping: number;

        /**
         * Gets the maximum number of particles active at the same time.
         * @returns The max number of active particles.
         */
        getCapacity(): number;

        /**
         * Gets if the system has been started. (Note: this will still be true after stop is called)
         * @returns True if it has been started, otherwise false.
         */
        isStarted(): boolean;

        /**
         * Animates the particle system for this frame.
         */
        animate(): void;
        /**
         * Renders the particle system in its current state.
         * @returns the current number of particles
         */
        render(): number;
        /**
         * Dispose the particle system and frees its associated resources.
         * @param disposeTexture defines if the particule texture must be disposed as well (true by default)
         */
        dispose(disposeTexture?: boolean): void;
        /**
         * Clones the particle system.
         * @param name The name of the cloned object
         * @param newEmitter The new emitter to use
         * @returns the cloned particle system
         */
        clone(name: string, newEmitter: any): Nullable<IParticleSystem>;
        /**
         * Serializes the particle system to a JSON object.
         * @returns the JSON object
         */
        serialize(): any;
        /**
         * Rebuild the particle system
         */
        rebuild(): void;

        /**
         * Starts the particle system and begins to emit
         * @param delay defines the delay in milliseconds before starting the system (0 by default)
         */
        start(delay?: number): void;

        /**
         * Stops the particle system.
         */
        stop(): void;

        /**
         * Remove all active particles
         */
        reset(): void;

        /**
         * Is this system ready to be used/rendered
         * @return true if the system is ready
         */
        isReady(): boolean; 
        /**
         * Adds a new color gradient
         * @param gradient defines the gradient to use (between 0 and 1)
         * @param color1 defines the color to affect to the specified gradient
         * @param color2 defines an additional color used to define a range ([color, color2]) with main color to pick the final color from
         * @returns the current particle system
         */
        addColorGradient(gradient: number, color1: Color4, color2?: Color4): IParticleSystem;   
        /**
         * Remove a specific color gradient
         * @param gradient defines the gradient to remove
         * @returns the current particle system
         */
        removeColorGradient(gradient: number): IParticleSystem;
        /**
         * Adds a new size gradient
         * @param gradient defines the gradient to use (between 0 and 1)
         * @param factor defines the size factor to affect to the specified gradient
         * @param factor2 defines an additional factor used to define a range ([factor, factor2]) with main value to pick the final value from
         * @returns the current particle system
         */
        addSizeGradient(gradient: number, factor: number, factor2?: number): IParticleSystem;
        /**
         * Remove a specific size gradient
         * @param gradient defines the gradient to remove
         * @returns the current particle system
         */
        removeSizeGradient(gradient: number): IParticleSystem;
        /**
         * Gets the current list of color gradients.
         * You must use addColorGradient and removeColorGradient to udpate this list
         * @returns the list of color gradients
         */
        getColorGradients(): Nullable<Array<ColorGradient>>;
        /**
         * Gets the current list of size gradients.
         * You must use addSizeGradient and removeSizeGradient to udpate this list
         * @returns the list of size gradients
         */
        getSizeGradients(): Nullable<Array<FactorGradient>>;
        /**
         * Gets the current list of angular speed gradients.
         * You must use addAngularSpeedGradient and removeAngularSpeedGradient to udpate this list
         * @returns the list of angular speed gradients
         */
        getAngularSpeedGradients(): Nullable<Array<FactorGradient>>;   
        /**
         * Adds a new angular speed gradient
         * @param gradient defines the gradient to use (between 0 and 1)
         * @param factor defines the angular speed to affect to the specified gradient
         * @param factor2 defines an additional factor used to define a range ([factor, factor2]) with main value to pick the final value from
         * @returns the current particle system
         */
        addAngularSpeedGradient(gradient: number, factor: number, factor2?: number): IParticleSystem;
        /**
         * Remove a specific angular speed gradient
         * @param gradient defines the gradient to remove
         * @returns the current particle system
         */
        removeAngularSpeedGradient(gradient: number): IParticleSystem;   
        /**
         * Gets the current list of velocity gradients.
         * You must use addVelocityGradient and removeVelocityGradient to udpate this list
         * @returns the list of velocity gradients
         */
        getVelocityGradients(): Nullable<Array<FactorGradient>>;
        /**
         * Adds a new velocity gradient
         * @param gradient defines the gradient to use (between 0 and 1)
         * @param factor defines the velocity to affect to the specified gradient         
         * @param factor2 defines an additional factor used to define a range ([factor, factor2]) with main value to pick the final value from
         * @returns the current particle system
         */
        addVelocityGradient(gradient: number, factor: number, factor2?: number): IParticleSystem;
        /**
         * Remove a specific velocity gradient
         * @param gradient defines the gradient to remove
         * @returns the current particle system
         */
        removeVelocityGradient(gradient: number): IParticleSystem;
        /**
         * Gets the current list of limit velocity gradients.
         * You must use addLimitVelocityGradient and removeLimitVelocityGradient to udpate this list
         * @returns the list of limit velocity gradients
         */
        getLimitVelocityGradients(): Nullable<Array<FactorGradient>>;
        /**
         * Adds a new limit velocity gradient
         * @param gradient defines the gradient to use (between 0 and 1)
         * @param factor defines the limit velocity to affect to the specified gradient         
         * @param factor2 defines an additional factor used to define a range ([factor, factor2]) with main value to pick the final value from
         * @returns the current particle system
         */
        addLimitVelocityGradient(gradient: number, factor: number, factor2?: number): IParticleSystem;
        /**
         * Remove a specific limit velocity gradient
         * @param gradient defines the gradient to remove
         * @returns the current particle system
         */
        removeLimitVelocityGradient(gradient: number): IParticleSystem;        
        /**
         * Adds a new drag gradient
         * @param gradient defines the gradient to use (between 0 and 1)
         * @param factor defines the drag to affect to the specified gradient         
         * @param factor2 defines an additional factor used to define a range ([factor, factor2]) with main value to pick the final value from
         * @returns the current particle system
         */
        addDragGradient(gradient: number, factor: number, factor2?: number): IParticleSystem;
        /**
         * Remove a specific drag gradient
         * @param gradient defines the gradient to remove
         * @returns the current particle system
         */
        removeDragGradient(gradient: number): IParticleSystem;   
        /**
         * Gets the current list of drag gradients.
         * You must use addDragGradient and removeDragGradient to udpate this list
         * @returns the list of drag gradients
         */
        getDragGradients(): Nullable<Array<FactorGradient>>;                    
        /**
         * Adds a new emit rate gradient (please note that this will only work if you set the targetStopDuration property)
         * @param gradient defines the gradient to use (between 0 and 1)
         * @param factor defines the emit rate to affect to the specified gradient         
         * @param factor2 defines an additional factor used to define a range ([factor, factor2]) with main value to pick the final value from
         * @returns the current particle system
         */
        addEmitRateGradient(gradient: number, factor: number, factor2?: number): IParticleSystem;
        /**
         * Remove a specific emit rate gradient
         * @param gradient defines the gradient to remove
         * @returns the current particle system
         */
        removeEmitRateGradient(gradient: number): IParticleSystem;    
        /**
         * Gets the current list of emit rate gradients.
         * You must use addEmitRateGradient and removeEmitRateGradient to udpate this list
         * @returns the list of emit rate gradients
         */
        getEmitRateGradients(): Nullable<Array<FactorGradient>>;   
        
        /**
         * Adds a new start size gradient (please note that this will only work if you set the targetStopDuration property)
         * @param gradient defines the gradient to use (between 0 and 1)
         * @param factor defines the start size to affect to the specified gradient         
         * @param factor2 defines an additional factor used to define a range ([factor, factor2]) with main value to pick the final value from
         * @returns the current particle system
         */
        addStartSizeGradient(gradient: number, factor: number, factor2?: number): IParticleSystem;
        /**
         * Remove a specific start size gradient
         * @param gradient defines the gradient to remove
         * @returns the current particle system
         */
        removeStartSizeGradient(gradient: number): IParticleSystem;    
        /**
         * Gets the current list of start size gradients.
         * You must use addStartSizeGradient and removeStartSizeGradient to udpate this list
         * @returns the list of start size gradients
         */
        getStartSizeGradients(): Nullable<Array<FactorGradient>>;  

        /**
         * Gets the current list of color gradients.
         * You must use addColorGradient and removeColorGradient to udpate this list
         * @returns the list of color gradients
         */
        getColorGradients(): Nullable<Array<ColorGradient>>;      
        
        /**
         * Adds a new ramp gradient used to remap particle colors
         * @param gradient defines the gradient to use (between 0 and 1)
         * @param color defines the color to affect to the specified gradient
         * @returns the current particle system
         */
        addRampGradient(gradient: number, color: Color3): IParticleSystem;     
        /**
         * Gets the current list of ramp gradients.
         * You must use addRampGradient and removeRampGradient to udpate this list
         * @returns the list of ramp gradients
         */
        getRampGradients(): Nullable<Array<Color3Gradient>>;
        
        /** Gets or sets a boolean indicating that ramp gradients must be used
         * @see http://doc.babylonjs.com/babylon101/particles#ramp-gradients
         */        
        useRampGradients: boolean;
        
        /**
         * Adds a new color remap gradient
         * @param gradient defines the gradient to use (between 0 and 1)
         * @param min defines the color remap minimal range        
         * @param max defines the color remap maximal range        
         * @returns the current particle system
         */
        addColorRemapGradient(gradient: number, min: number, max: number): IParticleSystem;    
        /**
         * Gets the current list of color remap gradients.
         * You must use addColorRemapGradient and removeColorRemapGradient to udpate this list
         * @returns the list of color remap gradients
         */
        getColorRemapGradients(): Nullable<Array<FactorGradient>>;
        
        /**
         * Adds a new alpha remap gradient
         * @param gradient defines the gradient to use (between 0 and 1)
         * @param min defines the alpha remap minimal range        
         * @param max defines the alpha remap maximal range        
         * @returns the current particle system
         */
        addAlphaRemapGradient(gradient: number, min: number, max: number): IParticleSystem; 
        /**
         * Gets the current list of alpha remap gradients.
         * You must use addAlphaRemapGradient and removeAlphaRemapGradient to udpate this list
         * @returns the list of alpha remap gradients
         */
        getAlphaRemapGradients(): Nullable<Array<FactorGradient>>;            

        /**
         * Creates a Point Emitter for the particle system (emits directly from the emitter position)
         * @param direction1 Particles are emitted between the direction1 and direction2 from within the box
         * @param direction2 Particles are emitted between the direction1 and direction2 from within the box
         * @returns the emitter
         */
        createPointEmitter(direction1: Vector3, direction2: Vector3): PointParticleEmitter;

        /**
         * Creates a Hemisphere Emitter for the particle system (emits along the hemisphere radius)
         * @param radius The radius of the hemisphere to emit from
         * @param radiusRange The range of the hemisphere to emit from [0-1] 0 Surface Only, 1 Entire Radius
         * @returns the emitter
         */
        createHemisphericEmitter(radius: number, radiusRange: number): HemisphericParticleEmitter;

        /**
         * Creates a Sphere Emitter for the particle system (emits along the sphere radius)
         * @param radius The radius of the sphere to emit from
         * @param radiusRange The range of the sphere to emit from [0-1] 0 Surface Only, 1 Entire Radius
         * @returns the emitter
         */
        createSphereEmitter(radius: number, radiusRange: number): SphereParticleEmitter;

        /**
         * Creates a Directed Sphere Emitter for the particle system (emits between direction1 and direction2)
         * @param radius The radius of the sphere to emit from
         * @param direction1 Particles are emitted between the direction1 and direction2 from within the sphere
         * @param direction2 Particles are emitted between the direction1 and direction2 from within the sphere
         * @returns the emitter
         */
        createDirectedSphereEmitter(radius: number, direction1:Vector3, direction2: Vector3): SphereDirectedParticleEmitter;

        /**
         * Creates a Cylinder Emitter for the particle system (emits from the cylinder to the particle position)
         * @param radius The radius of the emission cylinder
         * @param height The height of the emission cylinder
         * @param radiusRange The range of emission [0-1] 0 Surface only, 1 Entire Radius
         * @param directionRandomizer How much to randomize the particle direction [0-1]
         * @returns the emitter
         */
        createCylinderEmitter(radius: number, height: number, radiusRange: number, directionRandomizer: number): CylinderParticleEmitter;

        /**
         * Creates a Directed Cylinder Emitter for the particle system (emits between direction1 and direction2)
         * @param radius The radius of the cylinder to emit from
         * @param height The height of the emission cylinder
         * @param radiusRange the range of the emission cylinder [0-1] 0 Surface only, 1 Entire Radius (1 by default) 
         * @param direction1 Particles are emitted between the direction1 and direction2 from within the cylinder
         * @param direction2 Particles are emitted between the direction1 and direction2 from within the cylinder
         * @returns the emitter
         */
        createDirectedCylinderEmitter(radius: number, height: number, radiusRange:number , direction1:Vector3, direction2: Vector3): SphereDirectedParticleEmitter;

        /**
         * Creates a Cone Emitter for the particle system (emits from the cone to the particle position)
         * @param radius The radius of the cone to emit from
         * @param angle The base angle of the cone
         * @returns the emitter
         */
        createConeEmitter(radius: number, angle: number): ConeParticleEmitter;

        /**
         * Creates a Box Emitter for the particle system. (emits between direction1 and direction2 from withing the box defined by minEmitBox and maxEmitBox)
         * @param direction1 Particles are emitted between the direction1 and direction2 from within the box
         * @param direction2 Particles are emitted between the direction1 and direction2 from within the box
         * @param minEmitBox Particles are emitted from the box between minEmitBox and maxEmitBox
         * @param maxEmitBox  Particles are emitted from the box between minEmitBox and maxEmitBox
         * @returns the emitter
         */
        createBoxEmitter(direction1: Vector3, direction2: Vector3, minEmitBox: Vector3, maxEmitBox: Vector3): BoxParticleEmitter;   
        
        /**
         * Get hosting scene
         * @returns the scene
         */
        getScene(): Scene;
    }  
}