DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Mercurial (dcc6d7a0dc00)

VCS Links

Line Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521
/** -*- 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"

%{C++
#include "DrawResult.h"
#include "gfxContext.h"
#include "gfxMatrix.h"
#include "gfxRect.h"
#include "mozilla/gfx/2D.h"
#include "mozilla/Maybe.h"
#include "mozilla/RefPtr.h"
#include "nsRect.h"
#include "nsSize.h"
#include "limits.h"

class nsIDocument;

namespace mozilla {
namespace layers {
class LayerManager;
class ImageContainer;
}
}

class nsIFrame;

namespace mozilla {
class TimeStamp;
class SVGImageContext;
}

namespace mozilla {
namespace image {

class ImageRegion;
struct Orientation;

}
}

%}

native DrawResult(mozilla::image::DrawResult);
[ptr] native gfxContext(gfxContext);
[ref] native gfxMatrix(gfxMatrix);
[ref] native gfxRect(gfxRect);
[ref] native gfxSize(gfxSize);
native Filter(mozilla::gfx::Filter);
[ref] native nsIntRect(nsIntRect);
native nsIntRectByVal(nsIntRect);
[ref] native nsIntSize(nsIntSize);
native nsSize(nsSize);
[ptr] native nsIFrame(nsIFrame);
native TempRefImageContainer(already_AddRefed<mozilla::layers::ImageContainer>);
[ref] native ImageRegion(mozilla::image::ImageRegion);
[ptr] native LayerManager(mozilla::layers::LayerManager);
native Orientation(mozilla::image::Orientation);
[ref] native TimeStamp(mozilla::TimeStamp);
[ref] native MaybeSVGImageContext(mozilla::Maybe<mozilla::SVGImageContext>);
native TempRefSourceSurface(already_AddRefed<mozilla::gfx::SourceSurface>);
native TempRefImgIContainer(already_AddRefed<imgIContainer>);
native nsIntSizeByVal(nsIntSize);
[ptr] native nsIDocument(nsIDocument);


/**
 * imgIContainer is the interface that represents an image. It allows
 * access to frames as Thebes surfaces. It also allows drawing of images
 * onto Thebes contexts.
 *
 * Internally, imgIContainer also manages animation of images.
 */
