Skip to main content
Version: Phaser v4.0.0-rc.6

SpriteGPULayer

A SpriteGPULayer GameObject. This is a WebGL only GameObject.

It is optimized for rendering very large numbers of quads

following simple tween animations.

It is suited to complex backgrounds with animation.

A SpriteGPULayer is a composite object that contains a collection of

Member objects. It stores the rendering data for these

objects in a GPU buffer, and renders them in a single draw call.

Because it only updates the GPU buffer when necessary,

it is up to 100 times faster than rendering the objects individually.

Avoid changing the contents of the SpriteGPULayer frequently, as this

requires the whole buffer to be updated.

The layer can generally perform well with a million small quads.

The exact performance will depend on the device and the size of the quads.

If the quads are large, the layer will be fill-rate limited.

Avoid drawing more than a few million pixels per frame.

When populating the SpriteGPULayer, use addMember to add a new member

to the top of the layer. You should populate the layer all at once,

and leave it unchanged, rather than frequently adding and removing members,

because it is expensive to update the buffer.

Rather than create a new SpriteGPULayer.Member object for each addMember call,

you can reuse the same object. This is more efficient,

because creating millions of objects has a major performance cost

and may cause garbage collection issues.

Notes on modifying the SpriteGPULayer:

The following operations are expensive. They require some or all of the

buffer to be updated:

  • addData

  • addMember

  • editMember

  • patchMember

  • resize

  • removeMembers

Members are added at the end of the buffer. Removed members are spliced out

of the buffer, causing the whole buffer to be updated.

The index of later members will change if you remove an earlier member.

If you need to maintain a structure, such as a grid of tiles,

it's best to "remove" a member by setting its scaleX, scaleY, and alpha to 0.

It is still rendered, but it does not fill any pixels.

Changes to a small segment of the buffer are less expensive.

The buffer is split into several segments, and each segment can be updated

independently. Editing and patching members will only update the segments

that contain the members being edited.

Updating occurs at render time, so edits all happen at once.

This can reduce the amount of data that needs to be updated,

but it is still more expensive than not updating the buffer at all.

If you're updating a large number of segments, it may be more efficient

to call setAllSegmentsNeedUpdate and update the whole buffer at once

rather than make several segment updates in a row.

The animations in the initial member data are used to compile the shader

and frameDataTexture. If you add new animations after the initial

compilation, the shader and texture will be rebuilt, which is expensive.

Notes on textures:

This layer gains much of its speed from inflexibility. It can only use one

texture, and that texture must be a single image.

It cannot use multi-atlas textures.

Further, if the texture is not a power of two in size,

some texture seaming may occur if you line up sprites exactly.

This is because the GPU precision is limited by binary logic,

and texture coordinates will only be perfectly accurate for power of two textures.

This can be avoided by adding/extruding a pixel of padding around each frame

in the texture, or by using a power of two texture.

Which should you use?

  • If you are using pixel art mode or round pixels,

    you should aim to use a power of two texture.

  • If you are using smooth mode, you can use a non-power of two texture,

    but you should add padding around each frame to avoid seaming.

  • If you are using a single image, or none of the frames in the texture

    need to tile, it doesn't matter.

Constructor

new SpriteGPULayer(scene, texture, size)

Parameters

nametypeoptionaldescription
scenePhaser.SceneNoThe Scene to which this SpriteGPULayer belongs.
texturePhaser.Textures.TextureNoThe texture that will be used to render the SpriteGPULayer. This must be sourced from a single image; a multi atlas will not work.
sizenumberNoThe maximum number of quads that this SpriteGPULayer will hold. This can be increased later if necessary.

Scope: static

Extends

Phaser.GameObjects.GameObject
Phaser.GameObjects.Components.Alpha
Phaser.GameObjects.Components.BlendMode
Phaser.GameObjects.Components.Depth
Phaser.GameObjects.Components.ElapseTimer
Phaser.GameObjects.Components.Lighting
Phaser.GameObjects.Components.Mask
Phaser.GameObjects.Components.RenderNodes
Phaser.GameObjects.Components.TextureCrop
Phaser.GameObjects.Components.Visible

