Add multi-texture batching for WebGL renderer (#1376)

Allows up to 16 textures in a single draw call, eliminating GPU flushes
on texture changes. ~80% fewer draw calls on the platformer example,
1000 quads/flush on the sprite benchmark with 5000 objects.

- Generate multi-texture fragment shader dynamically with per-texture
  sampler uniforms and if/else selection chain
- Static quad-multi.vert with aTextureId attribute
- push() accepts optional textureId parameter (6 floats when provided)
- uploadTexture/bindTexture2D accept flush parameter to skip flushing
- QuadBatcher falls back to single-texture when custom ShaderEffect active
- Track scissor state with _scissorActive instead of gl.isEnabled() query
- Add unit tests for push with textureId and fragment shader generation
- Add "Tap or Click to spawn" hint to benchmark example

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: obiot

packages/examples/src/examples/benchmark/ExampleBenchmark.tsx

@@ -7,6 +7,7 @@ import {
 	loader,
 	plugin,
 	ScaleMethods,
+	Text,
 	video,
 } from "melonjs";
 import { createExampleComponent } from "../utils";
@@ -65,6 +66,18 @@ const createGame = () => {
 		// reset/empty the game world
 		game.world.reset();
 
+		// add hint text
+		const hint = new Text(game.viewport.width / 2, 20, {
+			font: "Arial",
+			size: "16px",
+			fillStyle: "#ffffff",
+			textAlign: "center",
+			text: "Tap or Click to spawn more sprites",
+		});
+		hint.floating = true;
+		hint.setOpacity(0.6);
+		game.world.addChild(hint, Infinity);
+
 		addFruits(FRUIT_STEP, "watermelon");
 	});
 };

packages/melonjs/CHANGELOG.md

@@ -2,8 +2,11 @@
 
 ## [19.1.0] (melonJS 2) - _2026-04-15_
 
+### Added
+- WebGL: multi-texture batching — up to 16 textures (based on device capabilities) drawn in a single batch/draw call, eliminating GPU flushes on texture changes. Automatically falls back to single-texture mode when a custom `ShaderEffect` is active. ~80% fewer draw calls on the platformer example (14 vs ~70 flushes/frame), with an estimated 30-50% FPS improvement on low-end mobile devices.
+
 ### Changed
-- WebGL: `failIfMajorPerformanceCaveat` default changed from `true` to `false` — allows WebGL context creation on machines with blocklisted GPU drivers or software renderers, matching PixiJS and Phaser behavior
+- WebGL: `failIfMajorPerformanceCaveat` default changed from `true` to `false` — allows WebGL context creation on machines with blocklisted GPU drivers or software renderers.
 
 ### Fixed
 - WebGL: `getSupportedCompressedTextureFormats()` no longer crashes when the GL context is unavailable — falls back to the base renderer's empty format list

packages/melonjs/src/video/webgl/batchers/material_batcher.js

