@ascii-fx/three 0.2.0 → 0.3.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.
Files changed (2) hide show
  1. package/README.md +33 -14
  2. package/package.json +3 -3
package/README.md CHANGED
@@ -1,26 +1,45 @@
1
1
  # @ascii-fx/three
2
2
 
3
- Three.js adapter. `AsciiPass` post-processes a scene through the exact matcher **on Three's own GPUDevice** — zero readback — and composites straight to the canvas. Requires `THREE.WebGPURenderer` (r170–r185 verified): exactly matching a WebGL renderer would need per-frame GPU→CPU readback, so it is not supported (spec §30).
3
+ Render a Three.js scene as ASCII, without ever leaving the GPU.
4
+
5
+ ```sh
6
+ pnpm add @ascii-fx/three three
7
+ ```
4
8
 
5
9
  ```ts
6
10
  import * as THREE from 'three/webgpu'
7
11
  import { AsciiPass } from '@ascii-fx/three'
8
12
 
9
- const renderer = new THREE.WebGPURenderer({ canvas })
10
- await renderer.init()
13
+ const renderer = new THREE.WebGPURenderer()
14
+ const pass = new AsciiPass({ renderer, profile, columns: 160 })
15
+
16
+ renderer.setAnimationLoop(() => pass.render(scene, camera))
17
+ ```
18
+
19
+ ## Why WebGPURenderer only
20
+
21
+ The pass runs the matcher **on Three's own `GPUDevice`** — the scene's render target is matched and composited in place, with no readback. That's what keeps it cheap enough to run every frame.
22
+
23
+ A WebGL renderer can't do that. Matching a WebGL-rendered scene exactly would mean pulling every frame back to the CPU, matching there, and pushing the result up again — a GPU→CPU→GPU round trip per frame, which is slow enough to defeat the point. Rather than ship a "supported" path that's quietly 20× slower, this package requires `THREE.WebGPURenderer` (r170–r185 verified) and says so.
11
24
 
12
- const pass = new AsciiPass({ profile, renderer, columns: 160, color: 'full' })
13
- await pass.init()
25
+ If you're on WebGL and want ASCII, render your scene to a canvas and feed that canvas to [`@ascii-fx/gpu`](../gpu) as a source — you'll pay the readback, but explicitly.
14
26
 
15
- function frame() {
16
- pass.render(scene, camera) // instead of renderer.render(scene, camera)
17
- requestAnimationFrame(frame)
18
- }
19
- pass.set({ columns: 180 })
20
- pass.pointer.set(x01, y01)
21
- pass.setInteraction({ type: 'wave' })
27
+ ## Glyphs as geometry
28
+
29
+ `AsciiGlyphs` is the other direction: an instanced mesh of glyph quads you can place in the scene, light, and move with the camera, rather than a full-frame post effect.
30
+
31
+ ```ts
32
+ import { AsciiGlyphs } from '@ascii-fx/three'
33
+
34
+ const glyphs = new AsciiGlyphs({ profile, columns: 120, rows: 40 })
35
+ scene.add(glyphs)
36
+ glyphs.setSource(video)
22
37
  ```
23
38
 
24
- Color handling (spec §28): render targets hold linear-light values, so the pass sRGB-encodes before quantization. With pure 0/1 scene colors this is exact (the conformance test uses that); midtones can differ ±1 byte across GPUs in the encode — a source-side conversion, not matcher variance. Tone mapping is not applied to render targets; treat the RT as the match source.
39
+ One draw call for the whole grid.
40
+
41
+ `three` is a peer dependency (`>=0.170.0`); add `@types/three` for TypeScript. For React Three Fiber, use [`@ascii-fx/react-three`](../react-three).
42
+
43
+ ## License
25
44
 
26
- `AsciiGlyphs` (experimental): instanced plane-per-cell renderer with a TSL node material sampling the profile atlas — glyph ids/colors as instanced attributes via `updateFromFrame(frame)` (CPU hop in v1; a zero-readback bridge from the GPU cell buffer is planned), transforms in the standard `instanceMatrix` for effects.
45
+ [MIT](../../LICENSE)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ascii-fx/three",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "description": "Three.js adapter for ASCII FX: AsciiPass postprocessing for WebGPURenderer and an instanced AsciiGlyphs renderer.",
5
5
  "keywords": [
6
6
  "ascii",
@@ -37,8 +37,8 @@
37
37
  "access": "public"
38
38
  },
39
39
  "dependencies": {
40
- "@ascii-fx/core": "0.2.0",
41
- "@ascii-fx/gpu": "0.2.0"
40
+ "@ascii-fx/core": "0.3.0",
41
+ "@ascii-fx/gpu": "0.3.0"
42
42
  },
43
43
  "devDependencies": {
44
44
  "@types/three": "0.185.4",