Source: src/gameobjects/spritegpulayer/SpriteGPULayer.js#L18
Since: 4.0.0

Inherited Members​

From Phaser.GameObjects.Components.Alpha:

From Phaser.GameObjects.Components.BlendMode:

From Phaser.GameObjects.Components.Depth:

From Phaser.GameObjects.Components.ElapseTimer:

From Phaser.GameObjects.Components.Filters:

From Phaser.GameObjects.Components.Lighting:

From Phaser.GameObjects.Components.Mask:

From Phaser.GameObjects.Components.RenderNodes:

From Phaser.GameObjects.Components.TextureCrop:

From Phaser.GameObjects.Components.Visible:

From Phaser.GameObjects.GameObject:

Public Members​

animationData​

animationData: Array.<object>​

Description:

An ordered list of animations in the frame data texture.

Source: src/gameobjects/spritegpulayer/SpriteGPULayer.js#L328
Since: 4.0.0

animationDataIndices​

animationDataIndices: object​

Description:

A map of frame indices to animation parameters in

the frame data texture.

These are the starting frame indices used by the vertex shader.

They can be used to map back to names in animationDataIndices.

Source: src/gameobjects/spritegpulayer/SpriteGPULayer.js#L349
Since: 4.0.0

animationDataNames​

animationDataNames: object​

Description:

A map of animation names to animation parameters in

the frame data texture.

This is used to convert animation names to indices and durations

for the vertex shader.

Source: src/gameobjects/spritegpulayer/SpriteGPULayer.js#L337
Since: 4.0.0

bufferUpdateSegments​

bufferUpdateSegments: number​

Description:

Which segments of the buffer require updates.

This is a bitfield with segments equal to _segments.

Source: src/gameobjects/spritegpulayer/SpriteGPULayer.js#L201
Since: 4.0.0

bufferUpdateSegmentSize​

bufferUpdateSegmentSize: number​

Description:

The size of each segment of the buffer that requires updates.

Source: src/gameobjects/spritegpulayer/SpriteGPULayer.js#L211
Since: 4.0.0

EASE​

EASE: object​

Description:

Strings for valid easing functions that can be assigned to

the ease property of an SpriteGPULayerMemberAnimation.

This is the reverse mapping of this.EASE_CODES.

Source: src/gameobjects/spritegpulayer/SpriteGPULayer.js#L256
Since: 4.0.0

EASE_CODES​

EASE_CODES: object​

Description:

Codes for valid easing functions that can be assigned to

the ease property of an SpriteGPULayerMemberAnimation.

This is the reverse mapping of this.EASE.

Source: src/gameobjects/spritegpulayer/SpriteGPULayer.js#L268
Since: 4.0.0

frameDataIndices​

frameDataIndices: object​

Description:

A map of frame names to indices in the frame data texture.

This is used to convert frame names to indices for the vertex shader.

Source: src/gameobjects/spritegpulayer/SpriteGPULayer.js#L308
Since: 4.0.0

frameDataIndicesInv​

frameDataIndicesInv: object​

Description:

A map of indices to frame names in the frame data texture.

This is used to convert frame indices back to names for debugging.

Source: src/gameobjects/spritegpulayer/SpriteGPULayer.js#L318
Since: 4.0.0

frameDataTexture​

frameDataTexture: Phaser.Renderer.WebGL.Wrappers.WebGLTextureWrapper​

Description:

A texture containing the frame data for the SpriteGPULayer.

This is used by the vertex shader.

The texture is composed of pixel strides, where each stride

is interpreted as 6 16-bit unsigned integers,

representing the x, y, width, height, and origin x and y of a frame.

The texture will be up to 4096 pixels wide and as tall as necessary.

There are two sets of data in the texture: frames and animations.

Frames are taken from the texture.

Animations are defined by calling setAnimations,

and consist of runs of frames suited to shader animation.

Although the texture will be regenerated by setAnimations,

the frames are stored first, so their indices won't change.

If you change the texture of this layer, you will need to

regenerate this by calling generateFrameDataTexture.

Source: src/gameobjects/spritegpulayer/SpriteGPULayer.js#L283
Since: 4.0.0

gravity​

