feat: context (TresContext) is now exposed from TresCanvas (#404)

* feat: context (TresContext) is now exposed from TresCanvas * docs: improved TresCanvas docs * docs: added exposed properties to TresCanvas docs * docs: added docs for useTresContext * chore: changes concerning code review --------- Co-authored-by: Tino Koch <[email protected]>
Tresjs · Sep 22, 2023 · 838d779 · 838d779
1 parent e3603f3
commit 838d779
Show file tree

Hide file tree

Showing 13 changed files with 552 additions and 541 deletions.
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
@@ -49,7 +49,7 @@ export default defineConfig({
       {
         text: 'API',
         items: [
-          { text: 'Renderer', link: '/api/renderer' },
+          { text: 'TresCanvas', link: '/api/tres-canvas' },
           {
             text: 'Instances, arguments and props',
             link: '/api/instances-arguments-and-props',

diff --git a/docs/advanced/primitive.md b/docs/advanced/primitive.md
@@ -1,12 +1,12 @@
 # Primitives
 
-The `<primitive />` component is a versatile low-level component in TresJS that allows you to directly use any Three.js object within your Vue application without an abstraction. It acts as a bridge between Vue's reactivity system and Three.js's scene graph.
+The `<primitive />` component is a versatile low-level component in TresJS that allows you to directly use any three.js object within your Vue application without an abstraction. It acts as a bridge between Vue's reactivity system and three.js's scene graph.
 
 ## Usage
 
 ```html
 <script setup lang="ts">
-  // Import necessary Three.js classes
+  // Import necessary three.js classes
   import { Mesh, BoxGeometry, MeshBasicMaterial } from 'three';
 
   // Create a box geometry and a basic material
@@ -26,7 +26,7 @@ The `<primitive />` component is a versatile low-level component in TresJS that
 
 ## Props
 
-`object`: This prop expects a Three.js Object3D or any of its derived classes. It is the primary object that the `<primitive />` component will render. In the updated example, a `Mesh` object with an associated `Material` is passed to this prop.
+`object`: This prop expects a three.js Object3D or any of its derived classes. It is the primary object that the `<primitive />` component will render. In the updated example, a `Mesh` object with an associated `Material` is passed to this prop.
 
 ## Usage with Models 
 

diff --git a/docs/api/composables.md b/docs/api/composables.md
@@ -14,7 +14,7 @@ The `useRenderLoop` composable is the core of **TresJS** animations. It allows y
 const { onLoop, resume } = useRenderLoop()
 
 onLoop(({ delta, elapsed, clock, dt }) => {
-  // I will run at every frame ~ 60FPS (depending of your monitor)
+  // I will run at every frame ~60FPS (depending of your monitor)
 })
 ```
 
@@ -136,12 +136,12 @@ Then you can bind the textures to the material.
       <TresSphereGeometry />
       <TresMeshStandardMaterial
         :map="map"
-        :displacementMap="displacementMap"
-        :normalMap="normalMap"
-        :roughnessMap="roughnessMap"
-        :metalnessMap="metalnessMap"
-        :aoMap="aoMap"
-        :alphaMap="alphaMap"
+        :displacement-map="displacementMap"
+        :normal-map="normalMap"
+        :roughness-map="roughnessMap"
+        :metalness-map="metalnessMap"
+        :ao-map="aoMap"
+        :alpha-map="alphaMap"
       />
     </TresMesh>
   </TresCanvas>
@@ -179,19 +179,16 @@ watch(carRef, ({ model }) => {
 })
 ```
 
-## useTresContext (former useTres)
-
-This composable aims to provide access to the state model which contains the default renderer, camera, scene, and other useful properties.
+## useTresContext
+This composable aims to provide access to the state model which contains multiple useful properties.
 
 ```ts
-const { camera, renderer } = useTresContext()
+const { camera, renderer, camera, cameras } = useTresContext()
 
-console.log(camera.value) // THREE.PerspectiveCamera
-console.log(renderer.value) // THREE.WebGLRenderer
 ```
 
 ::: warning
-`useTresContext` can be only be used inside of a `TresCanvas` since `TresCanvas` acts as the provider for the context data.
+`useTresContext` can be only be used inside of a `TresCanvas` since `TresCanvas` acts as the provider for the context data. Use [the context exposed by TresCanvas](tres-canvas#exposed-public-properties) if you find yourself needing it in parent components of TresCanvas. 
 :::
 
 ```vue
@@ -209,3 +206,19 @@ import { useTresContext } from '@tresjs/core'
 const context = useTresContext()
 </script>
 ```
+
+### Properties of context
+| Property | Description |
+| --- | --- |
+| **camera** | the currently active camera |
+| **cameras** | the cameras that exist in the scene |
+| **controls** | the controls of your scene |
+| **deregisterCamera** | a method to deregister a camera. This is only required if you manually create a camera. Cameras in the template are deregistered automatically. |
+| **extend** | Extends the component catalogue. See [extending](/advanced/extending) |
+| **raycaster** | the global raycaster used for pointer events |
+| **registerCamera** | a method to register a camera. This is only required if you manually create a camera. Cameras in the template are registered automatically. |
+| **renderer** | the [WebGLRenderer](https://threejs.org/docs/#api/en/renderers/WebGLRenderer) of your scene |
+| **scene** | the [scene](https://threejs.org/docs/?q=sce#api/en/scenes/Scene). |
+| **setCameraActive** | a method to set a camera active |
+| **sizes** | contains width, height and aspect ratio of your canvas |
+
diff --git a/docs/api/events.md b/docs/api/events.md
@@ -1,6 +1,6 @@
 # Events
 
-**TresJS** components emit pointer events when they are interacted with. This is the case for the components that represent Three.js classes that derive from [THREE.Object3D](https://threejs.org/docs/index.html?q=object#api/en/core/Object3D) (like meshes, groups,...).
+**TresJS** components emit pointer events when they are interacted with. This is the case for the components that represent three.js classes that derive from [THREE.Object3D](https://threejs.org/docs/index.html?q=object#api/en/core/Object3D) (like meshes, groups,...).
 
 <StackBlitzEmbed project-id="tresjs-events" />
 

diff --git a/docs/api/renderer.md b/docs/api/renderer.md
diff --git a/docs/api/tres-canvas.md b/docs/api/tres-canvas.md
@@ -0,0 +1,104 @@
+# TresCanvas
+
+The `TresCanvas` component is the main component of Tres. It's the one that creates the ThreeJS `WebGLRenderer`.
+
+```vue{2,5}
+<template>
+  <TresCanvas shadows :output-encoding="SRGBColorSpace">
+    <TresPerspectiveCamera />
+      <!-- Your scene goes here -->
+  </TresCanvas>
+</template>
+```
+
+## Canvas size
+
+The `TresCanvas` component will use the parent element size as the canvas size. If you want to use the window size as the canvas size, you can set the `window-size` prop to `true`.
+
+```vue
+<template>
+  <TresCanvas window-size>
+    <!-- Your scene goes here -->
+  </TresCanvas>
+</template>
+```
+
+Or you can use CSS to set your canvas size.
+
+```css
+html,
+body {
+  margin: 0;
+  padding: 0;
+  height: 100%;
+  width: 100%;
+}
+#canvas {
+  height: 100%;
+  width: 100%;
+}
+```
+
+## Presets
+
+Tres comes with a few presets for the `TresCanvas` component. You can use them by setting the `preset` prop.
+
+### Realistic
+
+The `realistic` preset makes easy to setup the renderer for more realistic 3D scenes.
+
+```vue
+<template>
+  <TresCanvas preset="realistic">
+    <!-- Your scene goes here -->
+  </TresCanvas>
+</template>
+```
+
+It's equivalent to:
+
+```ts
+renderer.shadows = true
+renderer.physicallyCorrectLights = true
+renderer.outputColorSpace = SRGBColorSpace
+renderer.toneMapping = ACESFilmicToneMapping
+renderer.toneMappingExposure = 3
+renderer.shadowMap.enabled = true
+renderer.shadowMap.type = PCFSoftShadowMap
+```
+
+## Props
+
+| Prop | Description | Default |
+| ---- | ---- | --- |
+| **alpha** | Controls the default clear alpha value. When set to true, the value is 0. Otherwise it's 1. | false |
+| **antialias** | Whether to perform antialiasing. | `true` |
+| **camera** | A manual camera to be used by the renderer. | |
+| **clearColor** | The color the renderer will use to clear the canvas. | `#000000` |
+| **context** | This can be used to attach the renderer to an existing [RenderingContext](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext) | |
+| **depth** | Whether the drawing buffer has a [depth buffer](https://en.wikipedia.org/wiki/Z-buffering) of at least 16 bits. | `true` |
+| **disableRender** | Disable render on requestAnimationFrame, usefull for PostProcessing | `false` |
+| **failIfMajorPerformanceCaveat** | Whether the renderer creation will fail upon low performance is detected. See [WebGL spec](https://registry.khronos.org/webgl/specs/latest/1.0/#5.2) for details. | `false` |
+| **logarithmicDepthBuffer** | Whether to use a logarithmic depth buffer. It may be necessary to use this if dealing with huge differences in scale in a single scene. Note that this setting uses gl_FragDepth if available which disables the [Early Fragment Test](https://www.khronos.org/opengl/wiki/Early_Fragment_Test) optimization and can cause a decrease in performance. | `false` |
+| **outputColorSpace** | Defines the output encoding | `LinearEncoding` |
+| **powerPreference** | Provides a hint to the user agent indicating what configuration of GPU is suitable for this WebGL context. Can be "high-performance", "low-power" or "default". | `default` |
+| **precision** | Shader precision. Can be "highp", "mediump" or "lowp". | "highp" if supported by the device |
+| **premultipliedAlpha** | Whether the renderer will assume that colors have [premultiplied alpha](https://en.wikipedia.org/wiki/Glossary_of_computer_graphics#premultiplied_alpha). | `true` |
+| **preserveDrawingBuffer** | Whether to preserve the buffers until manually cleared or overwritten.. | `false` |
+| **shadows** | Enable shadows in the renderer | `false` |
+| **shadowMapType** | Set the shadow map type | `PCFSoftShadowMap` |
+| **stencil** | Whether the drawing buffer has a [stencil buffer](https://en.wikipedia.org/wiki/Stencil_buffer) of at least 8 bits. | `true` |
+| **toneMapping** | Defines the tone mapping exposure used by the renderer. | `NoToneMapping` |
+| **toneMappingExposure** | Exposure level of tone mapping. | `1` |
+| **useLegacyLights** | Whether to use the legacy lighting mode or not | `true` |
+| **windowSize** | Whether to use the window size as the canvas size or the parent element. | `false` |
+
+### Defaults
+
+Tres tries to be as little opinionated as possible. That's why it doesn't set almost any default value for the `TresCanvas` component. It uses the defaults from [three.js](https://threejs.org/). The only exception is the `antialias` prop. It's set to `true` by default.
+
+## Exposed public properties
+
+| Property | Description |
+| ---- | ---- |
+| context | see [useTresContext](composables#usetrescontext) |
diff --git a/docs/examples/load-models.md b/docs/examples/load-models.md
@@ -12,7 +12,7 @@ There are several ways to load models on TresJS:
 
 ## Using `useLoader`
 
-The `useLoader` composable allows you to pass any type of Three.js loader and a URL to load the resource from. It returns a `Promise` with the loaded resource.
+The `useLoader` composable allows you to pass any type of three.js loader and a URL to load the resource from. It returns a `Promise` with the loaded resource.
 
 For a detailed explanation of how to use `useLoader`, check out the [useLoader](/api/composables#useloader) documentation.
 
@@ -33,7 +33,7 @@ Then you can pass the model scene to a TresJS [`primitive`](/advanced/primitive)
 </TresCanvas>
 ```
 
-> The `<primitive />` component is not a standalone component in the Tres source code. Instead, it's a part of the Tres core functionality. When you use `<primitive>`, it is translated to a `createElement` call, which creates the appropriate Three.js object based on the provided "object" prop.
+> The `<primitive />` component is not a standalone component in the Tres source code. Instead, it's a part of the Tres core functionality. When you use `<primitive>`, it is translated to a `createElement` call, which creates the appropriate three.js object based on the provided "object" prop.
 
 Notice in the example above that we are using the `Suspense` component to wrap the `TresCanvas` component. This is because `useLoader` returns a `Promise` and we need to wait for it to resolve before rendering the scene.
 

diff --git a/docs/examples/load-textures.md b/docs/examples/load-textures.md
@@ -10,7 +10,7 @@ There are two ways of loading 3D textures in TresJS:
 
 ## Using `useLoader`
 
-The `useLoader` composable allows you to pass any type of Three.js loader and a URL to load the resource from. It returns a `Promise` with the loaded resource.
+The `useLoader` composable allows you to pass any type of three.js loader and a URL to load the resource from. It returns a `Promise` with the loaded resource.
 
 For a detailed explanation of how to use `useLoader`, check out the [useLoader](/api/composables#use-loader) documentation.
 

diff --git a/playground/src/components/TheExperience.vue b/playground/src/components/TheExperience.vue
@@ -16,11 +16,11 @@ const gl = {
 
 const wireframe = ref(true)
 
-const context = ref()
+const canvas = ref()
 
 watchEffect(() => {
-  if (context.value) {
-    console.log({ context: context.value })
+  if (canvas.value) {
+    console.log(canvas.value.context)
   }
 })
 </script>
@@ -34,7 +34,7 @@ watchEffect(() => {
   <pre>{{ wireframe }}</pre>
   <TresCanvas
     v-bind="gl"
-    ref="context"
+    ref="canvas"
   >
     <TresPerspectiveCamera
       :position="[7, 7, 7]"