XRDepthInformation.height — Eigenschaft · JavaScript-Referenz

Signatur

XRDepthInformation.height

Beschreibung

Die schreibgeschützte Eigenschaft height des Interfaces XRDepthInformation gibt an, wie viele Zeilen der Tiefenpuffer hat, den das Gerät für den aktuellen Frame und die aktuelle Ansicht liefert. Zusammen mit width ergibt sich die Auflösung der Tiefenkarte.

Die Tiefenkarte ist in der Regel deutlich kleiner als die Kamera- oder Canvas-Auflösung (typisch z. B. 160×90 oder 256×192 Pixel). Mit width und height berechnet man Pufferindizes, prüft Grenzen und legt passende Texturen an, etwa in WebGL, wenn man mit XRWebGLDepthInformation arbeitet.

Ein XRDepthInformation-Objekt bekommt man bei CPU-optimierter Nutzung über XRFrame.getDepthInformation(view) und bei GPU-optimierter Nutzung über XRWebGLBinding.getDepthInformation(view). Die Session muss dafür mit dem Feature "depth-sensing" angefordert worden sein.

Wichtig: Die Puffer-Koordinaten sind normalisierte Ansichtskoordinaten und müssen mit normDepthBufferFromNormView umgerechnet werden. height gilt für den Rohpuffer, nicht unbedingt für die Ausrichtung des Bildschirms.

Rückgabewert

Typ

number

Beschreibung

Eine vorzeichenlose Ganzzahl (unsigned long): Höhe des Tiefenpuffers in Pixeln (Anzahl der Zeilen).

Beispiele

Auflösung der Tiefenkarte im Frame-Loop auslesen

const session = await navigator.xr.requestSession('immersive-ar', {
  requiredFeatures: ['depth-sensing'],
  depthSensing: {
    usagePreference: ['cpu-optimized'],
    dataFormatPreference: ['luminance-alpha', 'float32']
  }
});

const refSpace = await session.requestReferenceSpace('local');

const onFrame = (time, frame) => {
  session.requestAnimationFrame(onFrame);
  const pose = frame.getViewerPose(refSpace);
  if (!pose) return;

  for (const view of pose.views) {
    const depthInfo = frame.getDepthInformation(view);
    if (depthInfo) {
      console.log(`Tiefenpuffer: ${depthInfo.width}×${depthInfo.height}`);
    }
  }
};

session.requestAnimationFrame(onFrame);

Tiefenpuffer: 160×90

Tiefe in der Bildmitte über Pufferindizes ermitteln

// depthInfo stammt aus frame.getDepthInformation(view) (CPU-optimiert)
const mittlereTiefe = (depthInfo) => {
  const { width, height } = depthInfo;
  // Normalisierte Koordinaten (0..1) der Bildmitte
  const meter = depthInfo.getDepthInMeters(0.5, 0.5);
  console.log(`Puffer ${width}×${height}, Mitte: ${meter.toFixed(2)} m`);
  return meter;
};

Puffer 160×90, Mitte: 1.37 m

Passende WebGL-Textur für GPU-Tiefendaten anlegen

// gl: WebGL2RenderingContext, glBinding: XRWebGLBinding
const depthInfo = glBinding.getDepthInformation(view);
if (depthInfo) {
  // Seitenverhältnis der Tiefenkarte für Shader-Uniforms
  const aspect = depthInfo.width / depthInfo.height;
  gl.uniform2f(uDepthSize, depthInfo.width, depthInfo.height);
  gl.uniform1f(uDepthAspect, aspect);
  gl.activeTexture(gl.TEXTURE1);
  gl.bindTexture(gl.TEXTURE_2D, depthInfo.texture);
}

// Wichtig · Fallstricke

Experimentell: Depth Sensing wird derzeit nur von Chromium-Browsern auf Android mit ARCore-Unterstützung angeboten. Firefox und Safari unterstützen die API nicht. Außerdem ist ein sicherer Kontext (HTTPS) nötig.
Die Auflösung kann sich von Frame zu Frame ändern. Deshalb height nicht einmalig zwischenspeichern, sondern pro Frame lesen.
Das Objekt ist nur innerhalb des requestAnimationFrame-Callbacks gültig, in dem es geholt wurde. Außerhalb davon führt ein Zugriff zu einer InvalidStateError-Ausnahme.
getDepthInformation() kann null zurückgeben, wenn noch keine Tiefendaten vorliegen. Vor dem Zugriff auf height also immer prüfen.
Die Anzahl der Pixel ist nicht gleich der Anzahl der Bytes: Die Pufferlänge hängt von dataFormat ab (2 Byte bei "luminance-alpha", 4 Byte bei "float32").

Siehe auch

XRDepthInformation XRDepthInformation.width XRDepthInformation.normDepthBufferFromNormView XRDepthInformation.rawValueToMeters XRCPUDepthInformation.getDepthInMeters() XRFrame.getDepthInformation() XRWebGLBinding.getDepthInformation()