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