1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/image/public/imgIEncoder.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,133 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
1.5 + * This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsISupports.idl"
1.10 +#include "nsIAsyncInputStream.idl"
1.11 +#include "nsIEventTarget.idl"
1.12 +
1.13 +/**
1.14 + * imgIEncoder interface
1.15 + */
1.16 +[scriptable, uuid(4baa2d6e-fee7-42df-ae3f-5fbebc0c267c)]
1.17 +interface imgIEncoder : nsIAsyncInputStream
1.18 +{
1.19 + // Possible values for outputOptions. Multiple values are semicolon-separated.
1.20 + //
1.21 + // PNG:
1.22 + // ----
1.23 + // transparency=[yes|no|none] -- default: "yes"
1.24 + // Overrides default from input format. "no" and "none" are equivalent.
1.25 + //
1.26 + //
1.27 + // APNG:
1.28 + // -----
1.29 + // The following options can be used with startImageEncode():
1.30 + //
1.31 + // transparency=[yes|no|none] -- default: "yes"
1.32 + // Overrides default from input format. "no" and "none" are equivalent.
1.33 + // skipfirstframe=[yes|no] -- default: "no"
1.34 + // Controls display of the first frame in animations. PNG-only clients always
1.35 + // display the first frame (and only that frame).
1.36 + // frames=# -- default: "1"
1.37 + // Total number of frames in the image. The first frame, even if skipped, is
1.38 + // always included in the count.
1.39 + // plays=# -- default: "0"
1.40 + // Number of times to play the animation sequence. "0" will repeat forever.
1.41 + //
1.42 + //
1.43 + // The following options can be used for each frame, with addImageFrame():
1.44 + //
1.45 + // transparency=[yes|no|none] -- default: "yes"
1.46 + // Overrides default from input format. "no" and "none" are equivalent.
1.47 + // delay=# -- default: "500"
1.48 + // Number of milliseconds to display the frame, before moving to the next frame.
1.49 + // dispose=[none|background|previous] -- default: "none"
1.50 + // What to do with the image's canvas before rendering the next frame. See APNG spec.
1.51 + // blend=[source|over] -- default: "source"
1.52 + // How to render the new frame on the canvas. See APNG spec.
1.53 + // xoffset=# -- default: "0"
1.54 + // yoffset=# -- default: "0"
1.55 + // Where to draw the frame, relative to the canvas.
1.56 + //
1.57 + //
1.58 + // JPEG:
1.59 + // -----
1.60 + //
1.61 + // quality=# -- default: "92"
1.62 + // Quality of compression, 0-100 (worst-best).
1.63 + // Quality >= 90 prevents down-sampling of the color channels.
1.64 +
1.65 +
1.66 + // Possible values for input format (note that not all image formats
1.67 + // support saving alpha channels):
1.68 +
1.69 + // Input is RGB each pixel is represented by three bytes:
1.70 + // R, G, and B (in that order, regardless of host endianness)
1.71 + const uint32_t INPUT_FORMAT_RGB = 0;
1.72 +
1.73 + // Input is RGB each pixel is represented by four bytes:
1.74 + // R, G, and B (in that order, regardless of host endianness).
1.75 + // POST-MULTIPLIED alpha us used (50% transparent red is 0xff000080)
1.76 + const uint32_t INPUT_FORMAT_RGBA = 1;
1.77 +
1.78 + // Input is host-endian ARGB: On big-endian machines each pixel is therefore
1.79 + // ARGB, and for little-endian machiens (Intel) each pixel is BGRA
1.80 + // (This is used by canvas to match it's internal representation)
1.81 + //
1.82 + // PRE-MULTIPLIED alpha is used (That is, 50% transparent red is 0x80800000,
1.83 + // not 0x80ff0000
1.84 + const uint32_t INPUT_FORMAT_HOSTARGB = 2;
1.85 +
1.86 + /* data - list of bytes in the format specified by inputFormat
1.87 + * width - width in pixels
1.88 + * height - height in pixels
1.89 + * stride - number of bytes per row in the image
1.90 + * Normally (width*3) or (width*4), depending on your input format,
1.91 + * but some data uses padding at the end of each row, which would
1.92 + * be extra.
1.93 + * inputFormat - one of INPUT_FORMAT_* specifying the format of data
1.94 + * outputOptions - semicolon-delimited list of name=value pairs that can
1.95 + * give options to the output encoder. Options are encoder-
1.96 + * specific. Just give empty string for default behavior.
1.97 + */
1.98 + void initFromData([array, size_is(length), const] in uint8_t data,
1.99 + in unsigned long length,
1.100 + in uint32_t width,
1.101 + in uint32_t height,
1.102 + in uint32_t stride,
1.103 + in uint32_t inputFormat,
1.104 + in AString outputOptions);
1.105 +
1.106 + /*
1.107 + * For encoding images which may contain multiple frames, the 1-shot
1.108 + * initFromData() interface is too simplistic. The alternative is to
1.109 + * use startImageEncode(), call addImageFrame() one or more times, and
1.110 + * then finish initialization with endImageEncode().
1.111 + *
1.112 + * The arguments are basically the same as in initFromData().
1.113 + */
1.114 + void startImageEncode(in uint32_t width,
1.115 + in uint32_t height,
1.116 + in uint32_t inputFormat,
1.117 + in AString outputOptions);
1.118 +
1.119 + void addImageFrame( [array, size_is(length), const] in uint8_t data,
1.120 + in unsigned long length,
1.121 + in uint32_t width,
1.122 + in uint32_t height,
1.123 + in uint32_t stride,
1.124 + in uint32_t frameFormat,
1.125 + in AString frameOptions);
1.126 +
1.127 + void endImageEncode();
1.128 +
1.129 + /*
1.130 + * Sometimes an encoder can contain another encoder and direct access
1.131 + * to its buffer is necessary. It is only safe to assume that the buffer
1.132 + * returned from getImageBuffer() is of size equal to getImageBufferUsed().
1.133 + */
1.134 + [noscript] unsigned long getImageBufferUsed();
1.135 + [noscript] charPtr getImageBuffer();
1.136 +};
