Skip to content

Commit

Permalink
docs: add user input config docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@whereiswolf
whereiswolf committed Apr 21, 2024
1 parent 37fa163 commit 2dbbe4d
Showing 1 changed file with 68 additions and 29 deletions.
97 changes: 68 additions & 29 deletions docs/guide/controls/camera-controls.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,35 +26,74 @@ Is really important that the Perspective camera is set first in the canvas. Othe

Certainly! Here's the properties of the object in raw markdown table format:

| Prop | Description | Default |
| :------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| **makeDefault** | Whether to make this the default controls. | `false` |
| **camera** | The camera to control. | `undefined` |
| **domElement** | The DOM element to listen to. | `undefined` |
| **minPolarAngle** | Minimum vertical angle in radians. | `0` |
| **maxPolarAngle** | Maximum vertical angle in radians. | `Math.PI` |
| **minAzimuthAngle** | Minimum horizontal angle in radians. | `-Infinity` |
| **maxAzimuthAngle** | Maximum horizontal angle in radians. | `Infinity` |
| **distance** | Current distance. | `camera.position.z` |
| **minDistance** | Minimum distance for dolly. PerspectiveCamera only. | `Number.EPSILON` |
| **maxDistance** | Maximum distance for dolly. PerspectiveCamera only. | `Infinity` |
| **infinityDolly** | `true` to enable Infinity Dolly for wheel and pinch. | `false` |
| **minZoom** | Minimum camera zoom. | `0.01` |
| **maxZoom** | Maximum camera zoom. | `Infinity` |
| **smoothTime** | Approximate time in seconds to reach the target. A smaller value will reach the target faster. | `0.25` |
| **draggingSmoothTime** | The smoothTime while dragging. | `0.125` |
| **maxSpeed** | Max transition speed in units per second. | `Infinity` |
| **azimuthRotateSpeed** | Speed of azimuth (horizontal) rotation. | `1.0` |
| **polarRotateSpeed** | Speed of polar (vertical) rotation. | `1.0` |
| **dollySpeed** | Speed of mouse-wheel dollying. | `1.0` |
| **dollyDragInverted** | `true` to invert direction when dollying or zooming via drag. | `false` |
| **truckSpeed** | Speed of drag for truck and pedestal. | `2.0` |
| **dollyToCursor** | `true` to enable Dolly-in to the mouse cursor coords. | `false` |
| **dragToOffset** | Whether to drag to offset. | `false` |
| **verticalDragToForward** | The same as `.screenSpacePanning` in three.js's OrbitControls. | `false` |
| **boundaryFriction** | Friction ratio of the boundary. | `0.0` |
| **restThreshold** | Controls how soon the `rest` event fires as the camera slows. | `0.01` |
| **colliderMeshes** | An array of Meshes to collide with the camera. Be aware colliderMeshes may decrease performance. The collision test uses 4 raycasters from the camera since the near plane has 4 corners. | `[]` |
| Prop | Description | Default |
| :------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| **makeDefault** | Whether to make this the default controls. | `false` |
| **camera** | The camera to control. | `undefined` |
| **domElement** | The DOM element to listen to. | `undefined` |
| **minPolarAngle** | Minimum vertical angle in radians. | `0` |
| **maxPolarAngle** | Maximum vertical angle in radians. | `Math.PI` |
| **minAzimuthAngle** | Minimum horizontal angle in radians. | `-Infinity` |
| **maxAzimuthAngle** | Maximum horizontal angle in radians. | `Infinity` |
| **distance** | Current distance. | `camera.position.z` |
| **minDistance** | Minimum distance for dolly. PerspectiveCamera only. | `Number.EPSILON` |
| **maxDistance** | Maximum distance for dolly. PerspectiveCamera only. | `Infinity` |
| **infinityDolly** | `true` to enable Infinity Dolly for wheel and pinch. | `false` |
| **minZoom** | Minimum camera zoom. | `0.01` |
| **maxZoom** | Maximum camera zoom. | `Infinity` |
| **smoothTime** | Approximate time in seconds to reach the target. A smaller value will reach the target faster. | `0.25` |
| **draggingSmoothTime** | The smoothTime while dragging. | `0.125` |
| **maxSpeed** | Max transition speed in units per second. | `Infinity` |
| **azimuthRotateSpeed** | Speed of azimuth (horizontal) rotation. | `1.0` |
| **polarRotateSpeed** | Speed of polar (vertical) rotation. | `1.0` |
| **dollySpeed** | Speed of mouse-wheel dollying. | `1.0` |
| **dollyDragInverted** | `true` to invert direction when dollying or zooming via drag. | `false` |
| **truckSpeed** | Speed of drag for truck and pedestal. | `2.0` |
| **dollyToCursor** | `true` to enable Dolly-in to the mouse cursor coords. | `false` |
| **dragToOffset** | Whether to drag to offset. | `false` |
| **verticalDragToForward** | The same as `.screenSpacePanning` in three.js's OrbitControls. | `false` |
| **boundaryFriction** | Friction ratio of the boundary. | `0.0` |
| **restThreshold** | Controls how soon the `rest` event fires as the camera slows. | `0.01` |
| **colliderMeshes** | An array of Meshes to collide with the camera. Be aware colliderMeshes may decrease performance. The collision test uses 4 raycasters from the camera since the near plane has 4 corners. | `[]` |
| **mouseButtons** | Configuration of actions on mouse input. | See [`User input config`](#user-input-config) for details |
| **touches** | Configuration of actions on touch. | See [`User input config`](#user-input-config) for details |

## User input config

You can easily override the default user input config by defining `mouseButtons` and/or `touches` props that correspond to [`camera-controls` settings](https://github.com/yomotsu/camera-controls?#user-input-config). For ease of use, we're re-exporting the `CameraControls` class as `CameraControlsClass` which gives you access to the `ACTION` enum.

```vue
<script lang="ts" setup>
import { CameraControls, CameraControlsClass } from '@tresjs/cientos'
</script>
<template>
<CameraControls
:mouse-buttons="{ left: CameraControlsClass.ACTION.DOLLY, ... }"
:touches="{ one: CameraControlsClass.ACTION.TOUCH_TRUCK, ... }"
/>
</template>
```

### Mouse buttons

| Button to assign | Options | Default |
| ----------------------- | -------------------------------------------------------------- | --------------------------------------------------------------- |
| `mouseButtons.left` | `ROTATE` \| `TRUCK` \| `OFFSET` \| `DOLLY` \| `ZOOM` \| `NONE` | `ROTATE` |
| `mouseButtons.right` | `ROTATE` \| `TRUCK` \| `OFFSET` \| `DOLLY` \| `ZOOM` \| `NONE` | `TRUCK` |
| `mouseButtons.wheel` ¹ | `ROTATE` \| `TRUCK` \| `OFFSET` \| `DOLLY` \| `ZOOM` \| `NONE` | `DOLLY` for Perspective camera, `ZOOM` for Orthographic camera. |
| `mouseButtons.middle` ² | `ROTATE` \| `TRUCK` \| `OFFSET` \| `DOLLY` \| `ZOOM` \| `NONE` | `DOLLY` |

1. Mouse wheel event for scroll "up/down", on mac "up/down/left/right".
2. Mouse wheel "button" click event.

### Touches

| Fingers to assign | Options | Default |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `touches.one` | `TOUCH_ROTATE` \| `TOUCH_TRUCK` \| `TOUCH_OFFSET` \| `DOLLY` \| `ZOOM` \| `NONE` | `TOUCH_ROTATE` |
| `touches.two` | `TOUCH_DOLLY_TRUCK` \| `TOUCH_DOLLY_OFFSET` \| `TOUCH_DOLLY_ROTATE` \| `TOUCH_ZOOM_TRUCK` \| `TOUCH_ZOOM_OFFSET` \| `TOUCH_ZOOM_ROTATE` \| `TOUCH_DOLLY` \| `TOUCH_ZOOM` \| `TOUCH_ROTATE` \| `TOUCH_TRUCK` \| `TOUCH_OFFSET` \| `NONE` | `TOUCH_DOLLY_TRUCK` for Perspective camera, `TOUCH_ZOOM_TRUCK` for Othographic camera. |
| `touches.three` | `TOUCH_DOLLY_TRUCK` \| `TOUCH_DOLLY_OFFSET` \| `TOUCH_DOLLY_ROTATE` \| `TOUCH_ZOOM_TRUCK` \| `TOUCH_ZOOM_OFFSET` \| `TOUCH_ZOOM_ROTATE` \| `TOUCH_ROTATE` \| `TOUCH_TRUCK` \| `TOUCH_OFFSET` \| `NONE` | `TOUCH_TRUCK` |

## Events

Expand Down

0 comments on commit 2dbbe4d

Please sign in to comment.