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 |