Portals

Portals might have different meaning depending on the use-cases. In general, it means that we want to render something as children of something else without following the hierarchy of the template. Pseudo-code looks something like this:

1
<ngt-group>
2
 <!-- render ngt-mesh here -->
3
</ngt-group>
4

5
<!-- outside of the hierarchy -->
6
<ngt-mesh></ngt-mesh>

`NgTemplateOutlet`

For many cases, we can use NgTemplateOutlet if we just want to portal objects around with (or without) different context data. In other words, we can use this technique to reuse templates.

Preview
Code

1
import { NgTemplateOutlet } from '@angular/common';
2
import { ChangeDetectionStrategy, Component, CUSTOM_ELEMENTS_SCHEMA, ElementRef, viewChild } from '@angular/core';
3
import { extend, injectBeforeRender, NgtCanvas } from 'angular-three';
4
import { NgtsGrid } from 'angular-three-soba/abstractions';
5
import { NgtsPerspectiveCamera } from 'angular-three-soba/cameras';
6
import { NgtsOrbitControls } from 'angular-three-soba/controls';
7
import * as THREE from 'three';
8
import { DEG2RAD } from 'three/src/math/MathUtils.js';
9

10
extend(THREE);
11

12
@Component({
13
  template: `
14
    <ngts-perspective-camera [options]="{ makeDefault: true, position: [10, 10, 10], fov: 30 }" />
15
    <ngts-orbit-controls
16
      [options]="{
17
        enableZoom: false,
18
        maxPolarAngle: 85 * DEG2RAD,
19
        minPolarAngle: 20 * DEG2RAD,
20
        maxAzimuthAngle: 45 * DEG2RAD,
21
        minAzimuthAngle: -45 * DEG2RAD,
22
      }"
23
    />
24

25
    <ngts-grid
26
      [options]="{
27
        planeArgs: [10.5, 10.5],
28
        position: [0, -0.01, 0],
29
        cellSize: 0.6,
30
        cellThickness: 1,
31
        cellColor: '#6f6f6f',
32
        sectionSize: 3.3,
33
        sectionThickness: 1.5,
34
        sectionColor: '#9d4b4b',
35
        fadeDistance: 25,
36
        fadeStrength: 1,
37
        followCamera: false,
38
        infiniteGrid: true,
39
      }"
40
    />
41

42
    <ngt-directional-light [position]="[5, 10, 3]" />
43

44
    <ngt-object3D #trail [position]="[0, 0.5, 0]">
45
      <ng-container [ngTemplateOutlet]="forTrail" />
46
    </ngt-object3D>
47

48
    <ng-template #forTrail>
49
      <ng-container [ngTemplateOutlet]="mesh" [ngTemplateOutletContext]="{ color: '#fe3d00' }" />
50
      <ngt-group [position]="[0, 1, 0]">
51
        <ng-container [ngTemplateOutlet]="mesh" [ngTemplateOutletContext]="{ color: '#2f7dc6' }" />
52
      </ngt-group>
53
    </ng-template>
54

55
    <ng-template #mesh let-color="color">
56
      <ngt-mesh>
57
        <ngt-box-geometry />
58
        <ngt-mesh-standard-material [color]="color" />
59
      </ngt-mesh>
60
    </ng-template>
61
  `,
62
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
63
  changeDetection: ChangeDetectionStrategy.OnPush,
64
  imports: [NgtsOrbitControls, NgtsPerspectiveCamera, NgtsGrid, NgTemplateOutlet],
65
  host: { class: 'template-outlet-experience' },
66
})
67
export class Experience {
68
  protected readonly DEG2RAD = DEG2RAD;
69

70
  private trailRef = viewChild.required<ElementRef<THREE.Object3D>>('trail');
71

72
  constructor() {
73
    injectBeforeRender(() => {
74
      const obj = this.trailRef().nativeElement;
75
      obj.position.x = Math.sin(Date.now() / 1000) * 4;
76
    });
77
  }
78
}
79

80
@Component({
81
  template: `
82
    <ngt-canvas [sceneGraph]="scene" />
83
  `,
84
  imports: [NgtCanvas],
85
  changeDetection: ChangeDetectionStrategy.OnPush,
86
  host: { class: 'template-outlet-docs' },
87
})
88
export default class TemplateOutletScene {
89
  scene = Experience;
90
}

What we’re seeing here is:

An Object3D that is being moved back and forth
A Mesh as a child of the Object3D
A Group
Another Mesh as a child of the Group

The main takeaway here is that this Mesh is being reused and has different color based on where it’s rendered.

1
<ngt-object3D>
2
  <ng-container [ngTemplateOutlet]="forObject3D" />
3
</ngt-object3D>
4

5
<ng-template #forObject3D>
6
   <ng-container [ngTemplateOutlet]="mesh" [ngTemplateOutletContext]="{ color: '#fe3d00' }" />
7
   <ngt-group [position]="[0, 1, 0]">
8
    <ng-container [ngTemplateOutlet]="mesh" [ngTemplateOutletContext]="{ color: '#2f7dc6' }" />
9
   </ngt-group>
10
</ng-template>
11

12
<ng-template #mesh let-color="color">
13
  <ngt-mesh>
14
    <ngt-box-geometry />
15
    <ngt-mesh-standard-material [color]="color" />
16
  </ngt-mesh>
17
</ng-template>

`NgtParent`

This technique is useful for when you cannot control the template for, well, ng-template. For example, routed components via ngt-router-outlet

NgtParent is a structural directive and it takes an input parent. parent accepts

A string: which will be used to look up the object with getObjectByName()
An Object3D
An ElementRef<Object3D>
or a Signal of all of these above

Attaching *parent on an element will portal that element as a child to the parent input.

`NgtPortal`

In THREE.js, there is a construct called WebGLRenderTarget. It is used to render the scene into a texture and then render the texture into the canvas. This is useful for things like post-processing effects, or HUD-like visuals.

In Angular Three, we can use NgtPortal component to create an off-screen buffer that can be used to render secondary scenes.

NgtPortal provides a layered NgtSignalStore<NgtState> that its children can inject. This makes sure that children of NgtPortal access the state of the NgtPortal and not the root NgtSignalStore<NgtState>.

1
@Component({
2
  template: `
3
    <ngt-mesh>
4
      <ngt-torus-geometry />
5
    </ngt-mesh>
6

7
    <ngt-portal [container]="secondaryScene">
8
      <ng-template portalContent>
9
        <ngts-perspective-camera [options]="{ makeDefault: true }" />
10
        <ngt-mesh>
11
          <ngt-box-geometry />
12
        </ngt-mesh>
13
      </ng-template>
14
    </ngt-portal>
15
  `,
16
  imports: [NgtPortal, NgtPortalContent],
17
})
18
export class HUD {
19
  secondaryScene = new Scene();
20
}

The portal can have its own scene, camera, and children.