feat: ASCII

docs/.vitepress/config.ts

@@ -61,6 +61,7 @@ export default defineConfig({
           { text: 'Hue & Saturation', link: '/guide/pmndrs/hue-saturation' },
           { text: 'Lens Distortion', link: '/guide/pmndrs/lens-distortion' },
           { text: 'Grid', link: '/guide/pmndrs/grid' },
+          { text: 'ASCII', link: '/guide/pmndrs/ascii' },
           { text: 'FXAA', link: '/guide/pmndrs/fxaa' },
           { text: 'SMAA', link: '/guide/pmndrs/smaa' },
           { text: 'Kuwahara', link: '/guide/pmndrs/kuwahara' },

docs/.vitepress/theme/components/pmdrs/ASCIIDemo.vue

@@ -0,0 +1,96 @@
+<script setup lang="ts">
+import { Environment, Levioso, OrbitControls } from '@tresjs/cientos'
+import { TresCanvas } from '@tresjs/core'
+import { TresLeches, useControls } from '@tresjs/leches'
+import { NoToneMapping } from 'three'
+import { BlendFunction } from 'postprocessing'
+import { ASCIIPmndrs, EffectComposerPmndrs } from '@tresjs/post-processing'
+
+import '@tresjs/leches/styles'
+
+const gl = {
+  clearColor: '#ffffff',
+  toneMapping: NoToneMapping,
+}
+
+const glComposer = {
+  multisampling: 4,
+}
+
+const leviosoProps = {
+  speed: 2,
+  rotationFactor: 2,
+  range: [-1, 1] as [number, number],
+}
+
+const { size: textureSize, characters, font, fontSize, cellCount, enabled, blendFunction, opacity, cellSize, inverted, color, useSceneColor } = useControls({
+  enabled: true,
+  cellSize: { value: 10, step: 1, min: 2, max: 64 },
+  useSceneColor: false,
+  color: '#ffffff',
+  inverted: false,
+  characters: { value: ' .,:-~+=*≡TRESJCIENTOSLECHESPOSTPROCESSING3D#░▒▓█■▲◼◾' },
+  font: { value: 'Arial' },
+  fontSize: { value: 44, step: 1, min: 10, max: 100 },
+  size: { value: 1024, step: 128, min: 256, max: 2048, label: 'textureSize' },
+  cellCount: { value: 16, step: 1, min: 4, max: 64 },
+  opacity: { value: 1, step: 0.1, min: 0.0, max: 1.0 },
+  blendFunction: {
+    options: Object.keys(BlendFunction).map(key => ({
+      text: key,
+      value: BlendFunction[key as keyof typeof BlendFunction],
+    })),
+    value: BlendFunction.LINEAR_BURN,
+  },
+})
+</script>
+
+<template>
+  <div class="aspect-16/9">
+    <TresCanvas
+      v-bind="gl"
+    >
+      <TresPerspectiveCamera :position="[5, 3, 7]" />
+      <OrbitControls auto-rotate />
+
+      <Levioso v-bind="leviosoProps">
+        <TresMesh :position="[-2, .5, 0]">
+          <TresBoxGeometry :args="[2, 2, 2]" />
+          <TresMeshPhysicalMaterial color="white" />
+        </TresMesh>
+      </Levioso>
+
+      <Levioso v-bind="leviosoProps">
+        <TresMesh :position="[3, .5, 0]">
+          <TresSphereGeometry :args="[1.5, 32, 32]" />
+          <TresMeshPhysicalMaterial color="white" />
+        </TresMesh>
+      </Levioso>
+
+      <Suspense>
+        <Environment background :blur="0.2" preset="snow" />
+      </Suspense>
+
+      <Suspense>
+        <EffectComposerPmndrs v-bind="glComposer">
+          <ASCIIPmndrs
+            :blendFunction="enabled ? Number(blendFunction) : Number(BlendFunction.SKIP)"
+            :opacity="opacity"
+            :cellSize="cellSize"
+            :inverted="inverted"
+            :color="color"
+            :useSceneColor="useSceneColor"
+            :asciiTexture="{
+              characters,
+              font,
+              fontSize,
+              size: textureSize,
+              cellCount,
+            }"
+          />
+        </EffectComposerPmndrs>
+      </Suspense>
+    </TresCanvas>
+  </div>
+  <TresLeches :float="false" />
+</template>

docs/components.d.ts

@@ -7,6 +7,7 @@ export {}
 /* prettier-ignore */
 declare module 'vue' {
   export interface GlobalComponents {
+    ASCIIDemo: typeof import('./.vitepress/theme/components/pmdrs/ASCIIDemo.vue')['default']
     BarrelBlurDemo: typeof import('./.vitepress/theme/components/pmdrs/BarrelBlurDemo.vue')['default']
     BlenderCube: typeof import('./.vitepress/theme/components/BlenderCube.vue')['default']
     BloomDemo: typeof import('./.vitepress/theme/components/pmdrs/BloomDemo.vue')['default']

docs/guide/pmndrs/ascii.md

@@ -0,0 +1,71 @@
+# ASCII
+
+<DocsDemoGUI>
+  <ASCIIDemo />
+</DocsDemoGUI>
+
+<details>
+  <summary>Demo code</summary>
+
+  <<< @/.vitepress/theme/components/pmdrs/ASCIIDemo.vue{0}
+</details>
+
+The `ASCIIEffect` effect is part of the [`postprocessing`](https://pmndrs.github.io/postprocessing/public/docs/class/src/effects/ASCIIEffect.js~ASCIIEffect.html) package.
+This effect transforms the visual output into a grid of ASCII characters, offering a unique and artistic way to display 3D content. The ASCII characters used can be customized, allowing for a wide range of creative possibilities.
+
+## Usage
+
+The `<ASCIIPmndrs>` component is straightforward to integrate and offers a variety of customizable properties, allowing you to adapt it to diverse artistic and visual requirements.
+
+```vue{2,12-17,29-33}
+<script setup lang="ts">
+import { EffectComposerPmndrs, ASCIIPmndrs } from '@tresjs/post-processing/pmndrs'
+
+const gl = {
+  toneMapping: NoToneMapping,
+}
+
+const glComposer = {
+  multisampling: 4,
+}
+
+const effectProps = {
+  blendFunction: BlendFunction.NORMAL,
+  asciiTexture: {
+    characters: ' .,:-~+=*≡HELLOWORLD#░▒▓█■▲◼◾',
+  }
+}
+</script>
+
+<template>
+  <TresCanvas v-bind="gl">
+    <TresPerspectiveCamera />
+
+    <TresMesh :position="[0, .5, 0]">
+      <TresBoxGeometry :args="[2, 2, 2]" />
+      <TresMeshToonMaterial color="black" />
+    </TresMesh>
+
+    <Suspense>
+      <EffectComposerPmndrs v-bind="glComposer">
+        <ASCIIPmndrs v-bind="effectProps" />
+      </EffectComposerPmndrs>
+    </Suspense>
+  </TresCanvas>
+</template>
+```
+
+## Props
+
+| Prop           | Description                                                                                     | Default                     |
+| -------------- | ----------------------------------------------------------------------------------------------- | --------------------------- |
+| blendFunction  | Defines how the effect blends with the original scene. See the [`BlendFunction`](https://pmndrs.github.io/postprocessing/public/docs/variable/index.html#static-variable-BlendFunction) options. | `BlendFunction.NORMAL`      |
+| opacity        | The opacity of the effect.                                                                      | `1.0`                       |
+| cellSize       | The size of the ASCII grid cells.                                                               | `16`                 |
+| inverted       | Controls whether the effect should be inverted.                                                 | `false`                     |
+| color          | The color of the effect. Can be a [`Color`](https://threejs.org/docs/#api/en/math/Color), `string`, `number`, or `null`. If set to `null`, the colors of the scene will be used.                           | `null`                      |
+| useSceneColor  | Controls whether the effect should use the scene color. If `true`, overrides the `color` prop.                                 | `false`                     |
+| asciiTexture   | Options for creating an ASCIITexture instance. |  See the [`ASCIITexture`](https://pmndrs.github.io/postprocessing/public/docs/class/src/textures/ASCIITexture.js~ASCIITexture.html) documentation.                 |
+
+## Further Reading
+For more details, see the [ASCIIEffect documentation](https://pmndrs.github.io/postprocessing/public/docs/class/src/effects/ASCIIEffect.js~ASCIIEffect.html)

package.json

@@ -58,7 +58,7 @@
   },
   "dependencies": {
     "@vueuse/core": "^12.5.0",
-    "postprocessing": "^6.36.6"
+    "postprocessing": "^6.37.2"
   },
   "devDependencies": {
     "@release-it/conventional-changelog": "^10.0.0",

playground/src/pages/postprocessing/ascii.vue

@@ -0,0 +1,79 @@
+<script setup lang="ts">
+import { Environment, OrbitControls } from '@tresjs/cientos'
+import { TresCanvas } from '@tresjs/core'
+import { TresLeches, useControls } from '@tresjs/leches'
+import { NoToneMapping } from 'three'
+import { BlendFunction } from 'postprocessing'
+import { ASCIIPmndrs, EffectComposerPmndrs } from '@tresjs/post-processing'
+
+import '@tresjs/leches/styles'
+
+const gl = {
+  clearColor: '#ffffff',
+  toneMapping: NoToneMapping,
+}
+
+const { enabled, blendFunction, opacity, cellSize, inverted, color, useSceneColor, characters, font, fontSize, size, cellCount } = useControls({
+  enabled: true,
+  blendFunction: {
+    options: Object.keys(BlendFunction).map(key => ({
+      text: key,
+      value: BlendFunction[key as keyof typeof BlendFunction],
+    })),
+    value: BlendFunction.NORMAL,
+  },
+  opacity: { value: 1, step: 0.1, min: 0.0, max: 1.0 },
+  cellSize: { value: 12, step: 1, min: 2, max: 64 },
+  useSceneColor: false,
+  color: '#ffffff',
+  inverted: false,
+  characters: { value: '@#8&$%*o!;.' },
+  font: { value: 'Arial' },
+  fontSize: { value: 54, step: 1, min: 10, max: 100 },
+  size: { value: 1024, step: 128, min: 256, max: 2048, label: 'textureSize' },
+  cellCount: { value: 16, step: 1, min: 4, max: 64 },
+})
+</script>
+
+<template>
+  <TresLeches />
+
+  <TresCanvas
+    v-bind="gl"
+  >
+    <TresPerspectiveCamera
+      :position="[5, 6.5, 7.5]"
+      :look-at="[0, 0, 0]"
+    />
+    <OrbitControls auto-rotate />
+
+    <TresMesh :position="[0, .5, 0]">
+      <TresBoxGeometry :args="[2, 2, 2]" />
+      <TresMeshPhysicalMaterial color="white" />
+    </TresMesh>
+
+    <Suspense>
+      <Environment background preset="dawn" />
+    </Suspense>
+
+    <Suspense>
+      <EffectComposerPmndrs>
+        <ASCIIPmndrs
+          :blendFunction="enabled ? Number(blendFunction) : Number(BlendFunction.SKIP)"
+          :opacity="opacity"
+          :cellSize="cellSize"
+          :inverted="inverted"
+          :color="color"
+          :useSceneColor="useSceneColor"
+          :asciiTexture="{
+            characters,
+            font,
+            fontSize,
+            size,
+            cellCount,
+          }"
+        />
+      </EffectComposerPmndrs>
+    </Suspense>
+  </TresCanvas>
+</template>

playground/src/router.ts

@@ -52,6 +52,7 @@ export const postProcessingRoutes = [
   makeRoute('Scanline', '📽️', false),
   makeRoute('Color Depth', '🔳', false),
   makeRoute('Grid', '#️⃣', false),
+  makeRoute('ASCII', '🔡', false),
   makeRoute('SMAA', '📐', false),
   makeRoute('FXAA', '📐', false),
   makeRoute('Shock Wave', '🌊', false),