docs: add some advanced topics

Author: nartc

apps/documentation/docs/advanced/compound.mdx

@@ -0,0 +1,87 @@
+---
+id: compound
+title: Compound Component
+sidebar_label: Compound Component
+---
+
+Compound Component is a component that wraps at least one THREE.js entity in its template and all Inputs will be forwarded to that THREE.js entity.
+
+There are two steps to create a Compound component
+
+-   Ensure that NGT Custom Renderer recognizes the Compound Component's selector as a `compound`. We can use `[compoundPrefixes]` Input on `<ngt-canvas>` to configure this
+-   Add `ngtCompound` attribute on the THREE.js entity that we want our Compound Component to wrap
+
+Suppose we have the following template
+
+```html
+<ngt-mesh>
+    <ngt-box-geometry *args="args" />
+    <ngt-mesh-basic-material />
+</ngt-mesh>
+
+<ngt-mesh>
+    <ngt-box-geometry *args="argsTwo" />
+    <ngt-mesh-standard-material />
+</ngt-mesh>
+```
+
+We notice that we keep using `<ngt-mesh>` and `<ngt-box-geometry>`. This is a good candidate to make into a Compound Component. In this case,
+we'll make a `Box` component.
+
+```ts
+extend({ Mesh, BoxGeometry });
+
+@Component({
+    selector: 'tutorial-box',
+    standalone: true,
+    template: `
+        <ngt-mesh ngtCompound [ref]="boxRef">
+            <ngt-box-geometry *args="boxArgs" />
+            <ng-content />
+        </ngt-mesh>
+    `,
+    imports: [NgtArgs],
+})
+export class Box {
+    @Input() boxRef = injectNgtRef<Mesh>();
+    @Input() boxArgs: ConstructorParameters<typeof BoxGeometry> = [1, 1, 1];
+}
+
+@Component({
+    template: `<ngt-canvas [compoundPrefixes]="['tutorial']" />`,
+})
+export class SomeFeature {}
+```
+
+-   We use `<ngt-mesh>` and `<ngt-box-geometry>` with `<ng-content>`. This allows the consumers to pass in any Material, or other objects as children to our `<ngt-mesh>`
+
+    -   We use `ngtCompound` on the `<ngt-mesh>`. This lets NGT Custom Renderer knows that `Box` component will forward its Inputs to `<ngt-mesh>`
+        :::note
+
+        Inputs that are defined like `boxRef` and `boxArgs` will **not** get forwarded.
+
+        :::
+
+-   We `extend({Mesh, BoxGeometry})` to ensure that NGT Custom Renderer knows about `Mesh` and `BoxGeometry` if they consume `Box` component
+-   We let the NGT Custom Renderer knows that our `Box` component is a Compound Component by providing `['tutorial']` to `compoundPrefixes`
+
+Now that we have `Box`, we can consume it like following
+
+```html
+<tutorial-box>
+    <ngt-mesh-basic-material />
+</tutorial-box>
+
+<tutorial-box [position]="[2, 2, 2]">
+    <ngt-mesh-standard-material />
+</tutorial-box>
+
+<tutorial-box [position]="[-2, -2, -2]">
+    <ngt-mesh-standard-material />
+    <ngt-mesh>
+        <ngt-plane-geometry />
+    </ngt-mesh>
+</tutorial-box>
+```
+
+Check out [TBD: angular-three-soba](#) for more examples on Compound Components.

apps/documentation/docs/advanced/performance.mdx

@@ -0,0 +1,73 @@
+---
+id: performance
+title: Performance
+sidebar_label: Performance
+---
+
+## Re-use Geometries and Materials
+
+Each Geometry and Material consumes the GPU's resources. If we know certain Geometries and/or Materials will repeat, we can reuse them
+
+### Imperative
+
+We can have static geometries and materials as Component's properties
+
+```ts
+@Component({
+    standalone: true,
+    template: `
+        <ngt-mesh [geometry]="sphere" [material]="redMaterial" [position]="[1, 1, 1]" />
+        <ngt-mesh [geometry]="sphere" [material]="redMaterial" [position]="[2, 2, 2]" />
+    `,
+})
+export class SceneGraph {
+    readonly sphere = new THREE.SphereGeometry(1, 32, 32);
+    readonly redMaterial = new THREE.MeshBasicMaterial({ color: 'red' });
+}
+```
+
+We can also store these static objects in a Service to reuse across the application
+
+### Declarative
+
+We can put the Geometries and Materials declaratively on the template so they can react to Input changes; and still can reuse them
+
+```ts
+@Component({
+    standalone: true,
+    template: `
+        <ngt-sphere-geometry *args="sphereArgs" [ref]="sphereRef" />
+        <ngt-mesh-basic-material #redMaterial [color]="color" />
+
+        <ngt-mesh [geometry]="sphereRef.nativeElement" [material]="redMaterial" [position]="[1, 1, 1]" />
+        <ngt-mesh [geometry]="sphereRef.nativeElement" [material]="redMaterial" [position]="[2, 2, 2]" />
+    `,
+    imports: [NgtArgs],
+})
+export class SceneGraph {
+    readonly sphereRef = injectNgtRef<THREE.SphereGeometry>();
+
+    sphereArgs = [1, 32, 32];
+    color = 'red';
+}
+```
+
+## On-demand Rendering
+
+> Credit: [React Three Fiber](https://docs.pmnd.rs/react-three-fiber/advanced/scaling-performance#on-demand-rendering)
+
+The SceneGraph is usually rendered at 60 frames per second. This makes sense if the SceneGraph ontains _constantly_ moving parts (eg: game).
+Consequently, this drains the device's resources.
+
+If the SceneGraph has static entities, or entities that are allowed to come to a rest, constantly rendering at 60fps would be wasteful.
+In those cases, we can opt into on-demand rendering, which will only render when necessary. All we have to do is to set `frameloop="demand"` on the `<ngt-canvas>`
+
+```html
+<ngt-canvas frameloop="demand" />
+```
+
+:::info
+
+Check out [TBD: Color Grading Stackblitz example](#) to see on-demand rendering in action.
+
+:::

apps/documentation/sidebars.js

@@ -42,6 +42,11 @@ const sidebars = {
                 'api/additional-exports',
             ],
         },
+        {
+            type: 'category',
+            label: 'Advanced',
+            items: ['advanced/compound', 'advanced/performance'],
+        },
     ],
     // By default, Docusaurus generates a sidebar from the docs folder structure
     //    tutorialSidebar: [{ type: 'autogenerated', dirName: '.' }],