@threedog/post-effects 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 penstic
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/dof.js ADDED
@@ -0,0 +1,66 @@
1
+ // Depth of field: blur by distance from a focus plane, read from the scene depth texture (hdr slot, needsDepth).
2
+ // It swaps buffers like any pass, but copies the scene depth into its output target (gl_FragDepth, same fullscreen draw, no extra pass or target),
3
+ // so a later depth reader such as outline still finds the scene's depth in the buffer it reads; keepsDepth tells the chain check so.
4
+ import * as THREE from 'three';
5
+ import { Pass, FullScreenQuad } from 'three/addons/postprocessing/Pass.js';
6
+ /** @import { PostEffect } from 'threedog' */
7
+
8
+ class DofPass extends Pass {
9
+ constructor(camera) {
10
+ super();
11
+ this.camera = camera;
12
+ this.keepsDepth = true;
13
+ this.material = new THREE.ShaderMaterial({
14
+ uniforms: { tDiffuse: { value: null }, tDepth: { value: null }, uTexel: { value: new THREE.Vector2() }, uNear: { value: 0.3 }, uFar: { value: 1000 },
15
+ uFocus: { value: 10 }, uRange: { value: 2 }, uFalloff: { value: 20 }, uMaxBlur: { value: 6 } },
16
+ vertexShader: 'varying vec2 vUv; void main(){ vUv = uv; gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0); }',
17
+ fragmentShader: `uniform sampler2D tDiffuse; uniform sampler2D tDepth; uniform vec2 uTexel; uniform float uNear; uniform float uFar;
18
+ uniform float uFocus; uniform float uRange; uniform float uFalloff; uniform float uMaxBlur;
19
+ varying vec2 vUv;
20
+ float lin(vec2 uv){ float z = texture2D(tDepth, uv).x * 2.0 - 1.0; return 2.0 * uNear * uFar / (uFar + uNear - z * (uFar - uNear)); }
21
+ float coc(float d){ return clamp((abs(d - uFocus) - uRange) / uFalloff, 0.0, 1.0) * uMaxBlur; }
22
+ void main(){
23
+ gl_FragDepth = texture2D(tDepth, vUv).x;
24
+ float r = coc(lin(vUv));
25
+ if (r < 0.5) { gl_FragColor = texture2D(tDiffuse, vUv); return; }
26
+ vec3 sum = texture2D(tDiffuse, vUv).rgb; float w = 1.0;
27
+ // golden-angle disk; a neighbor in sharp focus (smaller blur than its distance) is left out so a crisp object does not bleed into the haze
28
+ for (int i = 1; i < 16; i++) {
29
+ float t = float(i) / 16.0, a = float(i) * 2.39996;
30
+ vec2 o = vec2(cos(a), sin(a)) * sqrt(t) * r;
31
+ float s = step(length(o) * 0.5, coc(lin(vUv + o * uTexel)) + 0.5);
32
+ sum += texture2D(tDiffuse, vUv + o * uTexel).rgb * s; w += s;
33
+ }
34
+ gl_FragColor = vec4(sum / w, 1.0);
35
+ }`,
36
+ });
37
+ // the depth test always passes; depth writes are on only to store gl_FragDepth
38
+ this.material.depthTest = true; this.material.depthWrite = true; this.material.depthFunc = THREE.AlwaysDepth;
39
+ this.quad = new FullScreenQuad(this.material);
40
+ }
41
+ render(renderer, writeBuffer, readBuffer) {
42
+ const u = this.material.uniforms;
43
+ u.tDiffuse.value = readBuffer.texture; u.tDepth.value = readBuffer.depthTexture;
44
+ u.uTexel.value.set(1 / readBuffer.width, 1 / readBuffer.height);
45
+ u.uNear.value = this.camera.near; u.uFar.value = this.camera.far;
46
+ renderer.setRenderTarget(this.renderToScreen ? null : writeBuffer);
47
+ this.quad.render(renderer);
48
+ }
49
+ dispose() { this.material.dispose(); this.quad.dispose(); }
50
+ }
51
+
52
+ /**
53
+ * Depth of field (hdr slot, costly): everything farther from `focus` than `range` blurs, up to `maxBlur` pixels over `falloff` meters.
54
+ * It reads scene depth, so it must run before any pass that swaps buffers; it passes the scene depth on in its output, so a depth reader
55
+ * after it (outline, whose default order is later) works: both can be on, lines drawn over the blurred image. Move the focus per frame with
56
+ * engine.post.get('dof').set({ focus: distanceToTarget }).
57
+ * @example post: [dof({ enabled: true, focus: 8, range: 3, maxBlur: 5 })]
58
+ * @param {{ focus?: number, range?: number, falloff?: number, maxBlur?: number, enabled?: boolean, order?: number }} [o]
59
+ * focus, range, falloff in meters; maxBlur in device pixels
60
+ * @returns {PostEffect}
61
+ */
62
+ export function dof({ focus = 10, range = 2, falloff = 20, maxBlur = 6, enabled = false, order = 5 } = {}) {
63
+ const update = (pass, p) => { const u = pass.material.uniforms; u.uFocus.value = p.focus; u.uRange.value = p.range; u.uFalloff.value = p.falloff; u.uMaxBlur.value = p.maxBlur; };
64
+ return { name: 'dof', slot: 'hdr', order, enabled, costly: true, needsDepth: true, params: { focus, range, falloff, maxBlur },
65
+ create: ({ camera, params }) => { const pass = new DofPass(camera); update(pass, params); return pass; }, update };
66
+ }
package/hdr.js ADDED
@@ -0,0 +1,28 @@
1
+ // Bloom and ambient occlusion (GTAO) as engine.post effects (hdr slot). Both are costly, so they start off on low-tier devices.
2
+ import * as THREE from 'three';
3
+ import { UnrealBloomPass } from 'three/addons/postprocessing/UnrealBloomPass.js';
4
+ import { GTAOPass } from 'three/addons/postprocessing/GTAOPass.js';
5
+ /** @import { PostEffect } from 'threedog' */
6
+
7
+ /**
8
+ * Bloom (glow around bright pixels), hdr slot. Off by default on low-tier devices.
9
+ * @example post: [bloom({ strength: 0.35, radius: 0.5, threshold: 0.85 })]
10
+ * @param {{ strength?: number, radius?: number, threshold?: number, enabled?: boolean, order?: number }} [o]
11
+ * @returns {PostEffect}
12
+ */
13
+ export function bloom({ strength = 0.35, radius = 0.5, threshold = 0.85, enabled, order = 30 } = {}) {
14
+ return { name: 'bloom', slot: 'hdr', order, enabled, costly: true, params: { strength, radius, threshold },
15
+ create: ({ width, height, params: p }) => new UnrealBloomPass(new THREE.Vector2(width, height), p.strength, p.radius, p.threshold),
16
+ update: (pass, p) => { pass.strength = p.strength; pass.radius = p.radius; pass.threshold = p.threshold; } };
17
+ }
18
+
19
+ /**
20
+ * Ambient occlusion (soft contact shadows in corners; costly), hdr slot, off unless enabled.
21
+ * @example post: [ao({ enabled: true })]
22
+ * @param {{ enabled?: boolean, order?: number }} [o]
23
+ * @returns {PostEffect}
24
+ */
25
+ export function ao({ enabled = false, order = 20 } = {}) {
26
+ return { name: 'ao', slot: 'hdr', order, enabled, costly: true,
27
+ create: ({ scene, camera, width, height }) => new GTAOPass(scene, camera, width, height) };
28
+ }
package/index.d.ts ADDED
@@ -0,0 +1,24 @@
1
+ // Types of @threedog/post-effects for code that imports it from the published package
2
+ // (TypeScript does not read JS inside node_modules, so without this the import would be untyped).
3
+ import type { PostEffect, ColorLike } from 'threedog';
4
+ import type { Data3DTexture } from 'three';
5
+
6
+ /** Color grading (ldr, fused): contrast / saturation 1 = unchanged, temperature -1 cool .. 1 warm, optional 3D LUT (e.g. LUTCubeLoader's texture3D) */
7
+ export function lut(o?: { lut?: Data3DTexture | null; amount?: number; contrast?: number; saturation?: number; temperature?: number; enabled?: boolean; order?: number }): PostEffect;
8
+ /** Film grain (ldr, fused); size in device pixels, animated = new noise 24 times a second */
9
+ export function grain(o?: { amount?: number; size?: number; animated?: boolean; enabled?: boolean; order?: number }): PostEffect;
10
+ /** Darker corners (ldr, fused); start: 0 center .. 1 corner */
11
+ export function vignette(o?: { strength?: number; start?: number; enabled?: boolean; order?: number }): PostEffect;
12
+ /** Red / blue shift apart toward the screen edge (ldr, fused; starts a fused group because it samples the input) */
13
+ export function chromatic(o?: { amount?: number; enabled?: boolean; order?: number }): PostEffect;
14
+ /** Depth of field (hdr, costly, reads scene depth; passes it on, so it can be on with outline when its order is lower, lines then stay sharp); meters / device pixels */
15
+ export function dof(o?: { focus?: number; range?: number; falloff?: number; maxBlur?: number; enabled?: boolean; order?: number }): PostEffect;
16
+
17
+ /** Bloom (glow around bright pixels; hdr, costly: off by default on low-tier devices) */
18
+ export function bloom(o?: { strength?: number; radius?: number; threshold?: number; enabled?: boolean; order?: number }): PostEffect;
19
+ /** Ambient occlusion (soft contact shadows in corners; hdr, costly, off unless enabled) */
20
+ export function ao(o?: { enabled?: boolean; order?: number }): PostEffect;
21
+ /** Outline (hdr, reads scene depth, off unless enabled). mode 'depth' (default) = silhouettes, 'normal' = creases (extra scene render, costly), 'both'; wobble = line jitter in pixels; offLayer = objects with that three.js layer enabled get no lines (use OUTLINE_OFF_LAYER) */
22
+ export function outline(o?: { color?: ColorLike; thickness?: number; strength?: number; mode?: 'depth' | 'normal' | 'both'; fadeWithDistance?: boolean; wobble?: number; offLayer?: number | null; enabled?: boolean; order?: number }): PostEffect;
23
+ /** Layer number (29) for outline({ offLayer }): mesh.layers.enable(OUTLINE_OFF_LAYER) exempts that object from the lines */
24
+ export const OUTLINE_OFF_LAYER: number;
package/index.js ADDED
@@ -0,0 +1,88 @@
1
+ // @threedog/post-effects: optional post effects for engine.post. The engine ships none (it owns no look); a style pack or a game adds the ones it wants:
2
+ // import { vignette, grain, lut } from '@threedog/post-effects';
3
+ // createEngine({ canvas, style: [lowpoly, postAdd(vignette({ enabled: true }), grain({ enabled: true }))] });
4
+ // Style packs list bloom / ao / outline in their own style.post; they all import from here, never from each other.
5
+ // hdr slot (linear, before tone mapping): bloom, ao, outline, dof. ldr slot (sRGB, after it): lut, grain, vignette, chromatic.
6
+ // lut / grain / vignette / chromatic carry a `fuse` GLSL snippet, so when several are on they run as one fullscreen pass.
7
+ // All are off unless you pass enabled: true.
8
+ import * as THREE from 'three';
9
+ export { dof } from './dof.js';
10
+ export { bloom, ao } from './hdr.js';
11
+ export { outline, OUTLINE_OFF_LAYER } from './outline.js';
12
+ /** @import { PostEffect } from 'threedog' */
13
+
14
+ // A 2x2x2 identity LUT stands in until the game gives a real one (a sampler uniform must always hold a texture)
15
+ const identity = new THREE.Data3DTexture(new Uint8Array([0, 0, 0, 255, 255, 0, 0, 255, 0, 255, 0, 255, 255, 255, 0, 255,
16
+ 0, 0, 255, 255, 255, 0, 255, 255, 0, 255, 255, 255, 255, 255, 255, 255]), 2, 2, 2);
17
+ identity.format = THREE.RGBAFormat; identity.minFilter = identity.magFilter = THREE.LinearFilter; identity.unpackAlignment = 1; identity.needsUpdate = true;
18
+
19
+ /**
20
+ * Color grading in sRGB space (ldr slot): contrast, saturation, warm/cool shift and an optional 3D LUT, in one fused snippet.
21
+ * @example
22
+ * import { LUTCubeLoader } from 'three/addons/loaders/LUTCubeLoader.js';
23
+ * const { texture3D } = await new LUTCubeLoader().loadAsync('/luts/warm.cube');
24
+ * post: [lut({ enabled: true, lut: texture3D, amount: 0.8, saturation: 1.1, temperature: 0.2 })]
25
+ * @param {{ lut?: import('three').Data3DTexture | null, amount?: number, contrast?: number, saturation?: number, temperature?: number, enabled?: boolean, order?: number }} [o]
26
+ * lut: a 3D LUT texture (null = only the numbers below); amount: how much of the LUT result to use (0..1); contrast, saturation: 1 = unchanged;
27
+ * temperature: -1 cool .. 1 warm
28
+ * @returns {PostEffect}
29
+ */
30
+ export function lut({ lut = null, amount = 1, contrast = 1, saturation = 1, temperature = 0, enabled = false, order = 10 } = {}) {
31
+ return { name: 'lut', slot: 'ldr', order, enabled, params: { lut, amount, contrast, saturation, temperature },
32
+ fuse: {
33
+ uniforms: { uLutTex: 'sampler3D', uLutSize: 'float', uLutAmount: 'float', uLutContrast: 'float', uLutSaturation: 'float', uLutTemp: 'float' },
34
+ values: p => ({ uLutTex: p.lut ?? identity, uLutSize: (p.lut ?? identity).image.width, uLutAmount: p.lut ? p.amount : 0,
35
+ uLutContrast: p.contrast, uLutSaturation: p.saturation, uLutTemp: p.temperature }),
36
+ glsl: `color.rgb += vec3(uLutTemp * 0.06, 0.0, -uLutTemp * 0.06);
37
+ color.rgb = clamp((color.rgb - 0.5) * uLutContrast + 0.5, 0.0, 1.0);
38
+ color.rgb = mix(vec3(dot(color.rgb, vec3(0.2126, 0.7152, 0.0722))), color.rgb, uLutSaturation);
39
+ if (uLutAmount > 0.0) color.rgb = mix(color.rgb, texture(uLutTex, clamp(color.rgb, 0.0, 1.0) * ((uLutSize - 1.0) / uLutSize) + 0.5 / uLutSize).rgb, uLutAmount);` } };
40
+ }
41
+
42
+ /**
43
+ * Film grain (ldr slot): per-pixel noise, a little weaker in highlights.
44
+ * @example post: [grain({ enabled: true, amount: 0.06 })]
45
+ * @param {{ amount?: number, size?: number, animated?: boolean, enabled?: boolean, order?: number }} [o]
46
+ * amount: noise strength; size: grain size in device pixels; animated: new noise every frame (24 per second)
47
+ * @returns {PostEffect}
48
+ */
49
+ export function grain({ amount = 0.06, size = 1, animated = true, enabled = false, order = 30 } = {}) {
50
+ return { name: 'grain', slot: 'ldr', order, enabled, params: { amount, size, animated },
51
+ fuse: {
52
+ uniforms: { uGrainAmount: 'float', uGrainSize: 'float', uGrainAnimated: 'float' },
53
+ values: p => ({ uGrainAmount: p.amount, uGrainSize: Math.max(1, p.size), uGrainAnimated: p.animated ? 1 : 0 }),
54
+ glsl: `float n = fxHash(floor(vUv * uResolution / uGrainSize) + (uGrainAnimated > 0.5 ? floor(uTime * 24.0) * 17.0 : 0.0)) - 0.5;
55
+ color.rgb += n * uGrainAmount * (1.0 - 0.5 * dot(color.rgb, vec3(0.299, 0.587, 0.114)));` } };
56
+ }
57
+
58
+ /**
59
+ * Vignette (ldr slot): darker screen corners.
60
+ * @example post: [vignette({ enabled: true, strength: 0.4 })]
61
+ * @param {{ strength?: number, start?: number, enabled?: boolean, order?: number }} [o]
62
+ * strength: darkness at the corners (0..1); start: distance from the center where darkening begins (0 center .. 1 corner)
63
+ * @returns {PostEffect}
64
+ */
65
+ export function vignette({ strength = 0.35, start = 0.45, enabled = false, order = 20 } = {}) {
66
+ return { name: 'vignette', slot: 'ldr', order, enabled, params: { strength, start },
67
+ fuse: {
68
+ uniforms: { uVigStrength: 'float', uVigStart: 'float' },
69
+ values: p => ({ uVigStrength: p.strength, uVigStart: p.start }),
70
+ glsl: 'color.rgb *= 1.0 - uVigStrength * smoothstep(uVigStart, 1.0, length(vUv - 0.5) * 1.4142);' } };
71
+ }
72
+
73
+ /**
74
+ * Chromatic aberration (ldr slot): red and blue shift apart toward the screen edge. Samples the pass input, so it starts a fused group
75
+ * (default order puts it first, so it still joins the others).
76
+ * @example post: [chromatic({ enabled: true, amount: 0.004 })]
77
+ * @param {{ amount?: number, enabled?: boolean, order?: number }} [o] amount: edge shift in screen fractions
78
+ * @returns {PostEffect}
79
+ */
80
+ export function chromatic({ amount = 0.004, enabled = false, order = 5 } = {}) {
81
+ return { name: 'chromatic', slot: 'ldr', order, enabled, params: { amount },
82
+ fuse: {
83
+ reads: true,
84
+ uniforms: { uChromaAmount: 'float' },
85
+ values: p => ({ uChromaAmount: p.amount }),
86
+ glsl: `vec2 off = (vUv - 0.5) * uChromaAmount;
87
+ color.r = texture2D(tDiffuse, vUv + off).r; color.b = texture2D(tDiffuse, vUv - off).b;` } };
88
+ }
package/outline.js ADDED
@@ -0,0 +1,120 @@
1
+ // Outline post effect: dark lines where depth jumps (object silhouettes), where surface normals turn sharply (creases), or both;
2
+ // optional hand-drawn wobble and per-object exemption through a three.js layer.
3
+ import * as THREE from 'three';
4
+ import { Pass, FullScreenQuad } from 'three/addons/postprocessing/Pass.js';
5
+ /** @import { PostEffect } from 'threedog' */
6
+
7
+ /** Layer number to put on objects that should get no outline: mesh.layers.enable(OUTLINE_OFF_LAYER), with outline({ offLayer: OUTLINE_OFF_LAYER }) */
8
+ export const OUTLINE_OFF_LAYER = 29;
9
+ const MODES = { depth: 0, normal: 1, both: 2 };
10
+
11
+ class OutlinePass extends Pass {
12
+ /** @param {any} scene @param {any} camera @param {Record<string, any>} p */
13
+ constructor(scene, camera, p) {
14
+ super();
15
+ this.scene = scene; this.camera = camera; this.p = p; this.time = 0;
16
+ this.normalMat = new THREE.MeshNormalMaterial();
17
+ this.maskMat = new THREE.MeshBasicMaterial({ color: 0xffffff });
18
+ this.normalRT = null; this.maskRT = null;
19
+ this.material = new THREE.ShaderMaterial({
20
+ uniforms: { tDiffuse: { value: null }, tDepth: { value: null }, tNormal: { value: null }, tMask: { value: null }, tMaskDepth: { value: null },
21
+ uTexel: { value: new THREE.Vector2() }, uNear: { value: 0.3 }, uFar: { value: 1000 }, uColor: { value: new THREE.Color(p.color) },
22
+ uThick: { value: 1 }, uStrength: { value: 1 }, uMode: { value: 0 }, uFade: { value: 1 }, uWobble: { value: 0 }, uTime: { value: 0 }, uUseMask: { value: 0 } },
23
+ vertexShader: 'varying vec2 vUv; void main(){ vUv = uv; gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0); }',
24
+ fragmentShader: `uniform sampler2D tDiffuse; uniform sampler2D tDepth; uniform sampler2D tNormal; uniform sampler2D tMask; uniform sampler2D tMaskDepth;
25
+ uniform vec2 uTexel; uniform float uNear; uniform float uFar; uniform vec3 uColor; uniform float uThick; uniform float uStrength;
26
+ uniform float uMode; uniform float uFade; uniform float uWobble; uniform float uTime; uniform float uUseMask;
27
+ varying vec2 vUv;
28
+ float lin(sampler2D t, vec2 uv){ float z = texture2D(t, uv).x * 2.0 - 1.0; return 2.0 * uNear * uFar / (uFar + uNear - z * (uFar - uNear)); }
29
+ float h2(vec2 p){ return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453); }
30
+ float vn(vec2 p){ vec2 i = floor(p), f = fract(p); f = f * f * (3.0 - 2.0 * f);
31
+ return mix(mix(h2(i), h2(i + vec2(1, 0)), f.x), mix(h2(i + vec2(0, 1)), h2(i + vec2(1, 1)), f.x), f.y); }
32
+ // object in the exempt layer at this pixel: its own render is not behind what the scene depth saw
33
+ float masked(vec2 uv){ return texture2D(tMask, uv).r > 0.5 && lin(tMaskDepth, uv) <= lin(tDepth, uv) + 0.05 ? 1.0 : 0.0; }
34
+ void main(){
35
+ vec4 c = texture2D(tDiffuse, vUv);
36
+ vec2 o = uTexel * uThick;
37
+ vec2 uv = vUv;
38
+ if (uWobble > 0.0) uv += (vec2(vn(vUv / uTexel * 0.04 + uTime), vn(vUv / uTexel * 0.04 + 17.3 + uTime)) - 0.5) * 2.0 * uWobble * uTexel;
39
+ vec2 nb[4] = vec2[4](vec2(o.x, 0.0), vec2(-o.x, 0.0), vec2(0.0, o.y), vec2(0.0, -o.y)); // the four neighbors, thickness apart
40
+ float d = lin(tDepth, uv), edge = 0.0;
41
+ if (uMode != 1.0) {
42
+ float e = 0.0;
43
+ for (int i = 0; i < 4; i++) e += abs(lin(tDepth, uv + nb[i]) - d);
44
+ edge = smoothstep(0.08, 0.3, e / max(d, 0.5) * 4.0);
45
+ }
46
+ if (uMode != 0.0) {
47
+ vec3 n = texture2D(tNormal, uv).xyz * 2.0 - 1.0;
48
+ float k = 0.0;
49
+ for (int i = 0; i < 4; i++) k += 1.0 - dot(n, texture2D(tNormal, uv + nb[i]).xyz * 2.0 - 1.0);
50
+ edge = max(edge, smoothstep(0.35, 0.8, k));
51
+ }
52
+ if (uFade > 0.5) edge *= 1.0 - smoothstep(uFar * 0.4, uFar * 0.9, d);
53
+ if (uUseMask > 0.5) { float m = masked(vUv); for (int i = 0; i < 4; i++) m = max(m, masked(vUv + nb[i])); edge *= 1.0 - m; }
54
+ gl_FragColor = vec4(mix(c.rgb, uColor, edge * uStrength), c.a);
55
+ }`,
56
+ });
57
+ this.quad = new FullScreenQuad(this.material);
58
+ }
59
+ // Render the scene once with an override material into a target the size of the input
60
+ _pass(renderer, rt, mat, layer) {
61
+ const { scene, camera } = this, bg = scene.background, fog = scene.fog, mask = camera.layers.mask, color = renderer.getClearColor(new THREE.Color()), alpha = renderer.getClearAlpha();
62
+ const shadows = renderer.shadowMap.autoUpdate;
63
+ renderer.shadowMap.autoUpdate = false; // an override material is unlit: redrawing the shadow maps for it would be pure waste
64
+ scene.overrideMaterial = mat; scene.background = null; scene.fog = null;
65
+ if (layer != null) camera.layers.set(layer);
66
+ // linear (0.5, 0.5, 1): an empty pixel reads as a normal facing the camera, and for the mask its red 0.5 stays below the > 0.5 test
67
+ renderer.setClearColor(new THREE.Color().setRGB(0.5, 0.5, 1, THREE.LinearSRGBColorSpace), 1);
68
+ renderer.setRenderTarget(rt); renderer.clear(); renderer.render(scene, camera);
69
+ scene.overrideMaterial = null; scene.background = bg; scene.fog = fog; camera.layers.mask = mask; renderer.setClearColor(color, alpha);
70
+ renderer.shadowMap.autoUpdate = shadows;
71
+ }
72
+ _target(rt, w, h, depth) {
73
+ if (rt && (rt.width !== w || rt.height !== h)) { rt.setSize(w, h); return rt; }
74
+ if (rt) return rt;
75
+ rt = new THREE.WebGLRenderTarget(w, h);
76
+ if (depth) rt.depthTexture = new THREE.DepthTexture(w, h);
77
+ return rt;
78
+ }
79
+ render(renderer, writeBuffer, readBuffer, deltaTime) {
80
+ const u = this.material.uniforms, p = this.p, mode = MODES[p.mode], w = readBuffer.width, h = readBuffer.height;
81
+ // wobble redraws at 8 steps a second, like a hand-drawn flip book, so the lines tremble instead of swimming
82
+ this.time = (this.time + deltaTime) % 64;
83
+ if (mode !== 0) { this.normalRT = this._target(this.normalRT, w, h, true); this._pass(renderer, this.normalRT, this.normalMat); u.tNormal.value = this.normalRT.texture; }
84
+ const useMask = p.offLayer != null;
85
+ if (useMask) { this.maskRT = this._target(this.maskRT, w, h, true); this._pass(renderer, this.maskRT, this.maskMat, p.offLayer); u.tMask.value = this.maskRT.texture; u.tMaskDepth.value = this.maskRT.depthTexture; }
86
+ u.tDiffuse.value = readBuffer.texture; u.tDepth.value = readBuffer.depthTexture;
87
+ u.uTexel.value.set(1 / w, 1 / h);
88
+ u.uNear.value = this.camera.near; u.uFar.value = this.camera.far;
89
+ u.uMode.value = mode; u.uUseMask.value = useMask ? 1 : 0; u.uTime.value = Math.floor(this.time * 8);
90
+ renderer.setRenderTarget(this.renderToScreen ? null : writeBuffer);
91
+ this.quad.render(renderer);
92
+ }
93
+ dispose() { this.material.dispose(); this.quad.dispose(); this.normalMat.dispose(); this.maskMat.dispose(); this.normalRT?.dispose(); this.maskRT?.dispose(); }
94
+ }
95
+
96
+ function apply(pass, p) {
97
+ if (!(p.mode in MODES)) throw new Error(`outline: unknown mode '${p.mode}', use 'depth' | 'normal' | 'both'`);
98
+ pass.p = p;
99
+ const u = pass.material.uniforms;
100
+ u.uColor.value.set(p.color); u.uThick.value = p.thickness; u.uStrength.value = p.strength; u.uFade.value = p.fadeWithDistance ? 1 : 0; u.uWobble.value = p.wobble;
101
+ }
102
+
103
+ /**
104
+ * Dark lines (cartoon look), hdr slot, before bloom so the glow does not blur the lines.
105
+ * mode 'depth' (default): silhouettes where depth jumps; 'normal': creases where surface normals turn (the scene is drawn once more with
106
+ * normals; costly, off by default on low-tier devices); 'both': either. Objects can opt out of the lines with offLayer.
107
+ * @example
108
+ * post: [outline({ enabled: true, color: 0x222222, thickness: 1.5 })]
109
+ * post: [outline({ enabled: true, mode: 'both', wobble: 1.5, offLayer: OUTLINE_OFF_LAYER })] // hand-drawn; then: sky.layers.enable(OUTLINE_OFF_LAYER)
110
+ * @param {{ color?: any, thickness?: number, strength?: number, mode?: 'depth' | 'normal' | 'both', fadeWithDistance?: boolean, wobble?: number,
111
+ * offLayer?: number | null, enabled?: boolean, order?: number }} [o]
112
+ * fadeWithDistance: lines fade out in the far 40..90% of the camera range (default true); wobble: line jitter in pixels (0 = straight);
113
+ * offLayer: objects with this three.js layer enabled get no outline (costs one extra render of just those objects; null = off)
114
+ * @returns {PostEffect}
115
+ */
116
+ export function outline({ color = 0x222222, thickness = 1, strength = 0.8, mode = 'depth', fadeWithDistance = true, wobble = 0, offLayer = null, enabled = false, order = 10 } = {}) {
117
+ return { name: 'outline', slot: 'hdr', order, enabled, needsDepth: true, costly: mode !== 'depth', params: { color, thickness, strength, mode, fadeWithDistance, wobble, offLayer },
118
+ create: ({ scene, camera, params }) => { const pass = new OutlinePass(scene, camera, params); apply(pass, params); return pass; },
119
+ update: apply };
120
+ }
package/package.json CHANGED
@@ -1,6 +1,30 @@
1
1
  {
2
2
  "name": "@threedog/post-effects",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "Optional post effects for threedog: bloom, ambient occlusion, outline, LUT color grading, film grain, vignette, chromatic aberration and depth of field (light ldr effects are fused into one fullscreen pass)",
5
+ "license": "MIT",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/penstic123-code/ThreeDog.js-Game-Engine.git",
9
+ "directory": "packages/post-effects"
10
+ },
11
+ "homepage": "https://github.com/penstic123-code/ThreeDog.js-Game-Engine#readme",
12
+ "type": "module",
13
+ "main": "./index.js",
14
+ "types": "./index.d.ts",
15
+ "exports": {
16
+ ".": {
17
+ "types": "./index.d.ts",
18
+ "default": "./index.js"
19
+ },
20
+ "./package.json": "./package.json"
21
+ },
22
+ "files": [
23
+ "*.js",
24
+ "*.d.ts"
25
+ ],
26
+ "peerDependencies": {
27
+ "threedog": "^0.1.0",
28
+ "three": "^0.187.0"
29
+ }
30
+ }
package/README.md DELETED
@@ -1,3 +0,0 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.