dom/canvas/ImageBitmap.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim:set ts=2 sw=2 sts=2 et cindent: */
   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 #ifndef mozilla_dom_ImageBitmap_h
   8 #define mozilla_dom_ImageBitmap_h
   9
  10 #include "mozilla/Attributes.h"
  11 #include "mozilla/dom/ImageBitmapSource.h"
  12 #include "mozilla/dom/TypedArray.h"
  13 #include "mozilla/gfx/Rect.h"
  14 #include "mozilla/Maybe.h"
  15 #include "mozilla/UniquePtr.h"
  16 #include "ImageData.h"
  17 #include "gfxTypes.h"  // for gfxAlphaType
  18 #include "nsCycleCollectionParticipant.h"
  19
  20 struct JSContext;
  21 struct JSStructuredCloneReader;
  22 struct JSStructuredCloneWriter;
  23
  24 class nsIGlobalObject;
  25
  26 namespace mozilla {
  27
  28 class ErrorResult;
  29
  30 namespace gfx {
  31 class DataSourceSurface;
  32 class DrawTarget;
  33 class SourceSurface;
  34 }  // namespace gfx
  35
  36 namespace layers {
  37 class Image;
  38 }
  39
  40 namespace dom {
  41 class OffscreenCanvas;
  42
  43 class ArrayBufferViewOrArrayBuffer;
  44 class CanvasRenderingContext2D;
  45 class CreateImageBitmapFromBlob;
  46 class CreateImageBitmapFromBlobTask;
  47 class CreateImageBitmapFromBlobWorkerTask;
  48 class File;
  49 class HTMLCanvasElement;
  50 class HTMLImageElement;
  51 class HTMLVideoElement;
  52 class ImageBitmapShutdownObserver;
  53 class ImageData;
  54 class ImageUtils;
  55 class Promise;
  56 class PostMessageEvent;  // For StructuredClone between windows.
  57 class SVGImageElement;
  58
  59 struct ImageBitmapCloneData final {
  60   RefPtr<gfx::DataSourceSurface> mSurface;
  61   gfx::IntRect mPictureRect;
  62   gfxAlphaType mAlphaType;
  63   bool mWriteOnly;
  64 };
  65
  66 /*
  67  * ImageBitmap is an opaque handler to several kinds of image-like objects from
  68  * HTMLImageElement, HTMLVideoElement, HTMLCanvasElement, ImageData to
  69  * CanvasRenderingContext2D and Image Blob.
  70  *
  71  * An ImageBitmap could be painted to a canvas element.
  72  *
  73  * Generally, an ImageBitmap only keeps a reference to its source object's
  74  * buffer, but if the source object is an ImageData, an Blob or a
  75  * HTMLCanvasElement with WebGL rendering context, the ImageBitmap copy the
  76  * source object's buffer.
  77  */
  78 class ImageBitmap final : public nsISupports, public nsWrapperCache {
  79  public:
  80   NS_DECL_CYCLE_COLLECTING_ISUPPORTS
  81   NS_DECL_CYCLE_COLLECTION_SCRIPT_HOLDER_CLASS(ImageBitmap)
  82
  83   nsCOMPtr<nsIGlobalObject> GetParentObject() const { return mParent; }
  84
  85   virtual JSObject* WrapObject(JSContext* aCx,
  86                                JS::Handle<JSObject*> aGivenProto) override;
  87
  88   uint32_t Width() const { return mPictureRect.Width(); }
  89
  90   uint32_t Height() const { return mPictureRect.Height(); }
  91
  92   void Close();
  93
  94   /*
  95    * The PrepareForDrawTarget() might return null if the mPictureRect does not
  96    * intersect with the size of mData.
  97    */
  98   already_AddRefed<gfx::SourceSurface> PrepareForDrawTarget(
  99       gfx::DrawTarget* aTarget);
 100
 101   /*
 102    * Transfer ownership of buffer to caller. So this function call
 103    * Close() implicitly.
 104    */
 105   already_AddRefed<layers::Image> TransferAsImage();
 106
 107   // This method returns null if the image has been already closed.
 108   UniquePtr<ImageBitmapCloneData> ToCloneData() const;
 109
 110   static already_AddRefed<ImageBitmap> CreateFromSourceSurface(
 111       nsIGlobalObject* aGlobal, gfx::SourceSurface* aSource, ErrorResult& aRv);
 112
 113   static already_AddRefed<ImageBitmap> CreateFromCloneData(
 114       nsIGlobalObject* aGlobal, ImageBitmapCloneData* aData);
 115
 116   static already_AddRefed<ImageBitmap> CreateFromOffscreenCanvas(
 117       nsIGlobalObject* aGlobal, OffscreenCanvas& aOffscreenCanvas,
 118       ErrorResult& aRv);
 119
 120   static already_AddRefed<Promise> Create(nsIGlobalObject* aGlobal,
 121                                           const ImageBitmapSource& aSrc,
 122                                           const Maybe<gfx::IntRect>& aCropRect,
 123                                           ErrorResult& aRv);
 124
 125   static JSObject* ReadStructuredClone(
 126       JSContext* aCx, JSStructuredCloneReader* aReader,
 127       nsIGlobalObject* aParent,
 128       const nsTArray<RefPtr<gfx::DataSourceSurface>>& aClonedSurfaces,
 129       uint32_t aIndex);
 130
 131   static bool WriteStructuredClone(
 132       JSStructuredCloneWriter* aWriter,
 133       nsTArray<RefPtr<gfx::DataSourceSurface>>& aClonedSurfaces,
 134       ImageBitmap* aImageBitmap);
 135
 136   friend CreateImageBitmapFromBlob;
 137   friend CreateImageBitmapFromBlobTask;
 138   friend CreateImageBitmapFromBlobWorkerTask;
 139
 140   size_t GetAllocatedSize() const;
 141
 142   void OnShutdown();
 143
 144   bool IsWriteOnly() const { return mWriteOnly; }
 145   bool IsClosed() const { return !mData; };
 146
 147  protected:
 148   /*
 149    * The default value of aIsPremultipliedAlpha is TRUE because that the
 150    * data stored in HTMLImageElement, HTMLVideoElement, HTMLCanvasElement,
 151    * CanvasRenderingContext2D are alpha-premultiplied in default.
 152    *
 153    * Actually, if one HTMLCanvasElement's rendering context is WebGLContext, it
 154    * is possible to get un-premultipliedAlpha data out. But, we do not do it in
 155    * the CreateInternal(from HTMLCanvasElement) method.
 156    *
 157    * It is also possible to decode an image which is encoded with alpha channel
 158    * to be non-premultipliedAlpha. This could be applied in
 159    * 1) the CreateInternal(from HTMLImageElement) method (which might trigger
 160    *    re-decoding if the original decoded data is alpha-premultiplied) and
 161    * 2) while decoding a blob. But we do not do it in both code path too.
 162    *
 163    * ImageData's underlying data is triggered as non-premultipliedAlpha, so set
 164    * the aIsPremultipliedAlpha to be false in the
 165    * CreateInternal(from ImageData) method.
 166    */
 167   ImageBitmap(nsIGlobalObject* aGlobal, layers::Image* aData, bool aWriteOnly,
 168               gfxAlphaType aAlphaType = gfxAlphaType::Premult);
 169
 170   virtual ~ImageBitmap();
 171
 172   void SetPictureRect(const gfx::IntRect& aRect, ErrorResult& aRv);
 173
 174   static already_AddRefed<ImageBitmap> CreateInternal(
 175       nsIGlobalObject* aGlobal, HTMLImageElement& aImageEl,
 176       const Maybe<gfx::IntRect>& aCropRect, ErrorResult& aRv);
 177
 178   static already_AddRefed<ImageBitmap> CreateInternal(
 179       nsIGlobalObject* aGlobal, SVGImageElement& aImageEl,
 180       const Maybe<gfx::IntRect>& aCropRect, ErrorResult& aRv);
 181
 182   static already_AddRefed<ImageBitmap> CreateInternal(
 183       nsIGlobalObject* aGlobal, HTMLVideoElement& aVideoEl,
 184       const Maybe<gfx::IntRect>& aCropRect, ErrorResult& aRv);
 185
 186   static already_AddRefed<ImageBitmap> CreateInternal(
 187       nsIGlobalObject* aGlobal, HTMLCanvasElement& aCanvasEl,
 188       const Maybe<gfx::IntRect>& aCropRect, ErrorResult& aRv);
 189
 190   static already_AddRefed<ImageBitmap> CreateInternal(
 191       nsIGlobalObject* aGlobal, ImageData& aImageData,
 192       const Maybe<gfx::IntRect>& aCropRect, ErrorResult& aRv);
 193
 194   static already_AddRefed<ImageBitmap> CreateInternal(
 195       nsIGlobalObject* aGlobal, CanvasRenderingContext2D& aCanvasCtx,
 196       const Maybe<gfx::IntRect>& aCropRect, ErrorResult& aRv);
 197
 198   static already_AddRefed<ImageBitmap> CreateInternal(
 199       nsIGlobalObject* aGlobal, ImageBitmap& aImageBitmap,
 200       const Maybe<gfx::IntRect>& aCropRect, ErrorResult& aRv);
 201
 202   nsCOMPtr<nsIGlobalObject> mParent;
 203
 204   /*
 205    * The mData is the data buffer of an ImageBitmap, so the mData must not be
 206    * null.
 207    *
 208    * The mSurface is a cache for drawing the ImageBitmap onto a
 209    * HTMLCanvasElement. The mSurface is null while the ImageBitmap is created
 210    * and then will be initialized while the PrepareForDrawTarget() method is
 211    * called first time.
 212    *
 213    * The mSurface might just be a reference to the same data buffer of the mData
 214    * if the are of mPictureRect is just the same as the mData's size. Or, it is
 215    * a independent data buffer which is copied and cropped form the mData's data
 216    * buffer.
 217    */
 218   RefPtr<layers::Image> mData;
 219   RefPtr<gfx::SourceSurface> mSurface;
 220
 221   /*
 222    * This is used in the ImageBitmap-Extensions implementation.
 223    * ImageUtils is a wrapper to layers::Image, which add some common methods for
 224    * accessing the layers::Image's data.
 225    */
 226   UniquePtr<ImageUtils> mDataWrapper;
 227
 228   /*
 229    * The mPictureRect is the size of the source image in default, however, if
 230    * users specify the cropping area while creating an ImageBitmap, then this
 231    * mPictureRect is the cropping area.
 232    *
 233    * Note that if the CreateInternal() copies and crops data from the source
 234    * image, then this mPictureRect is just the size of the final mData.
 235    *
 236    * The mPictureRect will be used at PrepareForDrawTarget() while user is going
 237    * to draw this ImageBitmap into a HTMLCanvasElement.
 238    */
 239   gfx::IntRect mPictureRect;
 240
 241   gfxAlphaType mAlphaType;
 242
 243   RefPtr<ImageBitmapShutdownObserver> mShutdownObserver;
 244
 245   /*
 246    * Whether this object allocated allocated and owns the image data.
 247    */
 248   bool mAllocatedImageData;
 249
 250   /*
 251    * Write-Only flag is set to true if this image has been generated from a
 252    * cross-origin source. This is the opposite of what is called 'origin-clean'
 253    * in the spec.
 254    */
 255   bool mWriteOnly;
 256 };
 257
 258 }  // namespace dom
 259 }  // namespace mozilla
 260
 261 #endif  // mozilla_dom_ImageBitmap_h