<div class="warning-box"> <strong class="title">Phaser CE</strong> All code shown here requires <a href="https://github.com/photonstorm/phaser/tree/master/v2-community">Phaser CE</a>, version 2.7.0 or above. </div>

If you've followed through Part 3 then Phaser is now ready to use multi texturing.

The method setTexturePriority is how you tell the renderer which textures it should batch.

It accepts a single argument, which is an array of Phaser.Cache Image keys:

function preload() {

    game.load.atlas('playerAtlas');
    game.load.atlas('enemyAtlas');
    game.load.atlas('levelAtlas');
    game.load.image('level1Background');
    game.load.atlas('UI');

}

function create() {

    game.renderer.setTexturePriority(['playerAtlas', 'enemyAtlas', 'levelAtlas', 'level1Background', 'UI']);

    ...

}

The number of textures that can be batched is hardware dependent.

If you provide more textures in the array than can be batched by the GPU, then only those at the start of the array will be used.

If your the array you pass to the method has 12 elements in it, but the GPU only supports 8 texture units, then Phaser will just bind the first 7, and ignore the rest. On more powerful devices, if the GPU supports 16 textures, it will bind them all, and your entire scene will render in one single draw call. Phaser reserves 1 texture as a 'swap texture', the rest are entirely free for use though.

Generally speaking you shouldn't provide more than 16 textures to this method. If in doubt, prioritize, and put your most important textures first in the array.

You can check the hardware limit via the renderer.maxTextures property.

Note that the Canvas Renderer also has a dummy setTexturePriority method, so you can call it safely in your game, no matter which renderer is being used.

Changing the Batch

When you call setTexturePriority it will return a new array that contains the keys of the textures that were successfully batched.

You can also check the WebGL Renderer property currentBatchedTextures at any time, to see which textures are currently being batched.

To stop all textures from being batched, call setTexturePriority with an empty array.

To change the textures being batched, call setTexturePriority with a new array of image keys. The old ones will all be purged out and no-longer batched, and the new ones enabled.

Changing a Single Texture

You can also change a texture priority at any time. Although we'd never suggest doing it in the main loop of your game, you could easily do it at a less vital time, such as when the game changes to a new level. This gives you the control to instruct Phaser which of the textures are the most important, depending on what your game needs at that moment in time.

You can do this by changing the BaseTexture.textureIndex property. Be sure that the new texture index doesn't clash with one already assigned, and isn't out of bounds (i.e. higher than the GPU supports). With careful use, you now have fine-grained control over exactly what is bound, and when.