imgIEncoder

Please add a summary to this article.
1.0
66
Introduced
Gecko 1.8
Inherits from: nsIAsyncInputStream Last changed in Gecko 1.9 (Firefox 3)

Method overview

void addImageFrame( [array, size_is(length), const] in PRUint8 data, in unsigned long length, in PRUint32 width, in PRUint32 height, in PRUint32 stride, in PRUint32 frameFormat, in AString frameOptions);
void encodeClipboardImage(in nsIClipboardImage aClipboardImage, out nsIFile aImageFile); Obsolete since Gecko 1.9
void endImageEncode();
void initFromData([array, size_is(length), const] in PRUint8 data, in unsigned long length, in PRUint32 width, in PRUint32 height, in PRUint32 stride, in PRUint32 inputFormat, in AString outputOptions);
void startImageEncode(in PRUint32 width, in PRUint32 height, in PRUint32 inputFormat, in AString outputOptions);

Constants

Possible values for input format (note that not all image formats support saving alpha channels):

Constant Value Description
INPUT_FORMAT_RGB 0 Input is RGB each pixel is represented by three bytes: R, G, and B (in that order, regardless of host endianness)
INPUT_FORMAT_RGBA 1

Input is RGB each pixel is represented by four bytes: R, G, and B (in that order, regardless of host endianness).

POST-MULTIPLIED alpha us used (For example 50% transparent red is 0xff000080)
INPUT_FORMAT_HOSTARGB 2

Input is host-endian ARGB: On big-endian machines each pixel is therefore ARGB, and for little-endian machiens (Intel) each pixel is BGRA (This is used by canvas to match it's internal representation)

PRE-MULTIPLIED alpha is used (That is, 50% transparent red is 0x80800000, not 0x80ff0000)
Possible values for outputOptions. Multiple values are semicolon-separated.

PNG:
----
transparency=[yes|no|none]  --  default: "yes"
    Overrides default from input format. "no" and "none" are equivalent.

APNG:
-----
The following options can be used with startImageEncode():

transparency=[yes|no|none]  --  default: "yes"
    Overrides default from input format. "no" and "none" are equivalent.
skipfirstframe=[yes|no]  --  default: "no"
    Controls display of the first frame in animations. PNG-only clients always display the first frame (and only that frame).
frames=#  --  default: "1"
    Total number of frames in the image. The first frame, even if skipped, is always included in the count.
plays=#  --  default: "0"
    Number of times to play the animation sequence. "0" will repeat forever.

The following options can be used for each frame, with addImageFrame():

transparency=[yes|no|none]  --  default: "yes"
    Overrides default from input format. "no" and "none" are equivalent.
delay=#  --  default: "500"
    Number of milliseconds to display the frame, before moving to the next frame.
dispose=[none|background|previous]  --  default: "none"
    What to do with the image's canvas before rendering the next frame. See APNG spec.
blend=[source|over]  --  default: "source"
    How to render the new frame on the canvas. See APNG spec.
xoffset=#  --  default: "0"
yoffset=#  --  default: "0"
    Where to draw the frame, relative to the canvas.

JPEG:
-----
quality=#  --  default: "92"
   Quality of compression, 0-100 (worst-best).
   Quality >= 90 prevents down-sampling of the color channels.

Methods

addImageFrame()

void addImageFrame(
  [array, size_is(length), const] in PRUint8 data,
  in unsigned long length,
  in PRUint32 width,
  in PRUint32 height,
  in PRUint32 stride,
  in PRUint32 frameFormat,
  in AString frameOptions
);
Parameters
data
List of bytes in the format specified by inputFormat.
length
Missing Description
width
Width in pixels.
height
Height in pixels.
stride
The number of bytes per row in the image. Normally (width*3) or (width*4), depending on your input format, but some data uses padding at the end of each row, which would be extra.
frameFormat
Missing Description
frameOptions
Missing Description

encodeClipboardImage()

Obsolete since Gecko 1.9 (Firefox 3)

void encodeClipboardImage(
  in nsIClipboardImage aClipboardImage,
  out nsIFile aImageFile
);
Parameters
aClipboardImage
Missing Description
aImageFile
Missing Description

endImageEncode()

void endImageEncode();
Parameters

None.

initFromData()

void initFromData(
  [array, size_is(length), const] in PRUint8 data,
  in unsigned long length,
  in PRUint32 width,
  in PRUint32 height,
  in PRUint32 stride,
  in PRUint32 inputFormat,
  in AString outputOptions
);
Parameters
data
List of bytes in the format specified by inputFormat.
length
Missing Description
width
Width in pixels.
height
Height in pixels.
stride
The number of bytes per row in the image. Normally (width*3) or (width*4), depending on your input format, but some data uses padding at the end of each row, which would be extra.
inputFormat
One of INPUT_FORMAT_* constants specifying the format of data.
outputOptions
Semicolon-delimited list of name=value pairs that can give options to the output encoder. Options are encoder-specific. Just give an empty string for default behavior.

startImageEncode()

void startImageEncode(
  in PRUint32 width,
  in PRUint32 height,
  in PRUint32 inputFormat,
  in AString outputOptions
);
Parameters
width
Width in pixels.
height
Height in pixels.
inputFormat
One of INPUT_FORMAT_* constants specifying the format of data.
outputOptions
Semicolon-delimited list of name=value pairs that can give options to the output encoder. Options are encoder-specific. Just give an empty string for default behavior.

Remarks

For encoding images which may contain multiple frames, the 1-shot initFromData() interface is too simplistic. The alternative is to use startImageEncode(), call addImageFrame() one or more times, and then finish initialization with endImageEncode().