/** -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- * * This Source Code Form is subject to the terms of the Mozilla Public * License, v. 2.0. If a copy of the MPL was not distributed with this * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ #include "nsISupports.idl" interface imgIDecoderObserver; %{C++ #include "gfxImageSurface.h" #include "gfxContext.h" #include "gfxMatrix.h" #include "gfxRect.h" #include "gfxPattern.h" #include "gfxASurface.h" #include "nsRect.h" #include "nsSize.h" #include "limits.h" namespace mozilla { namespace layers { class LayerManager; class ImageContainer; } } class nsIFrame; namespace mozilla { class TimeStamp; } %} [ptr] native gfxImageSurface(gfxImageSurface); [ptr] native gfxASurface(gfxASurface); native gfxImageFormat(gfxASurface::gfxImageFormat); [ptr] native gfxContext(gfxContext); [ref] native gfxMatrix(gfxMatrix); [ref] native gfxRect(gfxRect); native gfxGraphicsFilter(gfxPattern::GraphicsFilter); [ref] native nsIntRect(nsIntRect); [ref] native nsIntSize(nsIntSize); [ptr] native nsIFrame(nsIFrame); [ptr] native ImageContainer(mozilla::layers::ImageContainer); [ptr] native LayerManager(mozilla::layers::LayerManager); [ref] native TimeStamp(mozilla::TimeStamp); /** * 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. */ [scriptable, uuid(ead94080-cfd6-4a3e-8353-bd45333061d2)] interface imgIContainer : nsISupports { /** * The width of the container rectangle. In the case of any error, * zero is returned, and an exception will be thrown. */ readonly attribute int32_t width; /** * The height of the container rectangle. In the case of any error, * zero is returned, and an exception will be thrown. */ readonly attribute int32_t height; /** * Enumerated values for the 'type' attribute (below). */ const unsigned short TYPE_RASTER = 0; const unsigned short TYPE_VECTOR = 1; /** * The type of this image (one of the TYPE_* values above). */ readonly attribute unsigned short type; /** * Direct C++ accessor for 'type' attribute, for convenience. */ [noscript, notxpcom] uint16_t GetType(); /** * 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. * * @throws NS_ERROR_NOT_AVAILABLE if the animated state cannot be determined. */ readonly attribute boolean animated; /** * Whether the current frame is opaque; that is, needs the background painted * behind it. */ readonly attribute boolean currentFrameIsOpaque; /** * 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. * * FLAG_CLAMP: Extend the image to the fill area by clamping image sample * coordinates instead of by tiling. This only affects 'draw'. */ const long FLAG_NONE = 0x0; const long FLAG_SYNC_DECODE = 0x1; const long FLAG_DECODE_NO_PREMULTIPLY_ALPHA = 0x2; const long FLAG_DECODE_NO_COLORSPACE_CONVERSION = 0x4; const long FLAG_CLAMP = 0x8; /** * 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 FRAME_FIRST = 0; const unsigned long FRAME_CURRENT = 1; const unsigned long FRAME_MAX_VALUE = 1; /** * Get a surface for the given frame. This may be a platform-native, * optimized surface, so you cannot inspect its pixel data. * * @param aWhichFrame Frame specifier of the FRAME_* variety. * @param aFlags Flags of the FLAG_* variety */ [noscript] gfxASurface getFrame(in uint32_t aWhichFrame, in uint32_t aFlags); /** * Attempts to create an ImageContainer (and Image) containing the current * frame. Only valid for RASTER type images. */ [noscript] ImageContainer getImageContainer(); /** * Create and return a new copy of the given frame that you can write to * and otherwise inspect the pixels of. * * @param aWhichFrame Frame specifier of the FRAME_* variety. * @param aFlags Flags of the FLAG_* variety */ [noscript] gfxImageSurface copyFrame(in uint32_t aWhichFrame, in uint32_t aFlags); /** * Create a new imgContainer that contains only a single frame, which itself * contains a subregion of the given frame. * * @param aWhichFrame Frame specifier of the FRAME_* variety. * @param aRect the area of the current frame to be duplicated in the * returned imgContainer's frame. * @param aFlags Flags of the FLAG_* variety */ [noscript] imgIContainer extractFrame(in uint32_t aWhichFrame, [const] in nsIntRect aRect, in uint32_t aFlags); /** * Draw the current frame on to the context specified. * * @param aContext The Thebes context to draw the image to. * @param aFilter The filter to be used if we're scaling the image. * @param aUserSpaceToImageSpace The transformation from user space (e.g., * appunits) to image space. * @param aFill The area in the context to draw pixels to. When aFlags includes * FLAG_CLAMP, the image will be extended to this area by clampling * image sample coordinates. Otherwise, the image will be * automatically tiled as necessary. * @param aSubimage The area of the image, in pixels, that we are allowed to * sample from. * @param 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.) * @param aFlags Flags of the FLAG_* variety */ [noscript] 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 uint32_t aFlags); /** * 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 nullptr. * * "notxpcom" for convenience, since we have no need for nsresult return-val. */ [notxpcom] nsIFrame GetRootLayoutFrame(); /* * Ensures that an image is decoding. Calling this function guarantees that * the image will at some point fire off decode notifications. Calling draw(), * getFrame(), copyFrame(), or extractCurrentFrame() triggers the same * mechanism internally. Thus, if you want to be sure that the image will be * decoded but don't want to access it until then, you must call * requestDecode(). */ void requestDecode(); /** * 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 lockImage(); /** * 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. */ void unlockImage(); /** * If this image is unlocked, discard its decoded data. If the image is * locked or has already been discarded, do nothing. */ void requestDiscard(); /** * Indicates that this imgIContainer has been triggered to update * its internal animation state. Likely this should only be called * from within nsImageFrame or objects of similar type. */ [notxpcom] void requestRefresh([const] in TimeStamp aTime); /** * Animation mode Constants * 0 = normal * 1 = don't animate * 2 = loop once */ const short kNormalAnimMode = 0; const short kDontAnimMode = 1; const short kLoopOnceAnimMode = 2; attribute unsigned short animationMode; /* Methods to control animation */ void resetAnimation(); };