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

import "imgIContainer.idl";

Public Member Functions
PRUint16	GetType ()
	Direct C++ accessor for 'type' attribute, for convenience.
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,[const ] in gfxMatrix aUserSpaceToImageSpace,[const ] in gfxRect aFill,[const ] in nsIntRect aSubimage,[const ] in nsIntSize aViewportSize, in PRUint32 aFlags)
	Draw the current frame on to the context specified.
nsIFrame	GetRootLayoutFrame ()
	If this image is TYPE_VECTOR, i.e.
void	requestDecode ()
void	lockImage ()
	Increments the lock count on the image.
void	unlockImage ()
	Decreases the lock count on the image.
void	resetAnimation ()
Public Attributes
readonly attribute PRInt32	width
	The width of the container rectangle.
readonly attribute PRInt32	height
	The height of the container rectangle.
const unsigned short	TYPE_RASTER = 0
	Enumerated values for the 'type' attribute (below).
const unsigned short	TYPE_VECTOR = 1
readonly attribute unsigned short	type
	The type of this image (one of the TYPE_* values above).
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 long	FLAG_DECODE_NO_PREMULTIPLY_ALPHA = 0x2
const long	FLAG_DECODE_NO_COLORSPACE_CONVERSION = 0x4
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 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

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

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::draw	(	in gfxContext	aContext,
		in gfxGraphicsFilter	aFilter,
		[const ] in gfxMatrix	aUserSpaceToImageSpace,
		[const ] in gfxRect	aFill,
		[const ] in nsIntRect	aSubimage,
		[const ] in nsIntSize	aViewportSize,
		in PRUint32	aFlags
	)

Draw the current frame on to the context specified.

Parameters:

	aContext	The Thebes 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.
	aViewportSize	The size (in CSS pixels) of the viewport that would be available for the full image to occupy, if we were drawing the full image. (Note that we might not actually be drawing the full image -- we might be restricted by aSubimage -- but we still need the full image's viewport-size in order for SVG images with the "viewBox" attribute to position their content correctly.)
	aFlags	Flags of the FLAG_* variety

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

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

nsIFrame imgIContainer::GetRootLayoutFrame ( )

If this image is TYPE_VECTOR, i.e.

is really an embedded SVG document, this method returns a pointer to the root nsIFrame of that document. If not (or if the root nsIFrame isn't available for some reason), this method returns nsnull.

"notxpcom" for convenience, since we have no need for nsresult return-val.

PRUint16 imgIContainer::GetType ( )

Direct C++ accessor for 'type' attribute, for convenience.

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::requestDecode ( )

void imgIContainer::resetAnimation ( )

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 boolean imgIContainer::currentFrameIsOpaque

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

const long imgIContainer::FLAG_DECODE_NO_COLORSPACE_CONVERSION = 0x4

const long imgIContainer::FLAG_DECODE_NO_PREMULTIPLY_ALPHA = 0x2

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. It is an error to pass this flag from a call stack that originates in a decoder (ie, from a decoder observer event).

FLAG_DECODE_NO_PREMULTIPLY_ALPHA: Do not premultiply alpha if it's not already premultiplied in the image data.

FLAG_DECODE_NO_COLORSPACE_CONVERSION: Do not do any colorspace conversion; ignore any embedded profiles, and don't convert to any particular destination space.

const long imgIContainer::FLAG_SYNC_DECODE = 0x1

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.

In the case of any error, zero is returned, and an exception will be thrown.

const short imgIContainer::kDontAnimMode = 1

const short imgIContainer::kLoopOnceAnimMode = 2