From 5f8de423f190bbb79a62f804151bc24824fa32d8 Mon Sep 17 00:00:00 2001 From: "Matt A. Tobin" Date: Fri, 2 Feb 2018 04:16:08 -0500 Subject: Add m-esr52 at 52.6.0 --- dom/webidl/ImageBitmap.webidl | 412 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 412 insertions(+) create mode 100644 dom/webidl/ImageBitmap.webidl (limited to 'dom/webidl/ImageBitmap.webidl') diff --git a/dom/webidl/ImageBitmap.webidl b/dom/webidl/ImageBitmap.webidl new file mode 100644 index 000000000..3cfabff12 --- /dev/null +++ b/dom/webidl/ImageBitmap.webidl @@ -0,0 +1,412 @@ +/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ +/* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this file, + * You can obtain one at http://mozilla.org/MPL/2.0/. + * + * The origin of this IDL file is + * https://html.spec.whatwg.org/multipage/webappapis.html#images + * + * The origin of the extended IDL file is + * http://w3c.github.io/mediacapture-worker/#imagebitmap-extensions + */ + +// Extensions +// Bug 1141979 - [FoxEye] Extend ImageBitmap with interfaces to access its +// underlying image data +// +// Note: +// Our overload resolution implementation doesn't deal with a union as the +// distinguishing argument which means we cannot overload functions via union +// types, a.k.a. we cannot overload createImageBitmap() via ImageBitmapSource +// and BufferSource. Here, we work around this issue by adding the BufferSource +// into ImageBitmapSource. + +typedef (HTMLImageElement or + HTMLVideoElement or + HTMLCanvasElement or + Blob or + ImageData or + CanvasRenderingContext2D or + ImageBitmap or + BufferSource) ImageBitmapSource; + +[Exposed=(Window,Worker)] +interface ImageBitmap { + [Constant] + readonly attribute unsigned long width; + [Constant] + readonly attribute unsigned long height; +}; + +// It's crucial that there be a way to explicitly dispose of ImageBitmaps +// since they refer to potentially large graphics resources. Some uses +// of this API proposal will result in repeated allocations of ImageBitmaps, +// and garbage collection will not reliably reclaim them quickly enough. +// Here we reuse close(), which also exists on another Transferable type, +// MessagePort. Potentially, all Transferable types should inherit from a +// new interface type "Closeable". +partial interface ImageBitmap { + // Dispose of all graphical resources associated with this ImageBitmap. + void close(); +}; + +// ImageBitmap-extensions +// Bug 1141979 - [FoxEye] Extend ImageBitmap with interfaces to access its +// underlying image data + +/* + * An image or a video frame is conceptually a two-dimensional array of data and + * each element in the array is called a pixel. The pixels are usually stored in + * a one-dimensional array and could be arranged in a variety of image formats. + * Developers need to know how the pixels are formatted so that they are able to + * process them. + * + * The image format describes how pixels in an image are arranged. A single + * pixel has at least one, but usually multiple pixel values. The range of a + * pixel value varies, which means different image formats use different data + * types to store a single pixel value. + * + * The most frequently used data type is 8-bit unsigned integer whose range is + * from 0 to 255, others could be 16-bit integer or 32-bit floating points and + * so forth. The number of pixel values of a single pixel is called the number + * of channels of the image format. Multiple pixel values of a pixel are used + * together to describe the captured property which could be color or depth + * information. For example, if the data is a color image in RGB color space, + * then it is a three-channel image format and a pixel is described by R, G and + * B three pixel values with range from 0 to 255. As another example, if the + * data is a gray image, then it is a single-channel image format with 8-bit + * unsigned integer data type and the pixel value describes the gray scale. For + * depth data, it is a single channel image format too, but the data type is + * 16-bit unsigned integer and the pixel value is the depth level. + * + * For those image formats whose pixels contain multiple pixel values, the pixel + * values might be arranged in one of the following ways: + * 1) Planar pixel layout: + * each channel has its pixel values stored consecutively in separated + * buffers (a.k.a. planes) and then all channel buffers are stored + * consecutively in memory. + * (Ex: RRRRRR......GGGGGG......BBBBBB......) + * 2) Interleaving pixel layout: + * each pixel has its pixel values from all channels stored together and + * interleaves all channels. + * (Ex: RGBRGBRGBRGBRGB......) + */ + + +/* + * The ImageBitmap extensions use this enumeration to negotiate the image format + * while 1) accessing the underlying data of an ImageBitmap and + * 2) creating a new ImageBitmap. + * + * For each format in this enumeration, we use a 2x2 small image (4 pixels) as + * example to illustrate the pixel layout. + * + * 2x2 image: +--------+--------+ + * | pixel1 | pixel2 | + * +--------+--------+ + * | pixel3 | pixel4 | + * +--------+--------+ + * + */ +enum ImageBitmapFormat { + /* + * Channel order: R, G, B, A + * Channel size: full rgba-chennels + * Pixel layout: interleaving rgba-channels + * Pixel layout illustration: + * [Plane1]: R1 G1 B1 A1 R2 G2 B2 A2 R3 G3 B3 A3 R4 G4 B4 A4 + * Data type: 8-bit unsigned integer + */ + "RGBA32", + + /* + * Channel order: B, G, R, A + * Channel size: full bgra-channels + * Pixel layout: interleaving bgra-channels + * Pixel layout illustration: + * [Plane1]: B1 G1 R1 A1 B2 G2 R2 A2 B3 G3 R3 A3 B4 G4 R4 A4 + * Data type: 8-bit unsigned integer + */ + "BGRA32", + + /* + * Channel order: R, G, B + * Channel size: full rgb-channels + * Pixel layout: interleaving rgb-channels + * Pixel layout illustration: + * [Plane1]: R1 G1 B1 R2 G2 B2 R3 G3 B3 R4 G4 B4 + * Data type: 8-bit unsigned integer + */ + "RGB24", + + /* + * Channel order: B, G, R + * Channel size: full bgr-channels + * Pixel layout: interleaving bgr-channels + * Pixel layout illustration: + * [Plane1]: B1 G1 R1 B2 G2 R2 B3 G3 R3 B4 G4 R4 + * Data type: 8-bit unsigned integer + */ + "BGR24", + + /* + * Channel order: GRAY + * Channel size: full gray-channel + * Pixel layout: planar gray-channel + * Pixel layout illustration: + * [Plane1]: GRAY1 GRAY2 GRAY3 GRAY4 + * Data type: 8-bit unsigned integer + */ + "GRAY8", + + /* + * Channel order: Y, U, V + * Channel size: full yuv-channels + * Pixel layout: planar yuv-channels + * Pixel layout illustration: + * [Plane1]: Y1 Y2 Y3 Y4 + * [Plane2]: U1 U2 U3 U4 + * [Plane3]: V1 V2 V3 V4 + * Data type: 8-bit unsigned integer + */ + "YUV444P", + + /* + * Channel order: Y, U, V + * Channel size: full y-channel, half uv-channels + * Pixel layout: planar yuv-channels + * Pixel layout illustration: + * [Plane1]: Y1 Y2 Y3 Y4 + * [Plane2]: U1 U3 + * [Plane3]: V1 V3 + * Data type: 8-bit unsigned integer + */ + "YUV422P", + + /* + * Channel order: Y, U, V + * Channel size: full y-channel, quarter uv-channels + * Pixel layout: planar yuv-channels + * Pixel layout illustration: + * [Plane1]: Y1 Y2 Y3 Y4 + * [Plane2]: U1 + * [Plane3]: V1 + * Data type: 8-bit unsigned integer + */ + "YUV420P", + + /* + * Channel order: Y, U, V + * Channel size: full y-channel, quarter uv-channels + * Pixel layout: planar y-channel, interleaving uv-channels + * Pixel layout illustration: + * [Plane1]: Y1 Y2 Y3 Y4 + * [Plane2]: U1 V1 + * Data type: 8-bit unsigned integer + */ + "YUV420SP_NV12", + + /* + * Channel order: Y, V, U + * Channel size: full y-channel, quarter vu-channels + * Pixel layout: planar y-channel, interleaving vu-channels + * Pixel layout illustration: + * [Plane1]: Y1 Y2 Y3 Y4 + * [Plane2]: V1 U1 + * Data type: 8-bit unsigned integer + */ + "YUV420SP_NV21", + + /* + * Channel order: H, S, V + * Channel size: full hsv-channels + * Pixel layout: interleaving hsv-channels + * Pixel layout illustration: + * [Plane1]: H1 S1 V1 H2 S2 V2 H3 S3 V3 + * Data type: 32-bit floating point value + */ + "HSV", + + /* + * Channel order: l, a, b + * Channel size: full lab-channels + * Pixel layout: interleaving lab-channels + * Pixel layout illustration: + * [Plane1]: l1 a1 b1 l2 a2 b2 l3 a3 b3 + * Data type: 32-bit floating point value + */ + "Lab", + + /* + * Channel order: DEPTH + * Channel size: full depth-channel + * Pixel layout: planar depth-channel + * Pixel layout illustration: + * [Plane1]: DEPTH1 DEPTH2 DEPTH3 DEPTH4 + * Data type: 16-bit unsigned integer + */ + "DEPTH", +}; + +enum ChannelPixelLayoutDataType { + "uint8", + "int8", + "uint16", + "int16", + "uint32", + "int32", + "float32", + "float64" +}; + +/* + * Two concepts, ImagePixelLayout and ChannelPixelLayout, together generalize + * the variety of pixel layouts among image formats. + * + * The ChannelPixelLayout represents the pixel layout of a single channel in a + * certain image format and the ImagePixelLayout is just the collection of + * ChannelPixelLayouts. So, the ChannelPixelLayout is defined as a dictionary + * type with properties to describe the layout and the ImagePixelLayout is just + * an alias name to a sequence of ChannelPixelLayout objects. + * + * Since an image format is composed of at least one channel, an + * ImagePixelLayout object contains at least one ChannelPixelLayout object. + * + * Although an image or a video frame is a two-dimensional structure, its data + * is usually stored in a one-dimensional array in the row-major way and the + * ChannelPixelLayout objects use the following properties to describe the + * layout of pixel values in the buffer. + * + * 1) offset: + * denotes the beginning position of the channel's data relative to the + * beginning position of the one-dimensional array. + * 2) width & height: + * denote the width and height of the channel respectively. Each channel in + * an image format may have different height and width. + * 3) data type: + * denotes the format used to store one single pixel value. + * 4) stride: + * the number of bytes between the beginning two consecutive rows in memory. + * (The total bytes of each row plus the padding bytes of each raw.) + * 5) skip value: + * the value is zero for the planar pixel layout, and a positive integer for + * the interleaving pixel layout. (Describes how many bytes there are between + * two adjacent pixel values in this channel.) + */ + +/* + * Example1: RGBA image, width = 620, height = 480, stride = 2560 + * + * chanel_r: offset = 0, width = 620, height = 480, data type = uint8, stride = 2560, skip = 3 + * chanel_g: offset = 1, width = 620, height = 480, data type = uint8, stride = 2560, skip = 3 + * chanel_b: offset = 2, width = 620, height = 480, data type = uint8, stride = 2560, skip = 3 + * chanel_a: offset = 3, width = 620, height = 480, data type = uint8, stride = 2560, skip = 3 + * + * <---------------------------- stride ----------------------------> + * <---------------------- width x 4 ----------------------> + * [index] 01234 8 12 16 20 24 28 2479 2559 + * |||||---|---|---|---|---|---|----------------------------|-------| + * [data] RGBARGBARGBARGBARGBAR___R___R... A%%%%%%%% + * [data] RGBARGBARGBARGBARGBAR___R___R... A%%%%%%%% + * [data] RGBARGBARGBARGBARGBAR___R___R... A%%%%%%%% + * ^^^ + * r-skip + */ + +/* + * Example2: YUV420P image, width = 620, height = 480, stride = 640 + * + * chanel_y: offset = 0, width = 620, height = 480, stride = 640, skip = 0 + * chanel_u: offset = 307200, width = 310, height = 240, data type = uint8, stride = 320, skip = 0 + * chanel_v: offset = 384000, width = 310, height = 240, data type = uint8, stride = 320, skip = 0 + * + * <--------------------------- y-stride ---------------------------> + * <----------------------- y-width -----------------------> + * [index] 012345 619 639 + * ||||||--------------------------------------------------|--------| + * [data] YYYYYYYYYYYYYYYYYYYYYYYYYYYYY... Y%%%%%%%%% + * [data] YYYYYYYYYYYYYYYYYYYYYYYYYYYYY... Y%%%%%%%%% + * [data] YYYYYYYYYYYYYYYYYYYYYYYYYYYYY... Y%%%%%%%%% + * [data] ...... + * <-------- u-stride ----------> + * <----- u-width -----> + * [index] 307200 307509 307519 + * |-------------------|--------| + * [data] UUUUUUUUUU... U%%%%%%%%% + * [data] UUUUUUUUUU... U%%%%%%%%% + * [data] UUUUUUUUUU... U%%%%%%%%% + * [data] ...... + * <-------- v-stride ----------> + * <- --- v-width -----> + * [index] 384000 384309 384319 + * |-------------------|--------| + * [data] VVVVVVVVVV... V%%%%%%%%% + * [data] VVVVVVVVVV... V%%%%%%%%% + * [data] VVVVVVVVVV... V%%%%%%%%% + * [data] ...... + */ + +/* + * Example3: YUV420SP_NV12 image, width = 620, height = 480, stride = 640 + * + * chanel_y: offset = 0, width = 620, height = 480, stride = 640, skip = 0 + * chanel_u: offset = 307200, width = 310, height = 240, data type = uint8, stride = 640, skip = 1 + * chanel_v: offset = 307201, width = 310, height = 240, data type = uint8, stride = 640, skip = 1 + * + * <--------------------------- y-stride --------------------------> + * <----------------------- y-width ----------------------> + * [index] 012345 619 639 + * ||||||-------------------------------------------------|--------| + * [data] YYYYYYYYYYYYYYYYYYYYYYYYYYYYY... Y%%%%%%%%% + * [data] YYYYYYYYYYYYYYYYYYYYYYYYYYYYY... Y%%%%%%%%% + * [data] YYYYYYYYYYYYYYYYYYYYYYYYYYYYY... Y%%%%%%%%% + * [data] ...... + * <--------------------- u-stride / v-stride --------------------> + * <------------------ u-width + v-width -----------------> + * [index] 307200(u-offset) 307819 307839 + * |------------------------------------------------------|-------| + * [index] |307201(v-offset) |307820 | + * ||-----------------------------------------------------||------| + * [data] UVUVUVUVUVUVUVUVUVUVUVUVUVUVUV... UV%%%%%%% + * [data] UVUVUVUVUVUVUVUVUVUVUVUVUVUVUV... UV%%%%%%% + * [data] UVUVUVUVUVUVUVUVUVUVUVUVUVUVUV... UV%%%%%%% + * ^ ^ + * u-skip v-skip + */ + +/* + * Example4: DEPTH image, width = 640, height = 480, stride = 1280 + * + * chanel_d: offset = 0, width = 640, height = 480, data type = uint16, stride = 1280, skip = 0 + * + * note: each DEPTH value uses two bytes + * + * <----------------------- d-stride ----------------------> + * <----------------------- d-width -----------------------> + * [index] 02468 1278 + * |||||---------------------------------------------------| + * [data] DDDDDDDDDDDDDDDDDDDDDDDDDDDDD... D + * [data] DDDDDDDDDDDDDDDDDDDDDDDDDDDDD... D + * [data] DDDDDDDDDDDDDDDDDDDDDDDDDDDDD... D + * [data] ...... + */ + +dictionary ChannelPixelLayout { + required unsigned long offset; + required unsigned long width; + required unsigned long height; + required ChannelPixelLayoutDataType dataType; + required unsigned long stride; + required unsigned long skip; +}; + +typedef sequence ImagePixelLayout; + +partial interface ImageBitmap { + [Throws, Func="mozilla::dom::ImageBitmap::ExtensionsEnabled"] + ImageBitmapFormat findOptimalFormat (optional sequence aPossibleFormats); + [Throws, Func="mozilla::dom::ImageBitmap::ExtensionsEnabled"] + long mappedDataLength (ImageBitmapFormat aFormat); + [Throws, Func="mozilla::dom::ImageBitmap::ExtensionsEnabled"] + Promise mapDataInto (ImageBitmapFormat aFormat, BufferSource aBuffer, long aOffset); +}; -- cgit v1.2.3