1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/image/public/imgIContainer.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,344 @@
1.4 +/** -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
1.5 + *
1.6 + * This Source Code Form is subject to the terms of the Mozilla Public
1.7 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.8 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.9 +
1.10 +#include "nsISupports.idl"
1.11 +
1.12 +%{C++
1.13 +#include "gfxImageSurface.h"
1.14 +#include "gfxContext.h"
1.15 +#include "gfxMatrix.h"
1.16 +#include "gfxRect.h"
1.17 +#include "GraphicsFilter.h"
1.18 +#include "gfxASurface.h"
1.19 +#include "mozilla/gfx/2D.h"
1.20 +#include "mozilla/RefPtr.h"
1.21 +#include "nsRect.h"
1.22 +#include "nsSize.h"
1.23 +#include "limits.h"
1.24 +
1.25 +namespace mozilla {
1.26 +namespace layers {
1.27 +class LayerManager;
1.28 +class ImageContainer;
1.29 +}
1.30 +}
1.31 +
1.32 +class nsIFrame;
1.33 +
1.34 +namespace mozilla {
1.35 +class TimeStamp;
1.36 +class SVGImageContext;
1.37 +}
1.38 +
1.39 +namespace mozilla {
1.40 +namespace image {
1.41 +class Orientation;
1.42 +}
1.43 +}
1.44 +
1.45 +%}
1.46 +
1.47 +[ptr] native gfxImageSurface(gfxImageSurface);
1.48 +[ptr] native gfxASurface(gfxASurface);
1.49 +native gfxImageFormat(gfxASurface::gfxImageFormat);
1.50 +[ptr] native gfxContext(gfxContext);
1.51 +[ref] native gfxMatrix(gfxMatrix);
1.52 +[ref] native gfxRect(gfxRect);
1.53 +native gfxGraphicsFilter(GraphicsFilter);
1.54 +[ref] native nsIntRect(nsIntRect);
1.55 +[ref] native nsIntSize(nsIntSize);
1.56 +native nsSize(nsSize);
1.57 +[ptr] native nsIFrame(nsIFrame);
1.58 +[ptr] native ImageContainer(mozilla::layers::ImageContainer);
1.59 +[ptr] native LayerManager(mozilla::layers::LayerManager);
1.60 +native Orientation(mozilla::image::Orientation);
1.61 +[ref] native TimeStamp(mozilla::TimeStamp);
1.62 +[ptr] native SVGImageContext(mozilla::SVGImageContext);
1.63 +native TempRefSourceSurface(mozilla::TemporaryRef<mozilla::gfx::SourceSurface>);
1.64 +
1.65 +
1.66 +/**
1.67 + * imgIContainer is the interface that represents an image. It allows
1.68 + * access to frames as Thebes surfaces. It also allows drawing of images
1.69 + * onto Thebes contexts.
1.70 + *
1.71 + * Internally, imgIContainer also manages animation of images.
1.72 + */
1.73 +[scriptable, builtinclass, uuid(503a830c-734d-4362-91f6-73f83ac59646)]
1.74 +interface imgIContainer : nsISupports
1.75 +{
1.76 + /**
1.77 + * The width of the container rectangle. In the case of any error,
1.78 + * zero is returned, and an exception will be thrown.
1.79 + */
1.80 + readonly attribute int32_t width;
1.81 +
1.82 + /**
1.83 + * The height of the container rectangle. In the case of any error,
1.84 + * zero is returned, and an exception will be thrown.
1.85 + */
1.86 + readonly attribute int32_t height;
1.87 +
1.88 + /**
1.89 + * The intrinsic size of this image in appunits. If the image has no intrinsic
1.90 + * size in a dimension, -1 will be returned for that dimension. In the case of
1.91 + * any error, an exception will be thrown.
1.92 + */
1.93 + [noscript] readonly attribute nsSize intrinsicSize;
1.94 +
1.95 + /**
1.96 + * The (dimensionless) intrinsic ratio of this image. In the case of any error,
1.97 + * an exception will be thrown.
1.98 + */
1.99 + [noscript] readonly attribute nsSize intrinsicRatio;
1.100 +
1.101 + /**
1.102 + * Enumerated values for the 'type' attribute (below).
1.103 + */
1.104 + const unsigned short TYPE_RASTER = 0;
1.105 + const unsigned short TYPE_VECTOR = 1;
1.106 +
1.107 + /**
1.108 + * The type of this image (one of the TYPE_* values above).
1.109 + */
1.110 + readonly attribute unsigned short type;
1.111 +
1.112 + /**
1.113 + * Direct C++ accessor for 'type' attribute, for convenience.
1.114 + */
1.115 + [noscript, notxpcom] uint16_t GetType();
1.116 +
1.117 + /**
1.118 + * Whether this image is animated. You can only be guaranteed that querying
1.119 + * this will not throw if STATUS_DECODE_COMPLETE is set on the imgIRequest.
1.120 + *
1.121 + * @throws NS_ERROR_NOT_AVAILABLE if the animated state cannot be determined.
1.122 + */
1.123 + readonly attribute boolean animated;
1.124 +
1.125 + /**
1.126 + * Flags for imgIContainer operations.
1.127 + *
1.128 + * Meanings:
1.129 + *
1.130 + * FLAG_NONE: Lack of flags
1.131 + *
1.132 + * FLAG_SYNC_DECODE: Forces synchronous/non-progressive decode of all
1.133 + * available data before the call returns. It is an error to pass this flag
1.134 + * from a call stack that originates in a decoder (ie, from a decoder
1.135 + * observer event).
1.136 + *
1.137 + * FLAG_DECODE_NO_PREMULTIPLY_ALPHA: Do not premultiply alpha if
1.138 + * it's not already premultiplied in the image data.
1.139 + *
1.140 + * FLAG_DECODE_NO_COLORSPACE_CONVERSION: Do not do any colorspace conversion;
1.141 + * ignore any embedded profiles, and don't convert to any particular destination
1.142 + * space.
1.143 + *
1.144 + * FLAG_CLAMP: Extend the image to the fill area by clamping image sample
1.145 + * coordinates instead of by tiling. This only affects 'draw'.
1.146 + *
1.147 + * FLAG_HIGH_QUALITY_SCALING: A hint as to whether this image should be
1.148 + * scaled using the high quality scaler. Do not set this if not drawing to
1.149 + * a window or not listening to invalidations.
1.150 + */
1.151 +
1.152 + const long FLAG_NONE = 0x0;
1.153 + const long FLAG_SYNC_DECODE = 0x1;
1.154 + const long FLAG_DECODE_NO_PREMULTIPLY_ALPHA = 0x2;
1.155 + const long FLAG_DECODE_NO_COLORSPACE_CONVERSION = 0x4;
1.156 + const long FLAG_CLAMP = 0x8;
1.157 + const long FLAG_HIGH_QUALITY_SCALING = 0x10;
1.158 + const long FLAG_WANT_DATA_SURFACE = 0x20;
1.159 +
1.160 + /**
1.161 + * Constants for specifying various "special" frames.
1.162 + *
1.163 + * FRAME_FIRST: The first frame
1.164 + * FRAME_CURRENT: The current frame
1.165 + *
1.166 + * FRAME_MAX_VALUE should be set to the value of the maximum constant above,
1.167 + * as it is used for ensuring that a valid value was passed in.
1.168 + */
1.169 + const unsigned long FRAME_FIRST = 0;
1.170 + const unsigned long FRAME_CURRENT = 1;
1.171 + const unsigned long FRAME_MAX_VALUE = 1;
1.172 +
1.173 + /**
1.174 + * Get a surface for the given frame. This may be a platform-native,
1.175 + * optimized surface, so you cannot inspect its pixel data. If you
1.176 + * need that, use gfxASurface::GetAsReadableARGB32ImageSurface or
1.177 + * gfxASurface::CopyToARGB32ImageSurface.
1.178 + *
1.179 + * @param aWhichFrame Frame specifier of the FRAME_* variety.
1.180 + * @param aFlags Flags of the FLAG_* variety
1.181 + */
1.182 + [noscript, notxpcom] TempRefSourceSurface getFrame(in uint32_t aWhichFrame,
1.183 + in uint32_t aFlags);
1.184 +
1.185 + /**
1.186 + * Whether the given frame is opaque; that is, needs the background painted
1.187 + * behind it.
1.188 + *
1.189 + * @param aWhichFrame Frame specifier of the FRAME_* variety.
1.190 + */
1.191 + [notxpcom] boolean frameIsOpaque(in uint32_t aWhichFrame);
1.192 +
1.193 + /**
1.194 + * Attempts to create an ImageContainer (and Image) containing the current
1.195 + * frame. Only valid for RASTER type images.
1.196 + */
1.197 + [noscript] ImageContainer getImageContainer(in LayerManager aManager);
1.198 +
1.199 + /**
1.200 + * Draw a frame onto the context specified.
1.201 + *
1.202 + * @param aContext The Thebes context to draw the image to.
1.203 + * @param aFilter The filter to be used if we're scaling the image.
1.204 + * @param aUserSpaceToImageSpace The transformation from user space (e.g.,
1.205 + * appunits) to image space.
1.206 + * @param aFill The area in the context to draw pixels to. When aFlags includes
1.207 + * FLAG_CLAMP, the image will be extended to this area by clampling
1.208 + * image sample coordinates. Otherwise, the image will be
1.209 + * automatically tiled as necessary.
1.210 + * @param aSubimage The area of the image, in pixels, that we are allowed to
1.211 + * sample from.
1.212 + * @param aViewportSize
1.213 + * The size (in CSS pixels) of the viewport that would be available
1.214 + * for the full image to occupy, if we were drawing the full image.
1.215 + * (Note that we might not actually be drawing the full image -- we
1.216 + * might be restricted by aSubimage -- but we still need the full
1.217 + * image's viewport-size in order for SVG images with the "viewBox"
1.218 + * attribute to position their content correctly.)
1.219 + * @param aSVGContext If non-null, SVG-related rendering context such as
1.220 + * overridden attributes on the image document's root <svg>
1.221 + * node. Ignored for raster images.
1.222 + * @param aWhichFrame Frame specifier of the FRAME_* variety.
1.223 + * @param aFlags Flags of the FLAG_* variety
1.224 + */
1.225 + [noscript] void draw(in gfxContext aContext,
1.226 + in gfxGraphicsFilter aFilter,
1.227 + [const] in gfxMatrix aUserSpaceToImageSpace,
1.228 + [const] in gfxRect aFill,
1.229 + [const] in nsIntRect aSubimage,
1.230 + [const] in nsIntSize aViewportSize,
1.231 + [const] in SVGImageContext aSVGContext,
1.232 + in uint32_t aWhichFrame,
1.233 + in uint32_t aFlags);
1.234 +
1.235 + /*
1.236 + * Ensures that an image is decoding. Calling this function guarantees that
1.237 + * the image will at some point fire off decode notifications. Calling draw()
1.238 + * or getFrame() triggers the same mechanism internally. Thus, if you want to
1.239 + * be sure that the image will be decoded but don't want to access it until
1.240 + * then, you must call requestDecode().
1.241 + */
1.242 + void requestDecode();
1.243 +
1.244 + /*
1.245 + * This is equivalent to requestDecode() but it also decodes some of the image.
1.246 + */
1.247 + [noscript] void startDecoding();
1.248 +
1.249 + /*
1.250 + * Returns true if no more decoding can be performed on this image. Images
1.251 + * with errors return true since they cannot be decoded any further. Note that
1.252 + * because decoded images may be discarded, isDecoded() may return false even
1.253 + * if it has returned true in the past.
1.254 + */
1.255 + [noscript, notxpcom, nostdcall] bool isDecoded();
1.256 +
1.257 + /**
1.258 + * Increments the lock count on the image. An image will not be discarded
1.259 + * as long as the lock count is nonzero. Note that it is still possible for
1.260 + * the image to be undecoded if decode-on-draw is enabled and the image
1.261 + * was never drawn.
1.262 + *
1.263 + * Upon instantiation images have a lock count of zero.
1.264 + */
1.265 + void lockImage();
1.266 +
1.267 + /**
1.268 + * Decreases the lock count on the image. If the lock count drops to zero,
1.269 + * the image is allowed to discard its frame data to save memory.
1.270 + *
1.271 + * Upon instantiation images have a lock count of zero. It is an error to
1.272 + * call this method without first having made a matching lockImage() call.
1.273 + * In other words, the lock count is not allowed to be negative.
1.274 + */
1.275 + void unlockImage();
1.276 +
1.277 + /**
1.278 + * If this image is unlocked, discard its decoded data. If the image is
1.279 + * locked or has already been discarded, do nothing.
1.280 + */
1.281 + void requestDiscard();
1.282 +
1.283 + /**
1.284 + * Indicates that this imgIContainer has been triggered to update
1.285 + * its internal animation state. Likely this should only be called
1.286 + * from within nsImageFrame or objects of similar type.
1.287 + */
1.288 + [notxpcom] void requestRefresh([const] in TimeStamp aTime);
1.289 +
1.290 + /**
1.291 + * Animation mode Constants
1.292 + * 0 = normal
1.293 + * 1 = don't animate
1.294 + * 2 = loop once
1.295 + */
1.296 + const short kNormalAnimMode = 0;
1.297 + const short kDontAnimMode = 1;
1.298 + const short kLoopOnceAnimMode = 2;
1.299 +
1.300 + attribute unsigned short animationMode;
1.301 +
1.302 + /* Methods to control animation */
1.303 + void resetAnimation();
1.304 +
1.305 + /*
1.306 + * Returns an index for the requested animation frame (either FRAME_FIRST or
1.307 + * FRAME_CURRENT).
1.308 + *
1.309 + * The units of the index aren't specified, and may vary between different
1.310 + * types of images. What you can rely on is that on all occasions when
1.311 + * getFrameIndex(FRAME_CURRENT) returns a certain value,
1.312 + * draw(..FRAME_CURRENT..) will draw the same frame. The same holds for
1.313 + * FRAME_FIRST as well.
1.314 + *
1.315 + * @param aWhichFrame Frame specifier of the FRAME_* variety.
1.316 + */
1.317 + [notxpcom] float getFrameIndex(in uint32_t aWhichFrame);
1.318 +
1.319 + /*
1.320 + * Returns the inherent orientation of the image, as described in the image's
1.321 + * metadata (e.g. EXIF).
1.322 + */
1.323 + [notxpcom] Orientation getOrientation();
1.324 +
1.325 + /*
1.326 + * Returns the delay, in ms, between the first and second frame. If this
1.327 + * returns 0, there is no delay between first and second frame (i.e., this
1.328 + * image could render differently whenever it draws).
1.329 + *
1.330 + * If this image is not animated, or not known to be animated (see attribute
1.331 + * animated), returns -1.
1.332 + */
1.333 + [notxpcom] int32_t getFirstFrameDelay();
1.334 +
1.335 + /*
1.336 + * If this is an animated image that hasn't started animating already, this
1.337 + * sets the animation's start time to the indicated time.
1.338 + *
1.339 + * This has no effect if the image isn't animated or it has started animating
1.340 + * already; it also has no effect if the image format doesn't care about
1.341 + * animation start time.
1.342 + *
1.343 + * In all cases, animation does not actually begin until startAnimation(),
1.344 + * resetAnimation(), or requestRefresh() is called for the first time.
1.345 + */
1.346 + [notxpcom] void setAnimationStartTime([const] in TimeStamp aTime);
1.347 +};
