Signatur
Beschreibung
Die Eigenschaft origin eines XRRay-Objekts gibt den Punkt zurück, von dem der Strahl ausgeht. Die Koordinaten x, y und z sind in Metern angegeben und beziehen sich auf den Referenzraum, in dem der Strahl verwendet wird. Die Komponente w ist immer 1, weil es sich um einen Punkt handelt und nicht um einen Richtungsvektor.
Zusammen mit XRRay.direction (ein normalisierter Richtungsvektor mit w = 0) beschreibt origin den Strahl vollständig. Verwendet wird das Objekt vor allem im WebXR Hit Test Module: Über XRSession.requestHitTestSource() mit der Option offsetRay wird festgelegt, von wo aus ein Treffertest gegen die reale Umgebung (z. B. Böden, Wände) laufen soll.
Den Wert setzt man bei der Erzeugung mit new XRRay(origin, direction) oder new XRRay(transform). Danach lässt er sich nicht mehr ändern. Die Eigenschaft ist schreibgeschützt, und auch der zurückgegebene DOMPointReadOnly ist unveränderlich. Wer einen verschobenen Strahl braucht, legt ein neues XRRay an.
Rückgabewert
x, y, z in Metern und w = 1. Ohne Angabe im Konstruktor ist der Wert {x: 0, y: 0, z: 0, w: 1}.Beispiele
Standard-Ursprung und eigener Ursprung
// Ohne Argumente: Ursprung im Nullpunkt, Richtung -Z
const standardRay = new XRRay();
console.log(standardRay.origin.x, standardRay.origin.y, standardRay.origin.z, standardRay.origin.w);
// Strahl 1,6 m über dem Boden (ungefähr Augenhöhe), Blick nach vorn
const eyeRay = new XRRay(
{ x: 0, y: 1.6, z: 0 },
{ x: 0, y: 0, z: -1 }
);
const { x, y, z, w } = eyeRay.origin;
console.log(`Ursprung: (${x}, ${y}, ${z}), w=${w}`);Hit-Test-Quelle mit versetztem Strahlursprung
const startAR = async () => {
const session = await navigator.xr.requestSession('immersive-ar', {
requiredFeatures: ['hit-test']
});
const viewerSpace = await session.requestReferenceSpace('viewer');
// Strahl 10 cm unterhalb der Kamera starten lassen, leicht nach unten geneigt
const offsetRay = new XRRay(
{ x: 0, y: -0.1, z: 0 },
{ x: 0, y: -0.5, z: -1 }
);
console.log('Strahlursprung y =', offsetRay.origin.y);
const hitTestSource = await session.requestHitTestSource({
space: viewerSpace,
offsetRay
});
return { session, hitTestSource };
};
startAR().catch((err) => console.error('AR nicht verfügbar:', err));Ursprung ist unveränderlich
const ray = new XRRay({ x: 1, y: 2, z: 3 });
// Zuweisungen werden ignoriert (im Strict Mode: TypeError)
try {
'use strict';
ray.origin.x = 99;
} catch (e) {
console.log(e.name);
}
console.log(ray.origin.x);
// Verschieben = neuen Strahl anlegen
const moved = new XRRay(
{ x: ray.origin.x + 0.5, y: ray.origin.y, z: ray.origin.z },
ray.direction
);
console.log(moved.origin.x);// Wichtig · Fallstricke
- Browser-Kompatibilität:
XRRaygehört zum WebXR Hit Test Module und wird im Wesentlichen nur von Chromium-Browsern (Chrome für Android, Edge, Samsung Internet, Meta Quest Browser) unterstützt. Firefox und Safari unterstützen es derzeit nicht. Vor der Nutzung mit'XRRay' in windowprüfen. - Die API steht nur in sicheren Kontexten (HTTPS) zur Verfügung. Hit-Tests brauchen außerdem eine
immersive-ar-Sitzung mit dem Feature'hit-test'. - Übergibt man dem Konstruktor einen Ursprung, dessen
wnicht1ist, wird einTypeErrorausgelöst. - Die Koordinaten sind relativ zum Referenzraum, in dem der Strahl eingesetzt wird (z. B.
vieweroderlocal), und keine Weltkoordinaten. Für feste Weltpositionen den passenden Referenzraum wählen. - Die Einheit ist immer Meter. Werte aus Engines, die in Zentimetern rechnen, müssen vorher umgerechnet werden.