@pixi/core/lib/batch/BatchRenderer.d.ts

Core PixiJS

import { ViewableBuffer } from '../geometry/ViewableBuffer';
import { State } from '../state/State';
import { BaseTexture } from '../textures/BaseTexture';
import { BatchDrawCall } from './BatchDrawCall';
import { BatchGeometry } from './BatchGeometry';
import { BatchShaderGenerator } from './BatchShaderGenerator';
import { BatchTextureArray } from './BatchTextureArray';
import { ObjectRenderer } from './ObjectRenderer';
import type { BLEND_MODES } from '@pixi/constants';
import type { ExtensionMetadata } from '@pixi/extensions';
import type { Renderer } from '../Renderer';
import type { Shader } from '../shader/Shader';
import type { Texture } from '../textures/Texture';
/**
 * Interface for elements like Sprite, Mesh etc. for batching.
 * @memberof PIXI
 */
export interface IBatchableElement {
    _texture: Texture;
    vertexData: Float32Array;
    indices: Uint16Array | Uint32Array | Array<number>;
    uvs: Float32Array;
    worldAlpha: number;
    _tintRGB: number;
    blendMode: BLEND_MODES;
}
/**
 * Renderer dedicated to drawing and batching sprites.
 *
 * This is the default batch renderer. It buffers objects
 * with texture-based geometries and renders them in
 * batches. It uploads multiple textures to the GPU to
 * reduce to the number of draw calls.
 * @memberof PIXI
 */
