matcapTextureResource

matcapTextureResource and NgtsMatcapTexture are ports of Drei’s useMatcapTexture which load matcap textures from a repository of pre-made materials.

Matcaps (Material Captures) provide realistic lighting without actual lights in the scene by encoding lighting information directly into the texture.

Note: matcapTextureResource is not meant for production environments as it relies on third-party CDN.

Usage

Using matcapTextureResource

import { matcapTextureResource } from 'angular-three-soba/staging';

@Component({
  template: `
    @if (matcap.resource.hasValue()) {
      <ngt-mesh>
        <ngt-sphere-geometry />
        <ngt-mesh-matcap-material [matcap]="matcap.resource.value()" />
      </ngt-mesh>
    }
  `,
})
export class MatcapDemo {
  matcap = matcapTextureResource(
    () => 42, // matcap ID
    { format: () => 512 },
  );
}

Using String ID

matcap = matcapTextureResource(() => '3E2335_D36A1B_8E4A2E_2842A5');

Dynamic Matcap Selection

@Component({
  template: `
    @if (matcap.resource.hasValue()) {
      <ngt-mesh>
        <ngt-torus-geometry *args="[1, 0.4, 16, 32]" />
        <ngt-mesh-matcap-material [matcap]="matcap.resource.value()" />
      </ngt-mesh>
    }
    <p>Total matcaps available: {{ matcap.numTot() }}</p>
  `,
})
export class DynamicMatcapDemo {
  selectedId = signal(0);

  matcap = matcapTextureResource(this.selectedId, { format: () => 1024 });

  nextMatcap() {
    this.selectedId.update((id) => (id + 1) % this.matcap.numTot());
  }
}

Using NgtsMatcapTexture Directive

The structural directive provides a more declarative approach:

<ng-template [matcapTexture]="{ id: 42, format: 512 }" let-resource>
  @if (resource.hasValue()) {
    <ngt-mesh>
      <ngt-sphere-geometry />
      <ngt-mesh-matcap-material [matcap]="resource.value()" />
    </ngt-mesh>
  }
</ng-template>

With onLoad Callback

matcap = matcapTextureResource(() => 100, {
  format: () => 256,
  onLoad: (texture) => {
    console.log('Matcap loaded:', texture);
    texture.colorSpace = THREE.SRGBColorSpace;
  },
});

Available Formats

Format	Resolution	Use Case
64	64x64	Low quality, fast
128	128x128	Preview quality
256	256x256	Mobile/performance
512	512x512	Standard quality
1024	1024x1024	High quality

Notes

• The matcap repository contains hundreds of pre-made material captures
• Use numTot signal to know the total available matcaps
• Higher format numbers provide better quality but larger file sizes
• Matcaps work best for stylized, non-photorealistic rendering

Arguments

name	type	description	required
id	() => number | string	Signal containing the matcap ID (index or name from the repository). Default: () => 0	no
options.format	() => number	Signal containing texture resolution: 64, 128, 256, 512, or 1024. Default: 1024	no
options.onLoad	(texture: THREE.Texture) => void	Callback when texture loads successfully.	no
options.injector	Injector	Optional injector for dependency injection context.	no

Returns

type	description
object	An object containing texture loading state and utilities.

Properties

name	type	description
url	Signal<string>	Signal containing the resolved matcap texture URL.
resource	ResourceRef<THREE.Texture>	Resource reference for the loaded texture.
numTot	Signal<number>	Signal containing the total number of available matcaps.