From 780cbef3cfb296513acd7774284377d73cae5d1d Mon Sep 17 00:00:00 2001 From: Anthony Kim Date: Sat, 4 Jul 2026 14:43:52 -0700 Subject: [PATCH 1/6] Add shared atlas page merge garble repro --- .../test/WebglSharedAtlasGarble.test.ts | 201 ++++++++++++++++++ 1 file changed, 201 insertions(+) create mode 100644 addons/addon-webgl/test/WebglSharedAtlasGarble.test.ts diff --git a/addons/addon-webgl/test/WebglSharedAtlasGarble.test.ts b/addons/addon-webgl/test/WebglSharedAtlasGarble.test.ts new file mode 100644 index 000000000..cfd7af785 --- /dev/null +++ b/addons/addon-webgl/test/WebglSharedAtlasGarble.test.ts @@ -0,0 +1,201 @@ +/** + * Copyright (c) 2025 The xterm.js authors. All rights reserved. + * @license MIT + */ + +import { IImage32, decodePng } from '@lunapaint/png-codec'; +import test, { expect } from '@playwright/test'; +import { ITestContext, createTestContext, openTerminal } from '../../../test/playwright/TestUtils'; + +type CellSignature = number[]; + +const HEADER = ' HEADER_REF_0123456789'; +const HEADER_COLS = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]; +const TERM_B_SELECTOR = '#terminal-container-b .xterm-screen'; + +async function loadWebglStrict(ctx: ITestContext): Promise { + await ctx.page.evaluate(() => { + const w = window as any; + w.addon = new w.WebglAddon({ preserveDrawingBuffer: true }); + w.term.loadAddon(w.addon); + }); + const isWebglRenderer = await ctx.page.evaluate(() => { + const w = window as any; + return !!w.addon && w.term?._core?._renderService?._renderer?.value === w.addon._renderer; + }); + expect(isWebglRenderer, 'WebGL renderer must be active').toBe(true); +} + +async function createTerminalB(ctx: ITestContext): Promise { + await ctx.page.evaluate(() => { + const w = window as any; + w.termB?.dispose(); + document.getElementById('terminal-container-b')?.remove(); + const el = document.createElement('div'); + el.id = 'terminal-container-b'; + document.body.appendChild(el); + w.termB = new w.Terminal({ cols: 80, rows: 24, allowProposedApi: true }); + w.termB.open(el); + w.addonB = new w.WebglAddon({ preserveDrawingBuffer: true }); + w.termB.loadAddon(w.addonB); + }); +} + +async function writeToBAndWaitForRender(ctx: ITestContext, data: string): Promise { + await ctx.page.evaluate(d => new Promise(resolve => { + const termB = (window as any).termB; + const disposable = termB.onRender(() => { + disposable.dispose(); + resolve(); + }); + termB.write(d); + }), data); +} + +async function writeAndWaitForRender(ctx: ITestContext, data: string): Promise { + const renderPromise = new Promise(resolve => { + const disposable = ctx.proxy.onRender(() => { + disposable.dispose(); + resolve(); + }); + }); + await ctx.proxy.write(data); + await renderPromise; +} + +async function setMaxAtlasPages(ctx: ITestContext, maxAtlasPages: number): Promise { + const applied = await ctx.page.evaluate(max => { + const atlas = (window as any).term?._core?._renderService?._renderer?.value?._charAtlas; + if (!atlas) { + return false; + } + (atlas.constructor as any).maxAtlasPages = max; + return true; + }, maxAtlasPages); + expect(applied, 'should be able to set TextureAtlas.maxAtlasPages').toBe(true); +} + +async function resetMaxAtlasPages(ctx: ITestContext): Promise { + await ctx.page.evaluate(() => { + const atlas = (window as any).term?._core?._renderService?._renderer?.value?._charAtlas; + if (atlas) { + (atlas.constructor as any).maxAtlasPages = undefined; + } + }); +} + +function generateColoredAsciiFlood(cells: number, offset: number = 0): string { + const letters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789'; + let out = ''; + for (let i = 0; i < cells; i++) { + const ch = letters[(offset + i) % letters.length]; + const fg = (offset + i) % 256; + const bg = (offset + i * 7) % 256; + out += `\x1b[38;5;${fg}m\x1b[48;5;${bg}m${ch}`; + if ((i + 1) % 78 === 0 && i + 1 < cells) { + out += '\x1b[0m\r\n'; + } + } + return out + '\x1b[0m'; +} + +async function captureRowSignatures(ctx: ITestContext, row: number, cols: number[]): Promise { + const screenshotOptions = process.env.DEBUG ? { path: 'out-esbuild-test/playwright/shared-atlas-term-b.png' } : undefined; + const buffer = await ctx.page.locator(TERM_B_SELECTOR).screenshot(screenshotOptions); + const frame = { + cols: 80, + rows: 24, + decoded: (await decodePng(new Uint8Array(buffer), { force32: true })).image + }; + return cols.map(col => cellSignature(frame, col, row)); +} + +function cellSignature(frame: { cols: number, rows: number, decoded: IImage32 }, col: number, row: number): CellSignature { + const grid = 4; + const data = frame.decoded.data; + const imageWidth = frame.decoded.width; + const cellWidth = frame.decoded.width / frame.cols; + const cellHeight = frame.decoded.height / frame.rows; + const x0 = (col - 1) * cellWidth; + const y0 = (row - 1) * cellHeight; + const sums = new Array(grid * grid * 4).fill(0); + const counts = new Array(grid * grid).fill(0); + const startX = Math.max(0, Math.floor(x0)); + const startY = Math.max(0, Math.floor(y0)); + const endX = Math.min(frame.decoded.width, Math.ceil(x0 + cellWidth)); + const endY = Math.min(frame.decoded.height, Math.ceil(y0 + cellHeight)); + + for (let y = startY; y < endY; y++) { + const gy = Math.min(grid - 1, Math.max(0, Math.floor(((y - y0) / cellHeight) * grid))); + for (let x = startX; x < endX; x++) { + const gx = Math.min(grid - 1, Math.max(0, Math.floor(((x - x0) / cellWidth) * grid))); + const sub = gy * grid + gx; + const i = (y * imageWidth + x) * 4; + sums[sub * 4] += data[i]; + sums[sub * 4 + 1] += data[i + 1]; + sums[sub * 4 + 2] += data[i + 2]; + sums[sub * 4 + 3] += data[i + 3]; + counts[sub]++; + } + } + + const signature = new Array(grid * grid * 4).fill(0); + for (let sub = 0; sub < counts.length; sub++) { + if (counts[sub] > 0) { + signature[sub * 4] = sums[sub * 4] / counts[sub]; + signature[sub * 4 + 1] = sums[sub * 4 + 1] / counts[sub]; + signature[sub * 4 + 2] = sums[sub * 4 + 2] / counts[sub]; + signature[sub * 4 + 3] = sums[sub * 4 + 3] / counts[sub]; + } + } + return signature; +} + +function expectSignatureMatches(actual: CellSignature, reference: CellSignature, message: string): void { + let diff = 0; + for (let i = 0; i < actual.length; i++) { + diff = Math.max(diff, Math.abs(actual[i] - reference[i])); + } + expect(diff, `${message}; max channel diff ${diff}`).toBeLessThanOrEqual(14); +} + +test.describe('shared-atlas garble across terminals (#6038)', () => { + test.skip(({ browserName }) => browserName !== 'chromium'); + test.describe.configure({ timeout: 60000 }); + + test('keeps a second terminal rendering correctly after shared atlas page merges', async ({ browser }) => { + const ctx = await createTestContext(browser); + try { + await openTerminal(ctx, { cols: 80, rows: 24 }); + await loadWebglStrict(ctx); + await createTerminalB(ctx); + + const atlasShared = await ctx.page.evaluate(() => { + const w = window as any; + return w.term._core._renderService._renderer.value._charAtlas === w.termB._core._renderService._renderer.value._charAtlas; + }); + expect(atlasShared, 'terminals with equal configs should share one texture atlas').toBe(true); + + await setMaxAtlasPages(ctx, 4); + + await writeToBAndWaitForRender(ctx, HEADER); + const reference = await captureRowSignatures(ctx, 1, HEADER_COLS); + + for (let c = 0; c < 10; c++) { + await writeAndWaitForRender(ctx, '\x1b[2;1H' + generateColoredAsciiFlood(23 * 78, c * 23 * 78)); + } + + await writeToBAndWaitForRender(ctx, '\x1b[24;1Hx'); + const termBHeader = await ctx.page.evaluate(() => (window as any).termB.buffer.active.getLine(0)?.translateToString(true)); + expect(termBHeader, 'terminal B buffer must still contain the header').toBe(HEADER); + + const after = await captureRowSignatures(ctx, 1, HEADER_COLS); + for (let i = 0; i < HEADER_COLS.length; i++) { + expectSignatureMatches(after[i], reference[i], `terminal B header col ${HEADER_COLS[i]} garbled by terminal A's atlas merges`); + } + } finally { + await resetMaxAtlasPages(ctx).catch(() => {}); + await ctx.page.close(); + } + }); +}); From 6fe6fe1af303a4ed0b5e6ae2ab393dfd2be09347 Mon Sep 17 00:00:00 2001 From: Anthony Kim Date: Sat, 4 Jul 2026 14:44:23 -0700 Subject: [PATCH 2/6] Fix shared atlas page invalidation per renderer --- addons/addon-webgl/src/GlyphRenderer.ts | 11 ++++++++++- addons/addon-webgl/src/TextureAtlas.ts | 16 ++++++---------- addons/addon-webgl/src/Types.ts | 5 ++--- 3 files changed, 18 insertions(+), 14 deletions(-) diff --git a/addons/addon-webgl/src/GlyphRenderer.ts b/addons/addon-webgl/src/GlyphRenderer.ts index be1990c2a..1289adec2 100644 --- a/addons/addon-webgl/src/GlyphRenderer.ts +++ b/addons/addon-webgl/src/GlyphRenderer.ts @@ -100,6 +100,7 @@ export class GlyphRenderer extends Disposable { private readonly _attributesBuffer: WebGLBuffer; private _atlas: ITextureAtlas | undefined; + private _lastAtlasPagesVersion: number = -1; private _activeBuffer: number = 0; private readonly _vertices: IVertices = { count: 0, @@ -214,7 +215,14 @@ export class GlyphRenderer extends Disposable { } public beginFrame(): boolean { - return this._atlas ? this._atlas.beginFrame() : true; + if (!this._atlas) { + return true; + } + if (this._atlas.pagesVersion !== this._lastAtlasPagesVersion) { + this._lastAtlasPagesVersion = this._atlas.pagesVersion; + return true; + } + return false; } public updateCell(x: number, y: number, code: number, bg: number, fg: number, ext: number, chars: string, width: number, lastBg: number): void { @@ -375,6 +383,7 @@ export class GlyphRenderer extends Disposable { public setAtlas(atlas: ITextureAtlas): void { this._atlas = atlas; + this._lastAtlasPagesVersion = -1; this.invalidateAtlasTextures(); } diff --git a/addons/addon-webgl/src/TextureAtlas.ts b/addons/addon-webgl/src/TextureAtlas.ts index 1c3e08a1c..73056b87e 100644 --- a/addons/addon-webgl/src/TextureAtlas.ts +++ b/addons/addon-webgl/src/TextureAtlas.ts @@ -132,12 +132,8 @@ export class TextureAtlas implements ITextureAtlas { } } - private _requestClearModel = false; - public beginFrame(): boolean { - const result = this._requestClearModel; - this._requestClearModel = false; - return result; - } + private _pagesVersion = 0; + public get pagesVersion(): number { return this._pagesVersion; } public clearTexture(): void { if (this._pages[0].currentRow.x === 0 && this._pages[0].currentRow.y === 0) { @@ -206,8 +202,8 @@ export class TextureAtlas implements ITextureAtlas { // Add the new merged page to the end this.pages.push(mergedPage); - // Request the model to be cleared to refresh all texture pages. - this._requestClearModel = true; + // Invalidate renderer models so all texture pages are refreshed. + this._pagesVersion++; this._onAddTextureAtlasCanvas.fire(mergedPage.canvas); } @@ -818,8 +814,8 @@ export class TextureAtlas implements ITextureAtlas { this._overflowSizePage = new AtlasPage(this._document, this._config.deviceMaxTextureSize); this.pages.push(this._overflowSizePage); - // Request the model to be cleared to refresh all texture pages. - this._requestClearModel = true; + // Invalidate renderer models so all texture pages are refreshed. + this._pagesVersion++; this._onAddTextureAtlasCanvas.fire(this._overflowSizePage.canvas); } activePage = this._overflowSizePage; diff --git a/addons/addon-webgl/src/Types.ts b/addons/addon-webgl/src/Types.ts index 294582e37..3a85eb4d0 100644 --- a/addons/addon-webgl/src/Types.ts +++ b/addons/addon-webgl/src/Types.ts @@ -68,10 +68,9 @@ export interface ITextureAtlas extends IDisposable { warmUp(): void; /** - * Call when a frame is being drawn, this will return true if the atlas was cleared to make room - * for a new set of glyphs. + * Incremented whenever texture page indexes or coordinates cached by renderers may be stale. */ - beginFrame(): boolean; + readonly pagesVersion: number; /** * Clear all glyphs from the texture atlas. From 77bf56066c1e2197fe7c50b415fc376ced59eb29 Mon Sep 17 00:00:00 2001 From: Anthony Kim Date: Thu, 9 Jul 2026 11:00:31 -0700 Subject: [PATCH 3/6] wordings --- addons/addon-webgl/src/GlyphRenderer.ts | 8 ++++---- addons/addon-webgl/src/Types.ts | 4 +++- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/addons/addon-webgl/src/GlyphRenderer.ts b/addons/addon-webgl/src/GlyphRenderer.ts index 1289adec2..3c77c7cf5 100644 --- a/addons/addon-webgl/src/GlyphRenderer.ts +++ b/addons/addon-webgl/src/GlyphRenderer.ts @@ -100,7 +100,7 @@ export class GlyphRenderer extends Disposable { private readonly _attributesBuffer: WebGLBuffer; private _atlas: ITextureAtlas | undefined; - private _lastAtlasPagesVersion: number = -1; + private _lastSeenPagesVersion: number = -1; private _activeBuffer: number = 0; private readonly _vertices: IVertices = { count: 0, @@ -218,8 +218,8 @@ export class GlyphRenderer extends Disposable { if (!this._atlas) { return true; } - if (this._atlas.pagesVersion !== this._lastAtlasPagesVersion) { - this._lastAtlasPagesVersion = this._atlas.pagesVersion; + if (this._atlas.pagesVersion !== this._lastSeenPagesVersion) { + this._lastSeenPagesVersion = this._atlas.pagesVersion; return true; } return false; @@ -383,7 +383,7 @@ export class GlyphRenderer extends Disposable { public setAtlas(atlas: ITextureAtlas): void { this._atlas = atlas; - this._lastAtlasPagesVersion = -1; + this._lastSeenPagesVersion = -1; this.invalidateAtlasTextures(); } diff --git a/addons/addon-webgl/src/Types.ts b/addons/addon-webgl/src/Types.ts index 3a85eb4d0..1c9a7f931 100644 --- a/addons/addon-webgl/src/Types.ts +++ b/addons/addon-webgl/src/Types.ts @@ -68,7 +68,9 @@ export interface ITextureAtlas extends IDisposable { warmUp(): void; /** - * Incremented whenever texture page indexes or coordinates cached by renderers may be stale. + * Incremented whenever cached glyph texture page indexes or coordinates may be stale. + * Each renderer tracks its own last-seen value so shared atlas changes are observed + * independently by every terminal. */ readonly pagesVersion: number; From 64ecce4f255c003cdb13d385453980d68bc5e479 Mon Sep 17 00:00:00 2001 From: Anthony Kim Date: Thu, 9 Jul 2026 11:18:29 -0700 Subject: [PATCH 4/6] Do a better job with types in testing --- .../test/WebglSharedAtlasGarble.test.ts | 80 ++++++++++++++----- 1 file changed, 61 insertions(+), 19 deletions(-) diff --git a/addons/addon-webgl/test/WebglSharedAtlasGarble.test.ts b/addons/addon-webgl/test/WebglSharedAtlasGarble.test.ts index cfd7af785..b3066b0c9 100644 --- a/addons/addon-webgl/test/WebglSharedAtlasGarble.test.ts +++ b/addons/addon-webgl/test/WebglSharedAtlasGarble.test.ts @@ -5,9 +5,52 @@ import { IImage32, decodePng } from '@lunapaint/png-codec'; import test, { expect } from '@playwright/test'; +import type { Terminal, ITerminalInitOnlyOptions, ITerminalOptions } from '@xterm/xterm'; +import type { IWebglAddonOptions, WebglAddon } from '@xterm/addon-webgl'; import { ITestContext, createTestContext, openTerminal } from '../../../test/playwright/TestUtils'; type CellSignature = number[]; +type TestTerminalConstructor = new (options?: ITerminalOptions & ITerminalInitOnlyOptions) => ITestTerminal; +type TestWebglAddonConstructor = new (options?: IWebglAddonOptions) => ITestWebglAddon; + +interface ITestTextureAtlasConstructor { + maxAtlasPages: number | undefined; +} + +interface ITestTextureAtlas { + constructor: ITestTextureAtlasConstructor; +} + +interface ITestRenderer { + _charAtlas?: ITestTextureAtlas; +} + +interface ITestRenderService { + _renderer?: { + value?: ITestRenderer; + }; +} + +interface ITestTerminal extends Terminal { + _core?: { + _renderService?: ITestRenderService; + }; +} + +interface ITestWebglAddon extends WebglAddon { + _renderer?: ITestRenderer; +} + +declare global { + interface Window { // eslint-disable-line @typescript-eslint/naming-convention + Terminal: TestTerminalConstructor; + WebglAddon: TestWebglAddonConstructor; + term: ITestTerminal; + termB?: ITestTerminal; + addon?: ITestWebglAddon; + addonB?: ITestWebglAddon; + } +} const HEADER = ' HEADER_REF_0123456789'; const HEADER_COLS = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]; @@ -15,35 +58,35 @@ const TERM_B_SELECTOR = '#terminal-container-b .xterm-screen'; async function loadWebglStrict(ctx: ITestContext): Promise { await ctx.page.evaluate(() => { - const w = window as any; - w.addon = new w.WebglAddon({ preserveDrawingBuffer: true }); - w.term.loadAddon(w.addon); + window.addon = new window.WebglAddon({ preserveDrawingBuffer: true }); + window.term.loadAddon(window.addon); }); const isWebglRenderer = await ctx.page.evaluate(() => { - const w = window as any; - return !!w.addon && w.term?._core?._renderService?._renderer?.value === w.addon._renderer; + return !!window.addon && window.term?._core?._renderService?._renderer?.value === window.addon._renderer; }); expect(isWebglRenderer, 'WebGL renderer must be active').toBe(true); } async function createTerminalB(ctx: ITestContext): Promise { await ctx.page.evaluate(() => { - const w = window as any; - w.termB?.dispose(); + window.termB?.dispose(); document.getElementById('terminal-container-b')?.remove(); const el = document.createElement('div'); el.id = 'terminal-container-b'; document.body.appendChild(el); - w.termB = new w.Terminal({ cols: 80, rows: 24, allowProposedApi: true }); - w.termB.open(el); - w.addonB = new w.WebglAddon({ preserveDrawingBuffer: true }); - w.termB.loadAddon(w.addonB); + window.termB = new window.Terminal({ cols: 80, rows: 24, allowProposedApi: true }); + window.termB.open(el); + window.addonB = new window.WebglAddon({ preserveDrawingBuffer: true }); + window.termB.loadAddon(window.addonB); }); } async function writeToBAndWaitForRender(ctx: ITestContext, data: string): Promise { await ctx.page.evaluate(d => new Promise(resolve => { - const termB = (window as any).termB; + const termB = window.termB; + if (!termB) { + throw new Error('Terminal B must be created before writing to it'); + } const disposable = termB.onRender(() => { disposable.dispose(); resolve(); @@ -65,11 +108,11 @@ async function writeAndWaitForRender(ctx: ITestContext, data: string): Promise { const applied = await ctx.page.evaluate(max => { - const atlas = (window as any).term?._core?._renderService?._renderer?.value?._charAtlas; + const atlas = window.term?._core?._renderService?._renderer?.value?._charAtlas; if (!atlas) { return false; } - (atlas.constructor as any).maxAtlasPages = max; + atlas.constructor.maxAtlasPages = max; return true; }, maxAtlasPages); expect(applied, 'should be able to set TextureAtlas.maxAtlasPages').toBe(true); @@ -77,9 +120,9 @@ async function setMaxAtlasPages(ctx: ITestContext, maxAtlasPages: number): Promi async function resetMaxAtlasPages(ctx: ITestContext): Promise { await ctx.page.evaluate(() => { - const atlas = (window as any).term?._core?._renderService?._renderer?.value?._charAtlas; + const atlas = window.term?._core?._renderService?._renderer?.value?._charAtlas; if (atlas) { - (atlas.constructor as any).maxAtlasPages = undefined; + atlas.constructor.maxAtlasPages = undefined; } }); } @@ -171,8 +214,7 @@ test.describe('shared-atlas garble across terminals (#6038)', () => { await createTerminalB(ctx); const atlasShared = await ctx.page.evaluate(() => { - const w = window as any; - return w.term._core._renderService._renderer.value._charAtlas === w.termB._core._renderService._renderer.value._charAtlas; + return window.term._core?._renderService?._renderer?.value?._charAtlas === window.termB?._core?._renderService?._renderer?.value?._charAtlas; }); expect(atlasShared, 'terminals with equal configs should share one texture atlas').toBe(true); @@ -186,7 +228,7 @@ test.describe('shared-atlas garble across terminals (#6038)', () => { } await writeToBAndWaitForRender(ctx, '\x1b[24;1Hx'); - const termBHeader = await ctx.page.evaluate(() => (window as any).termB.buffer.active.getLine(0)?.translateToString(true)); + const termBHeader = await ctx.page.evaluate(() => window.termB?.buffer.active.getLine(0)?.translateToString(true)); expect(termBHeader, 'terminal B buffer must still contain the header').toBe(HEADER); const after = await captureRowSignatures(ctx, 1, HEADER_COLS); From 46556eb6cf953ff61ef5d4b02a2c192cdd5ee782 Mon Sep 17 00:00:00 2001 From: Anthony Kim Date: Thu, 9 Jul 2026 11:32:23 -0700 Subject: [PATCH 5/6] Rename to pageLayoutVersion --- addons/addon-webgl/src/GlyphRenderer.ts | 8 ++++---- addons/addon-webgl/src/TextureAtlas.ts | 12 ++++++------ addons/addon-webgl/src/Types.ts | 6 +++--- 3 files changed, 13 insertions(+), 13 deletions(-) diff --git a/addons/addon-webgl/src/GlyphRenderer.ts b/addons/addon-webgl/src/GlyphRenderer.ts index 3c77c7cf5..dcba0b4b8 100644 --- a/addons/addon-webgl/src/GlyphRenderer.ts +++ b/addons/addon-webgl/src/GlyphRenderer.ts @@ -100,7 +100,7 @@ export class GlyphRenderer extends Disposable { private readonly _attributesBuffer: WebGLBuffer; private _atlas: ITextureAtlas | undefined; - private _lastSeenPagesVersion: number = -1; + private _lastSeenPageLayoutVersion: number = -1; private _activeBuffer: number = 0; private readonly _vertices: IVertices = { count: 0, @@ -218,8 +218,8 @@ export class GlyphRenderer extends Disposable { if (!this._atlas) { return true; } - if (this._atlas.pagesVersion !== this._lastSeenPagesVersion) { - this._lastSeenPagesVersion = this._atlas.pagesVersion; + if (this._atlas.pageLayoutVersion !== this._lastSeenPageLayoutVersion) { + this._lastSeenPageLayoutVersion = this._atlas.pageLayoutVersion; return true; } return false; @@ -383,7 +383,7 @@ export class GlyphRenderer extends Disposable { public setAtlas(atlas: ITextureAtlas): void { this._atlas = atlas; - this._lastSeenPagesVersion = -1; + this._lastSeenPageLayoutVersion = -1; this.invalidateAtlasTextures(); } diff --git a/addons/addon-webgl/src/TextureAtlas.ts b/addons/addon-webgl/src/TextureAtlas.ts index 73056b87e..5368c9b46 100644 --- a/addons/addon-webgl/src/TextureAtlas.ts +++ b/addons/addon-webgl/src/TextureAtlas.ts @@ -132,8 +132,8 @@ export class TextureAtlas implements ITextureAtlas { } } - private _pagesVersion = 0; - public get pagesVersion(): number { return this._pagesVersion; } + private _pageLayoutVersion = 0; + public get pageLayoutVersion(): number { return this._pageLayoutVersion; } public clearTexture(): void { if (this._pages[0].currentRow.x === 0 && this._pages[0].currentRow.y === 0) { @@ -202,8 +202,8 @@ export class TextureAtlas implements ITextureAtlas { // Add the new merged page to the end this.pages.push(mergedPage); - // Invalidate renderer models so all texture pages are refreshed. - this._pagesVersion++; + // Request the model to be cleared to refresh all texture pages. + this._pageLayoutVersion++; this._onAddTextureAtlasCanvas.fire(mergedPage.canvas); } @@ -814,8 +814,8 @@ export class TextureAtlas implements ITextureAtlas { this._overflowSizePage = new AtlasPage(this._document, this._config.deviceMaxTextureSize); this.pages.push(this._overflowSizePage); - // Invalidate renderer models so all texture pages are refreshed. - this._pagesVersion++; + // Request the model to be cleared to refresh all texture pages. + this._pageLayoutVersion++; this._onAddTextureAtlasCanvas.fire(this._overflowSizePage.canvas); } activePage = this._overflowSizePage; diff --git a/addons/addon-webgl/src/Types.ts b/addons/addon-webgl/src/Types.ts index 1c9a7f931..0a46a0071 100644 --- a/addons/addon-webgl/src/Types.ts +++ b/addons/addon-webgl/src/Types.ts @@ -68,11 +68,11 @@ export interface ITextureAtlas extends IDisposable { warmUp(): void; /** - * Incremented whenever cached glyph texture page indexes or coordinates may be stale. - * Each renderer tracks its own last-seen value so shared atlas changes are observed + * Incremented whenever atlas page indexes or coordinates cached by renderers may be stale. + * Each renderer tracks its own last-seen value so shared atlas layout changes are observed * independently by every terminal. */ - readonly pagesVersion: number; + readonly pageLayoutVersion: number; /** * Clear all glyphs from the texture atlas. From 9559005bbce80f7f7f10c20e9e9983e33c4e9198 Mon Sep 17 00:00:00 2001 From: Anthony Kim Date: Thu, 9 Jul 2026 11:39:38 -0700 Subject: [PATCH 6/6] wroding --- addons/addon-webgl/src/GlyphRenderer.ts | 4 ++++ addons/addon-webgl/src/Types.ts | 7 ++++--- 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/addons/addon-webgl/src/GlyphRenderer.ts b/addons/addon-webgl/src/GlyphRenderer.ts index dcba0b4b8..720427723 100644 --- a/addons/addon-webgl/src/GlyphRenderer.ts +++ b/addons/addon-webgl/src/GlyphRenderer.ts @@ -214,6 +214,10 @@ export class GlyphRenderer extends Disposable { this.handleResize(); } + /** + * Call when a frame is being drawn. Returns whether the full model must be rebuilt before + * rendering this frame because the atlas page layout changed since this renderer last drew. + */ public beginFrame(): boolean { if (!this._atlas) { return true; diff --git a/addons/addon-webgl/src/Types.ts b/addons/addon-webgl/src/Types.ts index 0a46a0071..bfd6fd76c 100644 --- a/addons/addon-webgl/src/Types.ts +++ b/addons/addon-webgl/src/Types.ts @@ -68,9 +68,10 @@ export interface ITextureAtlas extends IDisposable { warmUp(): void; /** - * Incremented whenever atlas page indexes or coordinates cached by renderers may be stale. - * Each renderer tracks its own last-seen value so shared atlas layout changes are observed - * independently by every terminal. + * Incremented whenever cached glyph texture page mappings may be stale, such as after atlas page + * merges or overflow page creation. Renderers compare this against their own last-seen value and + * rebuild their model when it changes; a shared atlas can have many renderers, so this must not + * be a consume-once flag. */ readonly pageLayoutVersion: number;