feat: sampler and useSampler

.gitignore

@@ -27,3 +27,4 @@ docs/.vitepress/dist/
 docs/.vitepress/cache/
 docs/.vitepress/.temp/
 docs/components.d.ts
+playground/components.d.ts

docs/.vitepress/config.ts

@@ -41,6 +41,8 @@ export default defineConfig({
           { text: 'GlobalAudio', link: '/guide/abstractions/global-audio' },
           { text: 'Fbo', link: '/guide/abstractions/fbo' },
           { text: 'useFBO', link: '/guide/abstractions/use-fbo' },
+          { text: 'useSampler', link: '/guide/abstractions/use-sampler' },
+          { text: 'Sampler', link: '/guide/abstractions/sampler' },
         ],
       },
       {

docs/.vitepress/theme/components/SamplerDemo.vue

@@ -0,0 +1,24 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import { TresCanvas } from '@tresjs/core'
+import { OrbitControls, Sampler } from '@tresjs/cientos'
+</script>
+
+<template>
+  <TresCanvas clear-color="#82DBC5">
+    <TresPerspectiveCamera :position="[0, 0.5, 5]" />
+    <OrbitControls />
+
+    <Sampler :count="50">
+      <TresMesh>
+        <TresTorusGeometry />
+      </TresMesh>
+
+      <TresInstancedMesh :args="[null!, null!, 1000]">
+        <TresBoxGeometry :args="[0.1, 0.1, 0.1]" />
+        <TresMeshNormalMaterial />
+      </TresInstancedMesh>
+    </Sampler>
+    <TresGridHelper :args="[10, 10]" />
+  </TresCanvas>
+</template>

docs/.vitepress/theme/components/UseSamplerDemo.vue

@@ -0,0 +1,33 @@
+<script setup lang="ts">
+import { ref, watch } from 'vue'
+import { TresCanvas } from '@tresjs/core'
+import { OrbitControls, useSampler } from '@tresjs/cientos'
+
+const torusRef = ref()
+const instancesRef = ref()
+
+watch(torusRef, (value) => {
+  useSampler(value, 50, instancesRef.value, 'color')
+})
+</script>
+
+<template>
+  <TresCanvas clear-color="#82DBC5">
+    <TresPerspectiveCamera :position="[0, 0.5, 5]" />
+    <OrbitControls />
+
+    <TresMesh ref="torusRef">
+      <TresTorusGeometry />
+    </TresMesh>
+
+    <TresInstancedMesh
+      ref="instancesRef"
+      :args="[null!, null!, 1_000]"
+    >
+      <TresSphereGeometry :args="[0.1, 32, 32]" />
+      <TresMeshNormalMaterial />
+    </TresInstancedMesh>
+
+    <TresGridHelper :args="[10, 10]" />
+  </TresCanvas>
+</template>

docs/guide/abstractions/sampler.md

@@ -0,0 +1,23 @@
+# Sampler <Badge type="warning" text="^3.7.0" />
+
+Declarative abstraction around MeshSurfaceSampler & InstancedMesh. It samples points from the passed mesh and transforms an InstancedMesh's matrix to distribute instances on the points.
+
+<DocsDemo>
+  <SamplerDemo />
+</DocsDemo>
+
+## Usage
+
+`Experience.vue`
+
+<<< @/.vitepress/theme/components/SamplerDemo.vue{4,12-21}
+
+## Props
+
+| Props        | Description                                                        |
+|--------------|--------------------------------------------------------------------|
+| mesh         | **Mesh** Surface mesh from which to sample                         |
+| count        | **Number** Number of samples                                       |
+| instanceMesh | **InstanceMesh** InstanceMesh to scatter                           |
+| weight       | **String** A vertex attribute to be used as a weight when sampling |
+| transform    | **Function** A function that can be used as a custom sampling      |

docs/guide/abstractions/use-sampler.md

@@ -0,0 +1,21 @@
+# useSampler <Badge type="warning" text="^3.7.0" />
+
+A hook to obtain the result of the <Sampler /> as a buffer. Useful for driving anything other than InstancedMesh via the Sampler.
+
+<DocsDemo>
+  <UseSamplerDemo />
+</DocsDemo>
+
+## Usage
+
+<<< @/.vitepress/theme/components/UseSamplerDemo.vue{4,10,19-29}
+
+## Props
+
+| Props        | Description                                                        |
+|--------------|--------------------------------------------------------------------|
+| mesh         | **Mesh** Surface mesh from which to sample                         |
+| count        | **Number** Number of samples                                       |
+| instanceMesh | **InstanceMesh** InstanceMesh to scatter                           |
+| weight       | **String** A vertex attribute to be used as a weight when sampling |
+| transform    | **Function** A function that can be used as a custom sampling      |

playground/src/pages/abstractions/Sampler.vue

@@ -0,0 +1,58 @@
+<script setup lang="ts">
+import { ref, shallowReactive } from 'vue'
+import { TresCanvas } from '@tresjs/core'
+import { OrbitControls, Sampler, useTweakPane } from '@tresjs/cientos'
+import { SRGBColorSpace, ACESFilmicToneMapping } from 'three'
+import type { Mesh } from 'three'
+
+const gl = {
+  clearColor: '#82DBC5',
+  shadows: true,
+  alpha: false,
+  outputColorSpace: SRGBColorSpace,
+  toneMapping: ACESFilmicToneMapping,
+}
+
+const torusRef = ref<Mesh>()
+const instancesRef = ref<Mesh>()
+
+const state = shallowReactive({
+  count: 1,
+})
+
+const { pane } = useTweakPane()
+
+pane.addInput(state, 'count', {
+  label: 'samplers',
+  min: 1,
+  max: 50,
+  step: 1,
+})
+</script>
+
+<template>
+  <TresLeches />
+  <TresCanvas v-bind="gl">
+    <TresPerspectiveCamera :position="[0, 0.5, 5]" />
+    <OrbitControls />
+
+    <Sampler :count="state.count">
+      <TresMesh ref="torusRef">
+        <TresTorusGeometry />
+      </TresMesh>
+
+      <TresInstancedMesh
+        ref="instancesRef"
+        :args="[null!, null!, 1000]"
+      >
+        <TresBoxGeometry
+          :args="[0.1, 0.1, 0.1]"
+        />
+        <TresMeshNormalMaterial />
+      </TresInstancedMesh>
+    </Sampler>
+    <TresGridHelper
+      :args="[10, 10]"
+    />
+  </TresCanvas>
+</template>

playground/src/pages/abstractions/useSampler.vue

@@ -0,0 +1,38 @@
+<script setup lang="ts">
+import { TresCanvas } from '@tresjs/core'
+import { OrbitControls, useSampler } from '@tresjs/cientos'
+
+const torusRef = ref()
+const instancesRef = ref()
+
+watch(torusRef, (value) => {
+  useSampler(value, 50, instancesRef.value, 'color')
+})
+</script>
+
+<template>
+  <TresCanvas clear-color="#82DBC5">
+    <TresPerspectiveCamera :position="[0, 0.5, 5]" />
+    <OrbitControls />
+
+    <TresMesh
+      ref="torusRef"
+    >
+      <TresTorusGeometry />
+    </TresMesh>
+
+    <TresInstancedMesh
+      ref="instancesRef"
+      :args="[null!, null!, 1_000]"
+    >
+      <TresSphereGeometry
+        :args="[0.1, 32, 32]"
+      />
+      <TresMeshNormalMaterial />
+    </TresInstancedMesh>
+
+    <TresGridHelper
+      :args="[10, 10]"
+    />
+  </TresCanvas>
+</template>

playground/src/router/routes/abstractions.ts

@@ -39,4 +39,14 @@ export const abstractionsRoutes = [
     name: 'useFbo',
     component: () => import('../../pages/abstractions/useFBODemo.vue'),
   },
+  {
+    path: '/abstractions/use-sampler',
+    name: 'useSampler',
+    component: () => import('../../pages/abstractions/useSampler.vue'),
+  },
+  {
+    path: '/abstractions/sampler',
+    name: 'Sampler',
+    component: () => import('../../pages/abstractions/Sampler.vue'),
+  },
 ]

