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