gravity: number​

Description:

The gravity used by member animations in 'Gravity' mode.

This is the acceleration in pixels per second squared.

The default is 1024 pixels per second squared.

Any animation can be set to ease: 'Gravity' to use this value.

Instead of amplitude, the animation takes

velocity (a number of pixels) and

gravityFactor (0-1) parameters.

Source: src/gameobjects/spritegpulayer/SpriteGPULayer.js#L220
Since: 4.0.0

MAX_BUFFER_UPDATE_SEGMENTS_FULL​

MAX_BUFFER_UPDATE_SEGMENTS_FULL: number​

Description:

The state of bufferUpdateSegments when it's full.

This is a constant value and should not be altered.

If you do, all hell will break loose.

Source: src/gameobjects/spritegpulayer/SpriteGPULayer.js#L188
Since: 4.0.0

memberCount​

memberCount: number​

Description:

The number of quad members in the SpriteGPULayer.

Source: src/gameobjects/spritegpulayer/SpriteGPULayer.js#L145
Since: 4.0.0

nextMember​

nextMember: ArrayBuffer​

Description:

The next member buffer, used to store member data

before it is added to the GPU buffer.

Source: src/gameobjects/spritegpulayer/SpriteGPULayer.js#L383
Since: 4.0.0

nextMemberF32​

nextMemberF32: Float32Array​

Description:

A Float32Array view of the next member buffer.

Source: src/gameobjects/spritegpulayer/SpriteGPULayer.js#L393
Since: 4.0.0

nextMemberU32​

nextMemberU32: Uint32Array​

Description:

A Uint32Array view of the next member buffer.

This is used to write 32-bit integer data to the buffer.

It is used for color data.

Source: src/gameobjects/spritegpulayer/SpriteGPULayer.js#L402
Since: 4.0.0

size​

size: number​

Description:

The maximum number of quad members that can be in the SpriteGPULayer.

This value is read-only. Change buffer size with resize.

Source: src/gameobjects/spritegpulayer/SpriteGPULayer.js#L154
Since: 4.0.0

submitterNode​

submitterNode: Phaser.Renderer.WebGL.RenderNodes.SubmitterSpriteGPULayer​

Description:

The SubmitterSpriteGPULayer RenderNode for this SpriteGPULayer.

This handles rendering the SpriteGPULayer to the GPU.

It is created automatically when the SpriteGPULayer is initialized.

Most RenderNodes are singletons stored in the RenderNodeManager,

but because this one holds very specific data,

it is stored in the SpriteGPULayer itself.

Source: src/gameobjects/spritegpulayer/SpriteGPULayer.js#L363
Since: 4.0.0

Inherited Methods​

From Phaser.Events.EventEmitter:

From Phaser.GameObjects.Components.Alpha:

From Phaser.GameObjects.Components.BlendMode:

From Phaser.GameObjects.Components.Depth:

From Phaser.GameObjects.Components.ElapseTimer:

From Phaser.GameObjects.Components.Filters:

From Phaser.GameObjects.Components.Lighting:

From Phaser.GameObjects.Components.Mask:

From Phaser.GameObjects.Components.RenderNodes:

From Phaser.GameObjects.Components.RenderSteps:

From Phaser.GameObjects.Components.TextureCrop:

From Phaser.GameObjects.Components.Visible:

From Phaser.GameObjects.GameObject:

Public Methods​

addData​

<instance> addData(member)​

Description:

Adds data to the SpriteGPULayer buffer.

It is inserted at the end of the buffer.

This is mostly used internally by the SpriteGPULayer.

It takes raw data as a buffer, which is very efficient,

but addMember is easier to use.

Note that, if you add a member with an animation,

the animation must either already be enabled,

or you must enable it with setAnimationEnabled,

e.g. layer.setAnimationEnabled('Linear', true) or

layer.setAnimationEnabled(layer.EASE_CODES[layer.EASE.Linear], true).

This is a buffer modification, and is expensive.

Parameters:

nametypeoptionaldescription
memberFloat32ArrayNoThe raw data to add to the buffer.

Returns: Phaser.GameObjects.SpriteGPULayer - This SpriteGPULayer object.

