Skip to content

Commit 015168f

Browse files
nartcnartc
committed
docs: add Canvas API
1 parent 821fa55 commit 015168f

File tree

3 files changed

+103
-0
lines changed

3 files changed

+103
-0
lines changed

‎apps/documentation/docs/api/canvas.mdx

+94
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
---
2+
id: canvas
3+
title: Canvas
4+
sidebar_label: Canvas
5+
---
6+
7+
The root of a NGT 3D scene is the `NgtCanvas` component
8+
9+
```html
10+
<ngt-canvas [sceneGraph]="SceneGraph" [camera]="cameraOptions" />
11+
```
12+
13+
## Inputs
14+
15+
| name | description | type | default |
16+
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------ |
17+
| **sceneGraph** | **(required)** A component that will be rendered as the Root THREE.Scene | `Type<any>` | |
18+
| compoundPrefixes | An array of prefixes of HTML tags that NGT will treat as [TBD: Compound](#) | `string[]` | `[]` |
19+
| gl | A THREE.js Renderer instance of options that go into the default Renderer. It also accepts a callback that returns a THREE.js Renderer instance | `NgtGLOptions` | - |
20+
| size | Dimensions to fit the THREE.js Renderer to. Will measure `<canvas>` dimentions if omitted | `NgtSize` | - |
21+
| shadows | Enables PCFsoft shadows. Can accept `gl.shadowMap` options for fine-tuning | `boolean`, `Partial<THREE.WebGLShadowMap>` | `false` |
22+
| legacy | Disables THREE.js r139 ColorManagement | `boolean` | `false` |
23+
| linear | Switch off automatic sRGB encoding and gamma correction | `boolean` | `false` |
24+
| flat | Use `NoToneMapping` instead of `ACESFilmicToneMapping` | `boolean` | `false` |
25+
| orthographic | Creates an `OrthographicCamera` instead | `boolean` | `false` |
26+
| frameloop | R3F's render mode. Set to `demand` to only render when there are changes to the Scene Graph | `always`, `demand`, `never` | `always` |
27+
| performance | Performance options for adaptive environment | `Partial<Omit<NgtPerformance, 'regress'>>` | - |
28+
| dpr | Target pixel ratio. Can clamp between a range `[min, max]` | `NgtDpr` | `[1, 2]` |
29+
| raycaster | Options that go into the default `Raycaster` | `Partial<THREE.Raycaster>` | - |
30+
| camera | A Camera instance or options that go into the default Camera | [check source](https://github.com/angular-threejs/angular-three/blob/main/libs/angular-three/src/lib/types.ts) | - |
31+
| events | R3F event manager to manage elements' pointer events | `(store: NgtRxStore<NgtState>) => NgtEventManager<HTMLElement>` | - |
32+
| eventSource | The target where events are bound to | `HTMLElement`, `ElementRef<HTMLElement>` | `NgtCanvas` host element |
33+
| eventPrefix | The event prefix that is cast into Canvas pointer x/y events | `offset`, `client`, `page`, `layer`, `screen` | `offset` |
34+
| lookAt | Default coordinate for the camera to look at | `THREE.Vector3`, `Parameters<THREE.Vector3['set']>` | - |
35+
36+
```ts
37+
export type NgtGLRenderer = {
38+
render: (scene: THREE.Scene, camera: THREE.Camera) => void;
39+
};
40+
41+
export type NgtGLOptions =
42+
| NgtGLRenderer
43+
| ((canvas: HTMLCanvasElement) => NgtGLRenderer)
44+
| Partial<NgtProperties<THREE.WebGLRenderer> | THREE.WebGLRendererParameters>
45+
| undefined;
46+
47+
export type NgtSize = {
48+
width: number;
49+
height: number;
50+
top: number;
51+
left: number;
52+
};
53+
54+
export interface NgtPerformance {
55+
/** Current performance normal, between min and max */
56+
current: number;
57+
/** How low the performance can go, between 0 and max */
58+
min: number;
59+
/** How high the performance can go, between min and max */
60+
max: number;
61+
/** Time until current returns to max in ms */
62+
debounce: number;
63+
/** Sets current to min, puts the system in regression */
64+
regress: () => void;
65+
}
66+
67+
export type NgtDpr = number | [min: number, max: number];
68+
```
69+
70+
## Outputs
71+
72+
| name | description |
73+
| ------------- | ------------------------------------------------------------------------------------------------------------------ |
74+
| created | Emits after the `NgtCanvas` is created with all the internal building blocks |
75+
| pointerMissed | If observed, NGT will set the internal `pointermissed` event and will emit whenever the Raycaster missed an object |
76+
77+
## Canvas defaults
78+
79+
NgtCanvas sets up a translucent `THREE.WebGLRenderer` with the following constructor arguments:
80+
81+
- antialias = `true`
82+
- alpha = `true`
83+
- powerReference = `'high-performance'`
84+
85+
and the following properties:
86+
87+
- outputEncoding = `THREE.sRGBEncoding`
88+
- toneMapping = `THREE.ACESFilmicToneMapping`
89+
90+
- A `THREE.PCFSoftShadowMap` if `shadows` is `true`
91+
- A `THREE.PerspectiveCamera`, or a `THREE.OrthographicCamera` if `orthographic` is `true`
92+
- A `THREE.Scene`
93+
- A `THREE.Raycaster`
94+
- A `window:resize` listener that will update the `THREE.Renderer` and `THREE.Camera`` when the container is resized.

‎apps/documentation/sidebars.js

+5
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,11 @@ const sidebars = {
1919
label: 'Getting Started',
2020
items: ['getting-started/introduction', 'getting-started/installation', 'getting-started/first-scene'],
2121
},
22+
{
23+
type: 'category',
24+
label: 'API',
25+
items: ['api/canvas'],
26+
},
2227
],
2328
// By default, Docusaurus generates a sidebar from the docs folder structure
2429
// tutorialSidebar: [{ type: 'autogenerated', dirName: '.' }],

‎apps/documentation/src/css/custom.css

+4
Original file line numberDiff line numberDiff line change
@@ -53,3 +53,7 @@ a.navbar__item:hover,
5353
a.table-of-contents__link:hover {
5454
text-decoration: underline;
5555
}
56+
57+
div.menu__list-item-collapsible {
58+
font-weight: var(--ifm-font-weight-bold);
59+
}

0 commit comments

Comments
 (0)