src/core/abstractions/index.ts

@@ -6,8 +6,10 @@ import MouseParallax from './MouseParallax.vue'
 import { GlobalAudio } from './GlobalAudio'
 import Lensflare from './Lensflare/component.vue'
 import Fbo from './useFBO/component.vue'
+import Sampler from './useSampler/component.vue'
 
 export * from './useFBO/'
+export * from './useSampler/'
 export * from '../staging/useEnvironment'
 export {
   Text3D,
@@ -18,4 +20,5 @@ export {
   Lensflare,
   GlobalAudio,
   Fbo,
+  Sampler,
 }

src/core/abstractions/useSampler/component.vue

@@ -0,0 +1,31 @@
+<!-- eslint-disable max-len -->
+<script setup lang="ts">
+import { ref, watchEffect } from 'vue'
+import type { InstancedMesh, Mesh } from 'three'
+import type { useSamplerProps } from '.'
+import { useSampler } from '.'
+
+const props = defineProps<useSamplerProps>()
+
+const samplerRef = ref()
+const instancedRef = ref()
+const meshToSampleRef = ref()
+
+watchEffect(() => {
+  instancedRef.value = props.instanceMesh ?? samplerRef.value?.children.find((c: any ) => c.hasOwnProperty('instanceMatrix')) as InstancedMesh
+
+  meshToSampleRef.value = props.mesh ?? (samplerRef.value?.children.find((c: any) => c.type === 'Mesh') as Mesh)
+
+  useSampler(meshToSampleRef.value, props.count, instancedRef.value, props.weight, props.transform)
+})
+
+defineExpose({
+  samplerRef,
+})
+</script>
+
+<template>
+  <TresGroup ref="samplerRef">
+    <slot />
+  </TresGroup>
+</template>