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