three-projected-material

To use ProjectedMaterial with InstancedMesh, you must follow a specific workflow to prepare the geometry and individual instances:

1. Prepare Geometry: Call allocateProjectionData(geometry, instancesCount) on the geometry intended for the InstancedMesh. This must be done before calling projectInstanceAt.
2. Project Instances: Use material.projectInstanceAt(index, instancedMesh, matrix) to project onto a specific instance.
3. Matrix Update: Ensure you call matrix.updateMatrix() on your dummy/transform object before passing it to projectInstanceAt.

// 1. Prepare
allocateProjectionData(geometry, instancesCount)

// 2. Project
dummy.updateMatrix()
material.projectInstanceAt(i, instancedMesh, dummy.matrix)

You can use the library from a CDN. Ensure you use a three.js import map in your HTML.

<script type="importmap">
  {
    "imports": {
      "three": "https://unpkg.com/three/build/three.module.js"
    }
  }
</script>
<script type="module">
  import ProjectedMaterial from 'https://unpkg.com/three-projected-material/build/ProjectedMaterial.module.js'
  // ...
</script>

Import the material and apply it to a Three.js mesh. After setting up the mesh and camera, call material.project(mesh) to capture the current spatial relationship between the camera and the mesh for the projection.

import ProjectedMaterial from 'three-projected-material'

const geometry = new THREE.BoxGeometry(1, 1, 1)
const material = new ProjectedMaterial({
  camera, // the camera that acts as a projector
  texture, // the texture being projected
  textureScale: 0.8,
  textureOffset: new THREE.Vector2(0.1, 0.1),
  cover: true,
  color: '#ccc',
  roughness: 0.3,
})
const box = new THREE.Mesh(geometry, material)
webgl.scene.add(box)

// move the mesh any way you want!
box.rotation.y = -Math.PI / 4

// and when you're ready project the texture on the box!
material.project(box)

Install the package via npm or yarn after having installed three.js.

npm install three-projected-material
# or
yarn add three-projected-material

Methods for handling projection data in instanced scenarios.

### allocateProjectionData(geometry, instancesCount)
Allocate the data used when projecting on an `InstancedMesh`. Must be called before `.projectInstanceAt()`.
- `geometry`: The geometry passed to the `InstancedMesh`.
- `instancesCount`: The number of instances (must match `InstancedMesh`).

### material.projectInstanceAt(index, instancedMesh, matrix)
Performs projection for a specific instance in an `InstancedMesh`.
- `index`: The index of the instanced element.
- `instancedMesh`: The `InstancedMesh` using a `ProjectedMaterial`.
- `matrix`: The matrix of the element (ensure `.updateMatrix()` was called on the source object).

The ProjectedMaterial exposes a uniforms object used by the underlying shader. These values are updated by the class methods during the projection process.

uniforms: {
  projectedTexture: { value: Texture }
  isTextureLoaded: { value: boolean }
  isTextureProjected: { value: boolean }
  backgroundOpacity: { value: number }
  viewMatrixCamera: { value: Matrix4 }
  projectionMatrixCamera: { value: Matrix4 }
  projPosition: { value: Vector3 }
  projDirection: { value: Vector3 }
  savedModelMatrix: { value: Matrix4 }
  widthScaled: { value: number }
  heightScaled: { value: number }
  textureOffset: { value: Vector2 }
}

Use the project(mesh: Mesh) method to prepare a specific mesh to receive the projected texture from the material's camera.

material.project(myMesh);

Use the allocateProjectionData(geometry, instancesCount) function to prepare the necessary buffer data for projection. This is required when working with geometries that will be used with projected materials, especially in instanced scenarios.

import { allocateProjectionData } from 'three-projected-material';

allocateProjectionData(myBufferGeometry, 100);

To project a specific instance within an InstancedMesh, use projectInstanceAt. This method requires the index of the instance, the InstancedMesh itself, and the world matrix of that instance.

Parameters:

• index: The index of the instance to project.
• instancedMesh: The InstancedMesh containing the instance.
• matrixWorld: The Matrix4 representing the instance's world transform.
• options (optional): An object containing forceCameraSave (boolean) to force the camera state to be saved.

material.projectInstanceAt(
  0, 
  myInstancedMesh, 
  instanceMatrix, 
  { forceCameraSave: true }
);