image/public/imgIEncoder.idl@b8a032363ba2 (annotated)
image/public/imgIEncoder.idl
Thu, 22 Jan 2015 13:21:57 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Thu, 22 Jan 2015 13:21:57 +0100
- branch
- TOR_BUG_9701
- changeset 15
- b8a032363ba2
- permissions
- -rw-r--r--
Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6
| michael@0 | 1 | /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- |
| michael@0 | 2 | * This Source Code Form is subject to the terms of the Mozilla Public |
| michael@0 | 3 | * License, v. 2.0. If a copy of the MPL was not distributed with this |
| michael@0 | 4 | * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ |
| michael@0 | 5 | |
| michael@0 | 6 | #include "nsISupports.idl" |
| michael@0 | 7 | #include "nsIAsyncInputStream.idl" |
| michael@0 | 8 | #include "nsIEventTarget.idl" |
| michael@0 | 9 | |
| michael@0 | 10 | /** |
| michael@0 | 11 | * imgIEncoder interface |
| michael@0 | 12 | */ |
| michael@0 | 13 | [scriptable, uuid(4baa2d6e-fee7-42df-ae3f-5fbebc0c267c)] |
| michael@0 | 14 | interface imgIEncoder : nsIAsyncInputStream |
| michael@0 | 15 | { |
| michael@0 | 16 | // Possible values for outputOptions. Multiple values are semicolon-separated. |
| michael@0 | 17 | // |
| michael@0 | 18 | // PNG: |
| michael@0 | 19 | // ---- |
| michael@0 | 20 | // transparency=[yes|no|none] -- default: "yes" |
| michael@0 | 21 | // Overrides default from input format. "no" and "none" are equivalent. |
| michael@0 | 22 | // |
| michael@0 | 23 | // |
| michael@0 | 24 | // APNG: |
| michael@0 | 25 | // ----- |
| michael@0 | 26 | // The following options can be used with startImageEncode(): |
| michael@0 | 27 | // |
| michael@0 | 28 | // transparency=[yes|no|none] -- default: "yes" |
| michael@0 | 29 | // Overrides default from input format. "no" and "none" are equivalent. |
| michael@0 | 30 | // skipfirstframe=[yes|no] -- default: "no" |
| michael@0 | 31 | // Controls display of the first frame in animations. PNG-only clients always |
| michael@0 | 32 | // display the first frame (and only that frame). |
| michael@0 | 33 | // frames=# -- default: "1" |
| michael@0 | 34 | // Total number of frames in the image. The first frame, even if skipped, is |
| michael@0 | 35 | // always included in the count. |
| michael@0 | 36 | // plays=# -- default: "0" |
| michael@0 | 37 | // Number of times to play the animation sequence. "0" will repeat forever. |
| michael@0 | 38 | // |
| michael@0 | 39 | // |
| michael@0 | 40 | // The following options can be used for each frame, with addImageFrame(): |
| michael@0 | 41 | // |
| michael@0 | 42 | // transparency=[yes|no|none] -- default: "yes" |
| michael@0 | 43 | // Overrides default from input format. "no" and "none" are equivalent. |
| michael@0 | 44 | // delay=# -- default: "500" |
| michael@0 | 45 | // Number of milliseconds to display the frame, before moving to the next frame. |
| michael@0 | 46 | // dispose=[none|background|previous] -- default: "none" |
| michael@0 | 47 | // What to do with the image's canvas before rendering the next frame. See APNG spec. |
| michael@0 | 48 | // blend=[source|over] -- default: "source" |
| michael@0 | 49 | // How to render the new frame on the canvas. See APNG spec. |
| michael@0 | 50 | // xoffset=# -- default: "0" |
| michael@0 | 51 | // yoffset=# -- default: "0" |
| michael@0 | 52 | // Where to draw the frame, relative to the canvas. |
| michael@0 | 53 | // |
| michael@0 | 54 | // |
| michael@0 | 55 | // JPEG: |
| michael@0 | 56 | // ----- |
| michael@0 | 57 | // |
| michael@0 | 58 | // quality=# -- default: "92" |
| michael@0 | 59 | // Quality of compression, 0-100 (worst-best). |
| michael@0 | 60 | // Quality >= 90 prevents down-sampling of the color channels. |
| michael@0 | 61 | |
| michael@0 | 62 | |
| michael@0 | 63 | // Possible values for input format (note that not all image formats |
| michael@0 | 64 | // support saving alpha channels): |
| michael@0 | 65 | |
| michael@0 | 66 | // Input is RGB each pixel is represented by three bytes: |
| michael@0 | 67 | // R, G, and B (in that order, regardless of host endianness) |
| michael@0 | 68 | const uint32_t INPUT_FORMAT_RGB = 0; |
| michael@0 | 69 | |
| michael@0 | 70 | // Input is RGB each pixel is represented by four bytes: |
| michael@0 | 71 | // R, G, and B (in that order, regardless of host endianness). |
| michael@0 | 72 | // POST-MULTIPLIED alpha us used (50% transparent red is 0xff000080) |
| michael@0 | 73 | const uint32_t INPUT_FORMAT_RGBA = 1; |
| michael@0 | 74 | |
| michael@0 | 75 | // Input is host-endian ARGB: On big-endian machines each pixel is therefore |
| michael@0 | 76 | // ARGB, and for little-endian machiens (Intel) each pixel is BGRA |
| michael@0 | 77 | // (This is used by canvas to match it's internal representation) |
| michael@0 | 78 | // |
| michael@0 | 79 | // PRE-MULTIPLIED alpha is used (That is, 50% transparent red is 0x80800000, |
| michael@0 | 80 | // not 0x80ff0000 |
| michael@0 | 81 | const uint32_t INPUT_FORMAT_HOSTARGB = 2; |
| michael@0 | 82 | |
| michael@0 | 83 | /* data - list of bytes in the format specified by inputFormat |
| michael@0 | 84 | * width - width in pixels |
| michael@0 | 85 | * height - height in pixels |
| michael@0 | 86 | * stride - number of bytes per row in the image |
| michael@0 | 87 | * Normally (width*3) or (width*4), depending on your input format, |
| michael@0 | 88 | * but some data uses padding at the end of each row, which would |
| michael@0 | 89 | * be extra. |
| michael@0 | 90 | * inputFormat - one of INPUT_FORMAT_* specifying the format of data |
| michael@0 | 91 | * outputOptions - semicolon-delimited list of name=value pairs that can |
| michael@0 | 92 | * give options to the output encoder. Options are encoder- |
| michael@0 | 93 | * specific. Just give empty string for default behavior. |
| michael@0 | 94 | */ |
| michael@0 | 95 | void initFromData([array, size_is(length), const] in uint8_t data, |
| michael@0 | 96 | in unsigned long length, |
| michael@0 | 97 | in uint32_t width, |
| michael@0 | 98 | in uint32_t height, |
| michael@0 | 99 | in uint32_t stride, |
| michael@0 | 100 | in uint32_t inputFormat, |
| michael@0 | 101 | in AString outputOptions); |
| michael@0 | 102 | |
| michael@0 | 103 | /* |
| michael@0 | 104 | * For encoding images which may contain multiple frames, the 1-shot |
| michael@0 | 105 | * initFromData() interface is too simplistic. The alternative is to |
| michael@0 | 106 | * use startImageEncode(), call addImageFrame() one or more times, and |
| michael@0 | 107 | * then finish initialization with endImageEncode(). |
| michael@0 | 108 | * |
| michael@0 | 109 | * The arguments are basically the same as in initFromData(). |
| michael@0 | 110 | */ |
| michael@0 | 111 | void startImageEncode(in uint32_t width, |
| michael@0 | 112 | in uint32_t height, |
| michael@0 | 113 | in uint32_t inputFormat, |
| michael@0 | 114 | in AString outputOptions); |
| michael@0 | 115 | |
| michael@0 | 116 | void addImageFrame( [array, size_is(length), const] in uint8_t data, |
| michael@0 | 117 | in unsigned long length, |
| michael@0 | 118 | in uint32_t width, |
| michael@0 | 119 | in uint32_t height, |
| michael@0 | 120 | in uint32_t stride, |
| michael@0 | 121 | in uint32_t frameFormat, |
| michael@0 | 122 | in AString frameOptions); |
| michael@0 | 123 | |
| michael@0 | 124 | void endImageEncode(); |
| michael@0 | 125 | |
| michael@0 | 126 | /* |
| michael@0 | 127 | * Sometimes an encoder can contain another encoder and direct access |
| michael@0 | 128 | * to its buffer is necessary. It is only safe to assume that the buffer |
| michael@0 | 129 | * returned from getImageBuffer() is of size equal to getImageBufferUsed(). |
| michael@0 | 130 | */ |
| michael@0 | 131 | [noscript] unsigned long getImageBufferUsed(); |
| michael@0 | 132 | [noscript] charPtr getImageBuffer(); |
| michael@0 | 133 | }; |
