Signatur
Beschreibung
Die Eigenschaft width eines XRQuadLayer legt fest, wie breit die rechteckige, flache Ebene in der virtuellen Szene erscheint. Die Angabe erfolgt in Metern im Koordinatensystem des Referenzraums, der beim Anlegen der Ebene über space übergeben wurde. Zusammen mit height bestimmt sie die physische Größe der Ebene. Die Pixelauflösung der Textur hängt davon nicht ab.
Quad-Ebenen eignen sich vor allem für Inhalte, die gestochen scharf aussehen müssen, etwa Text, Menüs, Videos oder 2D-Oberflächen in VR. Der Compositor zeichnet sie direkt und scharf, ohne dass sie zuerst in die Projektionsebene gerendert und neu abgetastet werden. Der Startwert kommt aus dem Feld width des XRQuadLayerInit-Objekts, das an XRWebGLBinding.createQuadLayer() übergeben wird. Fehlt die Angabe, gilt 1.0.
Die Eigenschaft ist les- und schreibbar. Ändert man sie während der Sitzung, wirkt sich das ab dem nächsten Frame aus. So lässt sich eine Ebene zum Beispiel animiert vergrößern, ohne sie neu anzulegen. Damit der Inhalt nicht verzerrt wird, sollte das Verhältnis width / height zum Verhältnis viewPixelWidth / viewPixelHeight der Textur passen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $value | number | 1.0 | Nur beim Setzen: neue Breite der Ebene in Metern. Sollte eine positive, endliche Zahl sein. |
Rückgabewert
Beispiele
Quad-Ebene mit bestimmter Breite anlegen und auslesen
const session = await navigator.xr.requestSession('immersive-vr', {
requiredFeatures: ['layers']
});
const canvas = document.createElement('canvas');
const gl = canvas.getContext('webgl2', { xrCompatible: true });
const refSpace = await session.requestReferenceSpace('local');
const binding = new XRWebGLBinding(session, gl);
// 1,6 m breite Ebene im Seitenverhältnis 16:9
const quadLayer = binding.createQuadLayer({
space: refSpace,
viewPixelWidth: 1920,
viewPixelHeight: 1080,
width: 1.6,
height: 0.9,
transform: new XRRigidTransform({ x: 0, y: 1.5, z: -2 })
});
session.updateRenderState({ layers: [quadLayer] });
console.log(`Breite: ${quadLayer.width} m`);Breite animiert ändern und Seitenverhältnis beibehalten
const aspect = quadLayer.height / quadLayer.width;
const targetWidth = 2.4;
const onFrame = (time, frame) => {
// Breite schrittweise an den Zielwert annähern
const next = quadLayer.width + (targetWidth - quadLayer.width) * 0.1;
quadLayer.width = next;
quadLayer.height = next * aspect; // keine Verzerrung
if (Math.abs(targetWidth - next) > 0.001) {
frame.session.requestAnimationFrame(onFrame);
}
};
session.requestAnimationFrame(onFrame);Breite passend zur Texturauflösung berechnen
// Ebene mit 1 m Höhe; die Breite folgt aus dem Pixelformat
const pxW = 1280;
const pxH = 720;
const height = 1.0;
const menuLayer = binding.createQuadLayer({
space: refSpace,
viewPixelWidth: pxW,
viewPixelHeight: pxH,
height,
width: height * (pxW / pxH)
});
console.log(menuLayer.width.toFixed(3));// Wichtig · Fallstricke
- Kompatibilität: Die WebXR Layers API ist experimentell. Zuverlässig unterstützt wird sie vor allem im Meta Quest Browser. In anderen Browsern fehlt sie oft oder ist nur über Flags aktivierbar. Beim Anfordern der Sitzung muss das Feature
'layers'angegeben werden, am besten alsoptionalFeaturesmit einem Ausweichweg. Der WebXR-Layers-Polyfill von Immersive Web kann fehlende Unterstützung ausgleichen. - Meter statt Pixel:
widthändert nur die Größe im Raum, nicht die Texturauflösung. Eine breitere Ebene mit gleicherviewPixelWidthwirkt deshalb unschärfer. - Verzerrung: Wenn
width / heightnicht zum Pixel-Seitenverhältnis passt, wird der Inhalt gestaucht oder gestreckt dargestellt. - Stereo: Bei
layout: 'stereo-left-right'bezieht sichwidthauf die angezeigte Ebene, nicht auf die doppelt breite Textur. - Der Maßstab hängt von
spaceundtransformab. Eine Skalierung ist überXRRigidTransformnicht möglich, deshalb istwidthder richtige Weg, die Größe zu ändern.