image/imgIContainer.idl

   1 /** -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  *
   3  * This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #include "nsISupports.idl"
   8
   9 webidl Document;
  10
  11 %{C++
  12 #include "ImgDrawResult.h"
  13 #include "gfxPoint.h"
  14 #include "mozilla/gfx/Types.h"
  15 #include "mozilla/AspectRatio.h"
  16 #include "mozilla/Maybe.h"
  17 #include "mozilla/RefPtr.h"
  18 #include "nsRect.h"
  19 #include "nsSize.h"
  20 #include "nsTArray.h"
  21 #include "limits.h"
  22
  23 class gfxContext;
  24
  25 namespace mozilla {
  26 struct AspectRatio;
  27
  28 namespace gfx {
  29 class SourceSurface;
  30 }
  31
  32 class WindowRenderer;
  33 namespace layers {
  34 class ImageContainer;
  35 }
  36 }
  37
  38 class nsIFrame;
  39
  40 namespace mozilla {
  41 class TimeStamp;
  42 class SVGImageContext;
  43 struct MediaFeatureChange;
  44 }
  45
  46 namespace mozilla {
  47 namespace image {
  48
  49 class ImageRegion;
  50 class ImageIntRegion;
  51 struct Orientation;
  52 struct Resolution;
  53
  54 }
  55 }
  56
  57 %}
  58
  59 native MaybeAspectRatio(mozilla::Maybe<mozilla::AspectRatio>);
  60 native ImgDrawResult(mozilla::image::ImgDrawResult);
  61 [ptr] native gfxContext(gfxContext);
  62 [ref] native gfxMatrix(gfxMatrix);
  63 [ref] native gfxRect(gfxRect);
  64 [ref] native gfxSize(gfxSize);
  65 native SamplingFilter(mozilla::gfx::SamplingFilter);
  66 [ref] native nsIntRect(nsIntRect);
  67 native nsIntRectByVal(nsIntRect);
  68 [ref] native nsIntSize(nsIntSize);
  69 native nsSize(nsSize);
  70 [ptr] native nsIFrame(nsIFrame);
  71 native TempRefImageContainer(already_AddRefed<mozilla::layers::ImageContainer>);
  72 [ptr] native ImageContainer(mozilla::layers::ImageContainer);
  73 [ref] native ImageRegion(mozilla::image::ImageRegion);
  74 [ptr] native WindowRenderer(mozilla::WindowRenderer);
  75 native Orientation(mozilla::image::Orientation);
  76 native ImageResolution(mozilla::image::Resolution);
  77 [ref] native TimeStamp(mozilla::TimeStamp);
  78 [ref] native MaybeSVGImageContext(mozilla::Maybe<mozilla::SVGImageContext>);
  79 [ref] native MaybeImageIntRegion(mozilla::Maybe<mozilla::image::ImageIntRegion>);
  80 native TempRefSourceSurface(already_AddRefed<mozilla::gfx::SourceSurface>);
  81 native TempRefImgIContainer(already_AddRefed<imgIContainer>);
  82 native nsIntSizeByVal(nsIntSize);
  83
  84
  85 /**
  86  * imgIContainer is the interface that represents an image. It allows
  87  * access to frames as Thebes surfaces. It also allows drawing of images
  88  * onto Thebes contexts.
  89  *
  90  * Internally, imgIContainer also manages animation of images.
  91  */
  92 [scriptable, builtinclass, uuid(a8dbee24-ff86-4755-b40e-51175caf31af)]
  93 interface imgIContainer : nsISupports
  94 {
  95   /**
  96    * The width of the container rectangle.  In the case of any error,
  97    * zero is returned, and an exception will be thrown.
  98    */
  99   readonly attribute int32_t width;
 100
 101   /**
 102    * The height of the container rectangle.  In the case of any error,
 103    * zero is returned, and an exception will be thrown.
 104    */
 105   readonly attribute int32_t height;
 106
 107   /**
 108    * The intrinsic size of this image in appunits. If the image has no intrinsic
 109    * size in a dimension, -1 will be returned for that dimension. In the case of
 110    * any error, an exception will be thrown.
 111    */
 112   [noscript] readonly attribute nsSize intrinsicSize;
 113
 114   /**
 115    * The (dimensionless) intrinsic ratio of this image. In the case of any
 116    * error, Nothing() will be returned.
 117    */
 118   [notxpcom, nostdcall] readonly attribute MaybeAspectRatio intrinsicRatio;
 119
 120   /**
 121    * The x coordinate of the image's hotspot, or 0 if there is no hotspot.
 122    */
 123   readonly attribute int32_t hotspotX;
 124
 125   /**
 126    * The y coordinate of the image's hotspot, or 0 if there is no hotspot.
 127    */
 128   readonly attribute int32_t hotspotY;
 129
 130   /**
 131    * Given a size at which this image will be displayed, and the drawing
 132    * parameters affecting how it will be drawn, returns the image size which
 133    * should be used to draw to produce the highest quality result. This is the
 134    * appropriate size, for example, to use as an input to the pixel snapping
 135    * algorithm.
 136    *
 137    * For best results the size returned by this method should not be cached. It
 138    * can change over time due to changes in the internal state of the image.
 139    *
 140    * @param aDest The size of the destination rect into which this image will be
 141    *              drawn, in device pixels.
 142    * @param aWhichFrame Frame specifier of the FRAME_* variety.
 143    * @param aSamplingFilter The filter to be used if we're scaling the image.
 144    * @param aFlags Flags of the FLAG_* variety
 145    */
 146   [notxpcom, nostdcall] nsIntSizeByVal
 147   optimalImageSizeForDest([const] in gfxSize aDest, in uint32_t aWhichFrame,
 148                           in SamplingFilter aSamplingFilter, in uint32_t aFlags);
 149
 150   /**
 151     * Enumerated values for the 'type' attribute (below).
 152     */
 153   const unsigned short TYPE_RASTER = 0;
 154   const unsigned short TYPE_VECTOR = 1;
 155   const unsigned short TYPE_REQUEST = 2;
 156
 157   /**
 158    * The type of this image (one of the TYPE_* values above).
 159    */
 160   [infallible] readonly attribute unsigned short type;
 161
 162   /**
 163    * Whether this image is animated. You can only be guaranteed that querying
 164    * this will not throw if STATUS_DECODE_COMPLETE is set on the imgIRequest.
 165    *
 166    * @throws NS_ERROR_NOT_AVAILABLE if the animated state cannot be determined.
 167    */
 168   readonly attribute boolean animated;
 169
 170   /**
 171    * Producer ID for image containers created by this image.
 172    */
 173   [infallible] readonly attribute unsigned long producerId;
 174
 175   /**
 176    * Flags for imgIContainer operations.
 177    *
 178    * Meanings:
 179    *
 180    * FLAG_NONE: Lack of flags.
 181    *
 182    * FLAG_SYNC_DECODE: Forces synchronous/non-progressive decode of all
 183    * available data before the call returns.
 184    *
 185    * FLAG_SYNC_DECODE_IF_FAST: Like FLAG_SYNC_DECODE, but requests a sync decode
 186    * be performed only if ImageLib estimates it can be completed very quickly.
 187    *
 188    * FLAG_ASYNC_NOTIFY: Send notifications asynchronously, even if we decode
 189    * synchronously because of FLAG_SYNC_DECODE or FLAG_SYNC_DECODE_IF_FAST.
 190    *
 191    * FLAG_DECODE_NO_PREMULTIPLY_ALPHA: Do not premultiply alpha if
 192    * it's not already premultiplied in the image data.
 193    *
 194    * FLAG_DECODE_NO_COLORSPACE_CONVERSION: Do not do any colorspace conversion;
 195    * ignore any embedded profiles, and don't convert to any particular
 196    * destination space.
 197    *
 198    * FLAG_CLAMP: Extend the image to the fill area by clamping image sample
 199    * coordinates instead of by tiling. This only affects 'draw'.
 200    *
 201    * FLAG_HIGH_QUALITY_SCALING: A hint as to whether this image should be
 202    * scaled using the high quality scaler. Do not set this if not drawing to
 203    * a window or not listening to invalidations. Passing this flag will do two
 204    * things: 1) request a decode of the image at the size asked for by the
 205    * caller if one isn't already started or complete, and 2) allows a decoded
 206    * frame of any size (it could be neither the requested size, nor the
 207    * intrinsic size) to be substituted.
 208    *
 209    * FLAG_BYPASS_SURFACE_CACHE: Forces drawing to happen rather than taking
 210    * cached rendering from the surface cache. This is used when we are printing,
 211    * for example, where we want the vector commands from VectorImages to end up
 212    * in the PDF output rather than a cached rendering at screen resolution.
 213    *
 214    * FLAG_FORCE_PRESERVEASPECTRATIO_NONE: Force scaling this image
 215    * non-uniformly if necessary. This flag is for vector image only. A raster
 216    * image should ignore this flag. While drawing a vector image with this
 217    * flag, do not force uniform scaling even if its root <svg> node has a
 218    * preserveAspectRatio attribute that would otherwise require uniform
 219    * scaling , such as xMinYMin/ xMidYMin. Always scale the graphic content of
 220    * the given image non-uniformly if necessary such that the image's
 221    * viewBox (if specified or implied by height/width attributes) exactly
 222    * matches the viewport rectangle.
 223    *
 224    * FLAG_FORCE_UNIFORM_SCALING: Signal to ClippedImage::OptimalSizeForDest that
 225    * its returned size can only scale the image's size *uniformly* (by the same
 226    * factor in each dimension). We need this flag when painting border-image
 227    * section with SVG image source-data, if the SVG image has no viewBox and no
 228    * intrinsic size. In such a case, we synthesize a viewport for the SVG image
 229    * (a "window into SVG space") based on the border image area, and we need to
 230    * be sure we don't subsequently scale that viewport in a way that distorts
 231    * its contents by stretching them more in one dimension than the other.
 232    *
 233    * FLAG_AVOID_REDECODE_FOR_SIZE: If there is already a raster surface
 234    * available for this image, but it is not the same size as requested, skip
 235    * starting a new decode for said size.
 236    *
 237    * FLAG_DECODE_TO_SRGB_COLORSPACE: Instead of converting the colorspace to
 238    * the display's colorspace, use sRGB.
 239    *
 240    * FLAG_RECORD_BLOB: Instead of rasterizing an SVG image on the main thread,
 241    * record the drawing commands using blob images.
 242    */
 243   const unsigned long FLAG_NONE                            = 0x0;
 244   const unsigned long FLAG_SYNC_DECODE                     = 0x1;
 245   const unsigned long FLAG_SYNC_DECODE_IF_FAST             = 0x2;
 246   const unsigned long FLAG_ASYNC_NOTIFY                    = 0x4;
 247   const unsigned long FLAG_DECODE_NO_PREMULTIPLY_ALPHA     = 0x8;
 248   const unsigned long FLAG_DECODE_NO_COLORSPACE_CONVERSION = 0x10;
 249   const unsigned long FLAG_CLAMP                           = 0x20;
 250   const unsigned long FLAG_HIGH_QUALITY_SCALING            = 0x40;
 251   const unsigned long FLAG_BYPASS_SURFACE_CACHE            = 0x80;
 252   const unsigned long FLAG_FORCE_PRESERVEASPECTRATIO_NONE  = 0x100;
 253   const unsigned long FLAG_FORCE_UNIFORM_SCALING           = 0x200;
 254   const unsigned long FLAG_AVOID_REDECODE_FOR_SIZE         = 0x400;
 255   const unsigned long FLAG_DECODE_TO_SRGB_COLORSPACE       = 0x800;
 256   const unsigned long FLAG_RECORD_BLOB                     = 0x1000;
 257
 258   /**
 259    * A constant specifying the default set of decode flags (i.e., the default
 260    * values for FLAG_DECODE_*).
 261    */
 262   const unsigned long DECODE_FLAGS_DEFAULT = 0;
 263
 264   /**
 265    * A constant specifying the decode flags recommended to be used when
 266    * re-encoding an image, or with the clipboard.
 267    */
 268   const unsigned long DECODE_FLAGS_FOR_REENCODE =
 269       FLAG_DECODE_NO_PREMULTIPLY_ALPHA | FLAG_DECODE_TO_SRGB_COLORSPACE;
 270
 271   /**
 272     * Constants for specifying various "special" frames.
 273     *
 274     * FRAME_FIRST: The first frame
 275     * FRAME_CURRENT: The current frame
 276     *
 277     * FRAME_MAX_VALUE should be set to the value of the maximum constant above,
 278     * as it is used for ensuring that a valid value was passed in.
 279     */
 280   const unsigned long FRAME_FIRST = 0;
 281   const unsigned long FRAME_CURRENT = 1;
 282   const unsigned long FRAME_MAX_VALUE = 1;
 283
 284   /**
 285    * Get a surface for the given frame. This may be a platform-native,
 286    * optimized surface, so you cannot inspect its pixel data. If you
 287    * need that, use SourceSurface::GetDataSurface.
 288    *
 289    * @param aWhichFrame Frame specifier of the FRAME_* variety.
 290    * @param aFlags Flags of the FLAG_* variety
 291    */
 292   [noscript, notxpcom] TempRefSourceSurface getFrame(in uint32_t aWhichFrame,
 293                                                      in uint32_t aFlags);
 294
 295   /**
 296    * Get a surface for the given frame at the specified size. Matching the
 297    * requested size is best effort; it's not guaranteed that the surface you get
 298    * will be a perfect match. (Some reasons you may get a surface of a different
 299    * size include: if you requested upscaling, if downscale-during-decode is
 300    * disabled, or if you didn't request the first frame.)
 301    *
 302    * @param aSize The desired size.
 303    * @param aWhichFrame Frame specifier of the FRAME_* variety.
 304    * @param aFlags Flags of the FLAG_* variety
 305    */
 306   [noscript, notxpcom] TempRefSourceSurface getFrameAtSize([const] in nsIntSize aSize,
 307                                                            in uint32_t aWhichFrame,
 308                                                            in uint32_t aFlags);
 309
 310   /**
 311    * Returns true if this image will draw opaquely right now if asked to draw
 312    * with FLAG_HIGH_QUALITY_SCALING and otherwise default flags. If this image
 313    * (when decoded) is opaque but no decoded frames are available then
 314    * willDrawOpaqueNow will return false.
 315    */
 316   [noscript, notxpcom] boolean willDrawOpaqueNow();
 317
 318   /**
 319    * @return true if getImageContainer() is expected to return a valid
 320    *         ImageContainer when passed the given @Renderer and @Flags
 321    *         parameters.
 322    */
 323   [noscript, notxpcom] boolean isImageContainerAvailable(in WindowRenderer aRenderer,
 324                                                          in uint32_t aFlags);
 325
 326   /**
 327    * Attempts to create an ImageContainer (and Image) containing the current
 328    * frame at the given size. Match the requested size is best effort; it's
 329    * not guaranteed that the surface you get will be a perfect match. (Some
 330    * reasons you may get a surface of a different size include: if you
 331    * requested upscaling, or if downscale-during-decode is disabled.)
 332    *
 333    * Avoid calling this unless you're actually going to layerize this image.
 334    *
 335    * @param aRenderer The WindowRenderer which will be used to render the
 336    *                  ImageContainer.
 337    * @param aSVGContext If specified, SVG-related rendering context, such as
 338    *                    overridden attributes on the image document's root <svg>
 339    *                    node, and the size of the viewport that the full image
 340    *                    would occupy. Ignored for raster images.
 341    * @param aFlags Decoding / drawing flags (in other words, FLAG_* flags).
 342    *               Currently only FLAG_SYNC_DECODE and FLAG_SYNC_DECODE_IF_FAST
 343    *               are supported.
 344    * @param aContainer Return value for ImageContainer for the current frame.
 345    *                   May be null depending on the draw result.
 346    * @return The draw result for the current frame.
 347    */
 348   [noscript, notxpcom] ImgDrawResult getImageContainerAtSize(in WindowRenderer aRenderer,
 349                                                              [const] in nsIntSize aSize,
 350                                                              [const] in MaybeSVGImageContext aSVGContext,
 351                                                              [const] in MaybeImageIntRegion aRegion,
 352                                                              in uint32_t aFlags,
 353                                                              out ImageContainer aOutContainer);
 354
 355   /**
 356    * Draw the requested frame of this image onto the context specified.
 357    *
 358    * Drawing an image involves scaling it to a certain size (which may be
 359    * implemented as a "smart" scale by substituting an HQ-scaled frame or
 360    * rendering at a high DPI), and then selecting a region of that image to
 361    * draw. That region is drawn onto the graphics context and in the process
 362    * transformed by the context matrix, which determines the final area that is
 363    * filled. The basic process looks like this:
 364    *
 365    *                           +------------------+
 366    *                           |      Image       |
 367    *                           |                  |
 368    *                           | intrinsic width  |
 369    *                           |        X         |
 370    *                           | intrinsic height |
 371    *                           +------------------+
 372    *                          /                    \
 373    *                         /                      \
 374    *                        /    (scale to aSize)    \
 375    *                       /                          \
 376    *                      +----------------------------+
 377    *                      |                            |
 378    *                      |        Scaled Image        |
 379    *                      | aSize.width X aSize.height |
 380    *                      |                            |
 381    *                      |       +---------+          |
 382    *                      |       | aRegion |          |
 383    *                      |       +---------+          |
 384    *                      +-------(---------(----------+
 385    *                              |         |
 386    *                             /           \
 387    *                            |  (transform |
 388    *                           /  by aContext  \
 389    *                          |     matrix)     |
 390    *                         /                   \
 391    *                        +---------------------+
 392    *                        |                     |
 393    *                        |      Fill Rect      |
 394    *                        |                     |
 395    *                        +---------------------+
 396    *
 397    * The region may extend outside of the scaled image's boundaries. It's
 398    * actually a region in tiled image space, which is formed by tiling the
 399    * scaled image infinitely in every direction. Drawing with a region larger
 400    * than the scaled image thus causes the filled area to contain multiple tiled
 401    * copies of the image, which looks like this:
 402    *
 403    *           ....................................................
 404    *           :                :                :                :
 405    *           :      Tile      :      Tile      :      Tile      :
 406    *           :        +------------[aRegion]------------+       :
 407    *           :........|.......:................:........|.......:
 408    *           :        |       :                :        |       :
 409    *           :      Ti|le     :  Scaled Image  :      Ti|le     :
 410    *           :        |       :                :        |       :
 411    *           :........|.......:................:........|.......:
 412    *           :        +---------------------------------+       :
 413    *           :      Ti|le     :      Tile      :      Ti|le     :
 414    *           :       /        :                :         \      :
 415    *           :......(.........:................:..........).....:
 416    *                  |                                     |
 417    *                 /                                       \
 418    *                |      (transform by aContext matrix)     |
 419    *               /                                           \
 420    *              +---------------------------------------------+
 421    *              |     :                                 :     |
 422    *              |.....:.................................:.....|
 423    *              |     :                                 :     |
 424    *              |     :           Tiled Fill            :     |
 425    *              |     :                                 :     |
 426    *              |.....:.................................:.....|
 427    *              |     :                                 :     |
 428    *              +---------------------------------------------+
 429    *
 430    *
 431    * @param aContext The Thebes context to draw the image to.
 432    * @param aSize The size to which the image should be scaled before drawing.
 433    *              This requirement may be satisfied using HQ scaled frames,
 434    *              selecting from different resolution layers, drawing at a
 435    *              higher DPI, or just performing additional scaling on the
 436    *              graphics context. Callers can use optimalImageSizeForDest()
 437    *              to determine the best choice for this parameter if they have
 438    *              no special size requirements.
 439    * @param aRegion The region in tiled image space which will be drawn onto the
 440    *                graphics context. aRegion is in the coordinate space of the
 441    *                image after it has been scaled to aSize - that is, the image
 442    *                is scaled first, and then aRegion is applied. When aFlags
 443    *                includes FLAG_CLAMP, the image will be extended to this area
 444    *                by clamping image sample coordinates. Otherwise, the image
 445    *                will be automatically tiled as necessary. aRegion can also
 446    *                optionally contain a second region which restricts the set
 447    *                of pixels we're allowed to sample from when drawing; this
 448    *                is only of use to callers which need to draw with pixel
 449    *                snapping.
 450    * @param aWhichFrame Frame specifier of the FRAME_* variety.
 451    * @param aSamplingFilter The filter to be used if we're scaling the image.
 452    * @param aSVGContext If specified, SVG-related rendering context, such as
 453    *                    overridden attributes on the image document's root <svg>
 454    *                    node, and the size of the viewport that the full image
 455    *                    would occupy. Ignored for raster images.
 456    * @param aFlags Flags of the FLAG_* variety
 457    * @return A ImgDrawResult value indicating whether and to what degree the
 458    *         drawing operation was successful.
 459    */
 460   [noscript, notxpcom] ImgDrawResult
 461   draw(in gfxContext aContext,
 462        [const] in nsIntSize aSize,
 463        [const] in ImageRegion aRegion,
 464        in uint32_t aWhichFrame,
 465        in SamplingFilter aSamplingFilter,
 466        [const] in MaybeSVGImageContext aSVGContext,
 467        in uint32_t aFlags,
 468        in float aOpacity);
 469
 470   /*
 471    * Ensures that an image is decoding. Calling this function guarantees that
 472    * the image will at some point fire off decode notifications. Images that
 473    * can be decoded "quickly" according to some heuristic will be decoded
 474    * synchronously.
 475    *
 476    * @param aFlags Flags of the FLAG_* variety. Only FLAG_ASYNC_NOTIFY
 477    *               is accepted; all others are ignored.
 478    * @param aWhichFrame Frame specifier of the FRAME_* variety.
 479    */
 480   [noscript] void startDecoding(in uint32_t aFlags, in uint32_t aWhichFrame);
 481
 482 %{C++
 483   nsresult StartDecoding(uint32_t aFlags) {
 484     return StartDecoding(aFlags, FRAME_CURRENT);
 485   }
 486 %}
 487
 488   /*
 489    * Exactly like startDecoding above except returns whether the current frame
 490    * of the image is complete or not.
 491    *
 492    * @param aFlags Flags of the FLAG_* variety. Only FLAG_ASYNC_NOTIFY
 493    *               is accepted; all others are ignored.
 494    * @param aWhichFrame Frame specifier of the FRAME_* variety.
 495    */
 496   [noscript, notxpcom] boolean startDecodingWithResult(in uint32_t aFlags, in uint32_t aWhichFrame);
 497
 498 %{C++
 499   bool StartDecodingWithResult(uint32_t aFlags) {
 500     return StartDecodingWithResult(aFlags, FRAME_CURRENT);
 501   }
 502 %}
 503
 504   /*
 505    * This method triggers decoding for an image, but unlike startDecoding() it
 506    * enables the caller to provide more detailed information about the decode
 507    * request.
 508    *
 509    * @param aFlags Flags of the FLAG_* variety.
 510    * @param aWhichFrame Frame specifier of the FRAME_* variety.
 511    * @return DECODE_SURFACE_AVAILABLE if is a surface that satisfies the
 512    *         request and it is fully decoded.
 513    *         DECODE_REQUESTED if we requested a decode.
 514    *         DECODE_REQUEST_FAILED if we failed to request a decode. This means
 515    *         that either there is an error in the image or we cannot allocate a
 516    *         surface that big.
 517    */
 518    cenum DecodeResult : 8 {
 519      DECODE_SURFACE_AVAILABLE = 0,
 520      DECODE_REQUESTED = 1,
 521      DECODE_REQUEST_FAILED = 2
 522    };
 523   [noscript, notxpcom] imgIContainer_DecodeResult requestDecodeWithResult(in uint32_t aFlags, in uint32_t aWhichFrame);
 524
 525 %{C++
 526   DecodeResult RequestDecodeWithResult(uint32_t aFlags) {
 527     return RequestDecodeWithResult(aFlags, FRAME_CURRENT);
 528   }
 529 %}
 530
 531   /*
 532    * This method triggers decoding for an image, but unlike startDecoding() it
 533    * enables the caller to provide more detailed information about the decode
 534    * request.
 535    *
 536    * @param aSize The size to which the image should be scaled while decoding,
 537    *              if possible. If the image cannot be scaled to this size while
 538    *              being decoded, it will be decoded at its intrinsic size.
 539    * @param aFlags Flags of the FLAG_* variety.
 540    * @param aWhichFrame Frame specifier of the FRAME_* variety.
 541    */
 542   [noscript] void requestDecodeForSize([const] in nsIntSize aSize,
 543                                        in uint32_t aFlags,
 544                                        in uint32_t aWhichFrame);
 545
 546 %{C++
 547   nsresult RequestDecodeForSize(const nsIntSize& aSize, uint32_t aFlags) {
 548     return RequestDecodeForSize(aSize, aFlags, FRAME_CURRENT);
 549   }
 550 %}
 551
 552   /**
 553     * Increments the lock count on the image. An image will not be discarded
 554     * as long as the lock count is nonzero. Note that it is still possible for
 555     * the image to be undecoded if decode-on-draw is enabled and the image
 556     * was never drawn.
 557     *
 558     * Upon instantiation images have a lock count of zero.
 559     */
 560   void lockImage();
 561
 562   /**
 563     * Decreases the lock count on the image. If the lock count drops to zero,
 564     * the image is allowed to discard its frame data to save memory.
 565     *
 566     * Upon instantiation images have a lock count of zero. It is an error to
 567     * call this method without first having made a matching lockImage() call.
 568     * In other words, the lock count is not allowed to be negative.
 569     */
 570   void unlockImage();
 571
 572   /**
 573    * If this image is unlocked, discard its decoded data.  If the image is
 574    * locked or has already been discarded, do nothing.
 575    */
 576   void requestDiscard();
 577
 578   /**
 579     * Indicates that this imgIContainer has been triggered to update
 580     * its internal animation state. Likely this should only be called
 581     * from within nsImageFrame or objects of similar type.
 582     */
 583   [notxpcom] void requestRefresh([const] in TimeStamp aTime);
 584
 585   /**
 586    * Animation mode Constants
 587    *   0 = normal
 588    *   1 = don't animate
 589    *   2 = loop once
 590    */
 591   const short kNormalAnimMode   = 0;
 592   const short kDontAnimMode     = 1;
 593   const short kLoopOnceAnimMode = 2;
 594
 595   attribute unsigned short animationMode;
 596
 597   /* Methods to control animation */
 598   void resetAnimation();
 599
 600   /*
 601    * Returns an index for the requested animation frame (either FRAME_FIRST or
 602    * FRAME_CURRENT).
 603    *
 604    * The units of the index aren't specified, and may vary between different
 605    * types of images. What you can rely on is that on all occasions when
 606    * getFrameIndex(FRAME_CURRENT) returns a certain value,
 607    * draw(..FRAME_CURRENT..) will draw the same frame. The same holds for
 608    * FRAME_FIRST as well.
 609    *
 610    * @param aWhichFrame Frame specifier of the FRAME_* variety.
 611    */
 612   [notxpcom] float getFrameIndex(in uint32_t aWhichFrame);
 613
 614   /*
 615    * Returns the inherent orientation of the image, as described in the image's
 616    * metadata (e.g. EXIF).
 617    */
 618   [notxpcom] Orientation getOrientation();
 619
 620   /*
 621    * Returns the intrinsic resolution of the image, or 1.0 if the image doesn't
 622    * declare any.
 623    */
 624   [notxpcom] ImageResolution getResolution();
 625
 626   /*
 627    * Returns the delay, in ms, between the first and second frame. If this
 628    * returns 0, there is no delay between first and second frame (i.e., this
 629    * image could render differently whenever it draws).
 630    *
 631    * If this image is not animated, or not known to be animated (see attribute
 632    * animated), returns -1.
 633    */
 634   [notxpcom] int32_t getFirstFrameDelay();
 635
 636   /*
 637    * If this is an animated image that hasn't started animating already, this
 638    * sets the animation's start time to the indicated time.
 639    *
 640    * This has no effect if the image isn't animated or it has started animating
 641    * already; it also has no effect if the image format doesn't care about
 642    * animation start time.
 643    *
 644    * In all cases, animation does not actually begin until startAnimation(),
 645    * resetAnimation(), or requestRefresh() is called for the first time.
 646    */
 647   [notxpcom] void setAnimationStartTime([const] in TimeStamp aTime);
 648
 649   /*
 650    * Given an invalidation rect in the coordinate system used by the decoder,
 651    * returns an invalidation rect in image space.
 652    *
 653    * This is the identity transformation in most cases, but the result can
 654    * differ if the image is wrapped by an ImageWrapper that changes its size
 655    * or orientation.
 656    */
 657   [notxpcom] nsIntRectByVal
 658   getImageSpaceInvalidationRect([const] in nsIntRect aRect);
 659
 660   /*
 661    * Removes any ImageWrappers and returns the unwrapped base image.
 662    */
 663   [notxpcom, nostdcall] TempRefImgIContainer unwrap();
 664
 665   /*
 666    * Propagate the use counters (if any) from this container to the passed in
 667    * document.
 668    */
 669   [noscript, notxpcom] void propagateUseCounters(in Document aReferencingDocument);
 670
 671   %{C++
 672   /*
 673    * Called when media feature values that apply to all documents (such as
 674    * those based on system metrics) have changed.  If this image is a type
 675    * that can respond to media queries (i.e., an SVG image), this function
 676    * is overridden to handle restyling and invalidating the image.
 677    */
 678   virtual void MediaFeatureValuesChangedAllDocuments(const mozilla::MediaFeatureChange& aChange) {}
 679
 680   /*
 681    * Get the set of sizes the image can decode to natively.
 682    */
 683   virtual nsresult GetNativeSizes(nsTArray<nsIntSize>& aNativeSizes) const = 0;
 684
 685   virtual size_t GetNativeSizesLength() const = 0;
 686   %}
 687 };