pixi.js
    Preparing search index...

    Class HTMLSourceExperimental Advanced

    A texture source backed by the experimental HTML-in-Canvas browser APIs. It renders a live DOM Element into a texture you can use anywhere a normal texture works: on a Sprite, as a Texture frame, in a mesh, and so on.

    The element keeps its native browser behavior while it is rendered: forms stay editable, links stay clickable, and CSS animations keep running. PixiJS just mirrors its pixels into the GPU each time the browser repaints it.

    The source resource must be a direct child of the renderer's <canvas layoutsubtree> element. For an immutable, transferable copy that never repaints, use ElementImageSource instead.

    Note

    This relies on an experimental browser proposal and requires the HTML-in-Canvas API to be enabled; without it the texture uploader throws on first render. A generic HTML element passed to Texture.from resolves to an HTMLSource only as a last resort (it has the lowest texture-source priority); construct it explicitly when you need options or non-HTML elements such as SVG.

    import { Application, Sprite } from 'pixi.js';
    import { HTMLSource } from 'pixi.js/html-source';

    const app = new Application();

    await app.init({ resizeTo: window });
    document.body.appendChild(app.canvas);

    // The element must be a direct child of the Pixi canvas.
    const form = document.createElement('form');

    form.innerHTML = '<input value="still editable" />';
    app.canvas.appendChild(form);

    // Render the live form as a sprite. It stays interactive in the browser.
    const source = new HTMLSource({ resource: form });
    const sprite = Sprite.from(source);

    sprite.anchor.set(0.5);
    sprite.position.set(app.screen.width / 2, app.screen.height / 2);
    app.stage.addChild(sprite);

    // Continuous animation: drive repaints yourself each frame.
    const source = new HTMLSource({ resource: animatedDiv, autoRequestPaint: false });
    const sprite = Sprite.from(source);

    app.ticker.add(() => {
        sprite.rotation += 0.01;
        source.requestPaint(); // re-snapshot the DOM this frame
    });

    // Slice the rendered element into sub-textures (e.g. a "shatter" effect).
    import { Rectangle, Texture } from 'pixi.js';

    const pageSource = new HTMLSource({ resource: page });
    const chunk = new Texture({
        source: pageSource,
        frame: new Rectangle(0, 0, 64, 64),
    });

    // Auto-detected: a generic HTML element passed to Texture.from resolves to an HTMLSource
    // when no other built-in source claims it. Prefer the explicit form for options.
    const sprite = Sprite.from(divAlreadyInTheCanvas);

    Hierarchy (View Summary)

    Index

    Constructors

    constructor

    Properties

    _gcData? alphaMode antialias arrayLayerCount autoGarbageCollect autoGenerateMipmaps canvas destroyed dimension format height isPowerOfTwo label mipLevelCount pixelHeight pixelWidth resource uid uploadMethodId viewDimension width defaultOptions extension from

    Accessors

    addressMode isReady lodMaxClamp lodMinClamp magFilter maxAnisotropy minFilter mipmapFilter repeatMode resolution resourceHeight resourceWidth scaleMode source style wrapMode

    Methods

    destroy requestPaint resize unload update updateMipmaps test

    Constructors

    • Experimental

      Parameters

      • options: HTMLSourceOptions

        Options for creating the HTML source. resource is required.

      Returns HTMLSource

      const source = new HTMLSource({
          resource: domElement,   // a direct child of the Pixi canvas
          autoUpdate: true,       // track browser repaints (default)
          autoRequestPaint: true, // request one initial paint (default)
      });

    Properties

    Optional Experimental_gcData

    _gcData?: GCData

    GC tracking data, undefined if not being tracked

    alphaMode: ALPHA_MODES

    the alpha mode of the texture

    antialias: boolean = false

    Only really affects RenderTextures. Should we use antialiasing for this texture. It will look better, but may impact performance as a Blit operation will be required to resolve the texture.

    arrayLayerCount: number = 1

    how many array layers this texture has (WebGPU depthOrArrayLayers)

    autoGarbageCollect: boolean

    If true, the Garbage Collector will unload this texture if it is not used after a period of time

    autoGenerateMipmaps: boolean = false

    Should we auto generate mipmaps for this texture? This will automatically generate mipmaps for this texture when uploading to the GPU. Mipmapped textures take up more memory, but can look better when scaled down.

    For performance reasons, it is recommended to NOT use this with RenderTextures, as they are often updated every frame. If you do, make sure to call updateMipmaps after you update the texture.

    canvas: HTMLSourceCanvas

    Owning canvas used for paint events and HTMLSource.requestPaint. Set to null once the source is destroyed.

    destroyed: boolean

    Has the source been destroyed?

    dimension: TEXTURE_DIMENSIONS = '2d'

    how many dimensions does this texture have? currently v8 only supports 2d

    format: TEXTURE_FORMATS = 'rgba8unorm'

    the format that the texture data has

    height: number = 1

    the height of this texture source, accounting for resolution eg pixelHeight 200, resolution 2, then height will be 100

    isPowerOfTwo: boolean
    label: string

    optional label, can be used for debugging

    mipLevelCount: number = 1

    The number of mip levels to generate for this texture. this is overridden if autoGenerateMipmaps is true. it is read only!

    pixelHeight: number = 1

    the pixel height of this texture source. This is the REAL pure number, not accounting resolution

    pixelWidth: number = 1

    the pixel width of this texture source. This is the REAL pure number, not accounting resolution

    resource: Element

    the resource that will be uploaded to the GPU. This is where we get our pixels from eg an ImageBimt / Canvas / Video etc

    uid: number = ...

    unique id for this Texture source

    uploadMethodId: string = 'html'

    The upload method for this texture.

    viewDimension: TEXTURE_VIEW_DIMENSIONS = '2d'

    how this texture is viewed/sampled by shaders (WebGPU view dimension)

    width: number = 1

    the width of this texture source, accounting for resolution eg pixelWidth 200, resolution 2, then width will be 100

    defaultOptions: Partial<HTMLSourceOptions> = ...

    The default options applied to every HTMLSource, merged with the options passed to the constructor.

    // Make every HTMLSource opt out of automatic repaint tracking by default.
    HTMLSource.defaultOptions.autoUpdate = false;
    extension: ExtensionMetadata = ...

    Registers the source with the extensions system at the lowest texture-source priority, so automatic detection only falls back to it when no other built-in source claims the resource.

    from: (resource: TextureResourceOrOptions) => TextureSource

    A helper function that creates a new TextureSource based on the resource you provide.

    Type Declaration

    Accessors

    • get addressMode(): WRAP_MODE
      Experimental

      setting this will set wrapModeU, wrapModeV and wrapModeW all at once!

      Returns WRAP_MODE

    • set addressMode(value: WRAP_MODE): void
      Experimental

      Parameters

      Returns void

    • get isReady(): boolean
      Experimental

      true once the owning canvas has produced an initial paint snapshot, so the texture has real pixels. Non-auto-updating sources are ready immediately.

      Returns boolean

      const source = new HTMLSource({ resource: domElement });

      if (!source.isReady)
      {
          // The first paint has not landed yet — the texture is still blank.
      }
    • get lodMaxClamp(): number
      Experimental

      Specifies the minimum and maximum levels of detail, respectively, used internally when sampling a texture.

      Returns number

    • set lodMaxClamp(value: number): void
      Experimental

      Parameters

      • value: number

      Returns void

    • get lodMinClamp(): number
      Experimental

      Specifies the minimum and maximum levels of detail, respectively, used internally when sampling a texture.

      Returns number

    • set lodMinClamp(value: number): void
      Experimental

      Parameters

      • value: number

      Returns void

    • get magFilter(): SCALE_MODE
      Experimental

      Specifies the sampling behavior when the sample footprint is smaller than or equal to one texel.

      Returns SCALE_MODE

    • set magFilter(value: SCALE_MODE): void
      Experimental

      Parameters

      Returns void

    • get maxAnisotropy(): number
      Experimental

      Returns number

    • set maxAnisotropy(value: number): void
      Experimental

      Specifies the maximum anisotropy value clamp used by the sampler.

      Parameters

      • value: number

      Returns void

    • get minFilter(): SCALE_MODE
      Experimental

      Specifies the sampling behavior when the sample footprint is larger than one texel.

      Returns SCALE_MODE

    • set minFilter(value: SCALE_MODE): void
      Experimental

      Parameters

      Returns void

    • get mipmapFilter(): SCALE_MODE
      Experimental

      Specifies behavior for sampling between mipmap levels.

      Returns SCALE_MODE

    • set mipmapFilter(value: SCALE_MODE): void
      Experimental

      Parameters

      Returns void

    • get repeatMode(): WRAP_MODE
      Experimental

      setting this will set wrapModeU, wrapModeV and wrapModeW all at once!

      Returns WRAP_MODE

    • set repeatMode(value: WRAP_MODE): void
      Experimental

      Parameters

      Returns void

    • get resolution(): number
      Experimental

      the resolution of the texture. Changing this number, will not change the number of pixels in the actual texture but will the size of the texture when rendered.

      changing the resolution of this texture to 2 for example will make it appear twice as small when rendered (as pixel density will have increased)

      Returns number

    • set resolution(resolution: number): void
      Experimental

      Parameters

      • resolution: number

      Returns void

    • get resourceHeight(): number
      Experimental

      Height in real pixels (offsetHeight). Use height for CSS pixels.

      Returns number

    • get resourceWidth(): number
      Experimental

      Width in real pixels (offsetWidth). Use width for CSS pixels.

      Returns number

    • get scaleMode(): SCALE_MODE
      Experimental

      setting this will set magFilter,minFilter and mipmapFilter all at once!

      Returns SCALE_MODE

    • set scaleMode(value: SCALE_MODE): void
      Experimental

      Parameters

      Returns void

    • get wrapMode(): WRAP_MODE
      Experimental

      Returns WRAP_MODE

    • set wrapMode(value: WRAP_MODE): void
      Experimental

      Parameters

      Returns void

    Methods

    • Experimental

      Detaches the paint listener from the owning canvas and destroys the underlying texture source.

      Returns void

      const source = new HTMLSource({ resource: domElement });

      source.destroy();
    • Experimental

      Request a paint event from the owning canvas. Call this every frame to keep an animated or frequently-changing element in sync with the rendered texture.

      Returns boolean

      true if the request was made, false when the browser lacks the experimental requestPaint API or there is no owning canvas.

      const source = new HTMLSource({ resource: clock, autoRequestPaint: false });

      app.ticker.add(() => {
          clock.textContent = new Date().toLocaleTimeString();
          source.requestPaint();
      });
    • Experimental

      Resize the texture, this is handy if you want to use the texture as a render texture

      Parameters

      • Optionalwidth: number

        the new width of the texture

      • Optionalheight: number

        the new height of the texture

      • Optionalresolution: number

        the new resolution of the texture

      Returns boolean

      • if the texture was resized
    • Experimental

      This will unload the Texture source from the GPU. This will free up the GPU memory As soon as it is required fore rendering, it will be re-uploaded.

      Returns void

    • Experimental

      call this if you have modified the texture outside of the constructor

      Returns void

    • Experimental

      Lets the renderer know that this texture has been updated and its mipmaps should be re-generated. This is only important for RenderTexture instances, as standard Texture instances will have their mipmaps generated on upload. You should call this method after you make any change to the texture

      The reason for this is is can be quite expensive to update mipmaps for a texture. So by default, We want you, the developer to specify when this action should happen.

      Generally you don't want to have mipmaps generated on Render targets that are changed every frame,

      Returns void

    • Experimental

      Tests whether a resource should be handled by HTMLSource during automatic source detection (Texture.from, TextureSource.from). Deliberately strict: only generic HTML elements pass. Image, video, and canvas elements are rejected because they have dedicated, faster sources; snapshots are handled by ElementImageSource.

      Parameters

      • resource: any

        The resource to test.

      Returns resource is Element

      true if this source can handle the resource.

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Accessors
    Methods