imgIEncoder

modules/libpr0n/public/imgIEncoder.idlScriptable

Please add a summary to this article.

1.0

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().