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