Public Member Functions | Public Attributes

imgIContainer Interface Reference

imgIContainer is the interface that represents an image. More...

import "imgIContainer.idl";

List of all members.

Public Member Functions

gfxASurface getFrame (in PRUint32 aWhichFrame, in PRUint32 aFlags)
 Get a surface for the given frame.
gfxImageSurface copyFrame (in PRUint32 aWhichFrame, in PRUint32 aFlags)
 Create and return a new copy of the given frame that you can write to and otherwise inspect the pixels of.
imgIContainer extractFrame (in PRUint32 aWhichFrame,[const ] in nsIntRect aRect, in PRUint32 aFlags)
 Create a new imgContainer that contains only a single frame, which itself contains a subregion of the given frame.
void draw (in gfxContext aContext, in gfxGraphicsFilter aFilter, in gfxMatrix aUserSpaceToImageSpace, in gfxRect aFill, in nsIntRect aSubimage, in PRUint32 aFlags)
 Draw the current frame on to the context specified.
void requestDecode ()
void lockImage ()
 Increments the lock count on the image.
void unlockImage ()
 Decreases the lock count on the image.
void init (in imgIDecoderObserver aObserver, in string aMimeType, in PRUint32 aFlags)
 Creates a new image container.
void getCurrentFrameRect (in nsIntRect aFrameRect)
 The rectangle defining the location and size of the currently displayed frame.
void setFrameDisposalMethod (in unsigned long framenumber, in PRInt32 aDisposalMethod)
void setFrameBlendMethod (in unsigned long framenumber, in PRInt32 aBlendMethod)
void setFrameTimeout (in unsigned long framenumber, in PRInt32 aTimeout)
void setFrameHasNoAlpha (in unsigned long framenumber)
void setSize (in long aWidth, in long aHeight)
 Sets the size of the container.
void ensureCleanFrame (in unsigned long aFramenum, in PRInt32 aX, in PRInt32 aY, in PRInt32 aWidth, in PRInt32 aHeight, in gfxImageFormat aFormat,[array, size_is(imageLength)] out PRUint8 imageData, out unsigned long imageLength)
 Create or re-use a frame at index aFrameNum.
void appendFrame (in PRInt32 aX, in PRInt32 aY, in PRInt32 aWidth, in PRInt32 aHeight, in gfxImageFormat aFormat,[array, size_is(imageLength)] out PRUint8 imageData, out unsigned long imageLength)
 Adds to the end of the list of frames.
void appendPalettedFrame (in PRInt32 aX, in PRInt32 aY, in PRInt32 aWidth, in PRInt32 aHeight, in gfxImageFormat aFormat, in PRUint8 aPaletteDepth,[array, size_is(imageLength)] out PRUint8 imageData, out unsigned long imageLength,[array, size_is(paletteLength)] out PRUint32 paletteData, out unsigned long paletteLength)
void frameUpdated (in unsigned long framenum, in nsIntRect aNewRect)
void endFrameDecode (in unsigned long framenumber)
void decodingComplete ()
void startAnimation ()
void stopAnimation ()
void resetAnimation ()
void addSourceData ([array, size_is(aCount), const ] in char data, in unsigned long aCount)
void sourceDataComplete ()
void newSourceData ()

Public Attributes

readonly attribute PRInt32 width
 The width of the container rectangle.
readonly attribute PRInt32 height
 The height of the container rectangle.
readonly attribute boolean animated
 Whether this image is animated.
readonly attribute boolean currentFrameIsOpaque
 Whether the current frame is opaque; that is, needs the background painted behind it.
const long FLAG_NONE = 0x0
 Flags for imgIContainer operations.
const long FLAG_SYNC_DECODE = 0x1
const unsigned long FRAME_FIRST = 0
 Constants for specifying various "special" frames.
const unsigned long FRAME_CURRENT = 1
const unsigned long FRAME_MAX_VALUE = 1
const long INIT_FLAG_NONE = 0x0
 Flags for imgIContainer initialization.
const long INIT_FLAG_DISCARDABLE = 0x1
const long INIT_FLAG_DECODE_ON_DRAW = 0x2
const long INIT_FLAG_MULTIPART = 0x4
const long kDisposeClearAll = -1
 "Disposal" method indicates how the image should be handled before the subsequent image is displayed.
const long kDisposeNotSpecified = 0
const long kDisposeKeep = 1
const long kDisposeClear = 2
const long kDisposeRestorePrevious = 3
const long kBlendSource = 0
const long kBlendOver = 1
const short kNormalAnimMode = 0
 Animation mode Constants 0 = normal 1 = don't animate 2 = loop once.
