dom/base/ImageEncoder.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   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 ImageEncoder_h
   8 #define ImageEncoder_h
   9
  10 #include "imgIEncoder.h"
  11 #include "nsError.h"
  12 #include "mozilla/dom/File.h"
  13 #include "mozilla/dom/HTMLCanvasElementBinding.h"
  14 #include "mozilla/UniquePtr.h"
  15 #include "nsSize.h"
  16
  17 class nsICanvasRenderingContextInternal;
  18
  19 namespace mozilla {
  20
  21 namespace layers {
  22 class Image;
  23 }  // namespace layers
  24
  25 namespace dom {
  26
  27 class EncodeCompleteCallback;
  28 class EncodingRunnable;
  29 class OffscreenCanvasDisplayHelper;
  30
  31 class ImageEncoder {
  32  public:
  33   // Extracts data synchronously and gives you a stream containing the image
  34   // represented by aContext. aType may change to "image/png" if we had to fall
  35   // back to a PNG encoder. A return value of NS_OK implies successful data
  36   // extraction. If there are any unrecognized custom parse options in
  37   // aOptions, NS_ERROR_INVALID_ARG will be returned. When encountering this
  38   // error it is usual to call this function again without any options at all.
  39   static nsresult ExtractData(nsAString& aType, const nsAString& aOptions,
  40                               const nsIntSize aSize, bool aUsePlaceholder,
  41                               nsICanvasRenderingContextInternal* aContext,
  42                               OffscreenCanvasDisplayHelper* aOffscreenDisplay,
  43                               nsIInputStream** aStream);
  44
  45   // Extracts data asynchronously. aType may change to "image/png" if we had to
  46   // fall back to a PNG encoder. aOptions are the options to be passed to the
  47   // encoder and aUsingCustomOptions specifies whether custom parse options were
  48   // used (i.e. by using -moz-parse-options). If there are any unrecognized
  49   // custom parse options, we fall back to the default values for the encoder
  50   // without any options at all. A return value of NS_OK only implies
  51   // successful dispatching of the extraction step to the encoding thread.
  52   // aEncodeCallback will be called on main thread when encoding process is
  53   // success.
  54   // Note: The callback has to set a valid parent for content for the generated
  55   // Blob object.
  56   static nsresult ExtractDataAsync(nsAString& aType, const nsAString& aOptions,
  57                                    bool aUsingCustomOptions,
  58                                    UniquePtr<uint8_t[]> aImageBuffer,
  59                                    int32_t aFormat, const nsIntSize aSize,
  60                                    bool aUsePlaceholder,
  61                                    EncodeCompleteCallback* aEncodeCallback);
  62
  63   // Extract an Image asynchronously. Its function is same as ExtractDataAsync
  64   // except for the parameters. aImage is the uncompressed data. aEncodeCallback
  65   // will be called on main thread when encoding process is success.
  66   // Note: The callback has to set a valid parent for content for the generated
  67   // Blob object.
  68   static nsresult ExtractDataFromLayersImageAsync(
  69       nsAString& aType, const nsAString& aOptions, bool aUsingCustomOptions,
  70       layers::Image* aImage, bool aUsePlaceholder,
  71       EncodeCompleteCallback* aEncodeCallback);
  72
  73   // Gives you a stream containing the image represented by aImageBuffer.
  74   // The format is given in aFormat, for example
  75   // imgIEncoder::INPUT_FORMAT_HOSTARGB.
  76   static nsresult GetInputStream(int32_t aWidth, int32_t aHeight,
  77                                  uint8_t* aImageBuffer, int32_t aFormat,
  78                                  imgIEncoder* aEncoder,
  79                                  const nsAString& aEncoderOptions,
  80                                  nsIInputStream** aStream);
  81
  82  private:
  83   // When called asynchronously, aContext and aRenderer are null.
  84   static nsresult ExtractDataInternal(
  85       const nsAString& aType, const nsAString& aOptions, uint8_t* aImageBuffer,
  86       int32_t aFormat, const nsIntSize aSize, bool aUsePlaceholder,
  87       layers::Image* aImage, nsICanvasRenderingContextInternal* aContext,
  88       OffscreenCanvasDisplayHelper* aOffscreenDisplay, nsIInputStream** aStream,
  89       imgIEncoder* aEncoder);
  90
  91   // Creates and returns an encoder instance of the type specified in aType.
  92   // aType may change to "image/png" if no instance of the original type could
  93   // be created and we had to fall back to a PNG encoder. A null return value
  94   // should be interpreted as NS_IMAGELIB_ERROR_NO_ENCODER and aType is
  95   // undefined in this case.
  96   static already_AddRefed<imgIEncoder> GetImageEncoder(nsAString& aType);
  97
  98   friend class EncodingRunnable;
  99   friend class EncoderThreadPoolTerminator;
 100 };
 101
 102 /**
 103  *  The callback interface of ExtractDataAsync and
 104  * ExtractDataFromLayersImageAsync. ReceiveBlobImpl() is called on main thread
 105  * when encoding is complete.
 106  */
 107 class EncodeCompleteCallback {
 108  public:
 109   NS_INLINE_DECL_THREADSAFE_REFCOUNTING(EncodeCompleteCallback)
 110
 111   MOZ_CAN_RUN_SCRIPT
 112   virtual nsresult ReceiveBlobImpl(already_AddRefed<BlobImpl> aBlobImpl) = 0;
 113
 114   // CanBeDeletedOnAnyThread is pure virtual, so that whoever extends this class
 115   // needs to think how to handle cases like the owning DOM worker thread
 116   // shutting down.
 117   virtual bool CanBeDeletedOnAnyThread() = 0;
 118
 119  protected:
 120   virtual ~EncodeCompleteCallback() = default;
 121 };
 122
 123 }  // namespace dom
 124 }  // namespace mozilla
 125
 126 #endif  // ImageEncoder_h