Source: src/gameobjects/spritegpulayer/SpriteGPULayer.js#L719
Since: 4.0.0

addMember​

<instance> addMember([member])​

Description:

Adds a member to the SpriteGPULayer.

This is the easiest way to add a member to the SpriteGPULayer.

This is a buffer modification, and is expensive.

Parameters:

nametypeoptionaldescription
memberPartial.<Phaser.Types.GameObjects.SpriteGPULayer.Member>YesThe member to add to the SpriteGPULayer.

Returns: Phaser.GameObjects.SpriteGPULayer - This SpriteGPULayer object.

Source: src/gameobjects/spritegpulayer/SpriteGPULayer.js#L759
Since: 4.0.0

clearAllSegmentsNeedUpdate​

<instance> clearAllSegmentsNeedUpdate()​

Description:

Clears all segments of the buffer that require an update.

Source: src/gameobjects/spritegpulayer/SpriteGPULayer.js#L708
Since: 4.0.0

editMember​

<instance> editMember(index, member)​

Description:

Edits a member of the SpriteGPULayer.

This will update the member's data in the GPU buffer.

This is an expensive operation, as it requires the whole buffer to be updated.

Parameters:

nametypeoptionaldescription
indexnumberNoThe index of the member to edit.
memberPartial.<Phaser.Types.GameObjects.SpriteGPULayer.Member>NoThe new member data.

Returns: Phaser.GameObjects.SpriteGPULayer - This SpriteGPULayer object.

Source: src/gameobjects/spritegpulayer/SpriteGPULayer.js#L940
Since: 4.0.0

generateFrameDataTexture​

<instance> generateFrameDataTexture()​

Description:

Generate frameDataTexture for the SpriteGPULayer.

This is used by the vertex shader to access frame data.

Source: src/gameobjects/spritegpulayer/SpriteGPULayer.js#L532
Since: 4.0.0

getDataByteSize​

<instance> getDataByteSize()​

Description:

Get the number of bytes used to define a member.

If you are directly editing the buffer, you will need this value

as a 'stride' to move through the buffer.

Returns: number - The number of bytes used for each member.

Source: src/gameobjects/spritegpulayer/SpriteGPULayer.js#L431

getMember​

<instance> getMember(index)​

Description:

Returns a member of the SpriteGPULayer.

This returns an object copied from the buffer.

Editing it will not change anything in the SpriteGPULayer.

The object will be functionally identical to the data used to

create the buffer, but some values may be different.

  • Properties that support animation, but have no amplitude or duration or have easing 'None' (0), will be presented as numbers.

  • Animation easing values will be presented as numbers (the values

    in this.EASE).

  • Animation delay values will be normalized to the duration,

    e.g. a delay of 150 with a duration of 100 will return 50.

  • Some rounding may occur due to floating point precision.

Parameters:

nametypeoptionaldescription
indexnumberNoThe index of the member to get.

Returns: Phaser.Types.GameObjects.SpriteGPULayer.Member - The member data, or null if the index is out of bounds.

Source: src/gameobjects/spritegpulayer/SpriteGPULayer.js#L1020
Since: 4.0.0

getMemberData​

<instance> getMemberData(index, [out])​

Description:

Returns the raw data of a member of the SpriteGPULayer.

This can be useful as the base of efficient editing operations,

including calls to addData and patchMember,

so no data has to be converted.

This returns an Uint32Array copied from the buffer.

Editing it will not change anything in the SpriteGPULayer.

The array will be functionally identical to the data used to

create the buffer.

By default, the data is copied into this.nextMember.

You can use the views this.nextMemberF32 and this.nextMemberU32

to access the data in different formats.

If you provide an out parameter, the data will be copied to that array,

and you must construct your own views.

The primary data view is a 41-element array of 32-bit floats.

Some values are grouped to form animations, of the form:

  • 0: base value

  • 1: amplitude

  • 2: duration (if negative, the animation will yoyo)

  • 3: delay (the integer part is the easing, the decimal part is the delay divided by 2 * duration; if negative, the animation will not loop)

