feat: asciirenderer

README.md

@@ -77,6 +77,7 @@ The `native` route of the library **does not** export `Html` or `Loader`. The de
           <li><a href="#marchingcubes">MarchingCubes</a></li>
           <li><a href="#decal">Decal</a></li>
           <li><a href="#svg">Svg</a></li>
+          <li><a href="#asciirenderer">AsciiRenderer</a></li>
         </ul>
         <li><a href="#shaders">Shaders</a></li>
         <ul>
@@ -1249,6 +1250,38 @@ Accepts an SVG url or svg raw data.
 <Svg src={urlOrRawSvgString} />
 ```
 
+#### AsciiRenderer
+
+<p>
+  <a href="https://codesandbox.io/s/5jvdu3"><img width="20%" src="https://codesandbox.io/api/v1/sandboxes/5jvdu3/screenshot.png" alt="Demo"/></a>
+</p>
+
+Abstraction of three's [AsciiEffect](https://threejs.org/examples/?q=as#webgl_effects_ascii). It creates a DOM layer on top of the canvas and renders the scene as ascii characters.
+
+```tsx
+type AsciiRendererProps = {
+  /** Render index, default: 1 */
+  renderIndex?: number
+  /** CSS background color (can be "transparent"), default: black */
+  bgColor?: string
+  /** CSS character color, default: white */
+  fgColor?: string
+  /** Characters, default: ' .:-+*=%@#' */
+  characters?: string
+  /** Invert character, default: true */
+  invert?: boolean
+  /** Colorize output (very expensive!), default: false */
+  color?: boolean
+  /** Level of detail, default: 0.15 */
+  resolution?: number
+}
+```
+
+```jsx
+<Canvas>
+  <AsciiRenderer />
+```
+
 # Shaders
 
 #### MeshReflectorMaterial

src/core/AsciiRenderer.tsx

@@ -0,0 +1,71 @@
+import * as React from 'react'
+import { useFrame, useThree } from '@react-three/fiber'
+import { AsciiEffect } from 'three-stdlib'
+
+type AsciiRendererProps = {
+  /** Render index, default: 1 */
+  renderIndex?: number
+  /** CSS background color (can be "transparent"), default: black */
+  bgColor?: string
+  /** CSS character color, default: white */
+  fgColor?: string
+  /** Characters, default: ' .:-+*=%@#' */
+  characters?: string
+  /** Invert character, default: true */
+  invert?: boolean
+  /** Colorize output (very expensive!), default: false */
+  color?: boolean
+  /** Level of detail, default: 0.15 */
+  resolution?: number
+}
+
+export function AsciiRenderer({
+  renderIndex = 1,
+  bgColor = 'black',
+  fgColor = 'white',
+  characters = ' .:-+*=%@#',
+  invert = true,
+  color = false,
+  resolution = 0.15,
+}: AsciiRendererProps) {
+  // Reactive state
+  const { size, gl, scene, camera } = useThree()
+
+  // Create effect
+  const effect = React.useMemo(() => {
+    const effect = new AsciiEffect(gl, characters, { invert, color, resolution })
+    effect.domElement.style.position = 'absolute'
+    effect.domElement.style.top = '0px'
+    effect.domElement.style.left = '0px'
+    effect.domElement.style.pointerEvents = 'none'
+    return effect
+  }, [characters, invert, color, resolution])
+
+  // Styling
+  React.useLayoutEffect(() => {
+    effect.domElement.style.color = fgColor
+    effect.domElement.style.backgroundColor = bgColor
+  }, [fgColor, bgColor])
+
+  // Append on mount, remove on unmount
+  React.useEffect(() => {
+    gl.domElement.style.opacity = '0'
+    gl.domElement.parentNode!.appendChild(effect.domElement)
+    return () => {
+      gl.domElement.style.opacity = '1'
+      gl.domElement.parentNode!.removeChild(effect.domElement)
+    }
+  }, [effect])
+
+  // Set size
+  React.useEffect(() => {
+    effect.setSize(size.width, size.height)
+  }, [effect, size])
+
+  // Take over render-loop (that is what the index is for)
+  useFrame((state) => {
+    effect.render(scene, camera)
+  }, renderIndex)
+
+  // This component returns nothing, it is a purely logical
+}

src/core/index.ts

@@ -19,6 +19,7 @@ export * from './Clone'
 export * from './MarchingCubes'
 export * from './Decal'
 export * from './Svg'
+export * from './AsciiRenderer'
 
 // Cameras
 export * from './OrthographicCamera'