/** -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- * * ***** BEGIN LICENSE BLOCK ***** * Version: MPL 1.1/GPL 2.0/LGPL 2.1 * * The contents of this file are subject to the Mozilla Public License Version * 1.1 (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * http://www.mozilla.org/MPL/ * * Software distributed under the License is distributed on an "AS IS" basis, * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License * for the specific language governing rights and limitations under the * License. * * The Original Code is mozilla.org code. * * The Initial Developer of the Original Code is * Netscape Communications Corporation. * Portions created by the Initial Developer are Copyright (C) 2001 * the Initial Developer. All Rights Reserved. * * Contributor(s): * Stuart Parmenter * Federico Mena-Quintero * Joe Drew * Bobby Holley * * Alternatively, the contents of this file may be used under the terms of * either the GNU General Public License Version 2 or later (the "GPL"), or * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"), * in which case the provisions of the GPL or the LGPL are applicable instead * of those above. If you wish to allow use of your version of this file only * under the terms of either the GPL or the LGPL, and not to allow others to * use your version of this file under the terms of the MPL, indicate your * decision by deleting the provisions above and replace them with the notice * and other provisions required by the GPL or the LGPL. If you do not delete * the provisions above, a recipient may use your version of this file under * the terms of any one of the MPL, the GPL or the LGPL. * * ***** END LICENSE BLOCK ***** */ #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" %} [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); /** * 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(74c63935-b54f-43a4-9449-2e9c815e3bef)] interface imgIContainer : nsISupports { /** * The width of the container rectangle. */ readonly attribute PRInt32 width; /** * The height of the container rectangle. */ readonly attribute PRInt32 height; /** * Whether this image is animated. */ 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. */ const long FLAG_NONE = 0x0; const long FLAG_SYNC_DECODE = 0x1; /** * 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 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. * * @param aWhichFrame Frame specifier of the FRAME_* variety. * @param aFlags Flags of the FLAG_* variety */ [noscript] gfxImageSurface copyFrame(in PRUint32 aWhichFrame, in PRUint32 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 PRUint32 aWhichFrame, [const] in nsIntRect aRect, in PRUint32 aFlags); /** * Draw the current frame on to the context specified. * * @param aContext The Thebex 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. Image will be * automatically tiled as necessary. * @param aSubimage The area of the image, in pixels, that we are allowed to * sample from. * @param aFlags Flags of the FLAG_* variety */ [noscript] void draw(in gfxContext aContext, in gfxGraphicsFilter aFilter, in gfxMatrix aUserSpaceToImageSpace, in gfxRect aFill, in nsIntRect aSubimage, in PRUint32 aFlags); /* * 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(); /************ Internal libpr0n use only below here. *****************/ /** * 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 INIT_FLAG_NONE = 0x0; const long INIT_FLAG_DISCARDABLE = 0x1; const long INIT_FLAG_DECODE_ON_DRAW = 0x2; const long INIT_FLAG_MULTIPART = 0x4; /** * Creates a new image container. * * @param aObserver Observer to send decoder and animation notifications to. * @param aMimeType The mimetype of the image. * @param aFlags Initialization flags of the INIT_FLAG_* variety. */ void init(in imgIDecoderObserver aObserver, in string aMimeType, in PRUint32 aFlags); /** * "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. */ const long kDisposeClearAll = -1; // Clear the whole image, revealing // what was there before the gif displayed const long kDisposeNotSpecified = 0; // Leave frame, let new frame draw on top const long kDisposeKeep = 1; // Leave frame, let new frame draw on top const long kDisposeClear = 2; // Clear the frame's area, revealing bg const long kDisposeRestorePrevious = 3; // Restore the previous (composited) frame /* * "Blend" method indicates how the current image is combined with the * previous image. */ const long kBlendSource = 0; // All color components of the frame, including alpha, // overwrite the current contents of the frame's // output buffer region const long kBlendOver = 1; // The frame should be composited onto the output buffer // based on its alpha, using a simple OVER operation /** * 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; /** * 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. */ [noscript] void getCurrentFrameRect(in nsIntRect aFrameRect); /** * The index of the current frame that would be drawn if the image was to be * drawn now. */ readonly attribute unsigned long currentFrameIndex; /** * The total number of frames in this image. */ readonly attribute unsigned long numFrames; /** * The size, in bytes, occupied by the significant data portions of the image. * This includes both compressed source data and decoded frames. */ readonly attribute unsigned long dataSize; 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); /** * 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. */ [noscript] void setSize(in long aWidth, in long aHeight); /** * Create or re-use a frame at index aFrameNum. It is an error to call this with aFrameNum not in the range [0, numFrames]. */ [noscript] 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); /** * Adds to the end of the list of frames. */ [noscript] 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); [noscript] 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); [noscript] void frameUpdated(in unsigned long framenum, in nsIntRect aNewRect); /* notification when the current frame is done decoding */ void endFrameDecode(in unsigned long framenumber); /* notification that the entire image has been decoded */ void decodingComplete(); void startAnimation(); void stopAnimation(); void resetAnimation(); /** * number of times to loop the image. * @note -1 means forever. */ attribute long loopCount; /* Add compressed source data to the imgContainer. * * The decoder will use this data, either immediately or at draw time, do * decode the image. */ [noscript] void addSourceData([array, size_is(aCount), const] in char data, in unsigned long aCount); /* Called after the all the source data has been added with addSourceData. */ [noscript] void sourceDataComplete(); /* Called for multipart images when there's a new source image to add. */ [noscript] void newSourceData(); };