@@ -216,19 +216,23 @@ export class MaterialBatcher extends Batcher {
 	 * @param {WebGLTexture} texture - a WebGL texture
 	 * @param {number} unit - Texture unit to which the given texture is bound
 	 */
-	bindTexture2D(texture, unit) {
+	bindTexture2D(texture, unit, flush = true) {
 		const gl = this.gl;
 
 		if (texture !== this.boundTextures[unit]) {
-			this.flush();
+			if (flush) {
+				this.flush();
+			}
 			if (this.currentTextureUnit !== unit) {
 				this.currentTextureUnit = unit;
 				gl.activeTexture(gl.TEXTURE0 + unit);
 			}
 			gl.bindTexture(gl.TEXTURE_2D, texture);
 			this.boundTextures[unit] = texture;
 		} else if (this.currentTextureUnit !== unit) {
-			this.flush();
+			if (flush) {
+				this.flush();
+			}
 			this.currentTextureUnit = unit;
 			gl.activeTexture(gl.TEXTURE0 + unit);
 		}
@@ -256,7 +260,7 @@ export class MaterialBatcher extends Batcher {
 	/**
 	 * @ignore
 	 */
-	uploadTexture(texture, w, h, force = false) {
+	uploadTexture(texture, w, h, force = false, flush = true) {
 		const unit = this.renderer.cache.getUnit(texture);
 		const texture2D = this.boundTextures[unit];
 
@@ -273,9 +277,9 @@ export class MaterialBatcher extends Batcher {
 				texture2D,
 			);
 		} else {
-			this.bindTexture2D(texture2D, unit);
+			this.bindTexture2D(texture2D, unit, flush);
 		}
 
-		return this.currentTextureUnit;
+		return flush ? this.currentTextureUnit : unit;
 	}
 }

packages/melonjs/src/video/webgl/batchers/quad_batcher.js

@@ -1,7 +1,7 @@
 import { Vector2d } from "../../../math/vector2d.ts";
 import IndexBuffer from "../buffer/index.js";
-import quadFragment from "./../shaders/quad.frag";
-import quadVertex from "./../shaders/quad.vert";
+import { buildMultiTextureFragment } from "./../shaders/multitexture.js";
+import quadMultiVertex from "./../shaders/quad-multi.vert";
 import { MaterialBatcher } from "./material_batcher.js";
 
 /**
@@ -28,6 +28,13 @@ export default class QuadBatcher extends MaterialBatcher {
 	 * @ignore
 	 */
 	init(renderer) {
+		/**
+		 * the maximum number of texture units used for multi-texture batching
+		 * @type {number}
+		 * @ignore
+		 */
+		this.maxBatchTextures = Math.min(renderer.maxTextures, 16);
+
 		super.init(renderer, {
 			attributes: [
 				{
@@ -51,13 +58,33 @@ export default class QuadBatcher extends MaterialBatcher {
 					normalized: true,
 					offset: 4 * Float32Array.BYTES_PER_ELEMENT,
 				},
+				{
+					name: "aTextureId",
+					size: 1,
+					type: renderer.gl.FLOAT,
+					normalized: false,
+					offset: 5 * Float32Array.BYTES_PER_ELEMENT,
+				},
 			],
 			shader: {
-				vertex: quadVertex,
-				fragment: quadFragment,
+				vertex: quadMultiVertex,
+				fragment: buildMultiTextureFragment(this.maxBatchTextures),
 			},
 		});
 
+		// bind all sampler uniforms to their respective texture units
+		for (let i = 0; i < this.maxBatchTextures; i++) {
+			this.defaultShader.setUniform("uSampler" + i, i);
+		}
+
+		/**
+		 * whether multi-texture batching is currently active
+		 * (disabled when a custom ShaderEffect is applied)
+		 * @type {boolean}
+		 * @ignore
+		 */
+		this.useMultiTexture = true;
+
 		// create the index buffer for quad batching (4 verts + 6 indices per quad)
 		const maxQuads = this.vertexData.maxVertex / 4;
 		this.indexBuffer = new IndexBuffer(
@@ -68,6 +95,18 @@ export default class QuadBatcher extends MaterialBatcher {
 		this.indexBuffer.fillQuadPattern(maxQuads);
 	}
 
+	/**
+	 * Select the shader to use for compositing.
+	 * Multi-texture batching is automatically enabled when the default
+	 * shader is active, and disabled for custom ShaderEffect shaders.
+	 * @see GLShader
+	 * @param {GLShader} shader - a reference to a GLShader instance
+	 */
+	useShader(shader) {
+		super.useShader(shader);
+		this.useMultiTexture = shader === this.defaultShader;
+	}
+
 	/**
 	 * Reset compositor internal state
 	 * @ignore
@@ -83,6 +122,12 @@ export default class QuadBatcher extends MaterialBatcher {
 			this.renderer.WebGLVersion > 1,
 		);
 		this.indexBuffer.fillQuadPattern(maxQuads);
+
+		// re-bind sampler uniforms after context restore
+		for (let i = 0; i < this.maxBatchTextures; i++) {
+			this.defaultShader.setUniform("uSampler" + i, i);
+		}
+		this.useMultiTexture = true;
 	}
 
 	/**
@@ -145,11 +190,20 @@ export default class QuadBatcher extends MaterialBatcher {
 			this.flush();
 		}
 
-		const unit = this.uploadTexture(texture, w, h, reupload);
-
-		if (unit !== this.currentSamplerUnit) {
-			this.currentShader.setUniform("uSampler", unit);
-			this.currentSamplerUnit = unit;
+		let unit;
+
+		if (this.useMultiTexture) {
+			// multi-texture path: embed the texture unit in the vertex data
+			// and avoid flushing on texture changes
+			unit = this.uploadTexture(texture, w, h, reupload, false);
+		} else {
+			// single-texture fallback (custom ShaderEffect active):
+			// use regular upload which flushes on texture change, and set uSampler
+			unit = this.uploadTexture(texture, w, h, reupload);
+			if (unit !== this.currentSamplerUnit) {
+				this.currentShader.setUniform("uSampler", unit);
+				this.currentSamplerUnit = unit;
+			}
 		}
 
 		// Transform vertices
@@ -167,9 +221,11 @@ export default class QuadBatcher extends MaterialBatcher {
 		}
 
 		// 4 vertices per quad; the index buffer provides the 6 indices
-		vertexData.push(vec0.x, vec0.y, u0, v0, tint);
-		vertexData.push(vec1.x, vec1.y, u1, v0, tint);
-		vertexData.push(vec2.x, vec2.y, u0, v1, tint);
-		vertexData.push(vec3.x, vec3.y, u1, v1, tint);
+		// textureId is the unit index for multi-texture, or 0 for single-texture fallback
+		const textureId = this.useMultiTexture ? unit : 0;
+		vertexData.push(vec0.x, vec0.y, u0, v0, tint, textureId);
+		vertexData.push(vec1.x, vec1.y, u1, v0, tint, textureId);
+		vertexData.push(vec2.x, vec2.y, u0, v1, tint, textureId);
+		vertexData.push(vec3.x, vec3.y, u1, v1, tint, textureId);
 	}
 }

packages/melonjs/src/video/webgl/buffer/vertex.js

@@ -39,17 +39,26 @@ export default class VertexArrayBuffer {
 	}
 
 	/**
-	 * push a new vertex to the buffer (quad format: x, y, u, v, tint)
+	 * push a new vertex to the buffer
+	 * @param {number} x - x position
+	 * @param {number} y - y position
+	 * @param {number} u - texture U coordinate
+	 * @param {number} v - texture V coordinate
+	 * @param {number} tint - tint color in UINT32 (argb) format
+	 * @param {number} [textureId] - texture unit index for multi-texture batching
 	 * @ignore
 	 */
-	push(x, y, u, v, tint) {
+	push(x, y, u, v, tint, textureId) {
 		const offset = this.vertexCount * this.vertexSize;
 
 		this.bufferF32[offset] = x;
 		this.bufferF32[offset + 1] = y;
 		this.bufferF32[offset + 2] = u;
 		this.bufferF32[offset + 3] = v;
 		this.bufferU32[offset + 4] = tint;
+		if (arguments.length > 5) {
+			this.bufferF32[offset + 5] = textureId;
+		}
 
 		this.vertexCount++;
 

packages/melonjs/src/video/webgl/shaders/multitexture.js

@@ -0,0 +1,42 @@
+/**
+ * Generates a multi-texture fragment shader source string.
+ * Declares individual sampler uniforms (uSampler0..uSamplerN) and uses
+ * an if/else chain with 0.5-offset thresholds to select the correct texture unit.
+ * @param {number} maxTextures - the number of texture units to support
+ * @returns {string} GLSL fragment shader source
+ * @ignore
+ */
+export function buildMultiTextureFragment(maxTextures) {
+	const lines = [];
+
+	// declare sampler uniforms
+	for (let i = 0; i < maxTextures; i++) {
+		lines.push("uniform sampler2D uSampler" + i + ";");
+	}
+
+	lines.push("varying vec4 vColor;");
+	lines.push("varying vec2 vRegion;");
+	lines.push("varying float vTextureId;");
+	lines.push("");
+	lines.push("void main(void) {");
+	lines.push("    vec4 color;");
+
+	// generate if/else chain using < N.5 thresholds
+	for (let i = 0; i < maxTextures; i++) {
+		if (i === 0) {
+			lines.push("    if (vTextureId < 0.5) {");
+		} else {
+			lines.push("    } else if (vTextureId < " + (i + 0.5) + ") {");
+		}
+		lines.push("        color = texture2D(uSampler" + i + ", vRegion);");
+	}
+
+	// fallback to first sampler if vTextureId is out of range
+	lines.push("    } else {");
+	lines.push("        color = texture2D(uSampler0, vRegion);");
+	lines.push("    }");
+	lines.push("    gl_FragColor = color * vColor;");
+	lines.push("}");
+
+	return lines.join("\n");
+}

packages/melonjs/src/video/webgl/shaders/quad-multi.vert

@@ -0,0 +1,21 @@
+// Current vertex point
+attribute vec2 aVertex;
+attribute vec2 aRegion;
+attribute vec4 aColor;
+attribute float aTextureId;
+
+// Projection matrix
+uniform mat4 uProjectionMatrix;
+
+varying vec2 vRegion;
+varying vec4 vColor;
+varying float vTextureId;
+
+void main(void) {
+    // Transform the vertex position by the projection matrix
+    gl_Position = uProjectionMatrix * vec4(aVertex, 0.0, 1.0);
+    // Pass the remaining attributes to the fragment shader
+    vColor = vec4(aColor.bgr * aColor.a, aColor.a);
+    vRegion = aRegion;
+    vTextureId = aTextureId;
+}

packages/melonjs/src/video/webgl/webgl_renderer.js

@@ -158,6 +158,7 @@ export default class WebGLRenderer extends Renderer {
 		this.gl.depthMask(false);
 
 		this.gl.disable(this.gl.SCISSOR_TEST);
+		this._scissorActive = false;
 		this.gl.enable(this.gl.BLEND);
 
 		// set default mode
@@ -325,6 +326,7 @@ export default class WebGLRenderer extends Renderer {
 		this.setBatcher("quad");
 
 		this.gl.disable(this.gl.SCISSOR_TEST);
+		this._scissorActive = false;
 	}
 
 	/**
@@ -948,6 +950,7 @@ export default class WebGLRenderer extends Renderer {
 				const gl = this.gl;
 				const s = this.currentScissor;
 				gl.enable(gl.SCISSOR_TEST);
+				this._scissorActive = true;
 				gl.scissor(
 					s[0] + this.currentTransform.tx,
 					canvas.height - s[3] - s[1] - this.currentTransform.ty,
@@ -956,6 +959,7 @@ export default class WebGLRenderer extends Renderer {
 				);
 			} else {
 				this.gl.disable(this.gl.SCISSOR_TEST);
+				this._scissorActive = false;
 			}
 		}
 		// sync gradient from renderState
@@ -976,7 +980,7 @@ export default class WebGLRenderer extends Renderer {
 	 * renderer.restore();
 	 */
 	save() {
-		this.renderState.save(this.gl.isEnabled(this.gl.SCISSOR_TEST));
+		this.renderState.save(this._scissorActive === true);
 	}
 
 	/**
@@ -1711,6 +1715,7 @@ export default class WebGLRenderer extends Renderer {
 			this.flush();
 			// turn on scissor test
 			gl.enable(this.gl.SCISSOR_TEST);
+			this._scissorActive = true;
 			// set the scissor rectangle (note : coordinates are left/bottom)
 			gl.scissor(
 				// scissor does not account for currentTransform, so manually adjust
@@ -1727,6 +1732,7 @@ export default class WebGLRenderer extends Renderer {
 		} else {
 			// turn off scissor test
 			gl.disable(gl.SCISSOR_TEST);
+			this._scissorActive = false;
 		}
 	}