feat: add <Fbo /> abstraction (#228)

* [broken] add `useFBO` * Use `useTresContext` in `useFBO` * Lint * Refactor to renderless component * Lint * Setup docs page * Lint * Refactor to renderless component * Test with Alvaro * fix: check for `.value` in depth check * fix: `depth` was setting `depthBuffer` * feat: added sizes as default if width and height are not explicity set * feat: add composable + component approach * chore: forcing rename of folder for casing issues * chore: rename back * Update docs * Finalize docs of `<Fbo />` * Finalize docs * Fix default values for `width` and `height` * Fix typo * Update global components * Remove `docs/components.d.ts` * Use separate pages for `<Fbo />` and `useFBO` * Import demos * Lint `UseFBODemo.vue` * Refactor `UseFBODemo` * Add warning about usage in child component * chore: fix route for examples on playground and color of cube --------- Co-authored-by: alvarosabu <alvaro.saburido@gmail.com>
Tresjs · Oct 7, 2023 · 6efc076 · 6efc076
1 parent ac14fbe
commit 6efc076
Show file tree

Hide file tree

Showing 16 changed files with 508 additions and 52 deletions.
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
@@ -38,6 +38,8 @@ export default defineConfig({
           { text: 'MouseParallax', link: '/guide/abstractions/mouse-parallax' },
           { text: 'Lensflare', link: '/guide/abstractions/lensflare' },
           { text: 'GlobalAudio', link: '/guide/abstractions/global-audio' },
+          { text: 'Fbo', link: '/guide/abstractions/fbo' },
+          { text: 'useFBO', link: '/guide/abstractions/use-fbo' },
         ],
       },
       {

diff --git a/docs/.vitepress/theme/components/FboCube.vue b/docs/.vitepress/theme/components/FboCube.vue
@@ -0,0 +1,23 @@
+<script setup lang="ts">
+import { useFBO } from '@tresjs/cientos'
+
+const fboTarget = useFBO({
+  depth: true,
+  width: 512,
+  height: 512,
+  settings: {
+    samples: 1,
+  },
+})
+</script>
+
+<template>
+  <TresMesh>
+    <TresBoxGeometry :args="[1, 1, 1]" />
+
+    <TresMeshBasicMaterial
+      :color="0xffffff"
+      :map="fboTarget?.texture ?? null"
+    />
+  </TresMesh>
+</template>
diff --git a/docs/.vitepress/theme/components/FboDemo.vue b/docs/.vitepress/theme/components/FboDemo.vue
@@ -0,0 +1,78 @@
+<script setup lang="ts">
+import { TresCanvas, useRenderLoop } from '@tresjs/core'
+import { OrbitControls, Fbo } from '@tresjs/cientos'
+import { SRGBColorSpace, ACESFilmicToneMapping } from 'three'
+import { ref, shallowRef, shallowReactive, onMounted, nextTick } from 'vue'
+
+const gl = {
+  clearColor: '#82DBC5',
+  shadows: true,
+  alpha: false,
+  outputColorSpace: SRGBColorSpace,
+  toneMapping: ACESFilmicToneMapping,
+}
+
+const fboRef = ref(null)
+const torusRef = shallowRef(null)
+const capsuleRef = shallowRef(null)
+
+const { onLoop } = useRenderLoop()
+
+const state = shallowReactive({
+  depth: false,
+  settings: {
+    samples: 1,
+  },
+})
+
+onMounted(async () => {
+  await nextTick()
+
+  onLoop(({ elapsed }) => {
+    torusRef.value.rotation.x = elapsed * 0.745
+    torusRef.value.rotation.y = elapsed * 0.361
+
+    capsuleRef.value.rotation.x = elapsed * 0.471
+    capsuleRef.value.rotation.z = elapsed * 0.632
+  })
+})
+</script>
+
+<template>
+  <TresCanvas v-bind="gl">
+    <TresPerspectiveCamera :position="[0, 0.5, 5]" />
+    <OrbitControls />
+
+    <TresGridHelper :args="[10, 10]" />
+
+    <Fbo
+      ref="fboRef"
+      v-bind="state"
+    />
+
+    <TresMesh>
+      <TresBoxGeometry :args="[1, 1, 1]" />
+
+      <TresMeshBasicMaterial
+        :color="0xffffff"
+        :map="fboRef?.value.texture ?? null"
+      />
+    </TresMesh>
+
+    <TresMesh
+      ref="torusRef"
+      :position="[3, 0, 0]"
+    >
+      <TresTorusGeometry :args="[1, 0.5, 16, 100]" />
+      <TresMeshNormalMaterial />
+    </TresMesh>
+
+    <TresMesh
+      ref="capsuleRef"
+      :position="[-2, 0, 0]"
+    >
+      <TresCapsuleGeometry :args="[0.4, 1, 4, 8]" />
+      <TresMeshNormalMaterial />
+    </TresMesh>
+  </TresCanvas>
+</template>
diff --git a/docs/.vitepress/theme/components/UseFBODemo.vue b/docs/.vitepress/theme/components/UseFBODemo.vue
@@ -0,0 +1,58 @@
+<script setup lang="ts">
+import { TresCanvas, useRenderLoop } from '@tresjs/core'
+import { OrbitControls } from '@tresjs/cientos'
+import { SRGBColorSpace, ACESFilmicToneMapping } from 'three'
+import { shallowRef, onMounted, nextTick } from 'vue'
+
+const gl = {
+  clearColor: '#82DBC5',
+  shadows: true,
+  alpha: false,
+  outputColorSpace: SRGBColorSpace,
+  toneMapping: ACESFilmicToneMapping,
+}
+
+const torusRef = shallowRef(null)
+const capsuleRef = shallowRef(null)
+
+const { onLoop } = useRenderLoop()
+
+onMounted(async () => {
+  await nextTick()
+
+  onLoop(({ elapsed }) => {
+    torusRef.value.rotation.x = elapsed * 0.745
+    torusRef.value.rotation.y = elapsed * 0.361
+
+    capsuleRef.value.rotation.x = elapsed * 0.471
+    capsuleRef.value.rotation.z = elapsed * 0.632
+  })
+})
+</script>
+
+<template>
+  <TresCanvas v-bind="gl">
+    <TresPerspectiveCamera :position="[0, 0.5, 5]" />
+    <OrbitControls />
+
+    <TresGridHelper :args="[10, 10]" />
+
+    <FboCube />
+
+    <TresMesh
+      ref="torusRef"
+      :position="[3, 0, 0]"
+    >
+      <TresTorusGeometry :args="[1, 0.5, 16, 100]" />
+      <TresMeshNormalMaterial />
+    </TresMesh>
+
+    <TresMesh
+      ref="capsuleRef"
+      :position="[-2, 0, 0]"
+    >
+      <TresCapsuleGeometry :args="[0.4, 1, 4, 8]" />
+      <TresMeshNormalMaterial />
+    </TresMesh>
+  </TresCanvas>
+</template>
diff --git a/docs/components.d.ts b/docs/components.d.ts
diff --git a/docs/guide/abstractions/fbo.md b/docs/guide/abstractions/fbo.md
@@ -0,0 +1,22 @@
+# Fbo <Badge type="warning" text="^3.5.0" />
+
+An FBO (or Frame Buffer Object) is generally used to render to a texture. This is useful for post-processing effects like blurring, or for rendering to a texture that will be used as a texture in a later draw call.
+
+Cientos provides an `<Fbo />` component make it easy to use FBOs in your application.
+
+<DocsDemo>
+  <FboDemo />
+</DocsDemo>
+
+## Usage
+
+<<< @/.vitepress/theme/components/FboDemo.vue{3,15,48,49,50,51,58}
+
+## Props
+
+| Prop           | Description                                                                                                                                                            | Default              |
+| :------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| **`width`**    | `number` - The width of the FBO.                                                                                                                                       | Width of the canvas  |
+| **`height`**   | `number` - the height of the FBO                                                                                                                                       | Height of the canvas |
+| **`depth`**    | `boolean` - Whether or not the FBO should render the depth to a [`depthTexture`](https://threejs.org/docs/?q=webglre#api/en/renderers/WebGLRenderTarget.depthTexture). | `false`              |
+| **`settings`** | `WebGLRenderTargetOptions` - Every other configuration property for the [`WebGLRenderTarget` class](https://threejs.org/docs/#api/en/renderers/WebGLRenderTarget)      | `{}`                 |
diff --git a/docs/guide/abstractions/use-fbo.md b/docs/guide/abstractions/use-fbo.md
@@ -0,0 +1,32 @@
+# useFBO <Badge type="warning" text="^3.5.0" />
+
+An FBO (or Frame Buffer Object) is generally used to render to a texture. This is useful for post-processing effects like blurring, or for rendering to a texture that will be used as a texture in a later draw call.
+
+Cientos provides a `useFBO` composable to make it easy to use FBOs in your application.
+
+::: warning
+The `useFBO` composable must be used inside of a child component since it needs the context of TresCanvas.
+:::
+
+<DocsDemo>
+  <UseFBODemo />
+</DocsDemo>
+
+## Usage
+
+`FboCube.vue`
+
+<<< @/.vitepress/theme/components/FboCube.vue{2,4,5,6,7,8,9,10,11,20}
+
+`Experience.vue`
+
+<<< @/.vitepress/theme/components/UseFBODemo.vue{40}
+
+## Props
+
+| Prop           | Description                                                                                                                                                            | Default              |
+| :------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| **`width`**    | `number` - The width of the FBO.                                                                                                                                       | Width of the canvas  |
+| **`height`**   | `number` - the height of the FBO                                                                                                                                       | Height of the canvas |
+| **`depth`**    | `boolean` - Whether or not the FBO should render the depth to a [`depthTexture`](https://threejs.org/docs/?q=webglre#api/en/renderers/WebGLRenderTarget.depthTexture). | `false`              |
+| **`settings`** | `WebGLRenderTargetOptions` - Every other configuration property for the [`WebGLRenderTarget` class](https://threejs.org/docs/#api/en/renderers/WebGLRenderTarget)      | `{}`                 |
diff --git a/playground/components.d.ts b/playground/components.d.ts
@@ -9,6 +9,7 @@ declare module 'vue' {
   export interface GlobalComponents {
     AkuAku: typeof import('./src/components/AkuAku.vue')['default']
     DirectivesDemo: typeof import('./src/components/DirectivesDemo.vue')['default']
+    FboCube: typeof import('./src/components/FboCube.vue')['default']
     Gltf: typeof import('./src/components/gltf/index.vue')['default']
     ModelsDemo: typeof import('./src/components/ModelsDemo.vue')['default']
     RouterLink: typeof import('vue-router')['RouterLink']

diff --git a/playground/src/components/FboCube.vue b/playground/src/components/FboCube.vue
@@ -0,0 +1,23 @@
+<script setup lang="ts">
+import { useFBO } from '@tresjs/cientos'
+
+const fboTarget = useFBO({
+  depth: true,
+  width: 512,
+  height: 512,
+  settings: {
+    samples: 1,
+  },
+})
+</script>
+
+<template>
+  <TresMesh>
+    <TresBoxGeometry :args="[1, 1, 1]" />
+
+    <TresMeshBasicMaterial
+      :color="0xff8833"
+      :map="fboTarget?.texture ?? null"
+    />
+  </TresMesh>
+</template>