VideoFrame.displayWidth — Eigenschaft · JavaScript-Referenz

Signatur

VideoFrame.displayWidth

Beschreibung

Die schreibgeschützte Eigenschaft displayWidth des VideoFrame-Interfaces liefert die Darstellungsbreite eines Videobildes. Sie berücksichtigt Seitenverhältnis-Anpassungen wie nicht-quadratische Pixel (Pixel Aspect Ratio), wie sie etwa bei anamorphotischem Videomaterial oder bei manchen Broadcast-Formaten vorkommen.

Wichtig ist die Abgrenzung zu verwandten Eigenschaften: codedWidth ist die Breite des tatsächlich codierten Pixelpuffers (oft auf Blockgrößen wie 16 aufgerundet), visibleRect.width ist die Breite des sichtbaren Ausschnitts dieses Puffers, und displayWidth ist die Breite, mit der der sichtbare Ausschnitt schließlich auf dem Bildschirm dargestellt werden soll. Bei quadratischen Pixeln sind visibleRect.width und displayWidth meist identisch.

Nutzen Sie displayWidth zusammen mit displayHeight, wenn Sie ein Frame korrekt proportioniert in ein <canvas> zeichnen, Vorschaubilder erzeugen oder die Ausgabegröße für einen VideoEncoder festlegen möchten. Der Wert kann beim Erzeugen eines Frames über die Option displayWidth im VideoFrame()-Konstruktor explizit gesetzt werden.

Rückgabewert

Typ

number

Beschreibung

Eine ganze Zahl (unsigned long) mit der Darstellungsbreite in Pixeln. Ist das Frame bereits mit close() geschlossen, wird 0 zurückgegeben.

Beispiele

Abmessungen eines Frames aus einem Canvas auslesen

const canvas = new OffscreenCanvas(640, 360);
const ctx = canvas.getContext('2d');
ctx.fillStyle = 'teal';
ctx.fillRect(0, 0, 640, 360);

const frame = new VideoFrame(canvas, { timestamp: 0 });
console.log('codedWidth:', frame.codedWidth);
console.log('displayWidth:', frame.displayWidth);
console.log('displayHeight:', frame.displayHeight);

frame.close();
console.log('nach close():', frame.displayWidth);

codedWidth: 640 displayWidth: 640 displayHeight: 360 nach close(): 0

Anamorphotisches Seitenverhältnis explizit setzen

// 720×576-Puffer (PAL), der in 16:9 dargestellt werden soll
const width = 720;
const height = 576;
const data = new Uint8Array(width * height * 4); // RGBA

const frame = new VideoFrame(data, {
  format: 'RGBA',
  codedWidth: width,
  codedHeight: height,
  displayWidth: 1024,
  displayHeight: 576,
  timestamp: 0
});

console.log(frame.visibleRect.width, '→', frame.displayWidth);
frame.close();

720 → 1024

Frame proportional korrekt in ein Canvas zeichnen

const drawFrame = (frame, canvas) => {
  // Canvas-Größe an Darstellungsmaße anpassen
  canvas.width = frame.displayWidth;
  canvas.height = frame.displayHeight;
  const ctx = canvas.getContext('2d');
  ctx.drawImage(frame, 0, 0, frame.displayWidth, frame.displayHeight);
  frame.close(); // Speicher sofort freigeben
};

const decoder = new VideoDecoder({
  output: (frame) => drawFrame(frame, document.querySelector('canvas')),
  error: (e) => console.error('Decoder-Fehler:', e)
});

// Wichtig · Fallstricke

Nicht mit codedWidth verwechseln: codedWidth kann durch Padding größer sein als das sichtbare Bild. Wer damit zeichnet, erhält verzerrte Bilder oder schwarze bzw. grüne Ränder.
Die Eigenschaft ist schreibgeschützt. Um andere Darstellungsmaße festzulegen, erzeugen Sie mit new VideoFrame(frame, { displayWidth, displayHeight }) ein neues Frame.
Geben Sie im Konstruktor displayWidth an, müssen Sie auch displayHeight setzen, sonst wird ein TypeError ausgelöst.
Nach close() liefert die Eigenschaft 0. Lesen Sie die Maße also vor dem Schließen aus.
Kompatibilität: Die WebCodecs API steht nur in sicheren Kontexten (HTTPS) zur Verfügung, außerdem in Window und Dedicated Workers. Unterstützt wird sie von Chromium-Browsern ab Version 94, von Safari ab 16.4 und von Firefox ab 130. Prüfen Sie die Unterstützung vorher mit 'VideoFrame' in globalThis.

Siehe auch

VideoFrame VideoFrame.displayHeight VideoFrame.codedWidth VideoFrame.visibleRect VideoFrame.close() VideoDecoder VideoDecoder.state