@pmndrs/pointer-events
v6.4.5
Published
framework agnostic pointer-events implementation for threejs
Downloads
8,101
Readme
pointer-events
framework agnostic pointer-events implementation for three.js
based on 🎯 Designing Pointer-events for 3D & XR
How to use
import * as THREE from 'three'
import { forwardHtmlEvents } from '@pmndrs/pointer-events'
const canvas = document.getElementById('canvas')
const scene = new THREE.Scene()
const camera = new THREE.PerspectiveCamera(70, width / height, 0.01, 10)
camera.position.z = 1
const { update } = forwardHtmlEvents(canvas, () => camera, scene)
const width = window.innerWidth,
height = window.innerHeight
const geometry = new THREE.BoxGeometry(0.2, 0.2, 0.2)
const material = new THREE.MeshBasicMaterial({ color: new THREE.Color('red') })
const mesh = new THREE.Mesh(geometry, material)
scene.add(mesh)
mesh.addEventListener('pointerover', () => material.color.set('blue'))
mesh.addEventListener('pointerout', () => material.color.set('red'))
const renderer = new THREE.WebGLRenderer({ antialias: true })
renderer.setSize(width, height)
renderer.setAnimationLoop(() => {
update()
renderer.render(scene, camera)
})
Filtering
Based on the css pointer-events
property, the behavior of pointer events can be configured with the values none
, listener
, or auto
.
object.pointerEvents = 'none'
The values none
and auto
correspond to the css properties, where none
means that an object is not directly targetted and auto
means the object is always targetted for events. The additional value listener
, which is the default value, expresses that the object is only targetted by events if the object has any listeners. In 3D scenes this default is more reasonable than auto
, which is the default in the web, because 3D scenes often contain semi-transparent content, such as particles, that should not catch pointer events by default.
In addition to the pointerEvents
property, each 3D object can also filter events based on the pointerType
with the pointerEventsType
property. This property defaults to the value all
, which expresses that pointer events from pointers of all types should be accepted. To filter specific pointer types, such as screen-mouse
, which represents a normal mouse used through a 2D screen, pointerEventsType
can be set to { allow: "screen-mouse" }
or { deny: "screen-touch" }
. pointerEventsType
's allow
and deny
accept strings and array of strings. In case more custom logic is needed, pointerEventsType
also accepts a function. In general the pointer types screen-touch
, screen-pen
, ray
, grab
, and touch
are used by default. For pointer events that were forwarded through a portal using forwardObjectEvents
, their pointerType
is prefixed with forward-
, while events forwarded from the dom to the scene are prefixed with screen-
.
But wait ... there's more
Create your own Pointer
that can represent a WebXR controller or something else. These Pointer
can use a normal Ray
for intersection, or a set of Lines
, or even a Sphere
, for grab and touch events.
Performance
In some cases multi-modal interactivity requires multiple pointers at the same time. Executing pointer.move
, such as in the following example, can lead to performance issues because the scene graph will be traversed several times.
leftGrabPointer.move()
leftTouchPointer.move()
leftRayPointer.move()
rightGrabPointer.move()
rightTouchPointer.move()
rightRayPointer.move()
In this case, performance can be improved by combining the pointer using CombinedPointer
, which will traverse the scene graph once per combined pointer, calculating the intersections for each pointer on each object.
const leftPointer = new CombinedPointer()
const rightPointer = new CombinedPointer()
leftPointer.register(leftGrabPointer)
leftPointer.register(leftTouchPointer)
leftPointer.register(leftRayPointer)
rightPointer.register(rightGrabPointer)
rightPointer.register(rightTouchPointer)
rightPointer.register(rightRayPointer)
leftPointer.move()
rightPointer.move()
Pitfalls
The pointerEvents
attribute of any Mesh/Object3D/... will not be cloned when cloning the object.