@itwin/core-frontend/lib/esm/render/ParticleCollectionBuilder.d.ts

iTwin.js frontend components

/** @packageDocumentation
 * @module Rendering
 */
import { Id64String } from "@itwin/core-bentley";
import { Matrix3d, XAndY, XYAndZ } from "@itwin/core-geometry";
import { RenderTexture } from "@itwin/core-common";
import { Viewport } from "../Viewport";
import { RenderGraphic } from "./RenderGraphic";
/** Parameters used to construct a [[ParticleCollectionBuilder]].
 * @public
 * @extensions
 */
export interface ParticleCollectionBuilderParams {
    /** The image mapped to each particle quad.
     * @note The texture should be disposed of when no longer needed to free up WebGL resources. For example, if a [[Decorator]] creates the texture, the
     * texture should probably be disposed of when the decorator is removed from the [[ViewManager]].
     */
    texture: RenderTexture;
    /** The default extents of the particle quad. Individual particles may apply a scale to these extents to produce particles of varying dimensions.
     * Must be positive.
     */
    size: XAndY | number;
    /** The initial transparency of the particles as an integer in [0,255]. Defaults to zero if omitted. */
    transparency?: number;
    /** The origin of the particle collection in world coordinates. Defaults to (0, 0, 0). */
    origin?: XYAndZ;
    /** If the particles are to be pickable, a unique identifier to associate with the resultant [[RenderGraphic]].
     * @see [[IModelConnection.transientIdSequence]] to obtain an Id that is unique within an iModel.
     */
    pickableId?: Id64String;
    /** The viewport in which the particles will be drawn. */
    viewport: Viewport;
    /** If true, the finished graphic will be defined in view coordinates, for use as a decoration of type [[GraphicType.ViewBackground]] or [[GraphicType.ViewOverlay]].
     * Defaults to false, indicating the graphic will be defined in world coordinates.
     * @see [[CoordSystem.View]] and [[CoordSystem.World]].
     */
    isViewCoords?: boolean;
}
/** Describes a particle to to add to a particle collection via [[ParticleCollectionBuilder.addParticle]].
 * The x, y, and z coordinates represent the centroid of the particle quad in the collection's coordinate space.
 * @public
 * @extensions
 */
export interface ParticleProps extends XYAndZ {
    /** The size of the particle, in the collection's coordinate space. If omitted, it defaults to the size supplied to the collection by [[ParticleCollectionBuilderParams.size]].
     * Supplying a `number` produces a square; supplying a non-uniform `XAndY` produces a rectangle. Must be positive.
     */
    size?: XAndY | number;
    /** The transparency with which to draw the particle as an integer in [0,255]. If omitted, it defaults to the current value of [[ParticleCollectionBuilder.transparency]]. */
    transparency?: number;
    /** A rotation matrix to orient the particle.  If supplied then the particle will not be automatically oriented towards the camera. */
    rotationMatrix?: Matrix3d;
}
/** Interface for producing a collection of particles suitable for use in particle effects.
 * Particle effects involve animating hundreds or thousands of small particles to simulate phenomena like smoke, fire, snow, etc.
 * A particle collection represents each particle as a quad (rectangle) displaying an image. The position of each particle corresponds to the
 * centroid of its quad. The transparency and size of each particle can be specified individually. By default, the quads will always rotate to face the camera
 * such that the image is fully visible.
 *
 * Creating a particle collection using a ParticleCollectionBuilder is far more efficient (in both CPU and GPU usage) than doing so using a [[GraphicBuilder]].
 * @see interactive demonstrations of [Snow and Rain](https://www.itwinjs.org/sample-showcase/?group=Viewer+Features&sample=snow-rain-sample&imodel=Villa) and
   * [Fire and Smoke](https://www.itwinjs.org/sample-showcase/?group=Viewer+Features&sample=fire-sample&imodel=Villa) particle effects.
 * @see [SnowEffect]($frontend-devtools) for an example of a particle effect.
 * @public
 * @extensions
 */
export interface ParticleCollectionBuilder {
    /** The default transparency for newly-added particles as an integer in [0,255], used by [[ParticleCollectionBuilder.addParticle]] if [[ParticleProps.transparency]] is omitted.
     * Changing this value has no effect on the transparency of previously-added particles.
     */
    transparency: number;
    /** The default size of each particle, used by [[ParticleCollectionBuilder.addParticle]] if [[ParticleProps.size]] is omitted. */
    size: XAndY;
    /** Add a particle to the collection.
     * If `size` is omitted, `this.size` is used.
     * If `transparency` is omitted, `this.transparency` is used.
     * @throws Error if particle size is defined and not greater than zero.
     */
    addParticle: (particle: ParticleProps) => void;
    /** Produces a finished graphic from the accumulated particles.
     * It returns the finished graphic, or `undefined` if the collection contains no particles or the [[RenderSystem]] failed to produce the graphic.
     * @note After this method returns, the particle collection is empty.
     */
    finish: () => RenderGraphic | undefined;
}
/**
 * @public
 * @extensions
 */
export declare namespace ParticleCollectionBuilder {
    /** Creates a new ParticleCollectionBuilder.
     * @throws Error if size is not greater than zero.
     */
    function create(params: ParticleCollectionBuilderParams): ParticleCollectionBuilder;
}
//# sourceMappingURL=ParticleCollectionBuilder.d.ts.map