Return to the [Change Log index](CHANGELOG-v3.80.md).
## WebGL Context Restore
Phaser now performs a WebGL context restore.
WebGL can lose context when the browser wants to reclaim resources. This happens most often when a browser tab is inactive. When it happens is beyond the control of web developers.
When context is lost, the game canvas goes blank. A lost context loses all the data that was sent to the WebGL system. It cannot do anything until the browser restores the context, usually when the user returns to their tab.
Phaser now restores this data, with a few exceptions, allowing your games to seamlessly resume. For the most part, your WebGL games should now simply recover when the browser restores the WebGL context.
Key concepts:
-`WebGLRenderer` emits `LOSE_WEBGL` and `RESTORE_WEBGL` events.
- Dynamic textures are cleared.
- WebGL objects are now enclosed in wrappers.
- You can test WebGL context restore with WebGL extensions.
- Supporting changes were made to the rendering system.
### Events
`Phaser.Renderers.WebGL.WebGLRenderer` now emits events that you can use to stay informed about context loss.
-`Phaser.Renderer.Events#LOSE_WEBGL` is emitted when context is lost. This would be a good time to pause the game, or otherwise avoid making changes that the player cannot see.
-`Phaser.Renderer.Events#RESTORE_WEBGL` is emitted when context is restored. This would be a good time to restore dynamic textures, and start things moving again.
### Dynamic Textures
Dynamic textures and render textures are stored on the GPU. When context is lost, the texture is erased. When context is restored, the texture is re-enabled, but it remains blank.
A render texture which is redrawn every frame will naturally redraw itself.
Textures which are drawn once, however, will stay blank. You should listen for the `RESTORE_WEBGL` event to know when to redraw them.
WebGL objects are now wrapped. The wrapper holds the necessary information to automatically recreate the object when context is restored.
This is only relevant if you need deep access to the WebGL renderer.
Wrappers are created and managed by the `WebGLRenderer`. They have the following qualities:
- A property for the wrapped WebGL object, for use in rendering. This property should only be accessed within a call to WebGL; it may be changed within the wrapper.
-`createResource()`, which will create a new WebGL object from stored information.
-`destroy()`, which will remove the object. Do not call this directly; it is managed by the `WebGLRenderer`.
The following wrappers are available in the `Phaser.Renderer.WebGL.Wrappers` namespace:
-`WebGLAttribLocationWrapper`
-`WebGLBufferWrapper`
-`WebGLFramebufferWrapper`
-`WebGLProgramWrapper`
-`WebGLTextureWrapper`
-`WebGLUniformLocationWrapper`
### Testing Context Restore
You can test context loss and restore with a built-in WebGL extension. The following code snippet should be useful for testing purposes. It shows how to get the built-in extension, and simulate losing and restoring the context after 1 and 2 seconds respectively.
Several changes were made to the rendering system to support these improvements. In particular, many properties were changed to use wrappers instead of raw WebGL objects. The full list of changes is as follows:
-`Phaser.FX.Displacement`
-`glTexture` property type changed from `WebGLTexture` to `WebGLTextureWrapper`
-`BatchChar`
- Constructor:
-`texture` parameter type changed from `WebGLTexture` to `WebGLTextureWrapper`
-`Phaser.GameObjects.Shader`
-`vertexBuffer` property type changed from `WebGLBuffer` to `WebGLBufferWrapper`
-`program` property type changed from `WebGLProgram` to `WebGLProgramWrapper`
-`framebuffer` property type changed from `WebGLFramebuffer` to `WebGLFramebufferWrapper`
-`glTexture` property type changed from `WebGLTexture` to `WebGLTextureWrapper`
-`#initUniforms` method:
-`texture` parameter type changed from `WebGLTexture` to `WebGLTextureWrapper`
-`Phaser.GameObjects.TileSprite`
-`fillPattern` property type changed from `?(WebGLTexture|CanvasPattern)` to `?(WebGLTextureWrapper|CanvasPattern)`
-`Phaser.Renderer.WebGL.PipelineManager`
- Added property `postPipelineInstances` of type `PostFXPipeline[]`
- A texture with the key `'__NORMAL'` is created on boot if the WebGL renderer is being used. This is a 1x1 texture of colour #7f7fff, or a flat normal map.
