phaser - v4.0.0-rc.4
    Preparing search index...

    A Dynamic Texture is a special texture that allows you to draw textures, frames and most kind of Game Objects directly to it.

    You can take many complex objects and draw them to this one texture, which can then be used as the base texture for other Game Objects, such as Sprites. Should you then update this texture, all Game Objects using it will instantly be updated as well, reflecting the changes immediately.

    It's a powerful way to generate dynamic textures at run-time that are WebGL friendly and don't invoke expensive GPU uploads on each change.

    const t = this.textures.addDynamicTexture('player', 64, 128);
    // draw objects to t
    this.add.sprite(x, y, 'player');
    this.render();

    Because this is a standard Texture within Phaser, you can add frames to it, meaning you can use it to generate sprite sheets, texture atlases or tile sets.

    Under WebGL1, a FrameBuffer, which is what this Dynamic Texture uses internally, cannot be anti-aliased. This means that when drawing objects such as Shapes or Graphics instances to this texture, they may appear to be drawn with no aliasing around the edges. This is a technical limitation of WebGL1. To get around it, create your shape as a texture in an art package, then draw that to this texture.

    In the event that the WebGL context is lost, this DynamicTexture will lose its contents. Once context is restored (signalled by the restorewebgl event), you can choose to redraw the contents of the DynamicTexture. You are responsible for the redrawing logic.

    Hierarchy (View Summary)

    Index

    Constructors

    • Parameters

      • manager: TextureManager

        A reference to the Texture Manager this Texture belongs to.

      • key: string

        The unique string-based key of this Texture.

      • Optionalwidth: number

        The width of this Dymamic Texture in pixels. Defaults to 256 x 256. Default 256.

      • Optionalheight: number

        The height of this Dymamic Texture in pixels. Defaults to 256 x 256. Default 256.

      • OptionalforceEven: boolean

        Force the given width and height to be rounded to even values. This significantly improves the rendering quality. Set to false if you know you need an odd sized texture. Default true.

      Returns DynamicTexture

    Properties

    An internal Camera that can be used to move around this Dynamic Texture.

    Control it just like you would any Scene Camera. The difference is that it only impacts the placement of Game Objects (not textures) that you then draw to this texture.

    You can scroll, zoom and rotate this Camera.

    canvas: HTMLCanvasElement

    A reference to the Rendering Context belonging to the Canvas Element this Dynamic Texture is drawing to.

    commandBuffer: any[]

    An array of commands that are used to draw to this Dynamic Texture. This is flushed by the render method. The clear method will also clear this array, then store itself.

    context: CanvasRenderingContext2D

    The 2D Canvas Rendering Context.

    customData: object

    Any additional data that was set in the source JSON (if any), or any extra data you'd like to store relating to this texture

    dataSource: any[]

    An array of TextureSource data instances. Used to store additional data images, such as normal maps or specular maps.

    drawingContext: DrawingContext

    The drawing context of this Dynamic Texture. This contains the framebuffer that the Dynamic Texture is drawing to.

    firstFrame: string

    The name of the first frame of the Texture.

    frames: object

    A key-value object pair associating the unique Frame keys with the Frames objects.

    frameTotal: number

    The total number of Frames in this Texture, including the __BASE frame.

    A Texture will always contain at least 1 frame because every Texture contains a __BASE frame by default, in addition to any extra frames that have been added to it, such as when parsing a Sprite Sheet or Texture Atlas.

    height: number

    The height of this Dynamic Texture.

    Treat this property as read-only. Use the setSize method to change the size.

    key: string

    The unique string-based key of this Texture.

    A reference to the Texture Manager this Texture belongs to.

    A reference to either the Canvas or WebGL Renderer that the Game instance is using.

    smoothPixelArt: boolean

    Whether shaders using this texture should use special filtering code. This relies on shader support.

    If null, the game default will be used.

    source: TextureSource[]

    An array of TextureSource instances. These are unique to this Texture and contain the actual Image (or Canvas) data.

    type: string

    The internal data type of this object.

    width: number

    The width of this Dynamic Texture.

    Treat this property as read-only. Use the setSize method to change the size.

    Methods

    • Adds a new Frame to this Texture.

      A Frame is a rectangular region of a TextureSource with a unique index or string-based key.

      The name given must be unique within this Texture. If it already exists, this method will return null.

      Parameters

      • name: string | number

        The name of this Frame. The name is unique within the Texture.

      • sourceIndex: number

        The index of the TextureSource that this Frame is a part of.

      • x: number

        The x coordinate of the top-left of this Frame.

      • y: number

        The y coordinate of the top-left of this Frame.

      • width: number

        The width of this Frame.

      • height: number

        The height of this Frame.

      Returns Frame

    • Adds a callback to run during the render process. This callback runs as a step in the command buffer. It can be used to set up conditions for the next draw step.

      Note that this will only execute after render() is called.

      Parameters

      • callback: Function

        A callback function to run during the render process.

      Returns this

    • Draws the given object to this Dynamic Texture. This allows you to draw the object as it appears in the game world, or with various parameter overrides in the config.

      Parameters

      Returns this

    • Clears a portion or everything from this Dynamic Texture by erasing it and resetting it back to a blank, transparent, texture. To clear an area, specify the x, y, width and height.

      Parameters

      • Optionalx: number

        The left coordinate of the fill rectangle. Default 0.

      • Optionaly: number

        The top coordinate of the fill rectangle. Default 0.

      • Optionalwidth: number

        The width of the fill rectangle. Default this.width.

      • Optionalheight: number

        The height of the fill rectangle. Default this.height.

      Returns this

    • Draws the given object, or an array of objects, to this Dynamic Texture.

      It can accept any of the following:

      • Any renderable Game Object, such as a Sprite, Text, Graphics or TileSprite.
      • Tilemap Layers.
      • A Group. The contents of which will be iterated and drawn in turn.
      • A Container. The contents of which will be iterated fully, and drawn in turn.
      • A Scene Display List. Pass in Scene.children to draw the whole list.
      • Another Dynamic Texture, or a Render Texture.
      • A Texture Frame instance.
      • A string. This is used to look-up the texture from the Texture Manager.

      Note 1: You cannot draw a Dynamic Texture to itself.

      Note 2: GameObjects will use the camera, while textures and frames will not. Textures and frames are drawn using the stamp method.

      If passing in a Group or Container it will only draw children that return true when their willRender() method is called. I.e. a Container with 10 children, 5 of which have visible=false will only draw the 5 visible ones.

      If passing in an array of Game Objects it will draw them all, regardless if they pass a willRender check or not.

      You can pass in a string in which case it will look for a texture in the Texture Manager matching that string, and draw the base frame. If you need to specify exactly which frame to draw then use the method drawFrame instead.

      You can pass in the x and y coordinates to draw the objects at. The use of the coordinates differ based on what objects are being drawn. If the object is a Group, Container or Display List, the coordinates are added to the positions of the children. For all other types of object, the coordinates are exact. For textures and frames, the x and y values are the middle of the texture.

      The alpha and tint values are only used by Texture Frames. Game Objects use their own alpha and tint values when being drawn.

      Parameters

      • entries: any

        Any renderable Game Object, or Group, Container, Display List, other Render Texture, Texture Frame or an array of any of these.

      • Optionalx: number

        The x position to draw the Frame at, or the offset applied to the object. Default 0.

      • Optionaly: number

        The y position to draw the Frame at, or the offset applied to the object. Default 0.

      • Optionalalpha: number

        The alpha value. Only used when drawing Texture Frames to this texture. Game Objects use their own alpha. Default 1.

      • Optionaltint: number

        The tint color value. Only used when drawing Texture Frames to this texture. Game Objects use their own tint. WebGL only. Default 0xffffff.

      Returns this

    • Draws the given object, or an array of objects, to this Dynamic Texture using a blend mode of ERASE. This has the effect of erasing any filled pixels present in the objects from this texture.

      This method uses the draw method internally, and the parameters behave the same way.

      Parameters

      • entries: any

        Any renderable Game Object, or Group, Container, Display List, Render Texture, Texture Frame, or an array of any of these.

      • Optionalx: number

        The x position to draw the Frame at, or the offset applied to the object. Default 0.

      • Optionaly: number

        The y position to draw the Frame at, or the offset applied to the object. Default 0.

      • Optionalalpha: number

        The alpha value. Only used when drawing Texture Frames to this texture. Game Objects use their own alpha. Default 1.

      • Optionaltint: number

        The tint color value. Only used when drawing Texture Frames to this texture. Game Objects use their own tint. WebGL only. Default 0xffffff.

      Returns this

    • Fills this Dynamic Texture with the given color.

      By default it will fill the entire texture, however you can set it to fill a specific rectangular area by using the x, y, width and height arguments.

      The color should be given in hex format, i.e. 0xff0000 for red, 0x00ff00 for green, etc.

      Parameters

      • rgb: number

        The color to fill this Dynamic Texture with, such as 0xff0000 for red.

      • Optionalalpha: number

        The alpha value used by the fill. Default 1.

      • Optionalx: number

        The left coordinate of the fill rectangle. Default 0.

      • Optionaly: number

        The top coordinate of the fill rectangle. Default 0.

      • Optionalwidth: number

        The width of the fill rectangle. Default this.width.

      • Optionalheight: number

        The height of the fill rectangle. Default this.height.

      Returns this

    • Restores the object properties that were overridden during the capture method. This method is called automatically during rendering. Do not call it directly.

      Parameters

      • entry: GameObject

        The GameObject to restore the properties on.

      • cacheConfig: CaptureConfig

        The cached properties to restore.

      Returns void

    • Gets a Frame from this Texture based on either the key or the index of the Frame.

      In a Texture Atlas Frames are typically referenced by a key. In a Sprite Sheet Frames are referenced by an index. Passing no value for the name returns the base texture.

      Parameters

      • Optionalname: string | number

        The string-based name, or integer based index, of the Frame to get from this Texture.

      Returns Frame

    • Given a Frame name, return the data source image it uses to render with. You can use this to get the normal map for an image for example.

      This will return the actual DOM Image.

      Parameters

      • Optionalname: string | number

        The string-based name, or integer based index, of the Frame to get from this Texture.

      Returns HTMLImageElement | HTMLCanvasElement

    • Based on the given Texture Source Index, this method will get all of the Frames using that source and then work out the bounds that they encompass, returning them in an object.

      This is useful if this Texture is, for example, a sprite sheet within an Atlas, and you need to know the total bounds of the sprite sheet.

      Parameters

      • OptionalsourceIndex: number

        The index of the TextureSource to get the Frame bounds from. Default 0.

      Returns RectangleLike

    • Returns an array with all of the names of the Frames in this Texture.

      Useful if you want to randomly assign a Frame to a Game Object, as you can pick a random element from the returned array.

      Parameters

      • OptionalincludeBase: boolean

        Include the __BASE Frame in the output array? Default false.

      Returns string[]

    • Returns an array of all the Frames in the given TextureSource.

      Parameters

      • sourceIndex: number

        The index of the TextureSource to get the Frames from.

      • OptionalincludeBase: boolean

        Include the __BASE Frame in the output array? Default false.

      Returns Frame[]

    • Given a Frame name, return the source image it uses to render with.

      This will return the actual DOM Image or Canvas element.

      Parameters

      • Optionalname: string | number

        The string-based name, or integer based index, of the Frame to get from this Texture.

      Returns HTMLImageElement | GameObjects.RenderTexture | HTMLCanvasElement

    • Takes the given TextureSource and returns the index of it within this Texture. If it's not in this Texture, it returns -1. Unless this Texture has multiple TextureSources, such as with a multi-atlas, this method will always return zero or -1.

      Parameters

      Returns number

    • Checks to see if a Frame matching the given key exists within this Texture.

      Parameters

      • name: string

        The key of the Frame to check for.

      Returns boolean

    • Sets the preserve flag for this Dynamic Texture. Ordinarily, after each render, the command buffer is cleared. When this flag is set to true, the command buffer is preserved between renders. This makes it possible to repeat the same drawing commands on each render.

      Make sure to call clear() at the start if you don't want to accumulate drawing detail over the top of itself.

      Parameters

      • preserve: boolean

        Whether to preserve the command buffer after rendering.

      Returns this

    • Removes the given Frame from this Texture. The Frame is destroyed immediately.

      Any Game Objects using this Frame should stop using it before you remove it, as it does not happen automatically.

      Parameters

      • name: string

        The key of the Frame to remove.

      Returns boolean

    • Render the buffered drawing commands to this Dynamic Texture. You must do this in order to see anything drawn to it.

      Returns this

    • Takes the given Texture Frame and draws it to this Dynamic Texture as a fill pattern, i.e. in a grid-layout based on the frame dimensions. It uses a TileSprite internally to draw the frame repeatedly.

      Textures are referenced by their string-based keys, as stored in the Texture Manager.

      You can optionally provide a position, width, height, alpha and tint value to apply to the frames before they are drawn. The position controls the top-left where the repeating fill will start from. The width and height control the size of the filled area.

      The position can be negative if required, but the dimensions cannot.

      This method respects the camera settings of the Dynamic Texture.

      Parameters

      • key: string

        The key of the texture to be used, as stored in the Texture Manager.

      • Optionalframe: string | number

        The name or index of the frame within the Texture. Set to null to skip this argument if not required.

      • Optionalx: number

        The x position to start drawing the frames from (can be negative to offset). Default 0.

      • Optionaly: number

        The y position to start drawing the frames from (can be negative to offset). Default 0.

      • Optionalwidth: number

        The width of the area to repeat the frame within. Defaults to the width of this Dynamic Texture. Default this.width.

      • Optionalheight: number

        The height of the area to repeat the frame within. Defaults to the height of this Dynamic Texture. Default this.height.

      • Optionalconfig: TileSpriteConfig

        The configuration object for the TileSprite which repeats the texture, allowing you to set further properties on it.

      Returns this

    • Adds a data source image to this Texture.

      An example of a data source image would be a normal map, where all of the Frames for this Texture equally apply to the normal map.

      Parameters

      • data: HTMLImageElement | HTMLCanvasElement | HTMLImageElement[] | HTMLCanvasElement[]

        The source image.

      Returns void

    • Sets the Filter Mode for this Texture.

      The mode can be either Linear, the default, or Nearest.

      For pixel-art you should use Nearest.

      The mode applies to the entire Texture, not just a specific Frame of it.

      Parameters

      Returns void

    • Resizes this Dynamic Texture to the new dimensions given.

      In WebGL it will destroy and then re-create the frame buffer being used by this Dynamic Texture. In Canvas it will resize the underlying canvas DOM element.

      Both approaches will erase everything currently drawn to this texture.

      If the dimensions given are the same as those already being used, calling this method will do nothing.

      Parameters

      • width: number

        The new width of this Dynamic Texture.

      • Optionalheight: number

        The new height of this Dynamic Texture. If not specified, will be set the same as the width. Default width.

      • OptionalforceEven: boolean

        Force the given width and height to be rounded to even values. This significantly improves the rendering quality. Set to false if you know you need an odd sized texture. Default true.

      Returns this

    • Set the smoothPixelArt property for this Texture. If true, it will also run setFilter(Phaser.Textures.FilterMode.LINEAR) to enable the necessary linear filtering. If false, it will not change the filter mode, as it doesn't know the previous state, nor is it necessary to change it.

      Parameters

      • value: boolean

        The value of the smoothPixelArt property.

      Returns void

    • Takes a snapshot of the whole of this Dynamic Texture.

      The snapshot is taken immediately, but the results are returned via the given callback.

      To capture a portion of this Dynamic Texture see the snapshotArea method. To capture just a specific pixel, see the snapshotPixel method.

      Snapshots work by using the WebGL readPixels feature to grab every pixel from the frame buffer into an ArrayBufferView. It then parses this, copying the contents to a temporary Canvas and finally creating an Image object from it, which is the image returned to the callback provided.

      All in all, this is a computationally expensive and blocking process, which gets more expensive the larger the resolution this Dynamic Texture has, so please be careful how you employ this in your game.

      Parameters

      • callback: SnapshotCallback

        The Function to invoke after the snapshot image is created.

      • Optionaltype: string

        The format of the image to create, usually image/png or image/jpeg. Default 'image/png'.

      • OptionalencoderOptions: number

        The image quality, between 0 and 1. Used for image formats with lossy compression, such as image/jpeg. Default 0.92.

      Returns this

    • Takes a snapshot of the given area of this Dynamic Texture.

      The snapshot is taken immediately, but the results are returned via the given callback.

      To capture the whole Dynamic Texture see the snapshot method. To capture just a specific pixel, see the snapshotPixel method.

      Snapshots work by using the WebGL readPixels feature to grab every pixel from the frame buffer into an ArrayBufferView. It then parses this, copying the contents to a temporary Canvas and finally creating an Image object from it, which is the image returned to the callback provided.

      All in all, this is a computationally expensive and blocking process, which gets more expensive the larger the resolution this Dynamic Texture has, so please be careful how you employ this in your game.

      Parameters

      • x: number

        The x coordinate to grab from.

      • y: number

        The y coordinate to grab from.

      • width: number

        The width of the area to grab.

      • height: number

        The height of the area to grab.

      • callback: SnapshotCallback

        The Function to invoke after the snapshot image is created.

      • Optionaltype: string

        The format of the image to create, usually image/png or image/jpeg. Default 'image/png'.

      • OptionalencoderOptions: number

        The image quality, between 0 and 1. Used for image formats with lossy compression, such as image/jpeg. Default 0.92.

      Returns this

    • Takes a snapshot of the given pixel from this Dynamic Texture.

      The snapshot is taken immediately, but the results are returned via the given callback.

      To capture the whole Dynamic Texture see the snapshot method. To capture a portion of this Dynamic Texture see the snapshotArea method.

      Unlike the two other snapshot methods, this one will send your callback a Color object containing the color data for the requested pixel. It doesn't need to create an internal Canvas or Image object, so is a lot faster to execute, using less memory than the other snapshot methods.

      Parameters

      • x: number

        The x coordinate of the pixel to get.

      • y: number

        The y coordinate of the pixel to get.

      • callback: SnapshotCallback

        The Function to invoke after the snapshot pixel data is extracted.

      Returns this

    • Takes the given texture key and frame and then stamps it at the given x and y coordinates. You can use the optional 'config' argument to provide lots more options about how the stamp is applied, including the alpha, tint, angle, scale and origin.

      By default, the frame will stamp on the x/y coordinates based on its center.

      If you wish to stamp from the top-left, set the config originX and originY properties both to zero.

      This method ignores the camera property of the Dynamic Texture.

      Parameters

      • key: string

        The key of the texture to be used, as stored in the Texture Manager.

      • Optionalframe: string | number

        The name or index of the frame within the Texture. Set to null to skip this argument if not required.

      • Optionalx: number

        The x position to draw the frame at. Default 0.

      • Optionaly: number

        The y position to draw the frame at. Default 0.

      • Optionalconfig: StampConfig

        The stamp configuration object, allowing you to set the alpha, tint, angle, scale and origin of the stamp.

      Returns this