The overall structure is thus:

  • 0-3: x (animation)

  • 4-7: y (animation)

  • 8-11: rotation (animation)

  • 12-15: scaleX (animation)

  • 16-19: scaleY (animation)

  • 20-23: alpha (animation)

  • 24-27: frame index (animation)

  • 28-31: tintBlend (animation)

  • 32-35: no data

  • 36: originX

  • 37: originY

  • 38: tintFill

  • 39: creationTime

  • 40: scrollFactorX

  • 41: scrollFactorY

Elements 32-35 are only visible in the Uint32Array view.

They store 32-bit RGBA values for the four corners of the tint:

  • 32: bottom-left

  • 33: top-left

  • 34: bottom-right

  • 35: top-right

If the ease for an animation is 'Gravity', the amplitude is replaced

with a two-part value: the integer part is the velocity,

and the fractional part is the gravityFactor.

Parameters:

nametypeoptionaldescription
indexnumberNoThe index of the member to get.
outUint32ArrayYesAn optional array to copy the data to. If not provided, this.nextMember will be populated, and nextMemberU32 will be returned.

Returns: Uint32Array - The member data, or null if the index is out of bounds.

Source: src/gameobjects/spritegpulayer/SpriteGPULayer.js#L1128
Since: 4.0.0

getShaderFeatures​

<instance> getShaderFeatures()​

Description:

Return a list of features to enable in the shader program.

This is used when the shader program is compiled.

Returns: Array.<string> - An array of features to enable in the shader program.

Source: src/gameobjects/spritegpulayer/SpriteGPULayer.js#L444
Since: 4.0.0

insertMembers​

<instance> insertMembers(index, members)​

Description:

Inserts members into the SpriteGPULayer.

This will update the GPU buffer.

This is an expensive operation, as it requires the whole buffer to be

updated after the insertion point.

Parameters:

nametypeoptionaldescription
indexnumberNoThe index at which to insert members.
membersPhaser.Types.GameObjects.SpriteGPULayer.Member | Array.<Phaser.Types.GameObjects.SpriteGPULayer.Member>NoThe members to insert.

Returns: Phaser.GameObjects.SpriteGPULayer - This SpriteGPULayer object.

Source: src/gameobjects/spritegpulayer/SpriteGPULayer.js#L1261
Since: 4.0.0

insertMembersData​

<instance> insertMembersData(index, data)​

Description:

Inserts raw data into the SpriteGPULayer.

This will update the GPU buffer.

This is an expensive operation, as it requires the whole buffer to be

updated after the insertion point.

The data must be passed in as a Uint32Array.

This will preserve data that other TypedArrays would not.

As it uses an underlying ArrayBuffer, you can work on the data

with any TypedArray view before submitting it.

The buffer can contain 1 or more members.

Ensure that the buffer is the correct size for the number of members.

See getMemberData for the structure of the data.

Note that, if you add a member with an animation,

the animation must either already be enabled,

or you must enable it with setAnimationEnabled,

e.g. layer.setAnimationEnabled('Linear', true) or

layer.setAnimationEnabled(layer.EASE_CODES[layer.EASE.Linear], true).

Parameters:

nametypeoptionaldescription
indexnumberNoThe index at which to insert members.
dataUint32ArrayNoThe members to insert.

Returns: Phaser.GameObjects.SpriteGPULayer - This SpriteGPULayer object.

Source: src/gameobjects/spritegpulayer/SpriteGPULayer.js#L1322
Since: 4.0.0

patchMember​

<instance> patchMember(index, member, [mask])​

Description:

Update a member of the SpriteGPULayer with raw data.

This will update the member's data in the GPU buffer.

This is an expensive operation, as it requires the whole buffer to be updated.

You can supply a mask to control which properties are updated.

This can be useful for updating only a subset of properties.

Try using getMemberData to copy an existing member's data,

then modify the data you want to change.

The data must be passed in as an Uint32Array.

This will preserve data that other TypedArrays would not.

As it uses an underlying ArrayBuffer, you can work on the data

with any TypedArray view before submitting it.

Parameters:

nametypeoptionaldescription
indexnumberNoThe index of the member to patch.
memberUint32ArrayNoThe new member data.
maskArray.<number>YesThe mask to apply to the member data. A value of 1 will update the member data, a value of 0 will keep the existing member data.

