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