image/DecoderFactory.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  *
   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_image_DecoderFactory_h
   8 #define mozilla_image_DecoderFactory_h
   9
  10 #include "DecoderFlags.h"
  11 #include "mozilla/Attributes.h"
  12 #include "mozilla/Maybe.h"
  13 #include "mozilla/NotNull.h"
  14 #include "mozilla/gfx/2D.h"
  15 #include "nsCOMPtr.h"
  16 #include "Orientation.h"
  17 #include "SurfaceFlags.h"
  18
  19 namespace mozilla::image {
  20
  21 class Decoder;
  22 class IDecodingTask;
  23 class nsICODecoder;
  24 class RasterImage;
  25 class SourceBuffer;
  26 class SourceBufferIterator;
  27
  28 /**
  29  * The type of decoder; this is usually determined from a MIME type using
  30  * DecoderFactory::GetDecoderType().
  31  */
  32 enum class DecoderType {
  33   PNG,
  34   GIF,
  35   JPEG,
  36   BMP,
  37   BMP_CLIPBOARD,
  38   ICO,
  39   ICON,
  40   WEBP,
  41   AVIF,
  42   JXL,
  43   UNKNOWN
  44 };
  45
  46 class DecoderFactory {
  47  public:
  48   /// @return the type of decoder which is appropriate for @aMimeType.
  49   static DecoderType GetDecoderType(const char* aMimeType);
  50
  51   /// @return the default flags to use when creating a decoder of @aType.
  52   static DecoderFlags GetDefaultDecoderFlagsForType(DecoderType aType);
  53
  54   /**
  55    * Creates and initializes a decoder for non-animated images of type @aType.
  56    * (If the image *is* animated, only the first frame will be decoded.) The
  57    * decoder will send notifications to @aImage.
  58    *
  59    * @param aType Which type of decoder to create - JPEG, PNG, etc.
  60    * @param aImage The image will own the decoder and which should receive
  61    *               notifications as decoding progresses.
  62    * @param aSourceBuffer The SourceBuffer which the decoder will read its data
  63    *                      from.
  64    * @param aIntrinsicSize The intrinsic size of the image, normally obtained
  65    *                       during the metadata decode.
  66    * @param aOutputSize The output size for the decoder. If this is smaller than
  67    *                    the intrinsic size, the decoder will downscale the
  68    *                    image.
  69    * @param aDecoderFlags Flags specifying the behavior of this decoder.
  70    * @param aSurfaceFlags Flags specifying the type of output this decoder
  71    *                      should produce.
  72    * @param aOutTask Task representing the decoder.
  73    * @return NS_OK if the decoder has been created/initialized successfully;
  74    *         NS_ERROR_ALREADY_INITIALIZED if there is already an active decoder
  75    *           for this image;
  76    *         Else some other unrecoverable error occurred.
  77    */
  78   static nsresult CreateDecoder(DecoderType aType, NotNull<RasterImage*> aImage,
  79                                 NotNull<SourceBuffer*> aSourceBuffer,
  80                                 const gfx::IntSize& aIntrinsicSize,
  81                                 const gfx::IntSize& aOutputSize,
  82                                 DecoderFlags aDecoderFlags,
  83                                 SurfaceFlags aSurfaceFlags,
  84                                 IDecodingTask** aOutTask);
  85
  86   /**
  87    * Creates and initializes a decoder for animated images of type @aType.
  88    * The decoder will send notifications to @aImage.
  89    *
  90    * @param aType Which type of decoder to create - JPEG, PNG, etc.
  91    * @param aImage The image will own the decoder and which should receive
  92    *               notifications as decoding progresses.
  93    * @param aSourceBuffer The SourceBuffer which the decoder will read its data
  94    *                      from.
  95    * @param aIntrinsicSize The intrinsic size of the image, normally obtained
  96    *                       during the metadata decode.
  97    * @param aDecoderFlags Flags specifying the behavior of this decoder.
  98    * @param aSurfaceFlags Flags specifying the type of output this decoder
  99    *                      should produce.
 100    * @param aCurrentFrame The current frame the decoder should auto advance to.
 101    * @param aOutTask Task representing the decoder.
 102    * @return NS_OK if the decoder has been created/initialized successfully;
 103    *         NS_ERROR_ALREADY_INITIALIZED if there is already an active decoder
 104    *           for this image;
 105    *         Else some other unrecoverable error occurred.
 106    */
 107   static nsresult CreateAnimationDecoder(
 108       DecoderType aType, NotNull<RasterImage*> aImage,
 109       NotNull<SourceBuffer*> aSourceBuffer, const gfx::IntSize& aIntrinsicSize,
 110       DecoderFlags aDecoderFlags, SurfaceFlags aSurfaceFlags,
 111       size_t aCurrentFrame, IDecodingTask** aOutTask);
 112
 113   /**
 114    * Creates and initializes a decoder for animated images, cloned from the
 115    * given decoder.
 116    *
 117    * @param aDecoder Decoder to clone.
 118    */
 119   static already_AddRefed<Decoder> CloneAnimationDecoder(Decoder* aDecoder);
 120
 121   /**
 122    * Creates and initializes a metadata decoder of type @aType. This decoder
 123    * will only decode the image's header, extracting metadata like the size of
 124    * the image. No actual image data will be decoded and no surfaces will be
 125    * allocated. The decoder will send notifications to @aImage.
 126    *
 127    * @param aType Which type of decoder to create - JPEG, PNG, etc.
 128    * @param aImage The image will own the decoder and which should receive
 129    *               notifications as decoding progresses.
 130    * @param aSourceBuffer The SourceBuffer which the decoder will read its data
 131    *                      from.
 132    */
 133   static already_AddRefed<IDecodingTask> CreateMetadataDecoder(
 134       DecoderType aType, NotNull<RasterImage*> aImage, DecoderFlags aFlags,
 135       NotNull<SourceBuffer*> aSourceBuffer);
 136
 137   /**
 138    * Creates and initializes a decoder for an ICO resource, which may be either
 139    * a BMP or PNG image.
 140    *
 141    * @param aType Which type of decoder to create. This must be either BMP or
 142    *              PNG.
 143    * @param aIterator The SourceBufferIterator which the decoder will read its
 144    *                  data from.
 145    * @param aICODecoder The ICO decoder which is controlling this resource
 146    *                    decoder. @aICODecoder's settings will be copied to the
 147    *                    resource decoder, so the two decoders will have the
 148    *                    same decoder flags, surface flags, target size, and
 149    *                    other parameters.
 150    * @param aIsMetadataDecode Indicates whether or not this decoder is for
 151    *                          metadata or not. Independent of the state of the
 152    *                          parent decoder.
 153    * @param aExpectedSize The expected size of the resource from the ICO header.
 154    * @param aDataOffset If @aType is BMP, specifies the offset at which data
 155    *                    begins in the BMP resource. Must be Some() if and only
 156    *                    if @aType is BMP.
 157    */
 158   static already_AddRefed<Decoder> CreateDecoderForICOResource(
 159       DecoderType aType, SourceBufferIterator&& aIterator,
 160       NotNull<nsICODecoder*> aICODecoder, bool aIsMetadataDecode,
 161       const Maybe<OrientedIntSize>& aExpectedSize,
 162       const Maybe<uint32_t>& aDataOffset = Nothing());
 163
 164   /**
 165    * Creates and initializes an anonymous decoder (one which isn't associated
 166    * with an Image object). Only the first frame of the image will be decoded.
 167    *
 168    * @param aType Which type of decoder to create - JPEG, PNG, etc.
 169    * @param aSourceBuffer The SourceBuffer which the decoder will read its data
 170    *                      from.
 171    * @param aOutputSize If Some(), the output size for the decoder. If this is
 172    *                    smaller than the intrinsic size, the decoder will
 173    *                    downscale the image. If Nothing(), the output size will
 174    *                    be the intrinsic size.
 175    * @param aDecoderFlags Flags specifying the behavior of this decoder.
 176    * @param aSurfaceFlags Flags specifying the type of output this decoder
 177    *                      should produce.
 178    */
 179   static already_AddRefed<Decoder> CreateAnonymousDecoder(
 180       DecoderType aType, NotNull<SourceBuffer*> aSourceBuffer,
 181       const Maybe<gfx::IntSize>& aOutputSize, DecoderFlags aDecoderFlags,
 182       SurfaceFlags aSurfaceFlags);
 183
 184   /**
 185    * Creates and initializes an anonymous metadata decoder (one which isn't
 186    * associated with an Image object). This decoder will only decode the image's
 187    * header, extracting metadata like the size of the image. No actual image
 188    * data will be decoded and no surfaces will be allocated.
 189    *
 190    * @param aType Which type of decoder to create - JPEG, PNG, etc.
 191    * @param aSourceBuffer The SourceBuffer which the decoder will read its data
 192    *                      from.
 193    */
 194   static already_AddRefed<Decoder> CreateAnonymousMetadataDecoder(
 195       DecoderType aType, NotNull<SourceBuffer*> aSourceBuffer);
 196
 197  private:
 198   virtual ~DecoderFactory() = 0;
 199
 200   /**
 201    * An internal method which allocates a new decoder of the requested @aType.
 202    */
 203   static already_AddRefed<Decoder> GetDecoder(DecoderType aType,
 204                                               RasterImage* aImage,
 205                                               bool aIsRedecode);
 206 };
 207
 208 }  // namespace mozilla::image
 209
 210 #endif  // mozilla_image_DecoderFactory_h