Source: src/gameobjects/spritegpulayer/SpriteGPULayer.js#L966
Since: 4.0.0

preDestroy​

<instance> preDestroy()​

Description:

Internal destroy handler, called as part of the destroy process.

Access: protected

Source: src/gameobjects/spritegpulayer/SpriteGPULayer.js#L1601
Since: 4.0.0

removeMembers​

<instance> removeMembers(index, [count])​

Description:

Removes a member or a number of members from the SpriteGPULayer.

This will update the GPU buffer.

This is an expensive operation, as it requires the whole buffer to be updated.

The buffer is not resized.

Parameters:

nametypeoptionaldefaultdescription
indexnumberNoThe index of the member to remove.
countnumberYes1The number of members to remove, default 1.

Returns: Phaser.GameObjects.SpriteGPULayer - This SpriteGPULayer object.

Source: src/gameobjects/spritegpulayer/SpriteGPULayer.js#L1214
Since: 4.0.0

resize​

<instance> resize(count, [clear])​

Description:

Resizes the SpriteGPULayer buffer to a new size.

Optionally, clears the buffer.

This is an expensive operation, as it requires the whole buffer to be updated.

It can take many frames to complete.

Parameters:

nametypeoptionaldefaultdescription
countnumberNoThe new number of members in the SpriteGPULayer.
clearbooleanYesfalseWhether to clear the buffer.

Returns: Phaser.GameObjects.SpriteGPULayer - This SpriteGPULayer object.

Source: src/gameobjects/spritegpulayer/SpriteGPULayer.js#L634
Since: 4.0.0

setAllSegmentsNeedUpdate​

<instance> setAllSegmentsNeedUpdate()​

Description:

Sets all segments of the buffer to require an update.

Source: src/gameobjects/spritegpulayer/SpriteGPULayer.js#L697
Since: 4.0.0

setAnimationEnabled​

<instance> setAnimationEnabled(name, enabled)​

Description:

Set the enabled state of an animation.

This will enable or disable the animation in the shader program.

This method is called automatically when animations are added with

addMember, so you should not need to call it manually.

Every enabled animation has a cost in the shader program.

In particular, low-end devices may be unable to compile a large number

of animations, so be careful when enabling many animations.

Note that animations are not disabled automatically,

even if they are not used by any members.

There are probably too many members for this to be efficient.

Parameters:

nametypeoptionaldescription
namestringNoThe name of the animation to enable or disable.
enabledbooleanNoWhether to enable or disable the animation.

Returns: Phaser.GameObjects.SpriteGPULayer - This SpriteGPULayer object

Source: src/gameobjects/spritegpulayer/SpriteGPULayer.js#L1574
Since: 4.0.0

setAnimations​

<instance> setAnimations(animations)​

Description:

Set the animations available to the SpriteGPULayer.

This will call generateFrameDataTexture to regenerate

frameDataTexture.

Each animation can be either an Animation object, or an object

containing a name, duration, and an array of frame names/numbers.

If an Animation is used, it will be converted to the object form,

discarding any custom individual frame durations

and using the animation's duration as default.

This is not a Phaser Animation. It is intended to cycle automatically

on the GPU without supervision or interaction. It will not emit events,

allow you to pause the animation, set number of repeats, etc.

Parameters:

nametypeoptionaldescription
animationsArray.<Phaser.Animations.Animation> | Array.<Phaser.Types.GameObjects.SpriteGPULayer.SetAnimation>NoAn array of animations to set.

Returns: Phaser.GameObjects.SpriteGPULayer - This SpriteGPULayer object.

Source: src/gameobjects/spritegpulayer/SpriteGPULayer.js#L470
Since: 4.0.0

setSegmentNeedsUpdate​

<instance> setSegmentNeedsUpdate(index)​

Description:

Sets a segment of the buffer to require an update.

Parameters:

nametypeoptionaldescription
indexnumberNoThe index at which an update occurred, which requires the segment to be updated.

Source: src/gameobjects/spritegpulayer/SpriteGPULayer.js#L676
Since: 4.0.0