Merge pull request #18 from Tresjs/docs/7-document-args-and-properties

docs: document args and properties

docs/.vitepress/config.ts

@@ -17,10 +17,17 @@ export default defineConfig({
           { text: 'Your first Scene', link: '/guide/your-first-scene' },
         ],
       },
-      /*    {
+      {
         text: 'API',
+        items: [
+          { text: 'Renderer', link: '/api/renderer' },
+          {
+            text: 'Instances, arguments and props',
+            link: '/api/instances-arguments-and-props',
+          },
+        ],
       },
-      {
+      /*{
         text: 'Examples',
       }, */
       {

docs/.vitepress/theme/components/FirstScene.vue

@@ -1,17 +1,9 @@
 <script setup lang="ts">
 import { ref, onMounted } from 'vue'
 import { Color, sRGBEncoding, ACESFilmicToneMapping } from 'three'
-import { OrbitControls, useTweakPane } from '@tresjs/cientos'
-
-import Cone from './Cone.vue'
-import Cube from './Cube.vue'
-import Sphere from './Sphere.vue'
-import Ground from './Ground.vue'
-
+import { OrbitControls } from '@tresjs/cientos'
 const LightRef = ref()
 
-useTweakPane()
-
 onMounted(() => {
   LightRef.value.shadow.mapSize.set(1024, 1024)
   LightRef.value.shadow.camera.near = 0.5

docs/.vitepress/theme/index.ts

@@ -8,8 +8,11 @@ import StackBlitzEmbed from './components/StackBlitzEmbed.vue'
 export default {
   ...DefaultTheme,
   enhanceApp(ctx) {
+    DefaultTheme.enhanceApp(ctx)
     ctx.app.component('FirstScene', FirstScene)
     ctx.app.component('StackBlitzEmbed', StackBlitzEmbed)
     ctx.app.use(Tres)
+
+    console.log(ctx)
   },
 }

docs/advanced/extending.md

@@ -28,3 +28,34 @@ This will automatically add a `<TresOrbitControls>` to the catalogue, so you can
   </TresCanvas>
 </template>
 ```
+
+## Extending an element dynamically <Badge type="tip" text="^1.1.0" />
+
+Or you can also add it dynamically in your components:
+
+```vue{2,3,5,8,17,19}
+<script setup lang="ts">
+import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls'
+import { TextGeometry } from 'three/examples/jsm/geometries/TextGeometry'
+
+const { extend } = useCatalogue()
+
+// Add the element to the catalogue
+extend({ TextGeometry, OrbitControls })
+
+/* Rest of the code */
+</script>
+
+<template>
+  <TresCanvas shadows alpha>
+    <TresPerspectiveCamera :position="[5, 5, 5]" />
+    <TresScene>
+      <TresOrbitControls v-if="state.renderer" :args="[state.camera, state.renderer?.domElement]" />
+      <TresMesh>
+        <TresTextGeometry :args="['TresJS', { font, ...fontOptions }]" center />
+        <TresMeshMatcapMaterial :matcap="matcapTexture" />
+      </TresMesh>
+    </TresScene>
+  </TresCanvas>
+</template>
+```

docs/api/instances-arguments-and-props.md

@@ -0,0 +1,122 @@
+# Instances
+
+The core idea of **Tres** is an _autogenerated catalogue_ of all the ThreeJS elements. This catalogue is generated from the ThreeJS source code, so it's always up to date.
+
+When using ThreeJS, you need to import the elements you want to use. For example, if you want to use a `PerspectiveCamera`, you need to import it from the `three` package:
+
+```js
+import { PerspectiveCamera } from 'three'
+
+const camera = new PerspectiveCamera(45, width / height, 1, 1000)
+```
+
+With **Tres** you don't need to import anything, that's because **Tres** automatically generate a **Vue Component based of the Three Object you want to use in CamelCase with a Tres prefix**. For example, if you want to use a `PerspectiveCamera` you would use `<TresPerspectiveCamera />` component.
+
+```vue
+<template>
+  <TresCanvas>
+    <TresPerspectiveCamera />
+    <!-- Your scene goes here -->
+  </TresCanvas>
+</template>
+```
+
+This mean that you can the same [documentation](https://threejs.org/docs/) as you where using plain ThreeJS, but with the power of Vue.
+
+## Declaring objects
+
+If we follow this argument, you should be able to lay out an instance like this: ❌
+
+```vue
+<template>
+  <TresCanvas>
+    <TresPerspectiveCamera visible :position="new THREE.Vector3(1, 2, 3)" />
+    <!-- Your scene goes here -->
+  </TresCanvas>
+</template>
+```
+
+But with **Tres** this is not needed, you can define properties declaratively like this: ✅
+
+```vue
+<template>
+  <TresCanvas>
+    <TresPerspectiveCamera visible :position="[1, 2, 3]" />
+    <!-- Your scene goes here -->
+  </TresCanvas>
+</template>
+```
+
+## Arguments
+
+Some ThreeJS objects have arguments, for example, the `PerspectiveCamera` constructor has the following arguments:
+
+- `fov` - Camera frustum vertical field of view.
+- `aspect` - Camera frustum aspect ratio.
+- `near` - Camera frustum near plane.
+- `far` - Camera frustum far plane.
+
+To pass these arguments to the `TresPerspectiveCamera` component, you can use the `args` prop:
+
+```vue
+<template>
+  <TresCanvas>
+    <TresPerspectiveCamera :args="[45, 1, 0.1, 1000]" />
+    <!-- Your scene goes here -->
+  </TresCanvas>
+</template>
+```
+
+This is the same as doing this:
+
+```ts
+const camera = new PerspectiveCamera(45, 1, 0.1, 1000)
+```
+
+## rops
+
+You can also pass props to the component, for example, the `TresAmbientLight` has a `intensity` property, so you can pass it to the component like this:
+
+```html
+<TresAmbientLight :intensity="0.5" />
+```
+
+### Set
+
+All properties whose underlying object has a `.set()` method have a shortcut to recieve the value as an array. For example, the `TresPerspectiveCamera` has a `position` property, which is a `Vector3` object, so you can pass it to the component like this:
+
+```html
+<TresPerspectiveCamera :position="[1, 2, 3]" />
+```
+
+### Scalar
+
+Another shortcut you can use is pass a scalar value to a property that expects a `Vector3` object, using the same value for the rest of the Vector:
+
+```html
+<TresPerspectiveCamera :position="5" /> ✅
+```
+
+```html
+<TresPerspectiveCamera :position="[5, 5, 5]" /> ✅
+```
+
+### Colors
+
+You can pass colors to the components using the `color` prop, which accepts a string with the color name or a hex value:
+
+```html
+<TresAmbientLight color="teal" /> ✅
+```
+
+```html
+<TresAmbientLight color="#008080" /> ✅
+```
+
+### Methods
+
+Some underlying properties are actually methods, the `TresPerspectiveCamera` has a `lookAt` method inherit from [Object3d](https://threejs.org/docs/#api/en/core/Object3D.lookAt), so you can pass it the coords to the component like this:
+
+```html
+<TresPerspectiveCamera :look-at="[1, 2, 3]" />
+```

docs/api/renderer.md

@@ -0,0 +1,33 @@
+# Renderer
+
+The `Renderer` component is the main component of Tres. It's the one that creates the ThreeJS `WebGLRenderer` and define your Tres Scene.
+
+```vue{2,7}
+<template>
+  <TresCanvas shadows :output-encoding="sRGBEncoding">
+    <TresPerspectiveCamera />
+    <TresScene>
+      <!-- Your scene goes here -->
+    </TresScene>
+  </TresCanvas>
+</template>
+```
+
+## Props
+
+| Prop                        | Description                                                                                                                                                     | Default            |
+| --------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
+| **shadows**                 | Enable shadows in the Renderer                                                                                                                                  | `false`            |
+| **shadowMapType**           | Set the shadow map type                                                                                                                                         | `PCFSoftShadowMap` |
+| **physicallyCorrectLights** | Whether to use physically correct lighting mode. See the [lights / physical example](https://threejs.org/examples/#webgl_lights_physical).                      | `false`            |
+| **outputEncoding**          | Defines the output encoding                                                                                                                                     | `LinearEncoding`   |
+| **toneMapping**             | Defines the tone mapping exposure used by the renderer.                                                                                                         | `NoToneMapping`    |
+| **context**                 | This can be used to attach the renderer to an existing [RenderingContext](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext)               |                    |
+| **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`          |
+| **preserveDrawingBuffer**   | Whether to preserve the buffers until manually cleared or overwritten..                                                                                         | `false`            |
+| **clearColor**              | The color the renderer will use to clear the canvas.                                                                                                            | `#000000`          |
+| **windowSize**              | Whether to use the window size as the canvas size or the parent element.                                                                                        | `false`            |
+
+## Defaults
+
+Tres tries to be as less opinionated as possible. That's why it doesn't set almost any default value for the `Renderer` component. You need to set the props you want to use. The only exception is the `antialias` prop. It's set to `true` by default.

docs/index.md

@@ -32,4 +32,7 @@ features:
   - icon: 🥰
     title: Keeps up to date
     details: It brings all the updated features of ThreeJS right away.
+  - icon: 🌳
+    title: Ecosystem
+    details: Extend the core functionality with packages like `cientos` and `postprocessing`. Or add your own.
 ---

package.json

@@ -55,7 +55,7 @@
     "eslint-config-prettier": "^8.5.0",
     "eslint-plugin-vue": "^9.7.0",
     "prettier": "^2.7.1",
-    "vitepress": "1.0.0-alpha.26",
+    "vitepress": "1.0.0-alpha.29",
     "vue": "^3.2.41",
     "vue-eslint-parser": "^9.1.0"
   }

packages/tres/src/core/useRenderer/index.ts

@@ -140,7 +140,7 @@ export function useRenderer(canvas: MaybeElementRef, container: MaybeElementRef,
     }
 
     renderer.value.setSize(width.value, height.value)
-    renderer.value.setPixelRatio(pixelRatio.value)
+    renderer.value.setPixelRatio(Math.min(pixelRatio.value, 2))
   }
 
   const updateRendererOptions = () => {