const short kDontAnimMode = 1
const short kLoopOnceAnimMode = 2
attribute unsigned short animationMode
readonly attribute unsigned long currentFrameIndex
 The index of the current frame that would be drawn if the image was to be drawn now.
readonly attribute unsigned long numFrames
 The total number of frames in this image.
readonly attribute unsigned long dataSize
 The size, in bytes, occupied by the significant data portions of the image.
attribute long loopCount
 number of times to loop the image.

Detailed Description

imgIContainer is the interface that represents an image.

It allows access to frames as Thebes surfaces, and permits users to extract subregions as other imgIContainers. It also allows drawing of images on to Thebes contexts.

Internally, imgIContainer also manages animation of images.


Member Function Documentation

void imgIContainer::addSourceData ( [array, size_is(aCount), const ] in char  data,
in unsigned long  aCount 
)
void imgIContainer::appendFrame ( in PRInt32  aX,
in PRInt32  aY,
in PRInt32  aWidth,
in PRInt32  aHeight,
in gfxImageFormat  aFormat,
[array, size_is(imageLength)] out PRUint8  imageData,
out unsigned long  imageLength 
)

Adds to the end of the list of frames.

void imgIContainer::appendPalettedFrame ( in PRInt32  aX,
in PRInt32  aY,
in PRInt32  aWidth,
in PRInt32  aHeight,
in gfxImageFormat  aFormat,
in PRUint8  aPaletteDepth,
[array, size_is(imageLength)] out PRUint8  imageData,
out unsigned long  imageLength,
[array, size_is(paletteLength)] out PRUint32  paletteData,
out unsigned long  paletteLength 
)
gfxImageSurface imgIContainer::copyFrame ( in PRUint32  aWhichFrame,
in PRUint32  aFlags 
)

Create and return a new copy of the given frame that you can write to and otherwise inspect the pixels of.

Parameters:
aWhichFrame Frame specifier of the FRAME_* variety.
aFlags Flags of the FLAG_* variety
void imgIContainer::decodingComplete (  ) 
void imgIContainer::draw ( in gfxContext  aContext,
in gfxGraphicsFilter  aFilter,
in gfxMatrix  aUserSpaceToImageSpace,
in gfxRect  aFill,
in nsIntRect  aSubimage,
in PRUint32  aFlags 
)

Draw the current frame on to the context specified.

Parameters:
aContext The Thebex context to draw the image to.
aFilter The filter to be used if we're scaling the image.
aUserSpaceToImageSpace The transformation from user space (e.g., appunits) to image space.
aFill The area in the context to draw pixels to. Image will be automatically tiled as necessary.
aSubimage The area of the image, in pixels, that we are allowed to sample from.
aFlags Flags of the FLAG_* variety
void imgIContainer::endFrameDecode ( in unsigned long  framenumber  ) 
void imgIContainer::ensureCleanFrame ( in unsigned long  aFramenum,
in PRInt32  aX,
in PRInt32  aY,
in PRInt32  aWidth,
in PRInt32  aHeight,
in gfxImageFormat  aFormat,
[array, size_is(imageLength)] out PRUint8  imageData,
out unsigned long  imageLength 
)

Create or re-use a frame at index aFrameNum.

It is an error to call this with aFrameNum not in the range [0, numFrames].

imgIContainer imgIContainer::extractFrame ( in PRUint32  aWhichFrame,
[const ] in nsIntRect  aRect,
in PRUint32  aFlags 
)

Create a new imgContainer that contains only a single frame, which itself contains a subregion of the given frame.

Parameters:
aWhichFrame Frame specifier of the FRAME_* variety.
aRect the area of the current frame to be duplicated in the returned imgContainer's frame.
aFlags Flags of the FLAG_* variety
void imgIContainer::frameUpdated ( in unsigned long  framenum,
in nsIntRect  aNewRect 
)
void imgIContainer::getCurrentFrameRect ( in nsIntRect  aFrameRect  ) 

The rectangle defining the location and size of the currently displayed frame.

Should be an attribute, but can't be because of reference/pointer conflicts with native types in xpidl.

gfxASurface imgIContainer::getFrame ( in PRUint32  aWhichFrame,
in PRUint32  aFlags 
)

Get a surface for the given frame.

This may be a platform-native, optimized surface, so you cannot inspect its pixel data.

