gecko/image/imgIContainer.idl
Wes Kocher bb201c69bf Backed out 8 changesets (bug 1201796, bug 1196066) for mulet gij(28) failures CLOSED TREE
Backed out changeset 159d5d2946d3 (bug 1201796)
Backed out changeset 958988218976 (bug 1201796)
Backed out changeset 494e7553d641 (bug 1201796)
Backed out changeset d58149411b7d (bug 1201796)
Backed out changeset 35bd769b49f8 (bug 1196066)
Backed out changeset e4f3d4279b4c (bug 1196066)
Backed out changeset ca467297fa07 (bug 1196066)
Backed out changeset b4851ce6637d (bug 1196066)
2015-09-18 13:01:25 -07:00

557 lines
22 KiB
Plaintext

/** -*- 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 "gfxContext.h"
#include "gfxMatrix.h"
#include "gfxRect.h"
#include "GraphicsFilter.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;
/**
* An enumeration representing the result of a drawing operation.
*
* Most users of DrawResult will only be interested in whether the value is
* SUCCESS or not. The other values are primarily useful for debugging and error
* handling.
*
* SUCCESS: We successfully drew a completely decoded frame of the requested
* size. Drawing again with FLAG_SYNC_DECODE would not change the result.
*
* INCOMPLETE: We successfully drew a frame that was partially decoded. (Note
* that successfully drawing a partially decoded frame may not actually draw any
* pixels!) Drawing again with FLAG_SYNC_DECODE would improve the result.
*
* WRONG_SIZE: We successfully drew a wrongly-sized frame that had to be scaled.
* This is only returned if drawing again with FLAG_SYNC_DECODE would improve
* the result; if the size requested was larger than the intrinsic size of the
* image, for example, we would generally have to scale whether FLAG_SYNC_DECODE
* was specified or not, and therefore we would not return WRONG_SIZE.
*
* NOT_READY: We failed to draw because no decoded version of the image was
* available. Drawing again with FLAG_SYNC_DECODE would improve the result.
* (Though FLAG_SYNC_DECODE will not necessarily work until after the image's
* load event!)
*
* TEMPORARY_ERROR: We failed to draw due to a temporary error. Drawing may
* succeed at a later time.
*
* BAD_IMAGE: We failed to draw because the image has an error. This is a
* permanent condition.
*
* BAD_ARGS: We failed to draw because bad arguments were passed to draw().
*/
enum class DrawResult : uint8_t
{
SUCCESS,
INCOMPLETE,
WRONG_SIZE,
NOT_READY,
TEMPORARY_ERROR,
BAD_IMAGE,
BAD_ARGS
};
}
}
%}
native DrawResult(mozilla::image::DrawResult);
[ptr] native gfxContext(gfxContext);
[ref] native gfxMatrix(gfxMatrix);
[ref] native gfxRect(gfxRect);
[ref] native gfxSize(gfxSize);
native gfxGraphicsFilter(GraphicsFilter);
[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(4880727a-5673-44f7-b248-f6c86e22a434)]
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 gfxGraphicsFilter 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);
/**
* 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 gfxGraphicsFilter 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. Calling draw()
* or getFrame() 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();
/*
* This is equivalent to requestDecode() but it also synchronously decodes
* images that can be decoded "quickly" according to some heuristic.
*/
[noscript] void startDecoding();
/*
* This method is equivalent to requestDecode(), but 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);
};