dom/webidl/VideoFrame.webidl

   1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
   4  * You can obtain one at http://mozilla.org/MPL/2.0/.
   5  *
   6  * The origin of this IDL file is
   7  * https://w3c.github.io/webcodecs/#videoframe
   8  */
   9
  10 enum AlphaOption {
  11   "keep",
  12   "discard",
  13 };
  14
  15 // [Serializable, Transferable] are implemented without adding attributes here.
  16 [Exposed=(Window,DedicatedWorker), Pref="dom.media.webcodecs.enabled"]
  17 interface VideoFrame {
  18   // The constructors should be shorten to:
  19   //   ```
  20   //   constructor([AllowShared] BufferSource data, VideoFrameBufferInit init);
  21   //   constructor(CanvasImageSource image, optional VideoFrameInit init = {});
  22   //   ```
  23   // However, `[AllowShared] BufferSource` doesn't work for now (bug 1696216), and
  24   // `No support for unions as distinguishing arguments yet` error occurs when using
  25   //   `constructor(CanvasImageSource image, optional VideoFrameInit init = {})` and
  26   //   `constructor(([AllowShared] ArrayBufferView or [AllowShared] ArrayBuffer) data, VideoFrameBufferInit init)`
  27   // at the same time (bug 1786410).
  28   [Throws]
  29   constructor(HTMLImageElement imageElement, optional VideoFrameInit init = {});
  30   [Throws]
  31   constructor(SVGImageElement svgImageElement, optional VideoFrameInit init = {});
  32   [Throws]
  33   constructor(HTMLCanvasElement canvasElement, optional VideoFrameInit init = {});
  34   [Throws]
  35   constructor(HTMLVideoElement videoElement, optional VideoFrameInit init = {});
  36   [Throws]
  37   constructor(OffscreenCanvas offscreenCanvas, optional VideoFrameInit init = {});
  38   [Throws]
  39   constructor(ImageBitmap imageBitmap, optional VideoFrameInit init = {});
  40   [Throws]
  41   constructor(VideoFrame videoFrame, optional VideoFrameInit init = {});
  42   [Throws]
  43   constructor([AllowShared] ArrayBufferView bufferView, VideoFrameBufferInit init);
  44   [Throws]
  45   constructor([AllowShared] ArrayBuffer buffer, VideoFrameBufferInit init);
  46
  47
  48   readonly attribute VideoPixelFormat? format;
  49   readonly attribute unsigned long codedWidth;
  50   readonly attribute unsigned long codedHeight;
  51   readonly attribute DOMRectReadOnly? codedRect;
  52   readonly attribute DOMRectReadOnly? visibleRect;
  53   readonly attribute unsigned long displayWidth;
  54   readonly attribute unsigned long displayHeight;
  55   readonly attribute unsigned long long? duration;  // microseconds
  56   readonly attribute long long timestamp;           // microseconds
  57   readonly attribute VideoColorSpace colorSpace;
  58
  59   [Throws]
  60   unsigned long allocationSize(
  61       optional VideoFrameCopyToOptions options = {});
  62   [Throws]
  63   Promise<sequence<PlaneLayout>> copyTo(
  64       // bug 1696216: Should be `copyTo([AllowShared] BufferSource destination, ...)`
  65       ([AllowShared] ArrayBufferView or [AllowShared] ArrayBuffer) destination,
  66       optional VideoFrameCopyToOptions options = {});
  67   [Throws]
  68   VideoFrame clone();
  69   undefined close();
  70 };
  71
  72 dictionary VideoFrameInit {
  73   unsigned long long duration;  // microseconds
  74   long long timestamp;          // microseconds
  75   AlphaOption alpha = "keep";
  76
  77   // Default matches image. May be used to efficiently crop. Will trigger
  78   // new computation of displayWidth and displayHeight using image’s pixel
  79   // aspect ratio unless an explicit displayWidth and displayHeight are given.
  80   DOMRectInit visibleRect;
  81
  82   // Default matches image unless visibleRect is provided.
  83   [EnforceRange] unsigned long displayWidth;
  84   [EnforceRange] unsigned long displayHeight;
  85 };
  86
  87 dictionary VideoFrameBufferInit {
  88   required VideoPixelFormat format;
  89   required [EnforceRange] unsigned long codedWidth;
  90   required [EnforceRange] unsigned long codedHeight;
  91   required [EnforceRange] long long timestamp;  // microseconds
  92   [EnforceRange] unsigned long long duration;   // microseconds
  93
  94   // Default layout is tightly-packed.
  95   sequence<PlaneLayout> layout;
  96
  97   // Default visible rect is coded size positioned at (0,0)
  98   DOMRectInit visibleRect;
  99
 100   // Default display dimensions match visibleRect.
 101   [EnforceRange] unsigned long displayWidth;
 102   [EnforceRange] unsigned long displayHeight;
 103
 104   VideoColorSpaceInit colorSpace;
 105 };
 106
 107 dictionary VideoFrameCopyToOptions {
 108   DOMRectInit rect;
 109   sequence<PlaneLayout> layout;
 110 };
 111
 112 dictionary PlaneLayout {
 113   // TODO: https://github.com/w3c/webcodecs/pull/488
 114   required [EnforceRange] unsigned long offset;
 115   required [EnforceRange] unsigned long stride;
 116 };
 117
 118 enum VideoPixelFormat {
 119   // 4:2:0 Y, U, V
 120   "I420",
 121   // 4:2:0 Y, U, V, A
 122   "I420A",
 123   // 4:2:2 Y, U, V
 124   "I422",
 125   // 4:4:4 Y, U, V
 126   "I444",
 127   // 4:2:0 Y, UV
 128   "NV12",
 129   // 32bpp RGBA
 130   "RGBA",
 131   // 32bpp RGBX (opaque)
 132   "RGBX",
 133   // 32bpp BGRA
 134   "BGRA",
 135   // 32bpp BGRX (opaque)
 136   "BGRX",
 137 };