1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
2 * ***** BEGIN LICENSE BLOCK *****
3 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
4 *
5 * The contents of this file are subject to the Mozilla Public License Version
6 * 1.1 (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 * http://www.mozilla.org/MPL/
9 *
10 * Software distributed under the License is distributed on an "AS IS" basis,
11 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
12 * for the specific language governing rights and limitations under the
13 * License.
14 *
15 * The Original Code is Oracle Corporation code.
16 *
17 * The Initial Developer of the Original Code is Oracle Corporation.
18 * Portions created by the Initial Developer are Copyright (C) 2005
19 * the Initial Developer. All Rights Reserved.
20 *
21 * Contributor(s):
22 * Stuart Parmenter <pavlov@pavlov.net>
23 * Brett Wilson <brettw@gmail.com>
24 * Justin Dolske <dolske@mozilla.com>
25 *
26 * Alternatively, the contents of this file may be used under the terms of
27 * either the GNU General Public License Version 2 or later (the "GPL"), or
28 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
29 * in which case the provisions of the GPL or the LGPL are applicable instead
30 * of those above. If you wish to allow use of your version of this file only
31 * under the terms of either the GPL or the LGPL, and not to allow others to
32 * use your version of this file under the terms of the MPL, indicate your
33 * decision by deleting the provisions above and replace them with the notice
34 * and other provisions required by the GPL or the LGPL. If you do not delete
35 * the provisions above, a recipient may use your version of this file under
36 * the terms of any one of the MPL, the GPL or the LGPL.
37 *
38 * ***** END LICENSE BLOCK ***** */
39
40 #include "nsISupports.idl"
41 #include "nsIInputStream.idl"
42
43 /**
44 * imgIEncoder interface
45 */
46 [scriptable, uuid(ba3a854b-fb8d-4881-8af9-5849df10e5e5)]
47 interface imgIEncoder : nsIInputStream
48 {
49 // Possible values for outputOptions. Multiple values are semicolon-separated.
50 //
51 // PNG:
52 // ----
53 // transparency=[yes|no|none] -- default: "yes"
54 // Overrides default from input format. "no" and "none" are equivalent.
55 //
56 //
57 // APNG:
58 // -----
59 // The following options can be used with startImageEncode():
60 //
61 // transparency=[yes|no|none] -- default: "yes"
62 // Overrides default from input format. "no" and "none" are equivalent.
63 // skipfirstframe=[yes|no] -- default: "no"
64 // Controls display of the first frame in animations. PNG-only clients always
65 // display the first frame (and only that frame).
66 // frames=# -- default: "1"
67 // Total number of frames in the image. The first frame, even if skipped, is
68 // always included in the count.
69 // plays=# -- default: "0"
70 // Number of times to play the animation sequence. "0" will repeat forever.
71 //
72 //
73 // The following options can be used for each frame, with addImageFrame():
74 //
75 // transparency=[yes|no|none] -- default: "yes"
76 // Overrides default from input format. "no" and "none" are equivalent.
77 // delay=# -- default: "500"
78 // Number of milliseconds to display the frame, before moving to the next frame.
79 // dispose=[none|background|previous] -- default: "none"
80 // What to do with the image's canvas before rendering the next frame. See APNG spec.
81 // blend=[source|over] -- default: "source"
82 // How to render the new frame on the canvas. See APNG spec.
83 // xoffset=# -- default: "0"
84 // yoffset=# -- default: "0"
85 // Where to draw the frame, relative to the canvas.
86 //
87 //
88 // JPEG:
89 // -----
90 //
91 // quality=# -- default: "50"
92 // Quality of compression, 0-100 (worst-best).
93
94
95 // Possible values for input format (note that not all image formats
96 // support saving alpha channels):
97
98 // Input is RGB each pixel is represented by three bytes:
99 // R, G, and B (in that order, regardless of host endianness)
100 const PRUint32 INPUT_FORMAT_RGB = 0;
101
102 // Input is RGB each pixel is represented by four bytes:
103 // R, G, and B (in that order, regardless of host endianness).
104 // POST-MULTIPLIED alpha us used (50% transparent red is 0xff000080)
105 const PRUint32 INPUT_FORMAT_RGBA = 1;
106
107 // Input is host-endian ARGB: On big-endian machines each pixel is therefore
108 // ARGB, and for little-endian machiens (Intel) each pixel is BGRA
109 // (This is used by canvas to match it's internal representation)
110 //
111 // PRE-MULTIPLIED alpha is used (That is, 50% transparent red is 0x80800000,
112 // not 0x80ff0000
113 const PRUint32 INPUT_FORMAT_HOSTARGB = 2;
114
115 /* data - list of bytes in the format specified by inputFormat
116 * width - width in pixels
117 * height - height in pixels
118 * stride - number of bytes per row in the image
119 * Normally (width*3) or (width*4), depending on your input format,
120 * but some data uses padding at the end of each row, which would
121 * be extra.
122 * inputFormat - one of INPUT_FORMAT_* specifying the format of data
123 * outputOptions - semicolon-delimited list of name=value pairs that can
124 * give options to the output encoder. Options are encoder-
125 * specific. Just give empty string for default behavior.
126 */
127 void initFromData([array, size_is(length), const] in PRUint8 data,
128 in unsigned long length,
129 in PRUint32 width,
130 in PRUint32 height,
131 in PRUint32 stride,
132 in PRUint32 inputFormat,
133 in AString outputOptions);
134
135 /*
136 * For encoding images which may contain multiple frames, the 1-shot
137 * initFromData() interface is too simplistic. The alternative is to
138 * use startImageEncode(), call addImageFrame() one or more times, and
139 * then finish initialization with endImageEncode().
140 *
141 * The arguments are basically the same as in initFromData().
142 */
143 void startImageEncode(in PRUint32 width,
144 in PRUint32 height,
145 in PRUint32 inputFormat,
146 in AString outputOptions);
147
148 void addImageFrame( [array, size_is(length), const] in PRUint8 data,
149 in unsigned long length,
150 in PRUint32 width,
151 in PRUint32 height,
152 in PRUint32 stride,
153 in PRUint32 frameFormat,
154 in AString frameOptions);
155
156 void endImageEncode();
157 };