@masatomakino/threejs-billboard
    Preparing search index...

    Class SharedStageTexture

    Manages a single shared Canvas and Texture for use with SharedStageBillboard and SharedStagePlaneMesh classes.

    This class extends Three.js Texture and contains a PixiJS Application instance, using its Canvas as the texture source. Multiple SharedStage class instances can reference this single texture and display different content by adjusting their UV coordinates.

    SharedStageTexture provides a shared texture system where:

    • Single Canvas: One PixiJS canvas serves multiple billboard instances
    • UV Mapping: Each billboard displays a specific region via UV coordinates
    • Manual Updates: Texture updates must be explicitly triggered
    • Draw Call Reduction: Significantly reduces draw calls compared to individual textures

    SharedStageTexture Approach:

    • Single shared Canvas and Texture across multiple instances
    • Excellent for reducing draw calls with fixed number of billboards
    • Limited by total texture size constraints
    • Requires UV coordinate management

    MultiView Approach:

    • Each instance has independent Canvas using PixiJS v8 multiView
    • Superior for partial updates and flexible billboard count
    • Higher draw call count but more flexible

    Advantages:

    • Reduced draw calls when using multiple billboards
    • Shared material instances possible
    • Efficient for static or infrequently updated content

    Limitations:

    • Texture size constraints limit maximum billboard count
    • Full texture re-render required for any content change
    • More complex UV coordinate management

    Important: Textures are not automatically updated by default. Billboard or PlaneMesh instances using this texture must call setNeedUpdate() to trigger texture updates.

    // Create and initialize shared texture
    const sharedTexture = new SharedStageTexture();
    await sharedTexture.init(1024, 1024);

    // Create shared material
    const sharedMaterial = new SpriteMaterial({
      map: sharedTexture,
      transparent: true
    });

    // Create billboards that share the texture
    const billboard1 = new SharedStageBillboard(
      sharedMaterial,
      { x: 0, y: 0, width: 256, height: 256 }
    );
    const billboard2 = new SharedStageBillboard(
      sharedMaterial,
      { x: 256, y: 0, width: 256, height: 256 }
    );

    // Add PixiJS content to shared stage
    const sprite = new PIXI.Sprite(texture);
    sharedTexture.stage.addChild(sprite);

    // Trigger texture update
    sharedTexture.setNeedUpdate();

    Hierarchy

    • Texture
      • SharedStageTexture
    Index

    Constructors

    constructor

    Properties

    anisotropy app center channel colorSpace flipY format generateMipmaps id internalFormat isArrayTexture isRenderTargetTexture isTexture magFilter mapping matrix matrixAutoUpdate minFilter mipmaps name offset onUpdate pmremVersion premultiplyAlpha renderTarget repeat rotation source type unpackAlignment updateRanges userData uuid version wrapS wrapT DEFAULT_ANISOTROPY DEFAULT_IMAGE DEFAULT_MAPPING

    Accessors

    depth height image needsPMREMUpdate needsUpdate stage width

    Methods

    addEventListener addUpdateRange calculateUV calcurateUV clearUpdateRanges clone copy dispatchEvent dispose hasEventListener init removeEventListener setNeedUpdate setValues toJSON transformUv updateMatrix

    Constructors

    • Creates a new SharedStageTexture instance.

      Initializes the Three.js Texture and creates a PixiJS Application instance. The Application must be initialized separately using the init() method.

      Returns SharedStageTexture

      const sharedTexture = new SharedStageTexture();
      await sharedTexture.init(1024, 1024);

    Properties

    anisotropy: number

    The number of samples taken along the axis through the pixel that has the highest density of texels.

    A higher value gives a less blurry result than a basic mipmap, at the cost of more Texture samples being used.

    value of THREE.Texture.DEFAULT_ANISOTROPY. That is normally 1.

    app: Application

    The PixiJS Application instance that manages the shared canvas. Provides access to the renderer, stage, and other PixiJS functionality.

    center: Vector2

    The point around which rotation occurs.

    A value of (0.5, 0.5) corresponds to the center of the texture.

    new THREE.Vector2( 0, 0 ), lower left.

    channel: number

    Lets you select the uv attribute to map the texture to. 0 for uv, 1 for uv1, 2 for uv2 and 3 for uv3.

    colorSpace: string

    The Textures | {@link Texture constants} page for details of other color spaces.

    Textures containing color data should be annotated with SRGBColorSpace THREE.SRGBColorSpace or LinearSRGBColorSpace THREE.LinearSRGBColorSpace.

    THREE.NoColorSpace

    flipY: boolean

    If set to true, the texture is flipped along the vertical axis when uploaded to the GPU.

    Note that this property has no effect for ImageBitmap. You need to configure on bitmap creation instead. See THREE.ImageBitmapLoader | ImageBitmapLoader.

    THREE.ImageBitmapLoader | ImageBitmapLoader.

    true

    format: AnyPixelFormat

    These define how elements of a 2D texture, or texels, are read by shaders.

    All Texture types except THREE.DepthTexture and THREE.CompressedPixelFormat expect the values be THREE.PixelFormat

    THREE.RGBAFormat.

    generateMipmaps: boolean

    Whether to generate mipmaps, (if possible) for a texture.

    Set this to false if you are creating mipmaps manually.

    true
    id: number

    Unique number for this Texture instance.

    Note that ids are assigned in chronological order: 1, 2, 3, ..., incrementing by one for each new object.

    internalFormat: null | PixelFormatGPU

    The GPU Pixel Format allows the developer to specify how the data is going to be stored on the GPU.

    Compatible only with WebGL2RenderingContext | WebGL 2 Rendering Context.

    Texture Constants

    The default value is obtained using a combination of .format and .type.

    isArrayTexture: boolean

    Indicates if a texture should be handled like a texture array.

    false
    isRenderTargetTexture: boolean

    Indicates whether a texture belongs to a render target or not

    false

    isTexture: true

    Read-only flag to check if a given object is of type Texture.

    This is a constant value

    true

    magFilter: MagnificationTextureFilter

    How the Texture is sampled when a texel covers more than one pixel.

    THREE.LinearFilter

    mapping: AnyMapping

    How the image is applied to the object.

    All Texture types except THREE.CubeTexture expect the values be THREE.Mapping

    Texture Constants

    value of THREE.Texture.DEFAULT_MAPPING

    matrix: Matrix3

    The uv-transform matrix for the texture.

    When .matrixAutoUpdate property is true. Will be updated by the renderer from the properties:

    .matrixAutoUpdate

    new THREE.Matrix3()

    matrixAutoUpdate: boolean

    Whether is to update the texture's uv-transform .matrix.

    Set this to false if you are specifying the uv-transform matrix directly.

    .matrix

    true

    minFilter: MinificationTextureFilter

    How the Texture is sampled when a texel covers less than one pixel.

    THREE.LinearMipmapLinearFilter

    mipmaps:
        | undefined
        | CompressedTextureMipmap[]
        | CubeTexture[]
        | HTMLCanvasElement[]

    Array of user-specified mipmaps

    []

    name: string

    Optional name of the object

    (doesn't need to be unique).

    ""

    offset: Vector2

    How much a single repetition of the texture is offset from the beginning, in each direction U and V.

    Typical range is 0.0 to 1.0.

    new THREE.Vector2(0, 0)

    onUpdate: null | ((texture: Texture) => void)

    A callback function, called when the texture is updated (e.g., when needsUpdate has been set to true and then the texture is used).

    pmremVersion: number

    Indicates whether this texture should be processed by PMREMGenerator or not (only relevant for render target textures)

    premultiplyAlpha: boolean

    If set to true, the alpha channel, if present, is multiplied into the color channels when the texture is uploaded to the GPU.

    Note that this property has no effect for ImageBitmap. You need to configure on bitmap creation instead. See THREE.ImageBitmapLoader | ImageBitmapLoader.

    THREE.ImageBitmapLoader | ImageBitmapLoader.

    false

    renderTarget: null | RenderTarget<Texture>
    repeat: Vector2

    How many times the texture is repeated across the surface, in each direction U and V.

    If repeat is set greater than 1 in either direction, the corresponding Wrap parameter should also be set to THREE.RepeatWrapping or THREE.MirroredRepeatWrapping to achieve the desired tiling effect.

    new THREE.Vector2( 1, 1 )

    rotation: number

    How much the texture is rotated around the center point, in radians.

    Positive values are counter-clockwise.

    0

    source: Source

    The data definition of a texture. A reference to the data source can be shared across textures. This is often useful in context of spritesheets where multiple textures render the same data but with different Texture transformations.

    type: TextureDataType

    This must correspond to the .format.

    THREE.UnsignedByteType, is the type most used by Texture formats.

    THREE.UnsignedByteType

    unpackAlignment: number

    Specifies the alignment requirements for the start of each pixel row in memory.

    The allowable values are:

    • 1 (byte-alignment)
    • 2 (rows aligned to even-numbered bytes)
    • 4 (word-alignment)
    • 8 (rows start on double-word boundaries).

    glPixelStorei for more information.

    4

    updateRanges: { count: number; start: number }[]

    This can be used to only update a subregion or specific rows of the texture (for example, just the first 3 rows). Use the addUpdateRange() function to add ranges to this array.

    userData: Record<string, any>

    An object that can be used to store custom data about the texture.

    It should not hold references to functions as these will not be cloned.

    {}

    uuid: string

    UUID of this object instance.

    This gets automatically assigned and shouldn't be edited.

    version: number

    This starts at 0 and counts how many times .needsUpdate is set to true.

    Expects a Integer

    0

    wrapS: Wrapping

    This defines how the Texture is wrapped horizontally and corresponds to U in UV mapping.

    for WEBGL1 - tiling of images in textures only functions if image dimensions are powers of two (2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048, ...) in terms of pixels. Individual dimensions need not be equal, but each must be a power of two. This is a limitation of WebGL1, not three.js. WEBGL2 does not have this limitation.

    THREE.ClampToEdgeWrapping

    wrapT: Wrapping

    This defines how the Texture is wrapped vertically and corresponds to V in UV mapping.

    for WEBGL1 - tiling of images in textures only functions if image dimensions are powers of two (2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048, ...) in terms of pixels. Individual dimensions need not be equal, but each must be a power of two. This is a limitation of WebGL1, not three.js. WEBGL2 does not have this limitation.

    THREE.ClampToEdgeWrapping

    DEFAULT_ANISOTROPY: number

    The Global default value for .anisotropy.

    1.

    DEFAULT_IMAGE: any

    The Global default value for Texture.image | .image.

    null.

    DEFAULT_MAPPING: Mapping

    The Global default value for .mapping.

    THREE.UVMapping

    Accessors

    • get depth(): number

      The depth of the texture in pixels.

      Returns number

    • get height(): number

      Gets the actual height of the shared texture.

      Returns number

      The texture height in pixels

    • get image(): any

      An image object, typically created using the THREE.TextureLoader.load | TextureLoader.load() method.

      Returns any

      This can be any image (e.g., PNG, JPG, GIF, DDS) or video (e.g., MP4, OGG/OGV) type supported by three.js.

    • set image(data: any): void

      Parameters

      • data: any

      Returns void

    • set needsPMREMUpdate(value: boolean): void

      Indicates whether this texture should be processed by THREE.PMREMGenerator or not.

      Parameters

      • value: boolean

      Returns void

      Only relevant for render target textures.

      false

    • set needsUpdate(value: boolean): void

      Set this to true to trigger an update next time the texture is used. Particularly important for setting the wrap mode.

      Parameters

      • value: boolean

      Returns void

    • get stage(): Container

      Gets the PixiJS Container that serves as the root stage for content.

      All PixiJS display objects should be added to this stage to appear in the shared texture. The stage coordinates range from (0,0) to (width,height).

      Returns Container

      The root PixiJS Container for adding display objects

      // Add PixiJS content to the shared stage
      const sprite = new PIXI.Sprite(texture);
      sprite.position.set(100, 100);
      sharedTexture.stage.addChild(sprite);

      // Add graphics
      const graphics = new PIXI.Graphics();
      graphics.rect(0, 0, 200, 200).fill(0xff0000);
      sharedTexture.stage.addChild(graphics);
    • get width(): number

      Gets the actual width of the shared texture.

      Returns number

      The texture width in pixels

    Methods

    • Adds a listener to an event type.

      Type Parameters

      • T extends "dispose"

      Parameters

      • type: T

        The type of event to listen to.

      • listener: EventListener<{ dispose: {} }[T], T, SharedStageTexture>

        The function that gets called when the event is fired.

      Returns void

    • Adds a range of data in the data texture to be updated on the GPU.

      Parameters

      • start: number

        Position at which to start update.

      • count: number

        The number of components to update.

      Returns void

    • Calculate UV coordinates for the given texture area. Returns normalized coordinates where (0,0) is bottom-left and (1,1) is top-right, following Three.js texture coordinate conventions.

      Parameters

      • rect: TextureArea

        The texture area to calculate UV coordinates for

      Returns { x1: number; x2: number; y1: number; y2: number }

      UV coordinates object with x1,y1 (top-left) and x2,y2 (bottom-right)

      const textureArea = { x: 0, y: 0, width: 256, height: 256 };
      const uv = sharedTexture.calculateUV(textureArea);
      // uv.x1, uv.y1 = top-left corner
      // uv.x2, uv.y2 = bottom-right corner
      console.log(uv); // { x1: 0, y1: 0.75, x2: 0.25, y2: 1 }

    • Parameters

      • rect: TextureArea

        The texture area to calculate UV coordinates for

      Returns { x1: number; x2: number; y1: number; y2: number }

      UV coordinates object with x1,y1 (top-left) and x2,y2 (bottom-right)

      Use calculateUV instead. This method name contains a typo and will be removed in a future version. Calculate UV coordinates for the given texture area. Returns normalized coordinates where (0,0) is bottom-left and (1,1) is top-right, following Three.js texture coordinate conventions.

    • Clears the update ranges.

      Returns void

    • Make copy of the texture. Note this is not a "deep copy", the image is shared. Cloning the texture automatically marks it for texture upload.

      Returns this

    • Parameters

      • source: Texture

      Returns this

    • Fire an event type.

      Type Parameters

      • T extends "dispose"

      Parameters

      • event: BaseEvent<T> & { dispose: {} }[T]

        The event that gets fired.

      Returns void

    • Frees the GPU-related resources allocated by this instance

      Returns void

      Call this method whenever this instance is no longer used in your app.

    • Checks if listener is added to an event type.

      Type Parameters

      • T extends "dispose"

      Parameters

      • type: T

        The type of event to listen to.

      • listener: EventListener<{ dispose: {} }[T], T, SharedStageTexture>

        The function that gets called when the event is fired.

      Returns boolean

    • Initializes the PixiJS Application instance for shared texture use.

      This method must be called before using the SharedStageTexture. It configures the PixiJS Application with the specified dimensions and sets up the render loop integration with Three.js.

      Parameters

      • width: number

        Texture width in pixels (power-of-2 recommended for optimal performance)

      • height: number

        Texture height in pixels (power-of-2 recommended for optimal performance)

      Returns Promise<void>

      const sharedTexture = new SharedStageTexture();

      // Initialize with power-of-2 dimensions for best performance
      await sharedTexture.init(1024, 1024);

      // Or use non-power-of-2 if needed
      await sharedTexture.init(800, 600);

    • Removes a listener from an event type.

      Type Parameters

      • T extends "dispose"

      Parameters

      • type: T

        The type of the listener that gets removed.

      • listener: EventListener<{ dispose: {} }[T], T, SharedStageTexture>

        The listener function that gets removed.

      Returns void

    • Marks the texture for update on the next render frame.

      This method must be called whenever the PixiJS stage content changes and you want the changes to be reflected in the Three.js texture. The actual texture update will occur on the next animation frame to optimize performance.

      Returns void

      // Modify PixiJS content
      sprite.position.x += 10;
      graphics.tint = 0x00ff00;

      // Mark for update
      sharedTexture.setNeedUpdate();

      // The texture will be updated on the next frame automatically

    • Sets this texture's properties based on values.

      Parameters

      • values: TextureParameters

        A container with texture parameters.

      Returns void

    • Convert the texture to three.js JSON Object/Scene format.

      Parameters

      • Optionalmeta: string | {}

        Optional object containing metadata.

      Returns TextureJSON

    • Transform the UV based on the value of this texture's .offset, .repeat, .wrapS, .wrapT and .flipY properties.

      Parameters

      • uv: Vector2

      Returns Vector2

    • Update the texture's UV-transform .matrix from the texture properties .offset, .repeat, .rotation and .center.

      Returns void

    Settings

    Member Visibility

    On This Page

    Architecture OverviewComparison with MultiView ClassesPerformance CharacteristicsUpdate Mechanism
    Constructors
    Properties
    Accessors
    Methods