mask.mdx

title	sourcecode
Mask	src/core/Mask.tsx

Masks use the stencil buffer to cut out areas of the screen. This is usually cheaper as it doesn't require double renders or createPortal.

<Mask
  /** Each mask must have an id, you can have compound masks referring to the same id */
  id: number
  /** If colors of the masks own material will leak through, default: false */
  colorWrite?: boolean
  /** If depth  of the masks own material will leak through, default: false */
  depthWrite?: boolean
/>

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

<Mask id={1}>
  <planeGeometry />
  <meshBasicMaterial />
</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.

const stencil = useMask(1)
return (
  <mesh>
    <torusKnotGeometry />
    <meshStandardMaterial {...stencil} />

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.

<Mask position={[-1, 0, 0]} id={1}>
  <planeGeometry />
  <meshBasicMaterial />
</Mask>
<Mask colorWrite depthWrite position={[1, 0, 0]} id={1}>
  <circleGeometry />
  <meshBasicMaterial />
</Mask>

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

const stencil = useMask(1, true)