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(post): the grade has a gain and an offset, and the vignette a radius and a roundness - a grade could lift the blacks and not sink them, so a look whose contrast is a line through 0.5 came out a third as saturated in the dark; and a vignette was always full at the middle of every edge

yhh31cea23fd266
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 29bc278e1..957622801 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,7 @@ published separately; it ships inside the editor.
### Added
+- **The grade has a gain and an offset, and the vignette a radius and a roundness.** Color Grade could add to the blacks (Lift) and never take from them, and its contrast in a linear project is a power curve about 0.18, which leaves black where it was. A look graded elsewhere with a contrast that is a line through 0.5 sinks its blacks: without that, a meadow that measures 0.77 saturation there measured 0.50 here, with a film of blue over every dark green. **Gain** (`u_gain`) multiplies every tone and **Offset** (`u_offset`, which may be under zero) is added after it, as a grade's slope and offset are; `(c - 0.5) * k + 0.5` is a gain of `k` and an offset of `0.5 - 0.5 * k`. The Vignette was full at the middle of every edge whatever its numbers: **Radius** (`u_radius`) is where it is full, and **Roundness** (`u_roundness`) takes it from the frame's own ellipse to a circle whose 1 is the corner, the usual lens vignette. Every default is the picture as it was.
- **A blade's lean, its turn to the eye, and what a leaf lets through and mirrors are yours to set.** Four numbers of a field of grass were the engine's own. `Foliage.bladeLean` is how far a blade's tip is thrown over (it was 0.12 of its height, written into the builder). On the Foliage material, `u_specular` is how much a plant mirrors the sun and the sky (it was 0.5, written into the shader), `u_translucencyColor` the colour of the light that comes through a leaf, which was the leaf's own and is yellower in a real one, and `u_bladeFaceEye` turns the flat of each blade toward the eye so that a blade seen edge on is not a line. Every default is what it was.
- **A flower turns to face the eye.** A flat flower faces the sky, so a field of them is seen edge on from a few metres up and has no colour a field away; tipping each far plant's head at random (`farTilt`) showed half of them from behind. `Foliage.faceEyeNear` and `Foliage.faceEye` turn the head of every mesh plant toward the eye, by the first close to and by the second from half the draw distance away, as a clump of flowers shows its colour from the side. It is done the way a pivot painted into a uv is elsewhere: the copies carry in a second uv where each vertex of a head sits from its plant's axis, and a material's vertex hook now reads a mesh's second uv as `es_vertexUv1` (zero on a mesh with none), beside `es_vertexColor`. At 0 and 0, the default, no channel is added and nothing turns.
- **A far field of flowers shows its colour.** A mesh plant kept in a far version grows across the ground to stand for those left out. A flat flower grown that way is a disc facing the sky: from an eye a few metres up it is seen edge on, and a meadow that is all flowers at your feet was plain green a field away. `Foliage.farTilt` tips the top of each far plant over by so many degrees (the last tenth of its height: the flower, not its stem), each plant its own way round, so half the field shows its face. 0, the default, leaves a far plant as it was.
diff --git a/docs/astro/src/content/docs/graphics/post-processing.mdx b/docs/astro/src/content/docs/graphics/post-processing.mdx
index 348ee73a8..7f96f0962 100644
--- a/docs/astro/src/content/docs/graphics/post-processing.mdx
+++ b/docs/astro/src/content/docs/graphics/post-processing.mdx
@@ -20,7 +20,7 @@ several can stack in one frame at no extra target cost beyond the passes.
| `lutGrade` | Color grading through a lookup-table texture, on scene values in the chain | `u_lut` (texture), `intensity` |
| `displayLut` | A look read off a lookup table by the picture as the display shows it, in the last pass after the output transform | `u_lut` (texture), `intensity` |
| `agx` | The AgX view transform Blender uses: scene-linear in, display-linear out, so it goes last and the output transform stays `none`. Brings its own table | `contrast` (the look: 1 is AgX Base, 1.2 is Medium High Contrast) |
-| `vignette` | Darkened screen edges | `intensity`, `softness` |
+| `vignette` | Darkened screen edges: full at `radius`, soft for `softness` inside it. `roundness` 0 follows the frame (1 is the middle of an edge), 1 is a circle whose 1 is the corner | `intensity`, `softness`, `radius`, `roundness` |
| `chromaticAberration` | RGB fringing | `intensity` |
| `blur` | Gaussian blur | `intensity` |
| `fxaa` | Fast anti-aliasing | `intensity` |
@@ -127,6 +127,10 @@ as the display shows it, so put the grade **after Tonemap**: before it, 0 to 1 i
by default). White is no change; they are multipliers and are not colour-managed, so `(0.80, 1.01, 1.13)` in the shadows and `(1.07, 1.0, 0.90)` in the
highlights is teal and warm, and may go above 1.
- **S-Curve** blends in a smoothstep about the picture's range: shadows sink a little, highlights lift. 0 is off.
+- **Gain** and **Offset** are a grade's slope and offset: every tone is multiplied by the gain, then the offset is added. An offset under zero
+ sinks the blacks, and what is darker than it is black, which a contrast through mid-grey does not do in a linear project (there it is a
+ power curve about 0.18 and leaves black where it was). A contrast written elsewhere as a line through 0.5, `(c - 0.5) * k + 0.5`, is a gain
+ of `k` and an offset of `0.5 - 0.5 * k`: 1.04 is `u_gain` 1.04 and `u_offset` -0.02.
- **Lift** is a tinted black level, added to every tone at a tenth of its colour, so `(0.06, 0.085, 0.11)` lifts the blacks by about `(0.006, 0.0085, 0.011)`
toward teal and a scene with no black left reads as air rather than as ink.
diff --git a/docs/astro/src/content/docs/zh-cn/graphics/post-processing.mdx b/docs/astro/src/content/docs/zh-cn/graphics/post-processing.mdx
index dc51c707e..083a9ae4a 100644
--- a/docs/astro/src/content/docs/zh-cn/graphics/post-processing.mdx
+++ b/docs/astro/src/content/docs/zh-cn/graphics/post-processing.mdx
@@ -19,7 +19,7 @@ Estella 通过 ping-pong 帧缓冲运行全屏后处理。加一个 `PostProcess
| `lutGrade` | 通过查找表纹理(LUT)调色,作用在效果链里的场景值上 | `u_lut`(纹理)、`intensity` |
| `displayLut` | 在最后一个通道里、输出变换之后,按画面在显示器上的样子从查找表取出的调色 | `u_lut`(纹理)、`intensity` |
| `agx` | Blender 使用的 AgX 视图变换:输入场景线性、输出显示线性,所以放在最后,输出变换保持 `none`。自带查找表 | `contrast`(观感:1 是 AgX Base,1.2 是 Medium High Contrast) |
-| `vignette` | 屏幕边缘变暗 | `intensity`、`softness` |
+| `vignette` | 屏幕边缘变暗:在 `radius` 处达到最大,往里 `softness` 的范围内渐变。`roundness` 为 0 时跟随画面形状(1 是边的中点),为 1 时是圆形,1 是画面的角 | `intensity`、`softness`、`radius`、`roundness` |
| `chromaticAberration` | RGB 色散 | `intensity` |
| `motionBlur` | 沿上一帧以来的运动抹开:相机的移动来自深度缓冲,运动网格自身的移动来自运动 pass | `intensity`(快门)、`maxBlur`、`objectMotion` |
| `filmGrain` | 胶片晶粒大小的噪点,在中间调最强,随时钟闪动 | `intensity`、`size`、`response` |
@@ -108,6 +108,7 @@ Estella 通过 ping-pong 帧缓冲运行全屏后处理。加一个 `PostProcess
- **阴影染色**和**高光染色**分别乘在暗处和亮处,按亮度在**色调下限**和**色调上限**(默认 0.03 和 0.55)之间过渡。白色表示不变;它们是乘数,不做色彩管理,
阴影里的 `(0.80, 1.01, 1.13)` 和高光里的 `(1.07, 1.0, 0.90)` 就是偏青和偏暖,数值可以大于 1。
- **S 曲线**混入围绕画面范围的平滑阶梯曲线:阴影略沉,高光略提。0 为关闭。
+- **增益**和**偏移**是调色里的斜率和偏移:每个色调先乘以增益,再加上偏移。偏移小于零会把黑位压下去,比它暗的都成纯黑;线性项目里以中灰为轴的对比度做不到这一点(那里它是绕 0.18 的幂曲线,黑位不动)。别处写成过 0.5 的直线的对比度 `(c - 0.5) * k + 0.5`,等于增益 `k` 加偏移 `0.5 - 0.5 * k`:1.04 就是 `u_gain` 1.04、`u_offset` -0.02。
- **抬升**是带色相的黑位,按其颜色的十分之一加在所有色调上,`(0.06, 0.085, 0.11)` 会把黑位朝青色抬高约 `(0.006, 0.0085, 0.011)`,让没有纯黑的场景像空气而不是墨。
默认值是白、白、黑和 0,所以现有的分级不会变。
diff --git a/sdk/src/postprocess/effects.ts b/sdk/src/postprocess/effects.ts
index f3563104e..6c957b198 100644
--- a/sdk/src/postprocess/effects.ts
+++ b/sdk/src/postprocess/effects.ts
@@ -225,6 +225,8 @@ registerEffect({
uniforms: [
{ name: 'u_intensity', label: 'Intensity', min: 0, max: 1, step: 0.01, defaultValue: 0.6 },
{ name: 'u_softness', label: 'Softness', min: 0, max: 1, step: 0.01, defaultValue: 0.5 },
+ { name: 'u_radius', label: 'Radius', min: 0.05, max: 2, step: 0.01, defaultValue: 1 },
+ { name: 'u_roundness', label: 'Roundness', min: 0, max: 1, step: 0.01, defaultValue: 0 },
],
});
@@ -252,6 +254,9 @@ registerEffect({
{ name: 'u_toneLow', label: 'Tone Low', min: 0, max: 1, step: 0.01, defaultValue: 0.03 },
{ name: 'u_toneHigh', label: 'Tone High', min: 0, max: 1, step: 0.01, defaultValue: 0.55 },
{ name: 'u_curve', label: 'S-Curve', min: 0, max: 1, step: 0.01, defaultValue: 0, neutralValue: 0 },
+ // A grade's slope and offset, on the picture as the display shows it: every tone times the gain, then the offset added.
+ { name: 'u_gain', label: 'Gain', min: 0, max: 4, step: 0.01, defaultValue: 1, neutralValue: 1 },
+ { name: 'u_offset', label: 'Offset', min: -0.5, max: 0.5, step: 0.001, defaultValue: 0, neutralValue: 0 },
],
colors: [
// Multipliers, not colour-managed: white leaves a tone as it is, teal in the shadows and warm in the highlights is the cinema look.
diff --git a/sdk/src/postprocess/sources/basic.ts b/sdk/src/postprocess/sources/basic.ts
index 9832901fc..f9323ff3e 100644
--- a/sdk/src/postprocess/sources/basic.ts
+++ b/sdk/src/postprocess/sources/basic.ts
@@ -262,6 +262,10 @@ void main() {
#pragma domain PostProcess
#pragma param u_intensity float default(0.6) range(0,1)
#pragma param u_softness float default(0.5) range(0,1)
+// Where it is full, and over what shape. At roundness 0 the distance is the picture's own (1 at the middle of an edge, so the
+// darkening is an ellipse that fills the frame); at 1 it is a circle and 1 is the corner, whatever the frame's shape.
+#pragma param u_radius float default(1) range(0.05,2)
+#pragma param u_roundness float default(0) range(0,1)
#pragma fragment
precision highp float;
@@ -273,8 +277,9 @@ out vec4 fragColor;
void main() {
vec4 color = texture(u_texture, v_texCoord);
vec2 uv = v_texCoord * 2.0 - 1.0;
- float dist = length(uv);
- float vig = 1.0 - smoothstep(1.0 - u_softness, 1.0, dist);
+ vec2 round = vec2(u_viewport.x / max(u_viewport.y, 1.0), 1.0);
+ float dist = mix(length(uv), length(uv * round) / length(round), u_roundness);
+ float vig = 1.0 - smoothstep(u_radius - u_softness, u_radius, dist);
fragColor = vec4(color.rgb * mix(1.0, vig, u_intensity), color.a);
}
#pragma end
@@ -283,8 +288,9 @@ void main() {
@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {
let color = textureSampleLevel(t0, s0, v.v_texCoord, 0.0);
let uv = v.v_texCoord * 2.0 - 1.0;
- let dist = length(uv);
- let vig = 1.0 - smoothstep(1.0 - mc.u_softness, 1.0, dist);
+ let round = vec2f(tc.u_viewport.x / max(tc.u_viewport.y, 1.0), 1.0);
+ let dist = mix(length(uv), length(uv * round) / length(round), mc.u_roundness);
+ let vig = 1.0 - smoothstep(mc.u_radius - mc.u_softness, mc.u_radius, dist);
return vec4f(color.rgb * mix(1.0, vig, mc.u_intensity), color.a);
}
#pragma end
@@ -486,6 +492,8 @@ void main() {
#pragma param u_toneHigh float default(0.55) range(0,1)
#pragma param u_curve float default(0) range(0,1)
#pragma param u_lift color default(0,0,0,1)
+#pragma param u_gain float default(1) range(0,4)
+#pragma param u_offset float default(0) range(-0.5,0.5)
#pragma fragment
precision highp float;
@@ -518,6 +526,10 @@ void main() {
vec3 cc = clamp(c, 0.0, 1.0);
c = mix(c, cc * cc * (3.0 - 2.0 * cc), u_curve);
+ // Gain and offset (a grade's slope and offset): every tone times the gain, then the offset added. An offset under zero sinks the
+ // blacks, and what is darker than it is black; a contrast written as a line through 0.5 is a gain and an offset under zero.
+ c = c * u_gain + u_offset;
+
// Lift: a tinted black level, added to everything (a tenth of the colour, so a small lift is a usable colour).
c += u_lift.rgb * 0.1;
@@ -548,6 +560,8 @@ void main() {
let cc = clamp(c, vec3f(0.0), vec3f(1.0));
c = mix(c, cc * cc * (3.0 - 2.0 * cc), mc.u_curve);
+ c = c * mc.u_gain + vec3f(mc.u_offset);
+
c += mc.u_lift.rgb * 0.1;
let luma = dot(c, vec3f(0.2126, 0.7152, 0.0722));
diff --git a/sdk/tests/postprocess.test.ts b/sdk/tests/postprocess.test.ts
index 909bb75da..dceca2c96 100644
--- a/sdk/tests/postprocess.test.ts
+++ b/sdk/tests/postprocess.test.ts
@@ -384,6 +384,13 @@ describe('PostProcess API', () => {
it('should create vignette with its params reflected', () => {
postProcessEffects.createVignette();
expect(lastSource()).toContain('#pragma param u_softness float');
+ // Full at the radius, soft inside it, over the frame's own ellipse or a circle to the corner; the defaults are the shape it was.
+ expect(lastSource()).toContain('#pragma param u_radius float default(1)');
+ expect(lastSource()).toContain('#pragma param u_roundness float default(0)');
+ expect(lastSource()).toContain('smoothstep(u_radius - u_softness, u_radius, dist)');
+ expect(lastSource()).toContain('smoothstep(mc.u_radius - mc.u_softness, mc.u_radius, dist)');
+ expect(lastSource()).toContain('mix(length(uv), length(uv * round) / length(round), u_roundness)');
+ expect(lastSource()).toContain('mix(length(uv), length(uv * round) / length(round), mc.u_roundness)');
});
it('should create grayscale with Rec.601 luma weights', () => {
@@ -413,7 +420,7 @@ describe('PostProcess API', () => {
// Identity: 2^0=1, contrast 1, saturation 1, no white-balance shift, no S-curve; the tints are white and the lift black.
expect(defaults).toEqual({
u_exposure: 0, u_contrast: 1, u_saturation: 1, u_temperature: 0, u_tint: 0,
- u_toneLow: 0.03, u_toneHigh: 0.55, u_curve: 0,
+ u_toneLow: 0.03, u_toneHigh: 0.55, u_curve: 0, u_gain: 1, u_offset: 0,
});
const colours = Object.fromEntries((def?.colors ?? []).map(c => [c.name, c.defaultValue]));
expect(colours.u_shadowTint).toEqual({ r: 1, g: 1, b: 1, a: 1 });
@@ -421,6 +428,17 @@ describe('PostProcess API', () => {
expect(colours.u_lift).toEqual({ r: 0, g: 0, b: 0, a: 1 });
});
+ it('colorGrade has a gain and an offset, applied before the lift in both languages', () => {
+ postProcessEffects.createColorGrade();
+ const src = lastSource();
+ expect(src).toContain('#pragma param u_gain float default(1)');
+ expect(src).toContain('#pragma param u_offset float default(0) range(-0.5,0.5)');
+ expect(src.indexOf('c = c * u_gain + u_offset;')).toBeGreaterThan(0);
+ expect(src.indexOf('c = c * u_gain + u_offset;')).toBeLessThan(src.indexOf('c += u_lift.rgb * 0.1;'));
+ expect(src.indexOf('c = c * mc.u_gain + vec3f(mc.u_offset);')).toBeLessThan(src.indexOf('c += mc.u_lift.rgb * 0.1;'));
+ expect(src.indexOf('c = c * mc.u_gain + vec3f(mc.u_offset);')).toBeGreaterThan(0);
+ });
+
it('colorGrade takes contrast about the mid-grey of the colour space it runs in', () => {
const sourceFor = (linear: boolean): string => {
setLinearColorSpace(linear);
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 4e6abfa02..7c5421bab 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -4628,6 +4628,8 @@ export const NOTED = {
{"note": "A flower turns to face the eye."},
"feat(foliage): a blade's lean, its turn to the eye, and what a leaf lets through and mirrors are yours to set - Foliage.bladeLean was a 0.12 written into the builder, the mirror a 0.5 written into the shader, and the light through a leaf could only be the leaf's own colour; u_bladeFaceEye turns a blade's flat to the eye":
{"note": "A blade's lean, its turn to the eye, and what a leaf lets through and mirrors are yours to set."},
+ "feat(post): the grade has a gain and an offset, and the vignette a radius and a roundness - a grade could lift the blacks and not sink them, so a look whose contrast is a line through 0.5 came out a third as saturated in the dark; and a vignette was always full at the middle of every edge":
+ {"note": "The grade has a gain and an offset, and the vignette a radius and a roundness."},
"fix(terrain): a detail the pages cannot hold no longer cracks the ground - a tree that wanted more nodes than the atlas has pages was drawn in part by coarser pages standing in, which do not meet their finer neighbours' edges, and the pages were fought over every frame; the ground is now drawn at the share of its detail's range that fits, and says so once":
{"note": "A detail the pages cannot hold no longer cracks the ground."},
"fix(foliage): a far plant grows across the ground, not taller - a mesh plant kept in a far version was grown the same every way to cover the ground of those left out, so a flower that stood for ten stood ten times as high and a far meadow was a field of poles; it now grows across the ground only, and Foliage.farGrowUp gives its height a share of the growth back":