Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(render): a material can say its surface goes ON another one

esengine0f3dba109af1
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e05e43fb1..77443bd6d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -97,6 +97,18 @@ published separately; it ships inside the editor.
Per-instance, not per-object-record, because the record was out of room at the
time. The entry below is the change that moved it.
+- **A surface can say it goes ON another one.** Two coplanar surfaces — a decal
+ on a wall, a marking on a road, a patch on a floor — had no way to settle which
+ one the depth test keeps. Whichever drew first won, which is not a thing an
+ author can say. A material now carries `depthBias`, in units of the depth
+ buffer's own resolution, and both backends apply it to the constant and the
+ slope-scaled term (a constant alone stops separating them at a grazing angle).
+
+ It is the piece a decal cannot be built without, and it has none of a decal's
+ other machinery: no new pass, no depth read, no G-buffer. Two pixel scenes hold
+ it — the same wall and the same patch, differing in that one number, showing
+ the patch in one and the wall in the other.
+
- **A scatter brush.** Drag across the ground and copies of the selected object
land across it, turned and sized a little differently each — the first of the
authoring tools ruling 03 is about, since everything the renderer needed for
diff --git a/desktop b/desktop
index dab33b347..5eebbe685 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit dab33b34773ebdb882e456493ae897d307f5e938
+Subproject commit 5eebbe6853f2edabc23742978df8899249fdd21d
diff --git a/fixtures/scenes/mat-decal-flat.esscene b/fixtures/scenes/mat-decal-flat.esscene
new file mode 100644
index 000000000..e44756dfd
--- /dev/null
+++ b/fixtures/scenes/mat-decal-flat.esscene
@@ -0,0 +1,120 @@
+{
+ "version": 4,
+ "name": "Main",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 400
+ }
+ }
+ },
+ {
+ "type": "Camera",
+ "data": {
+ "projectionType": 1,
+ "orthoSize": 200,
+ "nearPlane": 1,
+ "farPlane": 2000,
+ "isActive": true,
+ "priority": 0
+ }
+ }
+ ]
+ },
+ {
+ "id": 1,
+ "name": "Wall",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ },
+ "scale": {
+ "x": 3.0,
+ "y": 3.0,
+ "z": 0.2
+ }
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "builtin:cube",
+ "opaque": true,
+ "lit": false,
+ "cullBackfaces": true,
+ "material": "/scenes/mat-decal/wall.esmaterial",
+ "color": {
+ "r": 1,
+ "g": 1,
+ "b": 1,
+ "a": 1
+ },
+ "layer": 0,
+ "enabled": true
+ }
+ }
+ ]
+ },
+ {
+ "id": 2,
+ "name": "Decal",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ },
+ "scale": {
+ "x": 1.2,
+ "y": 1.2,
+ "z": 0.2
+ }
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "builtin:cube",
+ "opaque": true,
+ "lit": false,
+ "cullBackfaces": true,
+ "material": "/scenes/mat-decal/decal-flat.esmaterial",
+ "color": {
+ "r": 1,
+ "g": 1,
+ "b": 1,
+ "a": 1
+ },
+ "layer": 0,
+ "enabled": true
+ }
+ }
+ ]
+ }
+ ]
+}
diff --git a/fixtures/scenes/mat-decal.esscene b/fixtures/scenes/mat-decal.esscene
new file mode 100644
index 000000000..30bea3c76
--- /dev/null
+++ b/fixtures/scenes/mat-decal.esscene
@@ -0,0 +1,120 @@
+{
+ "version": 4,
+ "name": "Main",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 400
+ }
+ }
+ },
+ {
+ "type": "Camera",
+ "data": {
+ "projectionType": 1,
+ "orthoSize": 200,
+ "nearPlane": 1,
+ "farPlane": 2000,
+ "isActive": true,
+ "priority": 0
+ }
+ }
+ ]
+ },
+ {
+ "id": 1,
+ "name": "Wall",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ },
+ "scale": {
+ "x": 3.0,
+ "y": 3.0,
+ "z": 0.2
+ }
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "builtin:cube",
+ "opaque": true,
+ "lit": false,
+ "cullBackfaces": true,
+ "material": "/scenes/mat-decal/wall.esmaterial",
+ "color": {
+ "r": 1,
+ "g": 1,
+ "b": 1,
+ "a": 1
+ },
+ "layer": 0,
+ "enabled": true
+ }
+ }
+ ]
+ },
+ {
+ "id": 2,
+ "name": "Decal",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ },
+ "scale": {
+ "x": 1.2,
+ "y": 1.2,
+ "z": 0.2
+ }
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "builtin:cube",
+ "opaque": true,
+ "lit": false,
+ "cullBackfaces": true,
+ "material": "/scenes/mat-decal/decal.esmaterial",
+ "color": {
+ "r": 1,
+ "g": 1,
+ "b": 1,
+ "a": 1
+ },
+ "layer": 0,
+ "enabled": true
+ }
+ }
+ ]
+ }
+ ]
+}
diff --git a/fixtures/scenes/mat-decal/decal-flat.esmaterial b/fixtures/scenes/mat-decal/decal-flat.esmaterial
new file mode 100644
index 000000000..90126861c
--- /dev/null
+++ b/fixtures/scenes/mat-decal/decal-flat.esmaterial
@@ -0,0 +1,12 @@
+{
+ "version": "1.0",
+ "type": "material",
+ "shader": "tint.esshader",
+ "blendMode": 0,
+ "depthTest": true,
+ "depthWrite": true,
+
+ "properties": {
+ "u_tint": { "r": 1, "g": 0, "b": 0, "a": 1 }
+ }
+}
diff --git a/fixtures/scenes/mat-decal/decal.esmaterial b/fixtures/scenes/mat-decal/decal.esmaterial
new file mode 100644
index 000000000..c7f214a3b
--- /dev/null
+++ b/fixtures/scenes/mat-decal/decal.esmaterial
@@ -0,0 +1,12 @@
+{
+ "version": "1.0",
+ "type": "material",
+ "shader": "tint.esshader",
+ "blendMode": 0,
+ "depthTest": true,
+ "depthWrite": true,
+ "depthBias": -8,
+ "properties": {
+ "u_tint": { "r": 1, "g": 0, "b": 0, "a": 1 }
+ }
+}
diff --git a/fixtures/scenes/mat-decal/tint.esshader b/fixtures/scenes/mat-decal/tint.esshader
new file mode 100644
index 000000000..b114d38e8
--- /dev/null
+++ b/fixtures/scenes/mat-decal/tint.esshader
@@ -0,0 +1,27 @@
+#pragma shader "MeshTintTest"
+#pragma version 300 es
+#pragma domain Unlit
+#pragma param u_tint color default(1,1,1,1)
+
+// Fragment only: the engine owns the vertex stage, which is what lets the same
+// material be compiled for a second vertex source (a GPU-resident mesh).
+#pragma fragment
+precision mediump float;
+
+in vec4 v_color;
+in vec2 v_texCoord;
+
+out vec4 fragColor;
+
+void main() {
+ fragColor = v_color * u_tint;
+}
+#pragma end
+
+#pragma fragment wgsl
+// No VSOut here: the engine's canonical vertex owns that interface and injects
+// it into a fragment-only twin.
+@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {
+ return v.v_color * mc.u_tint;
+}
+#pragma end
diff --git a/fixtures/scenes/mat-decal/wall.esmaterial b/fixtures/scenes/mat-decal/wall.esmaterial
new file mode 100644
index 000000000..5bc4c7f05
--- /dev/null
+++ b/fixtures/scenes/mat-decal/wall.esmaterial
@@ -0,0 +1,11 @@
+{
+ "version": "1.0",
+ "type": "material",
+ "shader": "tint.esshader",
+ "blendMode": 0,
+ "depthTest": true,
+ "depthWrite": true,
+ "properties": {
+ "u_tint": { "r": 0, "g": 1, "b": 0, "a": 1 }
+ }
+}
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index ca9ba97d2..f4e37ff03 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -5098,13 +5098,14 @@ static prototype: MaskReach
## Material — const @experimental
```
-{ createShader(vertexSrc: string, fragmentSrc: string): ShaderHandle; releaseShader(shader: ShaderHandle): void; create(options: MaterialOptions): MaterialHandle; compileShader(esshaderSource: string, features?: string[]): ShaderHandle; getSwitch(material: MaterialHandle, name: string): boolean; setSwitch(material: MaterialHandle, name: string, on: boolean): void; get(material: MaterialHandle): MaterialData | undefined; setUniform(material: MaterialHandle, name: string, value: UniformValue): void; getUniform(material: MaterialHandle, name: string): UniformValue | undefined; setBlendMode(material: MaterialHandle, mode: BlendMode): void; getBlendMode(material: MaterialHandle): BlendMode; setDepthTest(material: MaterialHandle, enabled: boolean): void; setDepthWrite(material: MaterialHandle, enabled: boolean): void; setCull(material: MaterialHandle, cull: CullMode): void; getShader(material: MaterialHandle): ShaderHandle; release(material: MaterialHandle): void; isValid(material: MaterialHandle): boolean; renderPreview(material: MaterialHandle, w: number, h: number): Promise<ImageData | null>; releaseAll(): void; createFromAsset(data: MaterialAssetData, shaderHandle: ShaderHandle, parentHandle?: MaterialHandle): MaterialHandle; createInstance(source: MaterialHandle): MaterialHandle; toAssetData(material: MaterialHandle, shaderPath: string, parentPath?: string): MaterialAssetData | null; getUniforms(material: MaterialHandle): Map<string, UniformValue>; tex(textureId: number, slot?: number): TextureRef; }
+{ createShader(vertexSrc: string, fragmentSrc: string): ShaderHandle; releaseShader(shader: ShaderHandle): void; create(options: MaterialOptions): MaterialHandle; compileShader(esshaderSource: string, features?: string[]): ShaderHandle; getSwitch(material: MaterialHandle, name: string): boolean; setSwitch(material: MaterialHandle, name: string, on: boolean): void; get(material: MaterialHandle): MaterialData | undefined; setUniform(material: MaterialHandle, name: string, value: UniformValue): void; getUniform(material: MaterialHandle, name: string): UniformValue | undefined; setBlendMode(material: MaterialHandle, mode: BlendMode): void; getBlendMode(material: MaterialHandle): BlendMode; setDepthTest(material: MaterialHandle, enabled: boolean): void; setDepthWrite(material: MaterialHandle, enabled: boolean): void; setDepthBias(material: MaterialHandle, units: number): void; setCull(material: MaterialHandle, cull: CullMode): void; getShader(material: MaterialHandle): ShaderHandle; release(material: MaterialHandle): void; isValid(material: MaterialHandle): boolean; renderPreview(material: MaterialHandle, w: number, h: number): Promise<ImageData | null>; releaseAll(): void; createFromAsset(data: MaterialAssetData, shaderHandle: ShaderHandle, parentHandle?: MaterialHandle): MaterialHandle; createInstance(source: MaterialHandle): MaterialHandle; toAssetData(material: MaterialHandle, shaderPath: string, parentPath?: string): MaterialAssetData | null; getUniforms(material: MaterialHandle): Map<string, UniformValue>; tex(textureId: number, slot?: number): TextureRef; }
```
## MaterialAssetData — interface @experimental
```
blendMode: number | undefined
cull: number | undefined
+depthBias: number | undefined
depthTest: boolean | undefined
depthWrite: boolean | undefined
instanceOf: string | undefined
@@ -5121,6 +5122,7 @@ blendMode: BlendMode
cachedBuffer_: Float32Array<ArrayBufferLike> | null
cachedIdx_: number
cull: CullMode
+depthBias: number
depthTest: boolean
depthWrite: boolean
dirty_: boolean
@@ -5158,6 +5160,7 @@ number
```
blendMode: BlendMode | undefined
cull: CullMode | undefined
+depthBias: number | undefined
depthTest: boolean | undefined
depthWrite: boolean | undefined
shader: number
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index de04a34fa..5bc54fb24 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -5106,13 +5106,14 @@ static prototype: MaskReach
## Material — const @experimental
```
-{ createShader(vertexSrc: string, fragmentSrc: string): ShaderHandle; releaseShader(shader: ShaderHandle): void; create(options: MaterialOptions): MaterialHandle; compileShader(esshaderSource: string, features?: string[]): ShaderHandle; getSwitch(material: MaterialHandle, name: string): boolean; setSwitch(material: MaterialHandle, name: string, on: boolean): void; get(material: MaterialHandle): MaterialData | undefined; setUniform(material: MaterialHandle, name: string, value: UniformValue): void; getUniform(material: MaterialHandle, name: string): UniformValue | undefined; setBlendMode(material: MaterialHandle, mode: BlendMode): void; getBlendMode(material: MaterialHandle): BlendMode; setDepthTest(material: MaterialHandle, enabled: boolean): void; setDepthWrite(material: MaterialHandle, enabled: boolean): void; setCull(material: MaterialHandle, cull: CullMode): void; getShader(material: MaterialHandle): ShaderHandle; release(material: MaterialHandle): void; isValid(material: MaterialHandle): boolean; renderPreview(material: MaterialHandle, w: number, h: number): Promise<ImageData | null>; releaseAll(): void; createFromAsset(data: MaterialAssetData, shaderHandle: ShaderHandle, parentHandle?: MaterialHandle): MaterialHandle; createInstance(source: MaterialHandle): MaterialHandle; toAssetData(material: MaterialHandle, shaderPath: string, parentPath?: string): MaterialAssetData | null; getUniforms(material: MaterialHandle): Map<string, UniformValue>; tex(textureId: number, slot?: number): TextureRef; }
+{ createShader(vertexSrc: string, fragmentSrc: string): ShaderHandle; releaseShader(shader: ShaderHandle): void; create(options: MaterialOptions): MaterialHandle; compileShader(esshaderSource: string, features?: string[]): ShaderHandle; getSwitch(material: MaterialHandle, name: string): boolean; setSwitch(material: MaterialHandle, name: string, on: boolean): void; get(material: MaterialHandle): MaterialData | undefined; setUniform(material: MaterialHandle, name: string, value: UniformValue): void; getUniform(material: MaterialHandle, name: string): UniformValue | undefined; setBlendMode(material: MaterialHandle, mode: BlendMode): void; getBlendMode(material: MaterialHandle): BlendMode; setDepthTest(material: MaterialHandle, enabled: boolean): void; setDepthWrite(material: MaterialHandle, enabled: boolean): void; setDepthBias(material: MaterialHandle, units: number): void; setCull(material: MaterialHandle, cull: CullMode): void; getShader(material: MaterialHandle): ShaderHandle; release(material: MaterialHandle): void; isValid(material: MaterialHandle): boolean; renderPreview(material: MaterialHandle, w: number, h: number): Promise<ImageData | null>; releaseAll(): void; createFromAsset(data: MaterialAssetData, shaderHandle: ShaderHandle, parentHandle?: MaterialHandle): MaterialHandle; createInstance(source: MaterialHandle): MaterialHandle; toAssetData(material: MaterialHandle, shaderPath: string, parentPath?: string): MaterialAssetData | null; getUniforms(material: MaterialHandle): Map<string, UniformValue>; tex(textureId: number, slot?: number): TextureRef; }
```
## MaterialAssetData — interface @experimental
```
blendMode: number | undefined
cull: number | undefined
+depthBias: number | undefined
depthTest: boolean | undefined
depthWrite: boolean | undefined
instanceOf: string | undefined
@@ -5129,6 +5130,7 @@ blendMode: BlendMode
cachedBuffer_: Float32Array<ArrayBufferLike> | null
cachedIdx_: number
cull: CullMode
+depthBias: number
depthTest: boolean
depthWrite: boolean
dirty_: boolean
@@ -5166,6 +5168,7 @@ number
```
blendMode: BlendMode | undefined
cull: CullMode | undefined
+depthBias: number | undefined
depthTest: boolean | undefined
depthWrite: boolean | undefined
shader: number
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 9d87b6a97..4cd2b900b 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -5093,13 +5093,14 @@ static prototype: MaskReach
## Material — const @experimental
```
-{ createShader(vertexSrc: string, fragmentSrc: string): ShaderHandle; releaseShader(shader: ShaderHandle): void; create(options: MaterialOptions): MaterialHandle; compileShader(esshaderSource: string, features?: string[]): ShaderHandle; getSwitch(material: MaterialHandle, name: string): boolean; setSwitch(material: MaterialHandle, name: string, on: boolean): void; get(material: MaterialHandle): MaterialData | undefined; setUniform(material: MaterialHandle, name: string, value: UniformValue): void; getUniform(material: MaterialHandle, name: string): UniformValue | undefined; setBlendMode(material: MaterialHandle, mode: BlendMode): void; getBlendMode(material: MaterialHandle): BlendMode; setDepthTest(material: MaterialHandle, enabled: boolean): void; setDepthWrite(material: MaterialHandle, enabled: boolean): void; setCull(material: MaterialHandle, cull: CullMode): void; getShader(material: MaterialHandle): ShaderHandle; release(material: MaterialHandle): void; isValid(material: MaterialHandle): boolean; renderPreview(material: MaterialHandle, w: number, h: number): Promise<ImageData | null>; releaseAll(): void; createFromAsset(data: MaterialAssetData, shaderHandle: ShaderHandle, parentHandle?: MaterialHandle): MaterialHandle; createInstance(source: MaterialHandle): MaterialHandle; toAssetData(material: MaterialHandle, shaderPath: string, parentPath?: string): MaterialAssetData | null; getUniforms(material: MaterialHandle): Map<string, UniformValue>; tex(textureId: number, slot?: number): TextureRef; }
+{ createShader(vertexSrc: string, fragmentSrc: string): ShaderHandle; releaseShader(shader: ShaderHandle): void; create(options: MaterialOptions): MaterialHandle; compileShader(esshaderSource: string, features?: string[]): ShaderHandle; getSwitch(material: MaterialHandle, name: string): boolean; setSwitch(material: MaterialHandle, name: string, on: boolean): void; get(material: MaterialHandle): MaterialData | undefined; setUniform(material: MaterialHandle, name: string, value: UniformValue): void; getUniform(material: MaterialHandle, name: string): UniformValue | undefined; setBlendMode(material: MaterialHandle, mode: BlendMode): void; getBlendMode(material: MaterialHandle): BlendMode; setDepthTest(material: MaterialHandle, enabled: boolean): void; setDepthWrite(material: MaterialHandle, enabled: boolean): void; setDepthBias(material: MaterialHandle, units: number): void; setCull(material: MaterialHandle, cull: CullMode): void; getShader(material: MaterialHandle): ShaderHandle; release(material: MaterialHandle): void; isValid(material: MaterialHandle): boolean; renderPreview(material: MaterialHandle, w: number, h: number): Promise<ImageData | null>; releaseAll(): void; createFromAsset(data: MaterialAssetData, shaderHandle: ShaderHandle, parentHandle?: MaterialHandle): MaterialHandle; createInstance(source: MaterialHandle): MaterialHandle; toAssetData(material: MaterialHandle, shaderPath: string, parentPath?: string): MaterialAssetData | null; getUniforms(material: MaterialHandle): Map<string, UniformValue>; tex(textureId: number, slot?: number): TextureRef; }
```
## MaterialAssetData — interface @experimental
```
blendMode: number | undefined
cull: number | undefined
+depthBias: number | undefined
depthTest: boolean | undefined
depthWrite: boolean | undefined
instanceOf: string | undefined
@@ -5116,6 +5117,7 @@ blendMode: BlendMode
cachedBuffer_: Float32Array<ArrayBufferLike> | null
cachedIdx_: number
cull: CullMode
+depthBias: number
depthTest: boolean
depthWrite: boolean
dirty_: boolean
@@ -5153,6 +5155,7 @@ number
```
blendMode: BlendMode | undefined
cull: CullMode | undefined
+depthBias: number | undefined
depthTest: boolean | undefined
depthWrite: boolean | undefined
shader: number
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 0c5c3fc40..4c595815c 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -5093,13 +5093,14 @@ static prototype: MaskReach
## Material — const @experimental
```
-{ createShader(vertexSrc: string, fragmentSrc: string): ShaderHandle; releaseShader(shader: ShaderHandle): void; create(options: MaterialOptions): MaterialHandle; compileShader(esshaderSource: string, features?: string[]): ShaderHandle; getSwitch(material: MaterialHandle, name: string): boolean; setSwitch(material: MaterialHandle, name: string, on: boolean): void; get(material: MaterialHandle): MaterialData | undefined; setUniform(material: MaterialHandle, name: string, value: UniformValue): void; getUniform(material: MaterialHandle, name: string): UniformValue | undefined; setBlendMode(material: MaterialHandle, mode: BlendMode): void; getBlendMode(material: MaterialHandle): BlendMode; setDepthTest(material: MaterialHandle, enabled: boolean): void; setDepthWrite(material: MaterialHandle, enabled: boolean): void; setCull(material: MaterialHandle, cull: CullMode): void; getShader(material: MaterialHandle): ShaderHandle; release(material: MaterialHandle): void; isValid(material: MaterialHandle): boolean; renderPreview(material: MaterialHandle, w: number, h: number): Promise<ImageData | null>; releaseAll(): void; createFromAsset(data: MaterialAssetData, shaderHandle: ShaderHandle, parentHandle?: MaterialHandle): MaterialHandle; createInstance(source: MaterialHandle): MaterialHandle; toAssetData(material: MaterialHandle, shaderPath: string, parentPath?: string): MaterialAssetData | null; getUniforms(material: MaterialHandle): Map<string, UniformValue>; tex(textureId: number, slot?: number): TextureRef; }
+{ createShader(vertexSrc: string, fragmentSrc: string): ShaderHandle; releaseShader(shader: ShaderHandle): void; create(options: MaterialOptions): MaterialHandle; compileShader(esshaderSource: string, features?: string[]): ShaderHandle; getSwitch(material: MaterialHandle, name: string): boolean; setSwitch(material: MaterialHandle, name: string, on: boolean): void; get(material: MaterialHandle): MaterialData | undefined; setUniform(material: MaterialHandle, name: string, value: UniformValue): void; getUniform(material: MaterialHandle, name: string): UniformValue | undefined; setBlendMode(material: MaterialHandle, mode: BlendMode): void; getBlendMode(material: MaterialHandle): BlendMode; setDepthTest(material: MaterialHandle, enabled: boolean): void; setDepthWrite(material: MaterialHandle, enabled: boolean): void; setDepthBias(material: MaterialHandle, units: number): void; setCull(material: MaterialHandle, cull: CullMode): void; getShader(material: MaterialHandle): ShaderHandle; release(material: MaterialHandle): void; isValid(material: MaterialHandle): boolean; renderPreview(material: MaterialHandle, w: number, h: number): Promise<ImageData | null>; releaseAll(): void; createFromAsset(data: MaterialAssetData, shaderHandle: ShaderHandle, parentHandle?: MaterialHandle): MaterialHandle; createInstance(source: MaterialHandle): MaterialHandle; toAssetData(material: MaterialHandle, shaderPath: string, parentPath?: string): MaterialAssetData | null; getUniforms(material: MaterialHandle): Map<string, UniformValue>; tex(textureId: number, slot?: number): TextureRef; }
```
## MaterialAssetData — interface @experimental
```
blendMode: number | undefined
cull: number | undefined
+depthBias: number | undefined
depthTest: boolean | undefined
depthWrite: boolean | undefined
instanceOf: string | undefined
@@ -5116,6 +5117,7 @@ blendMode: BlendMode
cachedBuffer_: Float32Array<ArrayBufferLike> | null
cachedIdx_: number
cull: CullMode
+depthBias: number
depthTest: boolean
depthWrite: boolean
dirty_: boolean
@@ -5153,6 +5155,7 @@ number
```
blendMode: BlendMode | undefined
cull: CullMode | undefined
+depthBias: number | undefined
depthTest: boolean | undefined
depthWrite: boolean | undefined
shader: number
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index 783274f7a..c6d7fb0be 100644
--- a/sdk/etc/wasm.api.md
+++ b/sdk/etc/wasm.api.md
@@ -323,7 +323,7 @@ initRendererWebGPU: (canvasSelector: string, width: number, height: number, read
initRendererWithContext: (contextHandle: number) => boolean
markDeviceRestored: (() => number) | undefined
material_compileEsshader: (source: string, featuresCsv: string) => number
-material_define: (materialId: number, shaderHandle: number, blendMode: number, flags: number) => void
+material_define: (materialId: number, shaderHandle: number, blendMode: number, flags: number, depthBias: number) => void
material_setTexture: (materialId: number, name: string, textureHandle: number) => void
material_setUniform: (materialId: number, name: string, arity: number, v0: number, v1: number, v2: number, v3: number) => void
material_undefine: (materialId: number) => void
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index ec49e6400..52d6304e1 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -5100,13 +5100,14 @@ static prototype: MaskReach
## Material — const @experimental
```
-{ createShader(vertexSrc: string, fragmentSrc: string): ShaderHandle; releaseShader(shader: ShaderHandle): void; create(options: MaterialOptions): MaterialHandle; compileShader(esshaderSource: string, features?: string[]): ShaderHandle; getSwitch(material: MaterialHandle, name: string): boolean; setSwitch(material: MaterialHandle, name: string, on: boolean): void; get(material: MaterialHandle): MaterialData | undefined; setUniform(material: MaterialHandle, name: string, value: UniformValue): void; getUniform(material: MaterialHandle, name: string): UniformValue | undefined; setBlendMode(material: MaterialHandle, mode: BlendMode): void; getBlendMode(material: MaterialHandle): BlendMode; setDepthTest(material: MaterialHandle, enabled: boolean): void; setDepthWrite(material: MaterialHandle, enabled: boolean): void; setCull(material: MaterialHandle, cull: CullMode): void; getShader(material: MaterialHandle): ShaderHandle; release(material: MaterialHandle): void; isValid(material: MaterialHandle): boolean; renderPreview(material: MaterialHandle, w: number, h: number): Promise<ImageData | null>; releaseAll(): void; createFromAsset(data: MaterialAssetData, shaderHandle: ShaderHandle, parentHandle?: MaterialHandle): MaterialHandle; createInstance(source: MaterialHandle): MaterialHandle; toAssetData(material: MaterialHandle, shaderPath: string, parentPath?: string): MaterialAssetData | null; getUniforms(material: MaterialHandle): Map<string, UniformValue>; tex(textureId: number, slot?: number): TextureRef; }
+{ createShader(vertexSrc: string, fragmentSrc: string): ShaderHandle; releaseShader(shader: ShaderHandle): void; create(options: MaterialOptions): MaterialHandle; compileShader(esshaderSource: string, features?: string[]): ShaderHandle; getSwitch(material: MaterialHandle, name: string): boolean; setSwitch(material: MaterialHandle, name: string, on: boolean): void; get(material: MaterialHandle): MaterialData | undefined; setUniform(material: MaterialHandle, name: string, value: UniformValue): void; getUniform(material: MaterialHandle, name: string): UniformValue | undefined; setBlendMode(material: MaterialHandle, mode: BlendMode): void; getBlendMode(material: MaterialHandle): BlendMode; setDepthTest(material: MaterialHandle, enabled: boolean): void; setDepthWrite(material: MaterialHandle, enabled: boolean): void; setDepthBias(material: MaterialHandle, units: number): void; setCull(material: MaterialHandle, cull: CullMode): void; getShader(material: MaterialHandle): ShaderHandle; release(material: MaterialHandle): void; isValid(material: MaterialHandle): boolean; renderPreview(material: MaterialHandle, w: number, h: number): Promise<ImageData | null>; releaseAll(): void; createFromAsset(data: MaterialAssetData, shaderHandle: ShaderHandle, parentHandle?: MaterialHandle): MaterialHandle; createInstance(source: MaterialHandle): MaterialHandle; toAssetData(material: MaterialHandle, shaderPath: string, parentPath?: string): MaterialAssetData | null; getUniforms(material: MaterialHandle): Map<string, UniformValue>; tex(textureId: number, slot?: number): TextureRef; }
```
## MaterialAssetData — interface @experimental
```
blendMode: number | undefined
cull: number | undefined
+depthBias: number | undefined
depthTest: boolean | undefined
depthWrite: boolean | undefined
instanceOf: string | undefined
@@ -5123,6 +5124,7 @@ blendMode: BlendMode
cachedBuffer_: Float32Array<ArrayBufferLike> | null
cachedIdx_: number
cull: CullMode
+depthBias: number
depthTest: boolean
depthWrite: boolean
dirty_: boolean
@@ -5160,6 +5162,7 @@ number
```
blendMode: BlendMode | undefined
cull: CullMode | undefined
+depthBias: number | undefined
depthTest: boolean | undefined
depthWrite: boolean | undefined
shader: number
diff --git a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
index bae30a432..e195d157e 100644
--- a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
+++ b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
@@ -67,7 +67,7 @@ export interface NativeEngineApi {
gl_checkErrors?(context: string): number;
gl_enableErrorCheck?(enabled: boolean): void;
material_compileEsshader?(source: string, featuresCsv: string): number;
- material_define?(materialId: number, shaderHandle: number, blendMode: number, flags: number): void;
+ material_define?(materialId: number, shaderHandle: number, blendMode: number, flags: number, depthBias: number): void;
material_setTexture?(materialId: number, name: string, textureHandle: number): void;
material_setUniform?(materialId: number, name: string, arity: number, v0: number, v1: number, v2: number, v3: number): void;
material_undefine?(materialId: number): void;
diff --git a/sdk/src/render/material.ts b/sdk/src/render/material.ts
index 0def48f1b..45dc0b836 100644
--- a/sdk/src/render/material.ts
+++ b/sdk/src/render/material.ts
@@ -84,6 +84,9 @@ export interface MaterialOptions {
depthTest?: boolean;
depthWrite?: boolean;
cull?: CullMode;
+ /** Depth-buffer units toward the eye — the only way to say which of two
+ * COPLANAR surfaces wins (a decal on a wall). 0 leaves it where it is. */
+ depthBias?: number;
/** Enabled static switches (#pragma switch) for the record; the shader permutation is
* chosen at compile time (see Material.compileShader). Stored for inspection/serialization. */
switches?: Record<string, boolean>;
@@ -103,6 +106,7 @@ export interface MaterialAssetData {
depthTest?: boolean;
depthWrite?: boolean;
cull?: number;
+ depthBias?: number;
/**
* Parent material asset ref — present on a material instance (UE MaterialInstanceConstant).
* The shader and any non-overridden render state are inherited from the parent; `shader`
@@ -121,13 +125,16 @@ export interface MaterialData {
depthTest: boolean;
depthWrite: boolean;
cull: CullMode;
+ /** Depth-buffer units toward the eye — the only way to say which of two
+ * COPLANAR surfaces wins (a decal on a wall). 0 leaves it where it is. */
+ depthBias: number;
/** Enabled static switches (the shader permutation was chosen for these at compile time). */
switches: Record<string, boolean>;
/**
* Instance parenting (UE MaterialInstanceConstant): when set, this material inherits the
* parent's shader + render state + params, and only its own diffs are stored — `uniforms`
* holds just the overridden params, and `overrides` names the overridden render-state
- * fields ('blendMode' | 'depthTest' | 'depthWrite' | 'cull'). Undefined on a base material.
+ * fields. Undefined on a base material.
*/
parent?: MaterialHandle;
overrides: Set<string>;
@@ -261,6 +268,7 @@ interface ResolvedMaterial {
depthTest: boolean;
depthWrite: boolean;
cull: CullMode;
+ depthBias: number;
uniforms: Map<string, UniformValue>;
}
@@ -274,7 +282,8 @@ function resolveMaterial(handle: MaterialHandle): ResolvedMaterial | null {
if (!parent) {
return {
shader: data.shader, blendMode: data.blendMode, depthTest: data.depthTest,
- depthWrite: data.depthWrite, cull: data.cull, uniforms: new Map(data.uniforms),
+ depthWrite: data.depthWrite, cull: data.cull, depthBias: data.depthBias,
+ uniforms: new Map(data.uniforms),
};
}
const uniforms = parent.uniforms; // fresh map from the recursive call
@@ -285,6 +294,7 @@ function resolveMaterial(handle: MaterialHandle): ResolvedMaterial | null {
depthTest: data.overrides.has('depthTest') ? data.depthTest : parent.depthTest,
depthWrite: data.overrides.has('depthWrite') ? data.depthWrite : parent.depthWrite,
cull: data.overrides.has('cull') ? data.cull : parent.cull,
+ depthBias: data.overrides.has('depthBias') ? data.depthBias : parent.depthBias,
uniforms,
};
}
@@ -295,7 +305,8 @@ function flushMaterial(handle: MaterialHandle): void {
const resolved = resolveMaterial(handle);
if (resolved && module) {
module.material_define(handle, resolved.shader, resolved.blendMode,
- materialFlags(resolved.depthTest, resolved.depthWrite, resolved.cull));
+ materialFlags(resolved.depthTest, resolved.depthWrite, resolved.cull),
+ resolved.depthBias);
for (const [name, value] of resolved.uniforms) pushUniform(handle, name, value);
}
const kids = childrenOf.get(handle);
@@ -362,6 +373,7 @@ export const Material = {
depthTest: options.depthTest ?? false,
depthWrite: options.depthWrite ?? true,
cull: options.cull ?? CullMode.None,
+ depthBias: options.depthBias ?? 0,
switches: options.switches ? { ...options.switches } : {},
overrides: new Set(),
dirty_: true,
@@ -493,6 +505,20 @@ export const Material = {
}
},
+ /**
+ * How far toward the eye this surface is pushed, in depth-buffer units —
+ * what makes a decal win against the wall it is laid on. Negative is toward
+ * the eye; 0 leaves the surface where its geometry puts it.
+ */
+ setDepthBias(material: MaterialHandle, units: number): void {
+ const data = materials.get(material);
+ if (data) {
+ data.depthBias = Math.round(units);
+ if (data.parent !== undefined) data.overrides.add('depthBias');
+ flushMaterial(material);
+ }
+ },
+
/** Sets the triangle culling mode. */
setCull(material: MaterialHandle, cull: CullMode): void {
const data = materials.get(material);
@@ -571,6 +597,7 @@ export const Material = {
if (data.depthTest !== undefined) this.setDepthTest(handle, data.depthTest);
if (data.depthWrite !== undefined) this.setDepthWrite(handle, data.depthWrite);
if (data.cull !== undefined) this.setCull(handle, data.cull as CullMode);
+ if (data.depthBias !== undefined) this.setDepthBias(handle, data.depthBias);
return handle;
}
@@ -581,6 +608,7 @@ export const Material = {
depthTest: data.depthTest ?? false,
depthWrite: data.depthWrite ?? true,
cull: (data.cull as CullMode) ?? CullMode.None,
+ depthBias: data.depthBias ?? 0,
switches: data.switches,
});
},
@@ -609,6 +637,7 @@ export const Material = {
depthTest: sourceData.depthTest,
depthWrite: sourceData.depthWrite,
cull: sourceData.cull,
+ depthBias: sourceData.depthBias,
switches: {}, // instance inherits the parent's shader permutation (switch override = follow-up)
parent: source,
overrides: new Set(),
@@ -649,6 +678,7 @@ export const Material = {
if (data.overrides.has('depthTest')) asset.depthTest = data.depthTest;
if (data.overrides.has('depthWrite')) asset.depthWrite = data.depthWrite;
if (data.overrides.has('cull')) asset.cull = data.cull;
+ if (data.overrides.has('depthBias')) asset.depthBias = data.depthBias;
return asset;
}
@@ -660,6 +690,7 @@ export const Material = {
depthTest: data.depthTest,
depthWrite: data.depthWrite,
cull: data.cull,
+ depthBias: data.depthBias,
properties,
};
if (Object.keys(data.switches).length > 0) asset.switches = { ...data.switches };
diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.ts
index c811059cd..3727a5299 100644
--- a/sdk/src/wasm.ts
+++ b/sdk/src/wasm.ts
@@ -409,7 +409,7 @@ export interface ESEngineModule {
// which is what makes them work on a device too; declared here because embind
// registers them by hand for the web.
material_compileEsshader(source: string, featuresCsv: string): number;
- material_define(materialId: number, shaderHandle: number, blendMode: number, flags: number): void;
+ material_define(materialId: number, shaderHandle: number, blendMode: number, flags: number, depthBias: number): void;
material_setUniform(materialId: number, name: string, arity: number,
v0: number, v1: number, v2: number, v3: number): void;
material_setTexture(materialId: number, name: string, textureHandle: number): void;
diff --git a/sdk/tests/material.test.ts b/sdk/tests/material.test.ts
index 94462a521..d106f6809 100644
--- a/sdk/tests/material.test.ts
+++ b/sdk/tests/material.test.ts
@@ -162,7 +162,7 @@ describe('Material API', () => {
cull: CullMode.Back,
});
expect(mock.material_define).toHaveBeenCalledWith(
- h, 42, BlendMode.Additive, flags(true, true, CullMode.Back),
+ h, 42, BlendMode.Additive, flags(true, true, CullMode.Back), 0,
);
});
@@ -299,7 +299,7 @@ describe('Material API', () => {
mock.material_define.mockClear();
Material.setBlendMode(h, BlendMode.Additive);
expect(mock.material_define).toHaveBeenCalledWith(
- h, 1, BlendMode.Additive, flags(false, true, CullMode.None),
+ h, 1, BlendMode.Additive, flags(false, true, CullMode.None), 0,
);
});
@@ -315,7 +315,7 @@ describe('Material API', () => {
Material.setDepthTest(h, true);
expect(Material.get(h)!.depthTest).toBe(true);
expect(mock.material_define).toHaveBeenCalledWith(
- h, 1, BlendMode.Normal, flags(true, true, CullMode.None),
+ h, 1, BlendMode.Normal, flags(true, true, CullMode.None), 0,
);
});
@@ -325,7 +325,47 @@ describe('Material API', () => {
Material.setDepthWrite(h, false);
expect(Material.get(h)!.depthWrite).toBe(false);
expect(mock.material_define).toHaveBeenCalledWith(
- h, 1, BlendMode.Normal, flags(false, false, CullMode.None),
+ h, 1, BlendMode.Normal, flags(false, false, CullMode.None), 0,
+ );
+ });
+
+ it('carries a depth bias through to the engine, as its own value', () => {
+ const h = Material.create({ shader: 1 as ShaderHandle });
+ mock.material_define.mockClear();
+ Material.setDepthBias(h, -8);
+ // Its own argument and not a bit in `flags`: a value packed into a
+ // word of switches is how the two sides come to disagree about it.
+ expect(mock.material_define).toHaveBeenCalledWith(
+ h, 1, BlendMode.Normal, flags(false, true, CullMode.None), -8,
+ );
+ expect(Material.get(h)?.depthBias).toBe(-8);
+ });
+
+ it('rounds a bias to whole depth-buffer units', () => {
+ const h = Material.create({ shader: 1 as ShaderHandle, depthBias: -2.6 });
+ expect(Material.get(h)?.depthBias).toBe(-2.6);
+ Material.setDepthBias(h, -2.6);
+ expect(Material.get(h)?.depthBias).toBe(-3);
+ });
+
+ it('lets an instance override its parent bias, and inherit it otherwise', () => {
+ const base = Material.create({ shader: 1 as ShaderHandle, depthBias: -4 });
+ const inherits = Material.createInstance(base);
+ const overrides = Material.createInstance(base);
+ mock.material_define.mockClear();
+ Material.setDepthBias(overrides, -16);
+
+ expect(mock.material_define).toHaveBeenCalledWith(
+ overrides, 1, BlendMode.Normal, flags(false, true, CullMode.None), -16,
+ );
+ mock.material_define.mockClear();
+ Material.setDepthBias(base, -9);
+ // The non-overriding child follows its parent; the overriding one does not.
+ expect(mock.material_define).toHaveBeenCalledWith(
+ inherits, 1, BlendMode.Normal, flags(false, true, CullMode.None), -9,
+ );
+ expect(mock.material_define).toHaveBeenCalledWith(
+ overrides, 1, BlendMode.Normal, flags(false, true, CullMode.None), -16,
);
});
@@ -335,7 +375,7 @@ describe('Material API', () => {
Material.setCull(h, CullMode.Front);
expect(Material.get(h)!.cull).toBe(CullMode.Front);
expect(mock.material_define).toHaveBeenCalledWith(
- h, 1, BlendMode.Normal, flags(false, true, CullMode.Front),
+ h, 1, BlendMode.Normal, flags(false, true, CullMode.Front), 0,
);
});
});
@@ -447,7 +487,7 @@ describe('Material API', () => {
mock.material_define.mockClear();
const inst = Material.createInstance(src);
expect(mock.material_define).toHaveBeenCalledWith(
- inst, 5, BlendMode.Multiply, flags(false, true, CullMode.None),
+ inst, 5, BlendMode.Multiply, flags(false, true, CullMode.None), 0,
);
});
@@ -572,6 +612,7 @@ describe('Material API', () => {
depthTest: true,
depthWrite: true,
cull: CullMode.None,
+ depthBias: 0,
properties: { u_time: 0.5 },
});
});
diff --git a/src/esengine/bindings/MaterialBindings.cpp b/src/esengine/bindings/MaterialBindings.cpp
index 77b231e33..024ebaea6 100644
--- a/src/esengine/bindings/MaterialBindings.cpp
+++ b/src/esengine/bindings/MaterialBindings.cpp
@@ -16,6 +16,7 @@
#include "../resource/ResourceManager.hpp"
#include "../resource/ShaderParser.hpp"
+#include <algorithm>
#include <cstdlib>
#include <sstream>
@@ -107,7 +108,8 @@ u32 material_compileEsshader(const std::string& source, const std::string& featu
return handle.id();
}
-void material_define(u32 materialId, u32 shaderHandle, u32 blendMode, u32 flags) {
+void material_define(u32 materialId, u32 shaderHandle, u32 blendMode, u32 flags,
+ i32 depthBias) {
auto* rc = g_renderContext;
if (!rc) return;
// The handle is the identity; the program id is a cache of what it currently
@@ -121,6 +123,9 @@ void material_define(u32 materialId, u32 shaderHandle, u32 blendMode, u32 flags)
rec.depthTest = (flags & 0x1u) != 0;
rec.depthWrite = (flags & 0x2u) != 0;
rec.cull = static_cast<CullMode>((flags >> 2) & 0x3u);
+ // Its own parameter and not another flag bit: this is a VALUE, and packing
+ // one into a word of booleans is how two sides come to disagree about it.
+ rec.depthBias = static_cast<i16>(std::clamp(depthBias, -32768, 32767));
rc->materials().define(materialId, rec);
}
diff --git a/src/esengine/bindings/MaterialBindings.hpp b/src/esengine/bindings/MaterialBindings.hpp
index 8fd186020..48b4510f5 100644
--- a/src/esengine/bindings/MaterialBindings.hpp
+++ b/src/esengine/bindings/MaterialBindings.hpp
@@ -32,12 +32,13 @@ namespace esengine {
u32 material_compileEsshader(const std::string& source, const std::string& featuresCsv);
/**
- * Publish a material's resolved render state. @p shaderHandle is the SDK shader
- * resource handle, translated here to the program id the render path binds;
- * @p flags packs depthTest (bit 0), depthWrite (bit 1) and CullMode (bits 2-3).
- * Param values arrive separately, via material_setUniform / material_setTexture.
+ * Publish a material's resolved render state. @p shaderHandle is translated here
+ * to the program id the render path binds; @p flags packs depthTest (bit 0),
+ * depthWrite (bit 1) and CullMode (bits 2-3), while @p depthBias is its own
+ * parameter because it is a value, not a switch.
*/
-void material_define(u32 materialId, u32 shaderHandle, u32 blendMode, u32 flags);
+void material_define(u32 materialId, u32 shaderHandle, u32 blendMode, u32 flags,
+ i32 depthBias);
/** Pack a named param's float components into the material's std140 block, by
* reflected offset. A no-op when the shader declares no matching `#pragma param`. */
diff --git a/src/esengine/renderer/draw/BatchBuilder.cpp b/src/esengine/renderer/draw/BatchBuilder.cpp
index 0b73d8b3a..3f9f8d382 100644
--- a/src/esengine/renderer/draw/BatchBuilder.cpp
+++ b/src/esengine/renderer/draw/BatchBuilder.cpp
@@ -118,6 +118,7 @@ void pushBatchDraw(DrawList& drawList, const ClipState& clips,
cmd.depth_test = depthTest;
cmd.depth_write = depthWrite;
cmd.cull = key.cull;
+ cmd.depth_bias = key.depthBias;
// The Batch stream always samples a texture (white fallback at minimum); other
// streams bind one only when the draw actually has one (the shape stream is
// textureless, so execute() must not touch sampler units for it).
diff --git a/src/esengine/renderer/draw/BatchBuilder.hpp b/src/esengine/renderer/draw/BatchBuilder.hpp
index ae22bcf13..c2ff85412 100644
--- a/src/esengine/renderer/draw/BatchBuilder.hpp
+++ b/src/esengine/renderer/draw/BatchBuilder.hpp
@@ -115,6 +115,7 @@ struct BatchDrawKey {
bool depthTest = false;
bool depthWrite = true;
u8 cull = 0; ///< CullMode: 0 = none, 1 = back, 2 = front.
+ i16 depthBias = 0; ///< Depth-buffer units toward the eye. @see PipelineDesc.
// The transient stream this draw's geometry lives in. Only the Batch stream carries
// a per-vertex texIndex, so only it participates in the multi-texture merge.
LayoutId layoutId = LayoutId::Batch;
diff --git a/src/esengine/renderer/draw/DrawCommand.hpp b/src/esengine/renderer/draw/DrawCommand.hpp
index 9704aac6d..1e6facd14 100644
--- a/src/esengine/renderer/draw/DrawCommand.hpp
+++ b/src/esengine/renderer/draw/DrawCommand.hpp
@@ -107,6 +107,7 @@ struct DrawCommand {
bool depth_test = false;
bool depth_write = true;
u8 cull = 0; ///< CullMode: 0 = none, 1 = back, 2 = front.
+ i16 depth_bias = 0; ///< Depth-buffer units toward the eye. @see PipelineDesc.
BatchBreak break_reason = BatchBreak::RunStart; ///< Why this draw call started.
u8 texture_count = 0;
@@ -371,6 +372,8 @@ struct DrawCommand {
if (shader_id != next.shader_id) return BatchBreak::Shader;
if (material_id != next.material_id) return BatchBreak::Material;
if (cull != next.cull) return BatchBreak::Cull;
+ if (depth_bias != next.depth_bias) return BatchBreak::Cull;
+ if (depth_bias != next.depth_bias) return BatchBreak::Cull;
if (state_flags != next.state_flags) return BatchBreak::State;
if (state_flags & CMD_STATE_SCISSOR) {
if (scissor != next.scissor) return BatchBreak::Scissor;
diff --git a/src/esengine/renderer/draw/DrawList.cpp b/src/esengine/renderer/draw/DrawList.cpp
index 9f9ba96b4..b2fd308c5 100644
--- a/src/esengine/renderer/draw/DrawList.cpp
+++ b/src/esengine/renderer/draw/DrawList.cpp
@@ -232,6 +232,7 @@ void DrawList::execute(GfxDevice& device, TransientBufferPool& buffers,
desc.stencil = stencil;
desc.cullEnabled = cmd.cull != 0;
desc.cullFront = cmd.cull == 2;
+ desc.depthBias = cmd.depth_bias;
if (lastHandle == PipelineHandle::Invalid || !(desc == lastDesc)) {
lastHandle = device.createPipeline(desc);
diff --git a/src/esengine/renderer/plugins/MeshPlugin.cpp b/src/esengine/renderer/plugins/MeshPlugin.cpp
index aa1443a0e..7d7a3277e 100644
--- a/src/esengine/renderer/plugins/MeshPlugin.cpp
+++ b/src/esengine/renderer/plugins/MeshPlugin.cpp
@@ -622,6 +622,7 @@ void MeshPlugin::collect(RenderCollectContext& collect_ctx) {
key.depthTest = m->depthTest;
key.depthWrite = m->depthWrite;
key.cull = static_cast<u8>(m->cull);
+ key.depthBias = m->depthBias;
}
} else if (mesh.lit && ctx.frame) {
if (litProgram == 0) litProgram = ctx.frame->batchProgram({"LIT"});
diff --git a/src/esengine/renderer/plugins/SpritePlugin.cpp b/src/esengine/renderer/plugins/SpritePlugin.cpp
index 1212a3b14..01459d399 100644
--- a/src/esengine/renderer/plugins/SpritePlugin.cpp
+++ b/src/esengine/renderer/plugins/SpritePlugin.cpp
@@ -112,6 +112,7 @@ void SpritePlugin::collect(RenderCollectContext& collect_ctx) {
key.depthTest = m->depthTest;
key.depthWrite = m->depthWrite;
key.cull = static_cast<u8>(m->cull);
+ key.depthBias = m->depthBias;
}
} else if (sprite.lit && ctx.frame) {
// A material owns shading fully, so it takes precedence over the toggle.
diff --git a/src/esengine/renderer/plugins/TrailPlugin.cpp b/src/esengine/renderer/plugins/TrailPlugin.cpp
index 269108e67..17e0f72b8 100644
--- a/src/esengine/renderer/plugins/TrailPlugin.cpp
+++ b/src/esengine/renderer/plugins/TrailPlugin.cpp
@@ -100,6 +100,7 @@ void TrailPlugin::collect(RenderCollectContext& collect_ctx) {
key.depthTest = m->depthTest;
key.depthWrite = m->depthWrite;
key.cull = static_cast<u8>(m->cull);
+ key.depthBias = m->depthBias;
}
}
diff --git a/src/esengine/renderer/plugins/UIElementPlugin.cpp b/src/esengine/renderer/plugins/UIElementPlugin.cpp
index ba090987a..0490a9b94 100644
--- a/src/esengine/renderer/plugins/UIElementPlugin.cpp
+++ b/src/esengine/renderer/plugins/UIElementPlugin.cpp
@@ -250,6 +250,7 @@ void UIElementPlugin::collect(RenderCollectContext& collect_ctx) {
key.depthTest = m->depthTest;
key.depthWrite = m->depthWrite;
key.cull = static_cast<u8>(m->cull);
+ key.depthBias = m->depthBias;
}
}
diff --git a/src/esengine/renderer/rhi/GLDevice.cpp b/src/esengine/renderer/rhi/GLDevice.cpp
index 7ddae4ea8..f1b48da6d 100644
--- a/src/esengine/renderer/rhi/GLDevice.cpp
+++ b/src/esengine/renderer/rhi/GLDevice.cpp
@@ -982,6 +982,7 @@ void GLDevice::setPipeline(PipelineHandle handle) {
setDepthWrite(desc.depthWrite);
setCulling(desc.cullEnabled);
if (desc.cullEnabled) setCullFace(desc.cullFront);
+ setDepthBias(desc.depthBias);
applyStencilMode(desc.stencil);
current_pipeline_ = handle;
@@ -989,6 +990,24 @@ void GLDevice::setPipeline(PipelineHandle handle) {
current_layout_ = desc.vertexLayout;
}
+/**
+ * @brief Push this surface toward the eye by @p bias units of depth resolution.
+ *
+ * @details Both terms take it: the constant separates coplanar surfaces head-on,
+ * the slope-scaled one keeps them separated at a grazing angle, where a
+ * constant offset spans less depth than one pixel of the surface does.
+ */
+void GLDevice::setDepthBias(i16 bias) {
+ if (bias == current_depth_bias_) return;
+ if (bias == 0) {
+ glDisable(GL_POLYGON_OFFSET_FILL);
+ } else {
+ glEnable(GL_POLYGON_OFFSET_FILL);
+ glPolygonOffset(static_cast<f32>(bias), static_cast<f32>(bias));
+ }
+ current_depth_bias_ = bias;
+}
+
void GLDevice::setStencilReference(i32 ref) {
switch (current_stencil_mode_) {
case GfxStencilMode::Write:
diff --git a/src/esengine/renderer/rhi/GLDevice.hpp b/src/esengine/renderer/rhi/GLDevice.hpp
index 13d7aa39f..872beb1de 100644
--- a/src/esengine/renderer/rhi/GLDevice.hpp
+++ b/src/esengine/renderer/rhi/GLDevice.hpp
@@ -159,6 +159,7 @@ private:
void setColorMask(bool r, bool g, bool b, bool a);
void setCulling(bool enabled);
void setCullFace(bool front);
+ void setDepthBias(i16 bias);
// Pipeline cache: a handle is (index + 1) into pipelines_; PipelineHandle::Invalid is 0.
// WebGL2 has no native pipeline object, so a pipeline is applied as a bundle of GL
@@ -205,6 +206,7 @@ private:
static constexpr u32 kTextureSlots = 16;
u32 active_texture_unit_ = 0;
u32 bound_texture_[kTextureSlots] = {};
+ i16 current_depth_bias_ = 0;
int scissor_test_ = -1; // tri-state: -1 unknown, 0 disabled, 1 enabled
struct LayoutRecord {
diff --git a/src/esengine/renderer/rhi/PipelineState.hpp b/src/esengine/renderer/rhi/PipelineState.hpp
index cfaaff4d6..6ac469b32 100644
--- a/src/esengine/renderer/rhi/PipelineState.hpp
+++ b/src/esengine/renderer/rhi/PipelineState.hpp
@@ -51,6 +51,10 @@ struct PipelineDesc {
GfxStencilMode stencil = GfxStencilMode::Off;
bool cullEnabled = false;
bool cullFront = false;
+ /// How far toward the eye this surface is pushed, in units of the depth
+ /// buffer's resolution — the only way to say which of two COPLANAR surfaces
+ /// wins. Drives both the constant and the slope-scaled term.
+ i16 depthBias = 0;
bool operator==(const PipelineDesc&) const = default;
};
diff --git a/src/esengine/renderer/store/MaterialStore.hpp b/src/esengine/renderer/store/MaterialStore.hpp
index 981644d1d..a56b2a00d 100644
--- a/src/esengine/renderer/store/MaterialStore.hpp
+++ b/src/esengine/renderer/store/MaterialStore.hpp
@@ -118,6 +118,9 @@ struct MaterialRecord {
bool depthTest = false;
bool depthWrite = true;
CullMode cull = CullMode::None;
+ /// Depth-buffer units toward the eye — what a surface laid ON another one
+ /// says so it wins. @see PipelineDesc::depthBias.
+ i16 depthBias = 0;
/// Packed std140 MaterialConstants payload (sized to the shader's blockSize), the GPU
/// UBO it uploads to (lazy), and whether the bytes changed since the last upload.
diff --git a/src/esengine/renderer/webgpu/WebGPUMappings.hpp b/src/esengine/renderer/webgpu/WebGPUMappings.hpp
index c185b26c4..6cc547c21 100644
--- a/src/esengine/renderer/webgpu/WebGPUMappings.hpp
+++ b/src/esengine/renderer/webgpu/WebGPUMappings.hpp
@@ -318,6 +318,11 @@ inline WGPUDepthStencilState toWGPUDepthStencil(const PipelineDesc& desc, WGPUTe
ds.stencilBack = toWGPUStencilFace(desc.stencil);
ds.stencilReadMask = 0xFFu;
ds.stencilWriteMask = toWGPUStencilWriteMask(desc.stencil);
+ // Both terms, for the reason GLDevice::setDepthBias gives: head-on the
+ // constant separates coplanar surfaces, at a grazing angle only the
+ // slope-scaled one does.
+ ds.depthBias = desc.depthBias;
+ ds.depthBiasSlopeScale = static_cast<float>(desc.depthBias);
return ds;
}
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 422dd406b..9b8727b4c 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,9 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'feat(render): a material can say its surface goes ON another one':
+ { note: 'A surface can say it goes ON another one.' },
+
'feat(editor): a scatter brush, and one stroke that undoes in one step':
{ note: 'A scatter brush.' },
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index 87df1d6ea..904ea2d83 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -543,6 +543,12 @@ export const SCENES = [
// A material drawing GPU-resident geometry. Its shader writes only a fragment,
// so the ENGINE owns the vertex stage and compiles a second variant for this
// source; wrong placement or an ignored tint moves the probes.
+
+ // Two COPLANAR surfaces, separated by nothing but the bias the decal's
+ // material carries: the centre is the decal, the ring is the wall. The twin
+ // below is identical but for that one number, and shows wall throughout.
+ { id: "mat-decal", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mat-decal.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[255,0,0],\"tol\":40},{\"x\":0.25,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":40}]" } },
+ { id: "mat-decal-flat", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mat-decal-flat.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":40},{\"x\":0.25,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":40}]" } },
{ id: "mesh-material", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_MESH_ASSET: "/scenes/white-triangles.esmesh", ESTELLA_VERIFY_MESH_MATERIAL: "/scenes/mesh-material/tintonly.esmaterial", ESTELLA_VERIFY_SCENE: "/scenes/mesh-material.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mesh-material.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.30,\"y\":0.556,\"rgb\":[0,0,255],\"tol\":40},{\"x\":0.70,\"y\":0.556,\"rgb\":[0,0,255],\"tol\":40},{\"x\":0.5,\"y\":0.12,\"rgb\":[0,0,0],\"tol\":30}]" } },
// What a normal is FOR: two coplanar triangles, one white colour, normals
// facing the viewer and +X, under a head-on directional light. Only a shader