OLD | NEW |
(Empty) | |
| 1 /* |
| 2 * Copyright 2006 The Android Open Source Project |
| 3 * |
| 4 * Use of this source code is governed by a BSD-style license that can be |
| 5 * found in the LICENSE file. |
| 6 */ |
| 7 |
| 8 #ifndef SkImageDecoder_DEFINED |
| 9 #define SkImageDecoder_DEFINED |
| 10 |
| 11 #include "SkBitmap.h" |
| 12 #include "SkImage.h" |
| 13 #include "SkPngChunkReader.h" |
| 14 #include "SkRect.h" |
| 15 #include "SkRefCnt.h" |
| 16 #include "SkTRegistry.h" |
| 17 #include "SkTypes.h" |
| 18 |
| 19 class SkStream; |
| 20 class SkStreamRewindable; |
| 21 |
| 22 /** \class SkImageDecoder |
| 23 |
| 24 DEPRECATED Please use SkImage::NewFromEncoded() or SkImageGenerator::NewFrom
Encoded(). |
| 25 |
| 26 Base class for decoding compressed images into a SkBitmap |
| 27 */ |
| 28 class SkImageDecoder : SkNoncopyable { |
| 29 public: |
| 30 virtual ~SkImageDecoder(); |
| 31 |
| 32 // TODO (scroggo): Merge with SkEncodedFormat |
| 33 enum Format { |
| 34 kUnknown_Format, |
| 35 kBMP_Format, |
| 36 kGIF_Format, |
| 37 kICO_Format, |
| 38 kJPEG_Format, |
| 39 kPNG_Format, |
| 40 kWBMP_Format, |
| 41 kWEBP_Format, |
| 42 kPKM_Format, |
| 43 kKTX_Format, |
| 44 kASTC_Format, |
| 45 |
| 46 kLastKnownFormat = kKTX_Format, |
| 47 }; |
| 48 |
| 49 /** Return the format of image this decoder can decode. If this decoder can
decode multiple |
| 50 formats, kUnknown_Format will be returned. |
| 51 */ |
| 52 virtual Format getFormat() const; |
| 53 |
| 54 /** If planes or rowBytes is NULL, decodes the header and computes component
Sizes |
| 55 for memory allocation. |
| 56 Otherwise, decodes the YUV planes into the provided image planes and |
| 57 updates componentSizes to the final image size. |
| 58 Returns whether the decoding was successful. |
| 59 */ |
| 60 bool decodeYUV8Planes(SkStream* stream, SkISize componentSizes[3], void* pla
nes[3], |
| 61 size_t rowBytes[3], SkYUVColorSpace*); |
| 62 |
| 63 /** Return the format of the SkStreamRewindable or kUnknown_Format if it can
not be determined. |
| 64 Rewinds the stream before returning. |
| 65 */ |
| 66 static Format GetStreamFormat(SkStreamRewindable*); |
| 67 |
| 68 /** Return a readable string of the Format provided. |
| 69 */ |
| 70 static const char* GetFormatName(Format); |
| 71 |
| 72 /** Return a readable string of the value returned by getFormat(). |
| 73 */ |
| 74 const char* getFormatName() const; |
| 75 |
| 76 /** Whether the decoder should skip writing zeroes to output if possible. |
| 77 */ |
| 78 bool getSkipWritingZeroes() const { return fSkipWritingZeroes; } |
| 79 |
| 80 /** Set to true if the decoder should skip writing any zeroes when |
| 81 creating the output image. |
| 82 This is a hint that may not be respected by the decoder. |
| 83 It should only be used if it is known that the memory to write |
| 84 to has already been set to 0; otherwise the resulting image will |
| 85 have garbage. |
| 86 This is ideal for images that contain a lot of completely transparent |
| 87 pixels, but may be a performance hit for an image that has only a |
| 88 few transparent pixels. |
| 89 The default is false. |
| 90 */ |
| 91 void setSkipWritingZeroes(bool skip) { fSkipWritingZeroes = skip; } |
| 92 |
| 93 /** Returns true if the decoder should try to dither the resulting image. |
| 94 The default setting is true. |
| 95 */ |
| 96 bool getDitherImage() const { return fDitherImage; } |
| 97 |
| 98 /** Set to true if the the decoder should try to dither the resulting image. |
| 99 The default setting is true. |
| 100 */ |
| 101 void setDitherImage(bool dither) { fDitherImage = dither; } |
| 102 |
| 103 /** Returns true if the decoder should try to decode the |
| 104 resulting image to a higher quality even at the expense of |
| 105 the decoding speed. |
| 106 */ |
| 107 bool getPreferQualityOverSpeed() const { return fPreferQualityOverSpeed; } |
| 108 |
| 109 /** Set to true if the the decoder should try to decode the |
| 110 resulting image to a higher quality even at the expense of |
| 111 the decoding speed. |
| 112 */ |
| 113 void setPreferQualityOverSpeed(bool qualityOverSpeed) { |
| 114 fPreferQualityOverSpeed = qualityOverSpeed; |
| 115 } |
| 116 |
| 117 /** Set to true to require the decoder to return a bitmap with unpremultipli
ed |
| 118 colors. The default is false, meaning the resulting bitmap will have its |
| 119 colors premultiplied. |
| 120 NOTE: Passing true to this function may result in a bitmap which cannot |
| 121 be properly used by Skia. |
| 122 */ |
| 123 void setRequireUnpremultipliedColors(bool request) { |
| 124 fRequireUnpremultipliedColors = request; |
| 125 } |
| 126 |
| 127 /** Returns true if the decoder will only return bitmaps with unpremultiplie
d |
| 128 colors. |
| 129 */ |
| 130 bool getRequireUnpremultipliedColors() const { return fRequireUnpremultiplie
dColors; } |
| 131 |
| 132 SkPngChunkReader* getPeeker() const { return fPeeker; } |
| 133 SkPngChunkReader* setPeeker(SkPngChunkReader*); |
| 134 |
| 135 /** |
| 136 * By default, the codec will try to comply with the "pref" colortype |
| 137 * that is passed to decode() or decodeSubset(). However, this can be calle
d |
| 138 * to override that, causing the codec to try to match the src depth instea
d |
| 139 * (as shown below). |
| 140 * |
| 141 * src_8Index -> kIndex_8_SkColorType |
| 142 * src_8Gray -> kN32_SkColorType |
| 143 * src_8bpc -> kN32_SkColorType |
| 144 */ |
| 145 void setPreserveSrcDepth(bool preserve) { |
| 146 fPreserveSrcDepth = preserve; |
| 147 } |
| 148 |
| 149 SkBitmap::Allocator* getAllocator() const { return fAllocator; } |
| 150 SkBitmap::Allocator* setAllocator(SkBitmap::Allocator*); |
| 151 |
| 152 // sample-size, if set to > 1, tells the decoder to return a smaller than |
| 153 // original bitmap, sampling 1 pixel for every size pixels. e.g. if sample |
| 154 // size is set to 3, then the returned bitmap will be 1/3 as wide and high, |
| 155 // and will contain 1/9 as many pixels as the original. |
| 156 // Note: this is a hint, and the codec may choose to ignore this, or only |
| 157 // approximate the sample size. |
| 158 int getSampleSize() const { return fSampleSize; } |
| 159 void setSampleSize(int size); |
| 160 |
| 161 /** Reset the sampleSize to its default of 1 |
| 162 */ |
| 163 void resetSampleSize() { this->setSampleSize(1); } |
| 164 |
| 165 /** Decoding is synchronous, but for long decodes, a different thread can |
| 166 call this method safely. This sets a state that the decoders will |
| 167 periodically check, and if they see it changed to cancel, they will |
| 168 cancel. This will result in decode() returning false. However, there is |
| 169 no guarantee that the decoder will see the state change in time, so |
| 170 it is possible that cancelDecode() will be called, but will be ignored |
| 171 and decode() will return true (assuming no other problems were |
| 172 encountered). |
| 173 |
| 174 This state is automatically reset at the beginning of decode(). |
| 175 */ |
| 176 void cancelDecode() { |
| 177 // now the subclass must query shouldCancelDecode() to be informed |
| 178 // of the request |
| 179 fShouldCancelDecode = true; |
| 180 } |
| 181 |
| 182 /** Passed to the decode method. If kDecodeBounds_Mode is passed, then |
| 183 only the bitmap's info need be set. If kDecodePixels_Mode |
| 184 is passed, then the bitmap must have pixels or a pixelRef. |
| 185 */ |
| 186 enum Mode { |
| 187 kDecodeBounds_Mode, //!< only return info in bitmap |
| 188 kDecodePixels_Mode //!< return entire bitmap (including pixels) |
| 189 }; |
| 190 |
| 191 /** Result of a decode. If read as a boolean, a partial success is |
| 192 considered a success (true). |
| 193 */ |
| 194 enum Result { |
| 195 kFailure = 0, //!< Image failed to decode. bitmap will be |
| 196 // unchanged. |
| 197 kPartialSuccess = 1, //!< Part of the image decoded. The rest is |
| 198 // filled in automatically |
| 199 kSuccess = 2 //!< The entire image was decoded, if Mode is |
| 200 // kDecodePixels_Mode, or the bounds were |
| 201 // decoded, in kDecodeBounds_Mode. |
| 202 }; |
| 203 |
| 204 /** Given a stream, decode it into the specified bitmap. |
| 205 If the decoder can decompress the image, it calls bitmap.setInfo(), |
| 206 and then if the Mode is kDecodePixels_Mode, call allocPixelRef(), |
| 207 which will allocated a pixelRef. To access the pixel memory, the codec |
| 208 needs to call lockPixels/unlockPixels on the |
| 209 bitmap. It can then set the pixels with the decompressed image. |
| 210 * If the image cannot be decompressed, return kFailure. After the |
| 211 * decoding, the function converts the decoded colortype in bitmap |
| 212 * to pref if possible. Whether a conversion is feasible is |
| 213 * tested by Bitmap::canCopyTo(pref). |
| 214 |
| 215 If an SkBitmap::Allocator is installed via setAllocator, it will be |
| 216 used to allocate the pixel memory. A clever allocator can be used |
| 217 to allocate the memory from a cache, volatile memory, or even from |
| 218 an existing bitmap's memory. |
| 219 |
| 220 If an SkPngChunkReader is installed via setPeeker, it may be used to |
| 221 peek into meta data during the decode. |
| 222 */ |
| 223 Result decode(SkStream*, SkBitmap* bitmap, SkColorType pref, Mode); |
| 224 Result decode(SkStream* stream, SkBitmap* bitmap, Mode mode) { |
| 225 return this->decode(stream, bitmap, kUnknown_SkColorType, mode); |
| 226 } |
| 227 |
| 228 /** Given a stream, this will try to find an appropriate decoder object. |
| 229 If none is found, the method returns NULL. |
| 230 |
| 231 DEPRECATED Please use SkImage::NewFromEncoded() or SkImageGenerator::New
FromEncoded(). |
| 232 */ |
| 233 static SkImageDecoder* Factory(SkStreamRewindable*); |
| 234 |
| 235 /** Decode the image stored in the specified file, and store the result |
| 236 in bitmap. Return true for success or false on failure. |
| 237 |
| 238 @param pref Prefer this colortype. |
| 239 |
| 240 @param format On success, if format is non-null, it is set to the format |
| 241 of the decoded file. On failure it is ignored. |
| 242 |
| 243 DEPRECATED Do not use. |
| 244 */ |
| 245 static bool DecodeFile(const char file[], SkBitmap* bitmap, SkColorType pref
, Mode, |
| 246 Format* format = NULL); |
| 247 static bool DecodeFile(const char file[], SkBitmap* bitmap) { |
| 248 return DecodeFile(file, bitmap, kUnknown_SkColorType, kDecodePixels_Mode
, NULL); |
| 249 } |
| 250 |
| 251 /** Decode the image stored in the specified memory buffer, and store the |
| 252 result in bitmap. Return true for success or false on failure. |
| 253 |
| 254 @param pref Prefer this colortype. |
| 255 |
| 256 @param format On success, if format is non-null, it is set to the format |
| 257 of the decoded buffer. On failure it is ignored. |
| 258 |
| 259 DEPRECATED Please use SkImage::NewFromEncoded() or SkImageGenerator::New
FromEncoded(). |
| 260 */ |
| 261 static bool DecodeMemory(const void* buffer, size_t size, SkBitmap* bitmap,
SkColorType pref, |
| 262 Mode, Format* format = NULL); |
| 263 static bool DecodeMemory(const void* buffer, size_t size, SkBitmap* bitmap){ |
| 264 return DecodeMemory(buffer, size, bitmap, kUnknown_SkColorType, kDecodeP
ixels_Mode, NULL); |
| 265 } |
| 266 |
| 267 /** Decode the image stored in the specified SkStreamRewindable, and store t
he result |
| 268 in bitmap. Return true for success or false on failure. |
| 269 |
| 270 @param pref Prefer this colortype. |
| 271 |
| 272 @param format On success, if format is non-null, it is set to the format |
| 273 of the decoded stream. On failure it is ignored. |
| 274 |
| 275 DEPRECATED Please use SkImage::NewFromEncoded() or SkImageGenerator::New
FromEncoded(). |
| 276 */ |
| 277 static bool DecodeStream(SkStreamRewindable* stream, SkBitmap* bitmap, SkCol
orType pref, Mode, |
| 278 Format* format = NULL); |
| 279 static bool DecodeStream(SkStreamRewindable* stream, SkBitmap* bitmap) { |
| 280 return DecodeStream(stream, bitmap, kUnknown_SkColorType, kDecodePixels_
Mode, NULL); |
| 281 } |
| 282 |
| 283 protected: |
| 284 // must be overridden in subclasses. This guy is called by decode(...) |
| 285 virtual Result onDecode(SkStream*, SkBitmap* bitmap, Mode) = 0; |
| 286 |
| 287 /** If planes or rowBytes is NULL, decodes the header and computes component
Sizes |
| 288 for memory allocation. |
| 289 Otherwise, decodes the YUV planes into the provided image planes and |
| 290 updates componentSizes to the final image size. |
| 291 Returns whether the decoding was successful. |
| 292 */ |
| 293 virtual bool onDecodeYUV8Planes(SkStream*, SkISize[3] /*componentSizes*/, |
| 294 void*[3] /*planes*/, size_t[3] /*rowBytes*/, |
| 295 SkYUVColorSpace*) { |
| 296 return false; |
| 297 } |
| 298 |
| 299 /** |
| 300 * Copy all fields on this decoder to the other decoder. Used by subclasses |
| 301 * to decode a subimage using a different decoder, but with the same settin
gs. |
| 302 */ |
| 303 void copyFieldsToOther(SkImageDecoder* other); |
| 304 |
| 305 /** Can be queried from within onDecode, to see if the user (possibly in |
| 306 a different thread) has requested the decode to cancel. If this returns |
| 307 true, your onDecode() should stop and return false. |
| 308 Each subclass needs to decide how often it can query this, to balance |
| 309 responsiveness with performance. |
| 310 |
| 311 Calling this outside of onDecode() may return undefined values. |
| 312 */ |
| 313 |
| 314 public: |
| 315 bool shouldCancelDecode() const { return fShouldCancelDecode; } |
| 316 |
| 317 protected: |
| 318 SkImageDecoder(); |
| 319 |
| 320 /** |
| 321 * Return the default preference being used by the current or latest call t
o decode. |
| 322 */ |
| 323 SkColorType getDefaultPref() { return fDefaultPref; } |
| 324 |
| 325 /* Helper for subclasses. Call this to allocate the pixel memory given the
bitmap's info. |
| 326 Returns true on success. This method handles checking for an optional Al
locator. |
| 327 */ |
| 328 bool allocPixelRef(SkBitmap*, SkColorTable*) const; |
| 329 |
| 330 /** |
| 331 * The raw data of the src image. |
| 332 */ |
| 333 enum SrcDepth { |
| 334 // Color-indexed. |
| 335 kIndex_SrcDepth, |
| 336 // Grayscale in 8 bits. |
| 337 k8BitGray_SrcDepth, |
| 338 // 8 bits per component. Used for 24 bit if there is no alpha. |
| 339 k32Bit_SrcDepth, |
| 340 }; |
| 341 /** The subclass, inside onDecode(), calls this to determine the colorType o
f |
| 342 the returned bitmap. SrcDepth and hasAlpha reflect the raw data of the |
| 343 src image. This routine returns the caller's preference given |
| 344 srcDepth and hasAlpha, or kUnknown_SkColorType if there is no preference
. |
| 345 */ |
| 346 SkColorType getPrefColorType(SrcDepth, bool hasAlpha) const; |
| 347 |
| 348 private: |
| 349 SkPngChunkReader* fPeeker; |
| 350 SkBitmap::Allocator* fAllocator; |
| 351 int fSampleSize; |
| 352 SkColorType fDefaultPref; // use if fUsePrefTable is false |
| 353 bool fPreserveSrcDepth; |
| 354 bool fDitherImage; |
| 355 bool fSkipWritingZeroes; |
| 356 mutable bool fShouldCancelDecode; |
| 357 bool fPreferQualityOverSpeed; |
| 358 bool fRequireUnpremultipliedColors; |
| 359 }; |
| 360 |
| 361 /** Calling newDecoder with a stream returns a new matching imagedecoder |
| 362 instance, or NULL if none can be found. The caller must manage its ownership |
| 363 of the stream as usual, calling unref() when it is done, as the returned |
| 364 decoder may have called ref() (and if so, the decoder is responsible for |
| 365 balancing its ownership when it is destroyed). |
| 366 */ |
| 367 class SkImageDecoderFactory : public SkRefCnt { |
| 368 public: |
| 369 |
| 370 |
| 371 virtual SkImageDecoder* newDecoder(SkStreamRewindable*) = 0; |
| 372 |
| 373 private: |
| 374 typedef SkRefCnt INHERITED; |
| 375 }; |
| 376 |
| 377 class SkDefaultImageDecoderFactory : SkImageDecoderFactory { |
| 378 public: |
| 379 // calls SkImageDecoder::Factory(stream) |
| 380 virtual SkImageDecoder* newDecoder(SkStreamRewindable* stream) { |
| 381 return SkImageDecoder::Factory(stream); |
| 382 } |
| 383 }; |
| 384 |
| 385 // This macro declares a global (i.e., non-class owned) creation entry point |
| 386 // for each decoder (e.g., CreateJPEGImageDecoder) |
| 387 #define DECLARE_DECODER_CREATOR(codec) \ |
| 388 SkImageDecoder *Create ## codec (); |
| 389 |
| 390 // This macro defines the global creation entry point for each decoder. Each |
| 391 // decoder implementation that registers with the decoder factory must call it. |
| 392 #define DEFINE_DECODER_CREATOR(codec) \ |
| 393 SkImageDecoder* Create##codec() { return new Sk##codec; } |
| 394 |
| 395 // All the decoders known by Skia. Note that, depending on the compiler settings
, |
| 396 // not all of these will be available |
| 397 DECLARE_DECODER_CREATOR(BMPImageDecoder); |
| 398 DECLARE_DECODER_CREATOR(GIFImageDecoder); |
| 399 DECLARE_DECODER_CREATOR(ICOImageDecoder); |
| 400 DECLARE_DECODER_CREATOR(JPEGImageDecoder); |
| 401 DECLARE_DECODER_CREATOR(PNGImageDecoder); |
| 402 DECLARE_DECODER_CREATOR(WBMPImageDecoder); |
| 403 DECLARE_DECODER_CREATOR(WEBPImageDecoder); |
| 404 DECLARE_DECODER_CREATOR(PKMImageDecoder); |
| 405 DECLARE_DECODER_CREATOR(KTXImageDecoder); |
| 406 DECLARE_DECODER_CREATOR(ASTCImageDecoder); |
| 407 |
| 408 // Typedefs to make registering decoder and formatter callbacks easier. |
| 409 // These have to be defined outside SkImageDecoder. :( |
| 410 typedef SkTRegistry<SkImageDecoder*(*)(SkStreamRewindable*)> SkImageDecod
er_DecodeReg; |
| 411 typedef SkTRegistry<SkImageDecoder::Format(*)(SkStreamRewindable*)> SkImageDecod
er_FormatReg; |
| 412 |
| 413 #endif |
OLD | NEW |