[scriptable, builtinclass, uuid(a8dbee24-ff86-4755-b40e-51175caf31af)]
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;

  /**
   * The intrinsic size of this image in appunits. If the image has no intrinsic
   * size in a dimension, -1 will be returned for that dimension. In the case of
   * any error, an exception will be thrown.
   */
  [noscript] readonly attribute nsSize intrinsicSize;

  /**
   * The (dimensionless) intrinsic ratio of this image. In the case of any
   * error, an exception will be thrown.
   */
  [noscript] readonly attribute nsSize intrinsicRatio;

  /**
   * Given a size at which this image will be displayed, and the drawing
   * parameters affecting how it will be drawn, returns the image size which
   * should be used to draw to produce the highest quality result. This is the
   * appropriate size, for example, to use as an input to the pixel snapping
   * algorithm.
   *
   * For best results the size returned by this method should not be cached. It
   * can change over time due to changes in the internal state of the image.
   *
   * @param aDest The size of the destination rect into which this image will be
   *              drawn, in device pixels.
   * @param aWhichFrame Frame specifier of the FRAME_* variety.
   * @param aFilter The filter to be used if we're scaling the image.
   * @param aFlags Flags of the FLAG_* variety
   */
  [notxpcom, nostdcall] nsIntSizeByVal
  optimalImageSizeForDest([const] in gfxSize aDest, in uint32_t aWhichFrame,
                          in Filter aFilter, in uint32_t aFlags);

  /**
    * 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).
   */
  [infallible] readonly attribute unsigned short type;

  /**
   * 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;

  /**
   * 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.
   *
   * FLAG_SYNC_DECODE_IF_FAST: Like FLAG_SYNC_DECODE, but requests a sync decode
   * be performed only if ImageLib estimates it can be completed very quickly.
   *
   * FLAG_ASYNC_NOTIFY: Send notifications asynchronously, even if we decode
   * synchronously beause of FLAG_SYNC_DECODE or FLAG_SYNC_DECODE_IF_FAST.
   *
   * 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'.
   *
   * FLAG_HIGH_QUALITY_SCALING: A hint as to whether this image should be
   * scaled using the high quality scaler. Do not set this if not drawing to
   * a window or not listening to invalidations.
   *
   * FLAG_WANT_DATA_SURFACE: Can be passed to GetFrame when the caller wants a
   * DataSourceSurface instead of a hardware accelerated surface. This can be
   * important for performance (by avoiding an upload to/readback from the GPU)
   * when the caller knows they want a SourceSurface of type DATA.
   *
   * FLAG_BYPASS_SURFACE_CACHE: Forces drawing to happen rather than taking
   * cached rendering from the surface cache. This is used when we are printing,
   * for example, where we want the vector commands from VectorImages to end up
   * in the PDF output rather than a cached rendering at screen resolution.
   */
  const unsigned long FLAG_NONE                            = 0x0;
  const unsigned long FLAG_SYNC_DECODE                     = 0x1;
  const unsigned long FLAG_SYNC_DECODE_IF_FAST             = 0x2;
  const unsigned long FLAG_ASYNC_NOTIFY                    = 0x4;
  const unsigned long FLAG_DECODE_NO_PREMULTIPLY_ALPHA     = 0x8;
  const unsigned long FLAG_DECODE_NO_COLORSPACE_CONVERSION = 0x10;
  const unsigned long FLAG_CLAMP                           = 0x20;
  const unsigned long FLAG_HIGH_QUALITY_SCALING            = 0x40;
  const unsigned long FLAG_WANT_DATA_SURFACE               = 0x80;
  const unsigned long FLAG_BYPASS_SURFACE_CACHE            = 0x100;

  /**
   * A constant specifying the default set of decode flags (i.e., the default
   * values for FLAG_DECODE_*).
   */
  const unsigned long DECODE_FLAGS_DEFAULT = 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 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. If you
   * need that, use SourceSurface::GetDataSurface.
   *
   * @param aWhichFrame Frame specifier of the FRAME_* variety.
   * @param aFlags Flags of the FLAG_* variety
   */
  [noscript, notxpcom] TempRefSourceSurface getFrame(in uint32_t aWhichFrame,
                                                     in uint32_t aFlags);

  /**
   * Get a surface for the given frame at the specified size. Matching the
   * requested size is best effort; it's not guaranteed that the surface you get
   * will be a perfect match. (Some reasons you may get a surface of a different
   * size include: if you requested upscaling, if downscale-during-decode is
   * disabled, or if you didn't request the first frame.)
   *
   * @param aSize The desired size.
   * @param aWhichFrame Frame specifier of the FRAME_* variety.
   * @param aFlags Flags of the FLAG_* variety
   */
  [noscript, notxpcom] TempRefSourceSurface getFrameAtSize([const] in nsIntSize aSize,
                                                           in uint32_t aWhichFrame,
                                                           in uint32_t aFlags);

  /**
   * Whether this image is opaque (i.e., needs a background painted behind it).
   */
  [notxpcom] boolean isOpaque();

  /**
   * @return true if getImageContainer() is expected to return a valid
   *         ImageContainer when passed the given @Manager and @Flags
   *         parameters.
   */
  [noscript, notxpcom] boolean isImageContainerAvailable(in LayerManager aManager,
                                                         in uint32_t aFlags);
  /**
   * Attempts to create an ImageContainer (and Image) containing the current
   * frame.
   *
   * Avoid calling this unless you're actually going to layerize this image.
   *
   * @param aManager The LayerManager which will be used to create the
   *                 ImageContainer.
   * @param aFlags Decoding / drawing flags (in other words, FLAG_* flags).
   *               Currently only FLAG_SYNC_DECODE and FLAG_SYNC_DECODE_IF_FAST
   *               are supported.
   * @return An ImageContainer for the current frame, or nullptr if one could
   *         not be created.
   */
  [noscript, notxpcom] TempRefImageContainer getImageContainer(in LayerManager aManager,
                                                               in uint32_t aFlags);

  /**
   * Draw the requested frame of this image onto the context specified.
   *
   * Drawing an image involves scaling it to a certain size (which may be
   * implemented as a "smart" scale by substituting an HQ-scaled frame or
   * rendering at a high DPI), and then selecting a region of that image to
   * draw. That region is drawn onto the graphics context and in the process
   * transformed by the context matrix, which determines the final area that is
   * filled. The basic process looks like this:
   *
   *                           +------------------+
   *                           |      Image       |
   *                           |                  |
   *                           | intrinsic width  |
   *                           |        X         |
   *                           | intrinsic height |
   *                           +------------------+
   *                          /                    \
   *                         /                      \
   *                        /    (scale to aSize)    \
   *                       /                          \
   *                      +----------------------------+
   *                      |                            |
   *                      |        Scaled Image        |
   *                      | aSize.width X aSize.height |
   *                      |                            |
   *                      |       +---------+          |
   *                      |       | aRegion |          |
   *                      |       +---------+          |
   *                      +-------(---------(----------+
   *                              |         |
   *                             /           \
   *                            |  (transform |
   *                           /  by aContext  \
   *                          |     matrix)     |
   *                         /                   \
   *                        +---------------------+
   *                        |                     |
   *                        |      Fill Rect      |
   *                        |                     |
   *                        +---------------------+
   *
   * The region may extend outside of the scaled image's boundaries. It's
   * actually a region in tiled image space, which is formed by tiling the
   * scaled image infinitely in every direction. Drawing with a region larger
   * than the scaled image thus causes the filled area to contain multiple tiled
   * copies of the image, which looks like this:
   *
   *           ....................................................
   *           :                :                :                :
   *           :      Tile      :      Tile      :      Tile      :
   *           :        +------------[aRegion]------------+       :
   *           :........|.......:................:........|.......:
   *           :        |       :                :        |       :
   *           :      Ti|le     :  Scaled Image  :      Ti|le     :
   *           :        |       :                :        |       :
   *           :........|.......:................:........|.......:
   *           :        +---------------------------------+       :
   *           :      Ti|le     :      Tile      :      Ti|le     :
   *           :       /        :                :         \      :
   *           :......(.........:................:..........).....:
   *                  |                                     |
   *                 /                                       \
   *                |      (transform by aContext matrix)     |
   *               /                                           \
   *              +---------------------------------------------+
   *              |     :                                 :     |
   *              |.....:.................................:.....|
   *              |     :                                 :     |
   *              |     :           Tiled Fill            :     |
   *              |     :                                 :     |
   *              |.....:.................................:.....|
   *              |     :                                 :     |
   *              +---------------------------------------------+
   *
   *
   * @param aContext The Thebes context to draw the image to.
   * @param aSize The size to which the image should be scaled before drawing.
   *              This requirement may be satisfied using HQ scaled frames,
   *              selecting from different resolution layers, drawing at a
   *              higher DPI, or just performing additional scaling on the
   *              graphics context. Callers can use optimalImageSizeForDest()
   *              to determine the best choice for this parameter if they have
   *              no special size requirements.
   * @param aRegion The region in tiled image space which will be drawn onto the
   *                graphics context. aRegion is in the coordinate space of the
   *                image after it has been scaled to aSize - that is, the image
   *                is scaled first, and then aRegion is applied. When aFlags
   *                includes FLAG_CLAMP, the image will be extended to this area
   *                by clamping image sample coordinates. Otherwise, the image
   *                will be automatically tiled as necessary. aRegion can also
   *                optionally contain a second region which restricts the set
   *                of pixels we're allowed to sample from when drawing; this
   *                is only of use to callers which need to draw with pixel
   *                snapping.
   * @param aWhichFrame Frame specifier of the FRAME_* variety.
   * @param aFilter The filter to be used if we're scaling the image.
   * @param aSVGContext If specified, SVG-related rendering context, such as
   *                    overridden attributes on the image document's root <svg>
   *                    node, and the size of the viewport that the full image
   *                    would occupy. Ignored for raster images.
   * @param aFlags Flags of the FLAG_* variety
   * @return A DrawResult value indicating whether and to what degree the
   *         drawing operation was successful.
   */
  [noscript, notxpcom] DrawResult
  draw(in gfxContext aContext,
       [const] in nsIntSize aSize,
       [const] in ImageRegion aRegion,
       in uint32_t aWhichFrame,
       in Filter aFilter,
       [const] in MaybeSVGImageContext aSVGContext,
       in uint32_t aFlags);

  /*
   * Ensures that an image is decoding. Calling this function guarantees that
   * the image will at some point fire off decode notifications. Images that
   * can be decoded "quickly" according to some heuristic will be decoded
   * synchronously.
   */
  [noscript] void startDecoding();

  /*
   * This method triggers decoding for an image, but unlike startDecoding() it
   * enables the caller to provide more detailed information about the decode
   * request.
   *
   * @param aSize The size to which the image should be scaled while decoding,
   *              if possible. If the image cannot be scaled to this size while
   *              being decoded, it will be decoded at its intrinsic size.
   * @param aFlags Flags of the FLAG_* variety. Only the decode flags
   *               (FLAG_DECODE_*) and FLAG_SYNC_DECODE (which will
   *               synchronously decode images that can be decoded "quickly",
   *               just like startDecoding() does) are accepted; others will be
   *               ignored.
   */
  [noscript] void requestDecodeForSize([const] in nsIntSize aSize,
                                       in uint32_t aFlags);

  /**
    * 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();

  /*
   * Returns an index for the requested animation frame (either FRAME_FIRST or
   * FRAME_CURRENT).
   *
   * The units of the index aren't specified, and may vary between different
   * types of images. What you can rely on is that on all occasions when
   * getFrameIndex(FRAME_CURRENT) returns a certain value,
   * draw(..FRAME_CURRENT..) will draw the same frame. The same holds for
   * FRAME_FIRST as well.
   *
   * @param aWhichFrame Frame specifier of the FRAME_* variety.
   */
  [notxpcom] float getFrameIndex(in uint32_t aWhichFrame);

  /*
   * Returns the inherent orientation of the image, as described in the image's
   * metadata (e.g. EXIF).
   */
  [notxpcom] Orientation getOrientation();

  /*
   * Returns the delay, in ms, between the first and second frame. If this
   * returns 0, there is no delay between first and second frame (i.e., this
   * image could render differently whenever it draws).
   *
   * If this image is not animated, or not known to be animated (see attribute
   * animated), returns -1.
   */
  [notxpcom] int32_t getFirstFrameDelay();

  /*
   * If this is an animated image that hasn't started animating already, this
   * sets the animation's start time to the indicated time.
   *
   * This has no effect if the image isn't animated or it has started animating
   * already; it also has no effect if the image format doesn't care about
   * animation start time.
   *
   * In all cases, animation does not actually begin until startAnimation(),
   * resetAnimation(), or requestRefresh() is called for the first time.
   */
  [notxpcom] void setAnimationStartTime([const] in TimeStamp aTime);

  /*
   * Given an invalidation rect in the coordinate system used by the decoder,
   * returns an invalidation rect in image space.
   *
   * This is the identity transformation in most cases, but the result can
   * differ if the image is wrapped by an ImageWrapper that changes its size
   * or orientation.
   */
  [notxpcom] nsIntRectByVal
  getImageSpaceInvalidationRect([const] in nsIntRect aRect);

  /*
   * Removes any ImageWrappers and returns the unwrapped base image.
   */
  [notxpcom, nostdcall] TempRefImgIContainer unwrap();

  /*
   * Propagate the use counters (if any) from this container to the passed in
   * document.
   */
  [noscript, notxpcom] void propagateUseCounters(in nsIDocument aDocument);
};