Mirrors/phaser
2
0
Fork 0
mirror of https://github.com/photonstorm/phaser synced 2024-11-24 21:53:59 +00:00
Code Issues Projects Releases Packages Wiki Activity

Add Changelog for WebGL Context Restore.

Browse source
This commit is contained in:
Ben Richards 2024-02-02 23:06:21 +13:00
parent 49e9d45435
commit b7f91a6c16
2 changed files with 232 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
changelog/3.80/CHANGELOG-v3.80.md
View file

@ -3,6 +3,7 @@
# New Features # New Features
* The Scale Manager has a new scale mode called `EXPAND`. This is inspired by the Expand mode in Godot: "Keep aspect ratio when stretching the screen, but keep neither the base width nor height. Depending on the screen aspect ratio, the viewport will either be larger in the horizontal direction (if the screen is wider than the base size) or in the vertical direction (if the screen is taller than the original size)" (thanks @rexrainbow) * The Scale Manager has a new scale mode called `EXPAND`. This is inspired by the Expand mode in Godot: "Keep aspect ratio when stretching the screen, but keep neither the base width nor height. Depending on the screen aspect ratio, the viewport will either be larger in the horizontal direction (if the screen is wider than the base size) or in the vertical direction (if the screen is taller than the original size)" (thanks @rexrainbow)
* Phaser now performs a [WebGL Context Restore](WebGLContextRestore.md) to keep the game running after losing WebGL context. This affects many parts of the rendering system, but everything should work just the same unless you're doing something very technical. See the link for more details.
# Updates # Updates

231
changelog/3.80/WebGLContextRestore.md Normal file
View file

