<Mask>

Masks use the stencil buffer to cut out areas of the screen. This component is a port of drei’s <Mask> component.

The Mask component requires Three.js to render with a stencil buffer. As of r163, stencil is set to false by default. To enable the stencil buffer, set it in your canvas’s renderer: <Canvas createRenderer={(canvas)=>{return new WebGLRenderer({canvas,stencil: true })}}>. In prior versions the default is true already.

1
<script lang="ts">
2
  import { Canvas } from '@threlte/core'
3
  import Scene from './Scene.svelte'
4
  import { WebGLRenderer } from 'three'
5
</script>
6

7
<div>
8
  <Canvas
9
    createRenderer={(canvas) => {
10
      return new WebGLRenderer({ canvas, stencil: true })
11
    }}
12
  >
13
    <Scene />
14
  </Canvas>
15
</div>
16

17
<style>
18
  div {
19
    height: 100%;
20
  }
21
</style>

1
<script lang="ts">
2
  import { T } from '@threlte/core'
3
  import { OrbitControls, Grid, Float, TransformControls, Mask, useMask } from '@threlte/extras'
4
  import { Pane, Checkbox, List } from 'svelte-tweakpane-ui'
5

6
  let inverse = $state(true)
7
  let move = $state(false)
8
  let id = $state<1 | 2 | 3>(1)
9

10
  const torusStencil = $derived(useMask(1, inverse))
11
  const boxStencil = $derived(useMask(2, inverse))
12
  const icoStencil = $derived(useMask(3, inverse))
13
</script>
14

15
<Pane
16
  title="Mask"
17
  position="fixed"
18
>
19
  <Checkbox
20
    bind:value={inverse}
21
    label="inverse"
22
  />
23
  <List
24
    bind:value={id}
25
    label="target"
26
    options={{ torus: 1, box: 2, ico: 3 }}
27
  />
28
  <Checkbox
29
    bind:value={move}
30
    label="move"
31
  />
32
</Pane>
33

34
<T.PerspectiveCamera
35
  makeDefault
36
  position={[3, 4, 15]}
37
  fov={15}
38
>
39
  <OrbitControls
40
    enableDamping
41
    target={[0, 0.5, 0]}
42
  />
43
</T.PerspectiveCamera>
44

45
<T.Group position={[0, 1, 2]}>
46
  {#snippet children({ ref })}
47
    <Mask {id}>
48
      <T.CircleGeometry args={[0.65]} />
49
      <T.MeshBasicMaterial />
50
    </Mask>
51
    <T.Mesh>
52
      <T.RingGeometry args={[0.6, 0.7, 50]} />
53
      <T.MeshBasicMaterial />
54
    </T.Mesh>
55
    {#if move}
56
      <TransformControls
57
        object={ref}
58
        showZ={false}
59
      />
60
    {/if}
61
  {/snippet}
62
</T.Group>
63

64
<T.DirectionalLight
65
  intensity={3}
66
  position.x={5}
67
  position.y={10}
68
/>
69
<T.AmbientLight intensity={0.6} />
70

71
<Grid
72
  gridSize={[8, 8]}
73
  cellColor="#46536b"
74
  position.y={-0.3}
75
  sectionThickness={0}
76
  fadeDistance={50}
77
/>
78

79
<Float
80
  floatIntensity={1}
81
  floatingRange={[0, 1]}
82
>
83
  <T.Mesh position={[0, 0.3, 0]}>
84
    <T.TorusKnotGeometry args={[0.5, 0.15, 100, 12, 2, 3]} />
85
    <T.MeshStandardMaterial
86
      color="#F85122"
87
      {...torusStencil}
88
    />
89
  </T.Mesh>
90
</Float>
91

92
<Float
93
  floatIntensity={1}
94
  floatingRange={[0, 0.5]}
95
>
96
  <T.Mesh
97
    position.y={0.5}
98
    position={[-1.5, 0, -2]}
99
  >
100
    <T.BoxGeometry />
101
    <T.MeshStandardMaterial
102
      color="#0059BA"
103
      {...boxStencil}
104
    />
105
  </T.Mesh>
106
</Float>
107

108
<Float
109
  floatIntensity={1}
110
  floatingRange={[0, 0.5]}
111
>
112
  <T.Mesh
113
    position={[1.5, 0.3, -2]}
114
    scale={0.8}
115
  >
116
    <T.IcosahedronGeometry />
117
    <T.MeshStandardMaterial
118
      color="#F8EBCE"
119
      {...icoStencil}
120
    />
121
  </T.Mesh>
122
</Float>

First you need to define a mask, give it the shape that you want.

1
<Mask id={1}>
2
  <T.PlaneGeometry />
3
  <T.MeshBasicMaterial />
4
</Mask>

Now refer to it with the useMask hook and the same id, your content will now be masked out by the geometry defined above.

1
<script lang="ts">
2
  import { useMask } from '@threlte/extras'
3
  const stencil = useMask(1)
4
</script>
5

6
<T.Mesh>
7
  <T.TorusKnotGeometry />
8
  <T.MeshStandardMaterial {...stencil} />
9
</T.Mesh>

You can build compound masks with multiple shapes by re-using an id. You can also use the mask as a normal mesh by providing colorWrite and depthWrite props.

1
<Mask
2
  position={[-1, 0, 0]}
3
  id={1}
4
>
5
  <T.PlaneGeometry />
6
  <T.MeshBasicMaterial />
7
</Mask>
8
<Mask
9
  colorWrite
10
  depthWrite
11
  position={[1, 0, 0]}
12
  id={1}
13
>
14
  <T.CircleGeometry />
15
  <T.MeshBasicMaterial />
16
</Mask>

Invert masks individually by providing a 2nd boolean argument to the useMask hook.

1
const stencil = useMask(1, true)

Component Signature

<Mask> extends < T . Mesh > and supports all its props, snippets, bindings and events.

Props

name

type

required

default

description

colorWrite

boolean

false

If colors of the masks own material will leak through.

depthWrite

boolean

false

If depth of the masks own material will leak through.

number

1

Each mask must have an id, you can have compound masks referring to the same id.