Merge pull request #3276 from meganrogge/webgl

add onContextLoss to webgl addon

addons/xterm-addon-webgl/README.md

@@ -19,3 +19,18 @@ terminal.loadAddon(new WebglAddon());
 ```
 
 See the full [API](https://github.com/xtermjs/xterm.js/blob/master/addons/xterm-addon-webgl/typings/xterm-addon-webgl.d.ts) for more advanced usage.
+
+### Handling Context Loss
+
+The browser may drop WebGL contexts for various reasons like OOM or after the system has been suspended. There is an API exposed that fires the `webglcontextlost` event fired on the canvas so embedders can handle it however they wish. An easy, but suboptimal way, to handle this is by disposing of WebglAddon when the event fires:
+
+```ts
+const terminal = new Terminal();
+const addon = new WebglAddon();
+addon.onContextLoss(e => {
+  addon.dispose();
+});
+terminal.loadAddon(addon);
+```
+
+Read more about handling WebGL context losses on the [Khronos wiki](https://www.khronos.org/webgl/wiki/HandlingContextLost).

addons/xterm-addon-webgl/src/WebglAddon.ts

@@ -3,14 +3,17 @@
  * @license MIT
  */
 
-import { Terminal, ITerminalAddon } from 'xterm';
+import { Terminal, ITerminalAddon, IEvent } from 'xterm';
 import { WebglRenderer } from './WebglRenderer';
 import { IRenderService } from 'browser/services/Services';
 import { IColorSet } from 'browser/Types';
+import { EventEmitter } from 'common/EventEmitter';
 
 export class WebglAddon implements ITerminalAddon {
   private _terminal?: Terminal;
   private _renderer?: WebglRenderer;
+  private _onContextLoss = new EventEmitter<void>();
+  public get onContextLoss(): IEvent<void> { return this._onContextLoss.event; }
 
   constructor(
     private _preserveDrawingBuffer?: boolean
@@ -24,6 +27,7 @@ export class WebglAddon implements ITerminalAddon {
     const renderService: IRenderService = (<any>terminal)._core._renderService;
     const colors: IColorSet = (<any>terminal)._core._colorManager.colors;
     this._renderer = new WebglRenderer(terminal, colors, this._preserveDrawingBuffer);
+    this._renderer.onContextLoss(() => this._onContextLoss.fire());
     renderService.setRenderer(this._renderer);
   }
 

addons/xterm-addon-webgl/src/WebglRenderer.ts

@@ -19,6 +19,7 @@ import { IRenderDimensions, IRenderer, IRequestRedrawEvent } from 'browser/rende
 import { ITerminal, IColorSet } from 'browser/Types';
 import { EventEmitter } from 'common/EventEmitter';
 import { CellData } from 'common/buffer/CellData';
+import { addDisposableDomListener } from 'browser/Lifecycle';
 
 export class WebglRenderer extends Disposable implements IRenderer {
   private _renderLayers: IRenderLayer[];
@@ -41,6 +42,9 @@ export class WebglRenderer extends Disposable implements IRenderer {
   private _onRequestRedraw = new EventEmitter<IRequestRedrawEvent>();
   public get onRequestRedraw(): IEvent<IRequestRedrawEvent> { return this._onRequestRedraw.event; }
 
+  private _onContextLoss = new EventEmitter<void>();
+  public get onContextLoss(): IEvent<void> { return this._onContextLoss.event; }
+
   constructor(
     private _terminal: Terminal,
     private _colors: IColorSet,
@@ -82,6 +86,9 @@ export class WebglRenderer extends Disposable implements IRenderer {
     if (!this._gl) {
       throw new Error('WebGL2 not supported ' + this._gl);
     }
+
+    this.register(addDisposableDomListener(this._canvas, 'webglcontextlost', (e) => { this._onContextLoss.fire(e); }));
+
     this._core.screenElement!.appendChild(this._canvas);
 
     this._rectangleRenderer = new RectangleRenderer(this._terminal, this._colors, this._gl, this.dimensions);

addons/xterm-addon-webgl/typings/xterm-addon-webgl.d.ts

@@ -3,6 +3,7 @@
  * @license MIT
  */
 
+import { IEvent } from 'node-pty';
 import { Terminal, ITerminalAddon } from 'xterm';
 
 declare module 'xterm-addon-webgl' {
@@ -29,5 +30,10 @@ declare module 'xterm-addon-webgl' {
      * Clears the terminal's texture atlas and triggers a redraw.
      */
     public clearTextureAtlas(): void;
+
+    /**
+     * Fired when the WebglRenderer loses context
+     */
+    public get onContextLoss(): IEvent<void>;
   }
 }