@ -0,0 +1,231 @@
# Phaser 3.80.0 Change Log
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 Object Wrappers
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.
```js
const webGLLoseContextExtension = game.renderer.getExtension('WEBGL_lose_context');
setTimeout(function () {
webGLLoseContextExtension.loseContext();
setTimeout(function () {
webGLLoseContextExtension.restoreContext();
}, 1000)
}, 1000);
```
### Supporting Changes
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[]`
- Added method `removePostPipeline(pipeline: PostFXPipeline)`
- Added method `restoreContext()`, used after context is restored
- `Phaser.Renderer.WebGL.RenderTarget`
- `framebuffer` property type changed from `WebGLFramebuffer` to `WebGLFramebufferWrapper`
- `texture` parameter type changed from `WebGLTexture` to `WebGLTextureWrapper`
- `#unbind` method:
- Return type changed from `WebGLFramebuffer` to `WebGLFramebufferWrapper`
- `Phaser.Renderer.WebGL.WebGLPipeline`
- `vertexBuffer` property type changed from `WebGLBuffer` to `WebGLBufferWrapper`
- `activeBuffer` property type changed from `WebGLBuffer` to `WebGLBufferWrapper`
- `currentTexture` property type changed from `WebGLTexture` to `WebGLTextureWrapper`
- `activeTextures` property type changed from `WebGLTexture[]` to `WebGLTextureWrapper[]`
- `#setShader` method:
- `vertexBuffer` parameter type changed from `WebGLBuffer` to `WebGLBufferWrapper`
- `#createBatch` method:
- `texture` parameter type changed from `WebGLTexture` to `WebGLTextureWrapper`
- `#addTextureToBatch` method:
- `texture` parameter type changed from `WebGLTexture` to `WebGLTextureWrapper`
- `#pushBatch` method:
- `texture` parameter type changed from `WebGLTexture` to `WebGLTextureWrapper`
- Added method `restoreContext()`, used after context is restored
- `#setVertexBuffer` method:
- `buffer` parameter type changed from `WebGLBuffer` to `WebGLBufferWrapper`
- `#batchQuad` method:
- `texture` parameter type changed from `WebGLTexture` to `WebGLTextureWrapper`
- `#batchTri` method:
- `texture` parameter type changed from `WebGLTexture` to `WebGLTextureWrapper`
- `#drawFillRect` method:
- `texture` parameter type changed from `WebGLTexture` to `WebGLTextureWrapper`
- `#setTexture2D` method:
- `texture` parameter type changed from `WebGLTexture` to `WebGLTextureWrapper`
- `#bindTexture` method:
- `texture` parameter type changed from `WebGLTexture` to `WebGLTextureWrapper`
- `Phaser.Renderer.WebGL.WebGLRenderer`
- Added property `glBufferWrappers` of type `WebGLBufferWrapper[]`
- Added property `glProgramWrappers` of type `WebGLProgramWrapper[]`
- Added property `glTextureWrappers` of type `WebGLTextureWrapper[]`
- Added property `glFramebufferWrappers` of type `WebGLFramebufferWrapper[]`
- Added property `glAttribLocationWrappers` of type `WebGLAttribLocationWrapper[]`
- Added property `glUniformLocationWrappers` of type `WebGLUniformLocationWrapper[]`
- `currentFramebuffer` property type changed from `WebGLFramebuffer` to `WebGLFramebufferWrapper`
- `fboStack` property type changed from `WebGLFramebuffer[]` to `WebGLFramebufferWrapper[]`
- `currentProgram` property type changed from `WebGLProgram` to `WebGLProgramWrapper`
- `blankTexture` property type changed from `WebGLTexture` to `WebGLTextureWrapper`
- `whiteTexture` property type changed from `WebGLTexture` to `WebGLTextureWrapper`
- Added method `createTemporaryTextures()`, used when booting on MacOS
- `#pushFramebuffer` method:
- `framebuffer` parameter changed from `WebGLFramebuffer` to `WebGLFramebufferWrapper`
- `texture` parameter changed from `WebGLTexture` to `WebGLTextureWrapper`
- `#setFramebuffer` method:
- `framebuffer` parameter changed from `WebGLFramebuffer` to `WebGLFramebufferWrapper`
- `texture` parameter changed from `WebGLTexture` to `WebGLTextureWrapper`
- `#popFramebuffer` method:
- Return type changed from `WebGLFramebuffer` to `WebGLFramebufferWrapper`
- `#setProgram` method:
- `program` parameter changed from `WebGLProgram` to `WebGLFramebufferWrapper`
- `#createTextureFromSource` method:
- Return type changed from `WebGLTexture` to `WebGLTextureWrapper`
- `#createTexture2D` method:
- `width` parameter made optional
- `height` parameter made optional
- Return type changed from `WebGLTexture` to `WebGLTextureWrapper`
- `#createFramebuffer` method:
- `texture` parameter type changed from `WebGLTexture` to `WebGLTextureWrapper`
- Return type changed from `WebGLFramebuffer` to `WebGLFramebufferWrapper`
- `#createProgram` method:
- Return type changed from `WebGLProgram` to `WebGLProgramWrapper`
- `#createVertexBuffer` method:
- Return type changed from `WebGLBuffer` to `WebGLBufferWrapper`
- Added method `createAttribLocation`
- Added method `createUniformLocation`
- `#createIndexBuffer` method:
- Return type changed from `WebGLBuffer` to `WebGLBufferWrapper`
- `#deleteTexture` method:
- `texture` parameter type changed from `WebGLTexture` to `WebGLTextureWrapper`
- `#deleteFramebuffer` method:
- `framebuffer` parameter type changed from `WebGLFramebuffer` to `WebGLFramebufferWrapper`
- `#deleteProgram` method:
- `program` parameter type changed from `WebGLProgram` to `WebGLProgramWrapper`
- Added method `deleteAttribLocation`
- Added method `deleteUniformLocation`
- `#deleteBuffer` method:
- `vertexBuffer` parameter type changed from `WebGLBuffer` to `WebGLBufferWrapper`
- `#snapshotFramebuffer` method:
- `framebuffer` parameter changed from `WebGLFramebuffer` to `WebGLFramebufferWrapper`
- `#canvasToTexture` method:
- `dstTexture` parameter type changed from `WebGLTexture` to `WebGLTextureWrapper`
- Return type changed from `WebGLTexture` to `WebGLTextureWrapper`
- `#createCanvasTexture` method:
- Return type changed from `WebGLTexture` to `WebGLTextureWrapper`
- `#updateCanvasTexture` method:
- `dstTexture` parameter type changed from `WebGLTexture` to `WebGLTextureWrapper`
- Return type changed from `WebGLTexture` to `WebGLTextureWrapper`
- `#createVideoTexture` method:
- Return type changed from `WebGLTexture` to `WebGLTextureWrapper`
- `#updateCanvasTexture` method:
- `dstTexture` parameter type changed from `WebGLTexture` to `WebGLTextureWrapper`
- Return type changed from `WebGLTexture` to `WebGLTextureWrapper`
- Added method `createUint8ArrayTexture`
- `#setTextureFilter` method:
- `texture` parameter type changed from `WebGLTexture` to `WebGLTextureWrapper`
- `Phaser.Renderers.WebGL.WebGLShader`
- `program` property type changed from `WebGLProgram` to `WebGLProgramWrapper`
- Added method `syncUniforms` for use during context recovery
- `Phaser.Renderers.WebGL.Pipelines.MultiPipeline`
- `#batchTexture` method:
- `texture` parameter type changed from `WebGLTexture` to `WebGLTextureWrapper`
- `Phaser.Renderers.WebGL.Pipelines.PreFXPipeline`
- `quadVertexBuffer` property type changed from `WebGLBuffer` to `WebGLBufferWrapper`
- `#batchQuad` method:
- `texture` parameter type changed from `WebGLTexture` to `WebGLTextureWrapper`
- `Phaser.Renderers.WebGL.Pipelines.DisplacementFXPipeline`
- `glTexture` property type changed from `WebGLTexture` to `WebGLTextureWrapper`
- `WebGLPipelineAttribute`
- `location` property changed from `number` to `-1|WebGLAttribLocationWrapper`
- `WebGLPipelineBatchEntry`
- `texture` property changed from `WebGLTexture` to `WebGLTextureWrapper`
- `WebGLPipelineUniformsConfig`
- Added property `setter` of type `?function` for use in restoring context
- `Phaser.Textures.DynamicTexture`
- `#getWebGLTexture` method:
- Return type changed from `WebGLTexture` to `WebGLTextureWrapper`
- `Phaser.Textures.Frame`
- `glTexture` property type changed from `WebGLTexture` to `WebGLTextureWrapper`
- Property is now read-only
- `Phaser.Textures.Texture`
- Constructor
- `source` parameter type options added `WebGLTextureWrapper`
- `Phaser.Textures.TextureManager`
- `#addGLTexture` method:
- `glTexture` parameter type changed from `WebGLTexture` to `WebGLTextureWrapper`
- `width` parameter removed
- `height` parameter removed
- Added method `addUint8Array` for creating textures from raw colour data
- `Phaser.Textures.TextureSource`
- `glTexture` property type changed from `WebGLTexture` to `WebGLTextureWrapper`
- `Phaser.Tilemaps.Tileset`
- `glTexture` property type changed from `WebGLTexture` to `WebGLTextureWrapper`