Emit LOSE_WEBGL event.

Also rearrange RESTORE_WEBGL event code.

src/renderer/events/LOSE_WEBGL_EVENT.js

@@ -0,0 +1,30 @@
+/**
+ * @author       Benjamin D. Richards <benjamindrichards@gmail.com>
+ * @copyright    2013-2023 Photon Storm Ltd.
+ * @license      {@link https://opensource.org/licenses/MIT|MIT License}
+ */
+
+/**
+ * The Lose WebGL Event.
+ *
+ * This event is dispatched by the WebGLRenderer when the WebGL context
+ * is lost.
+ *
+ * Context can be lost for a variety of reasons, like leaving the browser tab.
+ * The game canvas DOM object will dispatch `webglcontextlost`.
+ * All WebGL resources get wiped, and the context is reset.
+ *
+ * While WebGL is lost, the game will continue to run, but all WebGL resources
+ * are lost, and new ones cannot be created.
+ *
+ * Once the context is restored and the renderer has automatically restored
+ * the state, the renderer will emit a `RESTORE_WEBGL` event. At that point,
+ * it is safe to continue.
+ *
+ * @event Phaser.Renderer.Events#LOSE_WEBGL
+ * @type {string}
+ * @since 3.80.0
+ *
+ * @param {Phaser.Renderer.WebGL.WebGLRenderer} renderer - the renderer that owns the WebGL context
+ */
+module.exports = 'losewebgl';

src/renderer/events/RESTORE_WEBGL_EVENT.js

@@ -1,11 +1,11 @@
 /**
- * @author       Richard Davey <rich@photonstorm.com>
+ * @author       Benjamin D. Richards <benjamindrichards@gmail.com>
  * @copyright    2013-2023 Photon Storm Ltd.
  * @license      {@link https://opensource.org/licenses/MIT|MIT License}
  */
 
 /**
- * The Restore Event.
+ * The Restore WebGL Event.
  *
  * This event is dispatched by the WebGLRenderer when the WebGL context
  * is restored.
@@ -16,10 +16,10 @@
  * Listen to this event to know when you can safely do that.
  *
  * Context can be lost for a variety of reasons, like leaving the browser tab.
- * The browser window will dispatch `webglcontextlost` when this happens.
+ * The game canvas DOM object will dispatch `webglcontextlost`.
  * All WebGL resources get wiped, and the context is reset.
  *
- * Once the context is restored, the browser will dispatch
+ * Once the context is restored, the canvas will dispatch
  * `webglcontextrestored`. Phaser uses this to re-create necessary resources.
  * Please wait for Phaser to dispatch the `RESTORE_WEBGL` event before
  * re-creating any resources of your own.

src/renderer/events/index.js

@@ -10,6 +10,7 @@
 
 module.exports = {
 
+    LOSE_WEBGL: require('./LOSE_WEBGL_EVENT'),
     POST_RENDER: require('./POST_RENDER_EVENT'),
     PRE_RENDER: require('./PRE_RENDER_EVENT'),
     RENDER: require('./RENDER_EVENT'),

src/renderer/webgl/WebGLRenderer.js

@@ -773,6 +773,8 @@ var WebGLRenderer = new Class({
                 console.warn('WebGL Context lost. Renderer disabled');
             }
 
+            _this.emit(Events.LOSE_WEBGL, _this);
+
             event.preventDefault();
         };
 
@@ -838,9 +840,9 @@ var WebGLRenderer = new Class({
                 console.warn('WebGL Context restored. Renderer running again.');
             }
 
-            event.preventDefault();
-
             _this.emit(Events.RESTORE_WEBGL, _this);
+
+            event.preventDefault();
         };
 
         canvas.addEventListener('webglcontextrestored', this.contextRestoredHandler, false);