Parameters:
aWhichFrame Frame specifier of the FRAME_* variety.
aFlags Flags of the FLAG_* variety
void imgIContainer::init ( in imgIDecoderObserver  aObserver,
in string  aMimeType,
in PRUint32  aFlags 
)

Creates a new image container.

Parameters:
aObserver Observer to send decoder and animation notifications to.
aMimeType The mimetype of the image.
aFlags Initialization flags of the INIT_FLAG_* variety.
void imgIContainer::lockImage (  ) 

Increments the lock count on the image.

An image will not be discarded as long as the lock count is nonzero. Note that it is still possible for the image to be undecoded if decode-on-draw is enabled and the image was never drawn.

Upon instantiation images have a lock count of zero.

void imgIContainer::newSourceData (  ) 
void imgIContainer::requestDecode (  ) 
void imgIContainer::resetAnimation (  ) 
void imgIContainer::setFrameBlendMethod ( in unsigned long  framenumber,
in PRInt32  aBlendMethod 
)
void imgIContainer::setFrameDisposalMethod ( in unsigned long  framenumber,
in PRInt32  aDisposalMethod 
)
void imgIContainer::setFrameHasNoAlpha ( in unsigned long  framenumber  ) 
void imgIContainer::setFrameTimeout ( in unsigned long  framenumber,
in PRInt32  aTimeout 
)
void imgIContainer::setSize ( in long  aWidth,
in long  aHeight 
)

Sets the size of the container.

This should only be called by the decoder. This function may be called multiple times, but will throw an error if subsequent calls do not match the first.

void imgIContainer::sourceDataComplete (  ) 
void imgIContainer::startAnimation (  ) 
void imgIContainer::stopAnimation (  ) 
void imgIContainer::unlockImage (  ) 

Decreases the lock count on the image.

If the lock count drops to zero, the image is allowed to discard its frame data to save memory.

Upon instantiation images have a lock count of zero. It is an error to call this method without first having made a matching lockImage() call. In other words, the lock count is not allowed to be negative.


Member Data Documentation

readonly attribute boolean imgIContainer::animated

Whether this image is animated.

You can only be guaranteed that querying this will not throw if STATUS_DECODE_COMPLETE is set on the imgIRequest.

Exceptions:
NS_ERROR_NOT_AVAILABLE if the animated state cannot be determined.
attribute unsigned short imgIContainer::animationMode
readonly attribute unsigned long imgIContainer::currentFrameIndex

The index of the current frame that would be drawn if the image was to be drawn now.

Whether the current frame is opaque; that is, needs the background painted behind it.

readonly attribute unsigned long imgIContainer::dataSize

The size, in bytes, occupied by the significant data portions of the image.

This includes both compressed source data and decoded frames.

const long imgIContainer::FLAG_NONE = 0x0

Flags for imgIContainer operations.

Meanings:

FLAG_NONE: Lack of flags

FLAG_SYNC_DECODE: Forces synchronous/non-progressive decode of all available data before the call returns.

const unsigned long imgIContainer::FRAME_CURRENT = 1
const unsigned long imgIContainer::FRAME_FIRST = 0

Constants for specifying various "special" frames.

FRAME_FIRST: The first frame FRAME_CURRENT: The current frame

FRAME_MAX_VALUE should be set to the value of the maximum constant above, as it is used for ensuring that a valid value was passed in.

const unsigned long imgIContainer::FRAME_MAX_VALUE = 1
readonly attribute PRInt32 imgIContainer::height

The height of the container rectangle.

Flags for imgIContainer initialization.

Meanings:

INIT_FLAG_NONE: Lack of flags

INIT_FLAG_DISCARDABLE: The container should be discardable

INIT_FLAG_DECODE_ON_DRAW: The container should decode on draw rather than decoding on load.

INIT_FLAG_MULTIPART: The container will be used to display a stream of images in a multipart channel. If this flag is set, INIT_FLAG_DISCARDABLE and INIT_FLAG_DECODE_ON_DRAW must not be set.

const long imgIContainer::kBlendOver = 1

"Disposal" method indicates how the image should be handled before the subsequent image is displayed.

Don't change these without looking at the implementations using them, struct gif_struct::disposal_method and gif_write() in particular.

Animation mode Constants 0 = normal 1 = don't animate 2 = loop once.

attribute long imgIContainer::loopCount

number of times to loop the image.

Note:
-1 means forever.
readonly attribute unsigned long imgIContainer::numFrames

The total number of frames in this image.

readonly attribute PRInt32 imgIContainer::width

The width of the container rectangle.


The documentation for this interface was generated from the following file: