feat(Image): add component, playground, docs

docs/.vitepress/config.ts

@@ -78,6 +78,7 @@ export default defineConfig({
           { text: 'Edges', link: '/guide/abstractions/edges' },
           { text: 'PositionalAudio', link: '/guide/abstractions/positional-audio' },
           { text: 'AnimatedSprite', link: '/guide/abstractions/animated-sprite' },
+          { text: 'Image', link: '/guide/abstractions/image' },
           { text: 'Billboard', link: '/guide/abstractions/billboard' },
         ],
       },

docs/.vitepress/theme/components/ImageDemo.vue

@@ -0,0 +1,31 @@
+<script setup lang="ts">
+import { NoToneMapping, SRGBColorSpace } from 'three'
+import { TresCanvas } from '@tresjs/core'
+import { Image, OrbitControls } from '@tresjs/cientos'
+
+const gl = {
+  clearColor: '#82DBC5',
+  outputColorSpace: SRGBColorSpace,
+  toneMapping: NoToneMapping,
+}
+
+const URL_STUB = 'https://upload.wikimedia.org/wikipedia/commons/'
+
+const URLS = [
+  'f/f0/Cyanistes_caeruleus_Oulu_20150516.JPG',
+  '3/36/Cyanistes_caeruleus_Oulu_20130323.JPG',
+  '2/2e/Cyanistes_caeruleus_Oulu_20170507_02.jpg',
+].map(url => URL_STUB + url)
+</script>
+
+<template>
+  <TresCanvas
+    v-bind="gl"
+  >
+    <TresPerspectiveCamera :position="[0, 0, 2]" />
+    <OrbitControls />
+    <Image :url="URLS[0]" :radius="0.2" :transparent="true" :position="[-1.5, 0, -1]" />
+    <Image :url="URLS[1]" :radius="0.2" :transparent="true" />
+    <Image :url="URLS[2]" :radius="0.2" :transparent="true" :position="[1.5, 0, -1]" />
+  </TresCanvas>
+</template>

docs/component-list/components.ts

@@ -17,6 +17,7 @@ export default [
       },
       { text: 'Sampler', link: '/guide/abstractions/sampler' },
       { text: 'PositionalAudio', link: '/guide/abstractions/positional-audio' },
+      { text: 'Image', link: '/guide/abstractions/image' },
       { text: 'Billboard', link: '/guide/abstractions/billboard' },
     ],
   },

docs/guide/abstractions/image.md