export declare class BatchRenderer extends ObjectRenderer {
    /**
     * The maximum textures that this device supports.
     * @static
     * @default 32
     */
    static get defaultMaxTextures(): number;
    static set defaultMaxTextures(value: number);
    /** @ignore */
    private static _defaultMaxTextures;
    /**
     * The default sprite batch size.
     *
     * The default aims to balance desktop and mobile devices.
     * @static
     */
    static defaultBatchSize: number;
    /**
     * Can we upload the same buffer in a single frame?
     * @static
     */
    static get canUploadSameBuffer(): boolean;
    static set canUploadSameBuffer(value: boolean);
    /** @ignore */
    private static _canUploadSameBuffer;
    /** @ignore */
    static extension: ExtensionMetadata;
    /** The WebGL state in which this renderer will work. */
    readonly state: State;
    /**
     * The number of bufferable objects before a flush
     * occurs automatically.
     * @default PIXI.BatchRenderer.defaultBatchSize * 4
     */
    size: number;
    /**
     * Maximum number of textures that can be uploaded to
     * the GPU under the current context. It is initialized
     * properly in `this.contextChange`.
     * @see PIXI.BatchRenderer#contextChange
     * @readonly
     */
    maxTextures: number;
    /**
     * This is used to generate a shader that can
     * color each vertex based on a `aTextureId`
     * attribute that points to an texture in `uSampler`.
     *
     * This enables the objects with different textures
     * to be drawn in the same draw call.
     *
     * You can customize your shader by creating your
     * custom shader generator.
     */
    protected shaderGenerator: BatchShaderGenerator;
    /**
     * The class that represents the geometry of objects
     * that are going to be batched with this.
     * @member {object}
     * @default PIXI.BatchGeometry
     */
    protected geometryClass: typeof BatchGeometry;
    /**
     * Size of data being buffered per vertex in the
     * attribute buffers (in floats). By default, the
     * batch-renderer plugin uses 6:
     *
     * | aVertexPosition | 2 |
     * |-----------------|---|
     * | aTextureCoords  | 2 |
     * | aColor          | 1 |
     * | aTextureId      | 1 |
     * @default 6
     */
    protected vertexSize: number;
    /** Total count of all vertices used by the currently buffered objects. */
    protected _vertexCount: number;
    /** Total count of all indices used by the currently buffered objects. */
    protected _indexCount: number;
    /**
     * Buffer of objects that are yet to be rendered.
     * @member {PIXI.DisplayObject[]}
     */
    protected _bufferedElements: Array<IBatchableElement>;
    /**
     * Data for texture batch builder, helps to save a bit of CPU on a pass.
     * @member {PIXI.BaseTexture[]}
     */
    protected _bufferedTextures: Array<BaseTexture>;
    /** Number of elements that are buffered and are waiting to be flushed. */
    protected _bufferSize: number;
    /**
     * This shader is generated by `this.shaderGenerator`.
     *
     * It is generated specifically to handle the required
     * number of textures being batched together.
     */
    protected _shader: Shader;
    /**
     * A flush may occur multiple times in a single
     * frame. On iOS devices or when
     * `BatchRenderer.canUploadSameBuffer` is false, the
     * batch renderer does not upload data to the same
     * `WebGLBuffer` for performance reasons.
     *
     * This is the index into `packedGeometries` that points to
     * geometry holding the most recent buffers.
     */
    protected _flushId: number;
    /**
     * Pool of `ViewableBuffer` objects that are sorted in
     * order of increasing size. The flush method uses
     * the buffer with the least size above the amount
     * it requires. These are used for passing attributes.
     *
     * The first buffer has a size of 8; each subsequent
     * buffer has double capacity of its previous.
     * @member {PIXI.ViewableBuffer[]}
     * @see PIXI.BatchRenderer#getAttributeBuffer
     */
    protected _aBuffers: Array<ViewableBuffer>;
    /**
     * Pool of `Uint16Array` objects that are sorted in
     * order of increasing size. The flush method uses
     * the buffer with the least size above the amount
     * it requires. These are used for passing indices.
     *
     * The first buffer has a size of 12; each subsequent
     * buffer has double capacity of its previous.
     * @member {Uint16Array[]}
     * @see PIXI.BatchRenderer#getIndexBuffer
     */
    protected _iBuffers: Array<Uint16Array>;
    protected _dcIndex: number;
    protected _aIndex: number;
    protected _iIndex: number;
    protected _attributeBuffer: ViewableBuffer;
    protected _indexBuffer: Uint16Array;
    protected _tempBoundTextures: BaseTexture[];
    /**
     * Pool of `this.geometryClass` geometry objects
     * that store buffers. They are used to pass data
     * to the shader on each draw call.
     *
     * These are never re-allocated again, unless a
     * context change occurs; however, the pool may
     * be expanded if required.
     * @member {PIXI.Geometry[]}
     * @see PIXI.BatchRenderer.contextChange
     */
    private _packedGeometries;
    /**
     * Size of `this._packedGeometries`. It can be expanded
     * if more than `this._packedGeometryPoolSize` flushes
     * occur in a single frame.
     */
    private _packedGeometryPoolSize;
    /**
     * This will hook onto the renderer's `contextChange`
     * and `prerender` signals.
     * @param {PIXI.Renderer} renderer - The renderer this works for.
     */
    constructor(renderer: Renderer);
    /**
     * @see PIXI.BatchRenderer#maxTextures
     * @deprecated since 7.1.0
     * @readonly
     */
    get MAX_TEXTURES(): number;
    /**
     * The default vertex shader source
     * @readonly
     */
    static get defaultVertexSrc(): string;
    /**
     * The default fragment shader source
     * @readonly
     */
    static get defaultFragmentTemplate(): string;
    /**
     * Set the shader generator.
     * @param {object} [options]
     * @param {string} [options.vertex=PIXI.BatchRenderer.defaultVertexSrc] - Vertex shader source
     * @param {string} [options.fragment=PIXI.BatchRenderer.defaultFragmentTemplate] - Fragment shader template
     */
    setShaderGenerator({ vertex, fragment }?: {
        vertex?: string;
        fragment?: string;
    }): void;
    /**
     * Handles the `contextChange` signal.
     *
     * It calculates `this.maxTextures` and allocating the packed-geometry object pool.
     */
    contextChange(): void;
    /** Makes sure that static and dynamic flush pooled objects have correct dimensions. */
    initFlushBuffers(): void;
    /** Handles the `prerender` signal. It ensures that flushes start from the first geometry object again. */
    onPrerender(): void;
    /**
     * Buffers the "batchable" object. It need not be rendered immediately.
     * @param {PIXI.DisplayObject} element - the element to render when
     *    using this renderer
     */
    render(element: IBatchableElement): void;
    buildTexturesAndDrawCalls(): void;
    /**
     * Populating drawcalls for rendering
     * @param texArray
     * @param start
     * @param finish
     */
    buildDrawCalls(texArray: BatchTextureArray, start: number, finish: number): void;
    /**
     * Bind textures for current rendering
     * @param texArray
     */
    bindAndClearTexArray(texArray: BatchTextureArray): void;
    updateGeometry(): void;
    drawBatches(): void;
    /** Renders the content _now_ and empties the current batch. */
    flush(): void;
    /** Starts a new sprite batch. */
    start(): void;
    /** Stops and flushes the current batch. */
    stop(): void;
    /** Destroys this `BatchRenderer`. It cannot be used again. */
    destroy(): void;
    /**
     * Fetches an attribute buffer from `this._aBuffers` that can hold atleast `size` floats.
     * @param size - minimum capacity required
     * @returns - buffer than can hold atleast `size` floats
     */
    getAttributeBuffer(size: number): ViewableBuffer;
    /**
     * Fetches an index buffer from `this._iBuffers` that can
     * have at least `size` capacity.
     * @param size - minimum required capacity
     * @returns - buffer that can fit `size` indices.
     */
    getIndexBuffer(size: number): Uint16Array;
    /**
     * Takes the four batching parameters of `element`, interleaves
     * and pushes them into the batching attribute/index buffers given.
     *
     * It uses these properties: `vertexData` `uvs`, `textureId` and
     * `indicies`. It also uses the "tint" of the base-texture, if
     * present.
     * @param {PIXI.DisplayObject} element - element being rendered
     * @param attributeBuffer - attribute buffer.
     * @param indexBuffer - index buffer
     * @param aIndex - number of floats already in the attribute buffer
     * @param iIndex - number of indices already in `indexBuffer`
     */
    packInterleavedGeometry(element: IBatchableElement, attributeBuffer: ViewableBuffer, indexBuffer: Uint16Array, aIndex: number, iIndex: number): void;
    /**
     * Pool of `BatchDrawCall` objects that `flush` used
     * to create "batches" of the objects being rendered.
     *
     * These are never re-allocated again.
     * Shared between all batch renderers because it can be only one "flush" working at the moment.
     * @member {PIXI.BatchDrawCall[]}
     */
    static _drawCallPool: Array<BatchDrawCall>;
    /**
     * Pool of `BatchDrawCall` objects that `flush` used
     * to create "batches" of the objects being rendered.
     *
     * These are never re-allocated again.
     * Shared between all batch renderers because it can be only one "flush" working at the moment.
     * @member {PIXI.BatchTextureArray[]}
     */
    static _textureArrayPool: Array<BatchTextureArray>;
}