@@ -0,0 +1,33 @@
+# Image
+
+<DocsDemo>
+  <ImageDemo />
+</DocsDemo>
+
+`<Image />` is a shader-based component that optionally loads then displays an image texture on a default plane or on your custom geometry.
+
+## Usage
+
+<<< @/.vitepress/theme/components/ImageDemo.vue
+
+## Props
+
+::: info
+`<Image />` is a THREE.Mesh and most Mesh attributes can be used as props on the component.
+:::
+
+| Prop             | Description                                          | Default       |
+| :--------------- | :--------------------------------------------------- | ------------- |
+| `segments`          | Number of divisions in the default geometry.              | `1`           |
+| `scale` | Scale of the geometry. `number \| [number, number]`                         | `1`           |
+| `color`    | Color multiplied into the image texture.                         | `'white'`           |
+| `zoom`          | Shrinks or enlarges the image texture. | `1` |
+| `radius`        | Border radius applied to the image texture. (Intended for rectangular geometries. Use with `transparent`.) | `0` |
+| `grayscale`        | Power of grayscale effect. 0 is off. 1 is full grayscale. | `0` |
+| `toneMapped`        | Whether this material is tone mapped according to the renderers toneMapping settings. [See THREE.material.tonemapped](https://threejs.org/docs/?q=material#api/en/materials/Material.toneMapped) | `0` |
+| `transparent` |  Whether the image material should be transparent. [See THREE.material.transparent](https://threejs.org/docs/?q=material#api/en/materials/Material.transparent) | `false` |
+| `transparent` |  Whether the image material should be transparent. [See THREE.material.transparent](https://threejs.org/docs/?q=material#api/en/materials/Material.transparent) | `false` |
+| `opacity` | Opacity of the image material. [See THREE.material.transparent](https://threejs.org/docs/?q=material#api/en/materials/Material.transparent) | `1` |
+| `side` | THREE.Side of the image material. [See THREE.material.side](https://threejs.org/docs/?q=material#api/en/materials/Material.side) | `FrontSide` |
+| `texture` | Image texture to display on the geometry. |  |
+| `url` | Image URL to load and display on the geometry. |  |

playground/vue/src/pages/abstractions/ImageDemo.vue

@@ -0,0 +1,89 @@
+<script setup lang="ts">
+import { TresCanvas } from '@tresjs/core'
+import { Image, OrbitControls } from '@tresjs/cientos'
+import { Color, DoubleSide, FrontSide, NoToneMapping } from 'three'
+import { TresLeches, useControls } from '@tresjs/leches'
+import '@tresjs/leches/styles'
+
+const URLS = [
+  'https://upload.wikimedia.org/wikipedia/commons/1/13/20220713-great-tit.jpg',
+  'https://upload.wikimedia.org/wikipedia/commons/0/00/Friendly_Robin.jpg',
+]
+
+const c = useControls({
+  url: 'https://upload.wikimedia.org/wikipedia/commons/d/d4/Mars_2009_Plouaret.jpg',
+  segments: { value: 1, min: 1, max: 10, step: 1 },
+  scaleX: { value: 1, min: 0, max: 3, step: 0.01 },
+  scaleY: { value: 1, min: 0, max: 3, step: 0.01 },
+  isRed: false,
+  zoom: { value: 1, min: 0, max: 3, step: 0.01 },
+  radius: { value: 0, min: 0, max: 1, step: 0.01 },
+  grayscale: { value: 0, min: 0, max: 1, step: 0.01 },
+  toneMapped: false,
+  transparent: true,
+  opacity: { value: 1, min: 0, max: 1, step: 0.01 },
+  isDoubleSided: true,
+  enabled: true,
+})
+
+const opacity = shallowRef(1)
+const url = shallowRef(URLS[0])
+const sx = shallowRef(1)
+
+let elapsed = 0
+setInterval(() => {
+  elapsed += 0.01
+  opacity.value = Math.abs(Math.sin(elapsed))
+  url.value = Math.sin(elapsed) > 0 ? URLS[0] : URLS[1]
+  sx.value = (Math.cos(elapsed) * 0.5 + 0.5)
+}, 1000 / 30)
+</script>
+
+<template>
+  <TresLeches />
+  <TresCanvas :tone-mapping="NoToneMapping">
+    <TresPerspectiveCamera />
+    <OrbitControls />
+    <Image
+      :position-y="2"
+      :url="url"
+      :radius="opacity"
+      :color="new Color('white')"
+    >
+      <TresBoxGeometry />
+    </Image>
+    <Image
+      v-if="c.enabled.value.value"
+      :url="c.url.value.value"
+      :segments="c.segments.value.value"
+      :scale="[c.scaleX.value.value, c.scaleY.value.value]"
+      :color="c.isRed.value.value ? '#F00' : '#FFF'"
+      :zoom="c.zoom.value.value"
+      :radius="c.radius.value.value"
+      :grayscale="c.grayscale.value.value"
+      :tone-mapped="c.toneMapped.value.value"
+      :transparent="c.transparent.value.value"
+      :opacity="c.opacity.value.value"
+      :side="c.isDoubleSided.value.value ? DoubleSide : FrontSide"
+    />
+    <Image
+      :position-x="2"
+      :scale="[sx, 1]"
+      :url="url"
+    />
+    <Image
+      :position-y="-2"
+      :scale="sx"
+      :url="url"
+    >
+      <TresCircleGeometry />
+    </Image>
+
+    <Image
+      :position-x="-2"
+      :url="url"
+      :radius="opacity"
+      :transparent="true"
+    />
+  </TresCanvas>
+</template>

playground/vue/src/router/routes/abstractions.ts

@@ -64,6 +64,11 @@ export const abstractionsRoutes = [
     name: 'AnimatedSprite',
     component: () => import('../../pages/abstractions/AnimatedSpriteDemo.vue'),
   },
+  {
+    path: '/abstractions/image',
+    name: 'Image',
+    component: () => import('../../pages/abstractions/ImageDemo.vue'),
+  },
   {
     path: '/abstractions/billboard',
     name: 'Billboard',

src/core/abstractions/Image/ImageMaterial.vue

@@ -0,0 +1,15 @@
+<script setup lang="ts">
+import { shallowRef } from 'vue'
+import { extend } from '@tresjs/core'
+import ImageMaterial from './ImageMaterialImpl'
+
+extend({ ImageMaterial })
+
+const materialRef = shallowRef()
+
+defineExpose({ instance: materialRef })
+</script>
+
+<template>
+  <TresImageMaterial ref="materialRef" />
+</template>

src/core/abstractions/Image/ImageMaterialImpl.ts

@@ -0,0 +1,79 @@
+import { shaderMaterial } from './../../../utils/shaderMaterial'
+import { Color, Vector2 } from 'three'
+
+/**
+ * NOTE: Source:
+ * https://threejs.org/docs/?q=material#api/en/materials/Material.transparent
+ */
+const imageMaterialImpl = shaderMaterial(
+  {
+    color: /* @__PURE__ */ new Color('white'),
+    scale: /* @__PURE__ */ new Vector2(1, 1),
+    imageBounds: /* @__PURE__ */ new Vector2(1, 1),
+    resolution: 1024,
+    map: null,
+    zoom: 1,
+    radius: 0,
+    grayscale: 0,
+    opacity: 1,
+  },
+  /* glsl */ `
+    varying vec2 vUv;
+    varying vec2 vPos;
+    void main() {
+      gl_Position = projectionMatrix * viewMatrix * modelMatrix * vec4(position, 1.);
+      vUv = uv;
+      vPos = position.xy;
+    }
+  `,
+  /* glsl */ `
+    // mostly from https://gist.github.com/statico/df64c5d167362ecf7b34fca0b1459a44
+    varying vec2 vUv;
+    varying vec2 vPos;
+    uniform vec2 scale;
+    uniform vec2 imageBounds;
+    uniform float resolution;
+    uniform vec3 color;
+    uniform sampler2D map;
+    uniform float radius;
+    uniform float zoom;
+    uniform float grayscale;
+    uniform float opacity;
+    const vec3 luma = vec3(.299, 0.587, 0.114);
+    vec4 toGrayscale(vec4 color, float intensity) {
+      return vec4(mix(color.rgb, vec3(dot(color.rgb, luma)), intensity), color.a);
+    }
+    vec2 aspect(vec2 size) {
+      return size / min(size.x, size.y);
+    }
+
+    const float PI = 3.14159265;
+
+    // from https://iquilezles.org/articles/distfunctions
+    float udRoundBox( vec2 p, vec2 b, float r ) {
+      return length(max(abs(p)-b+r,0.0))-r;
+    }
+
+    void main() {
+      vec2 s = aspect(scale);
+      vec2 i = aspect(imageBounds);
+      float rs = s.x / s.y;
+      float ri = i.x / i.y;
+      vec2 new = rs < ri ? vec2(i.x * s.y / i.y, s.y) : vec2(s.x, i.y * s.x / i.x);
+      vec2 offset = (rs < ri ? vec2((new.x - s.x) / 2.0, 0.0) : vec2(0.0, (new.y - s.y) / 2.0)) / new;
+      vec2 uv = vUv * s / new + offset;
+      vec2 zUv = (uv - vec2(0.5, 0.5)) / zoom + vec2(0.5, 0.5);
+
+      vec2 res = vec2(scale * resolution);
+      vec2 halfRes = 0.5 * res;
+      float b = udRoundBox(vUv.xy * res - halfRes, halfRes, resolution * radius);    
+        vec3 a = mix(vec3(1.0,0.0,0.0), vec3(0.0,0.0,0.0), smoothstep(0.0, 1.0, b));
+      gl_FragColor = toGrayscale(texture2D(map, zUv) * vec4(color, opacity * a), grayscale);
+
+      #include <tonemapping_fragment>
+      #include <colorspace_fragment>
+    }
+  `,
+)
+
+export default imageMaterialImpl