1 /* 2 * Copyright (C) 2006 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef SkImageDecoder_DEFINED 18 #define SkImageDecoder_DEFINED 19 20 #include "SkBitmap.h" 21 #include "SkRefCnt.h" 22 23 class SkStream; 24 25 /** \class SkImageDecoder 26 27 Base class for decoding compressed images into a SkBitmap 28 */ 29 class SkImageDecoder { 30 public: 31 virtual ~SkImageDecoder(); 32 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 42 kLastKnownFormat = kWBMP_Format 43 }; 44 45 /** Return the compressed data's format (see Format enum) 46 */ 47 virtual Format getFormat() const; 48 49 /** Returns true if the decoder should try to dither the resulting image. 50 The default setting is true. 51 */ 52 bool getDitherImage() const { return fDitherImage; } 53 54 /** Set to true if the the decoder should try to dither the resulting image. 55 The default setting is true. 56 */ 57 void setDitherImage(bool dither) { fDitherImage = dither; } 58 59 /** \class Peeker 60 61 Base class for optional callbacks to retrieve meta/chunk data out of 62 an image as it is being decoded. 63 */ 64 class Peeker : public SkRefCnt { 65 public: 66 /** Return true to continue decoding, or false to indicate an error, which 67 will cause the decoder to not return the image. 68 */ 69 virtual bool peek(const char tag[], const void* data, size_t length) = 0; 70 }; 71 72 Peeker* getPeeker() const { return fPeeker; } 73 Peeker* setPeeker(Peeker*); 74 75 /** \class Peeker 76 77 Base class for optional callbacks to retrieve meta/chunk data out of 78 an image as it is being decoded. 79 */ 80 class Chooser : public SkRefCnt { 81 public: 82 virtual void begin(int count) {} 83 virtual void inspect(int index, SkBitmap::Config config, int width, int height) {} 84 /** Return the index of the subimage you want, or -1 to choose none of them. 85 */ 86 virtual int choose() = 0; 87 }; 88 89 Chooser* getChooser() const { return fChooser; } 90 Chooser* setChooser(Chooser*); 91 92 /** This optional table describes the caller's preferred config based on 93 information about the src data. For this table, the src attributes are 94 described in terms of depth (index (8), 16, 32/24) and if there is 95 per-pixel alpha. These inputs combine to create an index into the 96 pref[] table, which contains the caller's preferred config for that 97 input, or kNo_Config if there is no preference. 98 99 To specify no preferrence, call setPrefConfigTable(NULL), which is 100 the default. 101 102 Note, it is still at the discretion of the codec as to what output 103 config is actually returned, as it may not be able to support the 104 caller's preference. 105 106 Here is how the index into the table is computed from the src: 107 depth [8, 16, 32/24] -> 0, 2, 4 108 alpha [no, yes] -> 0, 1 109 The two index values are OR'd together. 110 src: 8-index, no-alpha -> 0 111 src: 8-index, yes-alpha -> 1 112 src: 16bit, no-alpha -> 2 // e.g. 565 113 src: 16bit, yes-alpha -> 3 // e.g. 1555 114 src: 32/24, no-alpha -> 4 115 src: 32/24, yes-alpha -> 5 116 */ 117 void setPrefConfigTable(const SkBitmap::Config pref[6]); 118 119 SkBitmap::Allocator* getAllocator() const { return fAllocator; } 120 SkBitmap::Allocator* setAllocator(SkBitmap::Allocator*); 121 122 // sample-size, if set to > 1, tells the decoder to return a smaller than 123 // original bitmap, sampling 1 pixel for every size pixels. e.g. if sample 124 // size is set to 3, then the returned bitmap will be 1/3 as wide and high, 125 // and will contain 1/9 as many pixels as the original. 126 // Note: this is a hint, and the codec may choose to ignore this, or only 127 // approximate the sample size. 128 int getSampleSize() const { return fSampleSize; } 129 void setSampleSize(int size); 130 131 /** Reset the sampleSize to its default of 1 132 */ 133 void resetSampleSize() { this->setSampleSize(1); } 134 135 /** Decoding is synchronous, but for long decodes, a different thread can 136 call this method safely. This sets a state that the decoders will 137 periodically check, and if they see it changed to cancel, they will 138 cancel. This will result in decode() returning false. However, there is 139 no guarantee that the decoder will see the state change in time, so 140 it is possible that cancelDecode() will be called, but will be ignored 141 and decode() will return true (assuming no other problems were 142 encountered). 143 144 This state is automatically reset at the beginning of decode(). 145 */ 146 void cancelDecode() { 147 // now the subclass must query shouldCancelDecode() to be informed 148 // of the request 149 fShouldCancelDecode = true; 150 } 151 152 /** Passed to the decode method. If kDecodeBounds_Mode is passed, then 153 only the bitmap's width/height/config need be set. If kDecodePixels_Mode 154 is passed, then the bitmap must have pixels or a pixelRef. 155 */ 156 enum Mode { 157 kDecodeBounds_Mode, //!< only return width/height/config in bitmap 158 kDecodePixels_Mode //!< return entire bitmap (including pixels) 159 }; 160 161 /** Given a stream, decode it into the specified bitmap. 162 If the decoder can decompress the image, it calls bitmap.setConfig(), 163 and then if the Mode is kDecodePixels_Mode, call allocPixelRef(), 164 which will allocated a pixelRef. To access the pixel memory, the codec 165 needs to call lockPixels/unlockPixels on the 166 bitmap. It can then set the pixels with the decompressed image. 167 * If the image cannot be decompressed, return false. After the 168 * decoding, the function converts the decoded config in bitmap 169 * to pref if possible. Whether a conversion is feasible is 170 * tested by Bitmap::canCopyTo(pref). 171 172 note: document use of Allocator, Peeker and Chooser 173 */ 174 bool decode(SkStream*, SkBitmap* bitmap, SkBitmap::Config pref, Mode); 175 bool decode(SkStream* stream, SkBitmap* bitmap, Mode mode) { 176 return this->decode(stream, bitmap, SkBitmap::kNo_Config, mode); 177 } 178 179 /** Given a stream, this will try to find an appropriate decoder object. 180 If none is found, the method returns NULL. 181 */ 182 static SkImageDecoder* Factory(SkStream*); 183 184 /** Decode the image stored in the specified file, and store the result 185 in bitmap. Return true for success or false on failure. 186 187 If pref is kNo_Config, then the decoder is free to choose the most natural 188 config given the image data. If pref something other than kNo_Config, 189 the decoder will attempt to decode the image into that format, unless 190 there is a conflict (e.g. the image has per-pixel alpha and the bitmap's 191 config does not support that), in which case the decoder will choose a 192 closest match configuration. 193 194 @param format On success, if format is non-null, it is set to the format 195 of the decoded file. On failure it is ignored. 196 */ 197 static bool DecodeFile(const char file[], SkBitmap* bitmap, 198 SkBitmap::Config prefConfig, Mode, 199 Format* format = NULL); 200 static bool DecodeFile(const char file[], SkBitmap* bitmap) { 201 return DecodeFile(file, bitmap, SkBitmap::kNo_Config, 202 kDecodePixels_Mode, NULL); 203 } 204 /** Decode the image stored in the specified memory buffer, and store the 205 result in bitmap. Return true for success or false on failure. 206 207 If pref is kNo_Config, then the decoder is free to choose the most natural 208 config given the image data. If pref something other than kNo_Config, 209 the decoder will attempt to decode the image into that format, unless 210 there is a conflict (e.g. the image has per-pixel alpha and the bitmap's 211 config does not support that), in which case the decoder will choose a 212 closest match configuration. 213 214 @param format On success, if format is non-null, it is set to the format 215 of the decoded buffer. On failure it is ignored. 216 */ 217 static bool DecodeMemory(const void* buffer, size_t size, SkBitmap* bitmap, 218 SkBitmap::Config prefConfig, Mode, 219 Format* format = NULL); 220 static bool DecodeMemory(const void* buffer, size_t size, SkBitmap* bitmap){ 221 return DecodeMemory(buffer, size, bitmap, SkBitmap::kNo_Config, 222 kDecodePixels_Mode, NULL); 223 } 224 /** Decode the image stored in the specified SkStream, and store the result 225 in bitmap. Return true for success or false on failure. 226 227 If pref is kNo_Config, then the decoder is free to choose the most 228 natural config given the image data. If pref something other than 229 kNo_Config, the decoder will attempt to decode the image into that 230 format, unless there is a conflict (e.g. the image has per-pixel alpha 231 and the bitmap's config does not support that), in which case the 232 decoder will choose a closest match configuration. 233 234 @param format On success, if format is non-null, it is set to the format 235 of the decoded stream. On failure it is ignored. 236 */ 237 static bool DecodeStream(SkStream* stream, SkBitmap* bitmap, 238 SkBitmap::Config prefConfig, Mode, 239 Format* format = NULL); 240 static bool DecodeStream(SkStream* stream, SkBitmap* bitmap) { 241 return DecodeStream(stream, bitmap, SkBitmap::kNo_Config, 242 kDecodePixels_Mode, NULL); 243 } 244 245 /** Return the default config for the running device. 246 Currently this used as a suggestion to image decoders that need to guess 247 what config they should decode into. 248 Default is kNo_Config, but this can be changed with SetDeviceConfig() 249 */ 250 static SkBitmap::Config GetDeviceConfig(); 251 /** Set the default config for the running device. 252 Currently this used as a suggestion to image decoders that need to guess 253 what config they should decode into. 254 Default is kNo_Config. 255 This can be queried with GetDeviceConfig() 256 */ 257 static void SetDeviceConfig(SkBitmap::Config); 258 259 /** @cond UNIT_TEST */ 260 SkDEBUGCODE(static void UnitTest();) 261 /** @endcond */ 262 263 protected: 264 // must be overridden in subclasses. This guy is called by decode(...) 265 virtual bool onDecode(SkStream*, SkBitmap* bitmap, Mode) = 0; 266 267 /** Can be queried from within onDecode, to see if the user (possibly in 268 a different thread) has requested the decode to cancel. If this returns 269 true, your onDecode() should stop and return false. 270 Each subclass needs to decide how often it can query this, to balance 271 responsiveness with performance. 272 273 Calling this outside of onDecode() may return undefined values. 274 */ 275 276 public: 277 bool shouldCancelDecode() const { return fShouldCancelDecode; } 278 279 protected: 280 SkImageDecoder(); 281 282 // helper function for decoders to handle the (common) case where there is only 283 // once choice available in the image file. 284 bool chooseFromOneChoice(SkBitmap::Config config, int width, int height) const; 285 286 /* Helper for subclasses. Call this to allocate the pixel memory given the bitmap's 287 width/height/rowbytes/config. Returns true on success. This method handles checking 288 for an optional Allocator. 289 */ 290 bool allocPixelRef(SkBitmap*, SkColorTable*) const; 291 292 enum SrcDepth { 293 kIndex_SrcDepth, 294 k16Bit_SrcDepth, 295 k32Bit_SrcDepth 296 }; 297 /** The subclass, inside onDecode(), calls this to determine the config of 298 the returned bitmap. SrcDepth and hasAlpha reflect the raw data of the 299 src image. This routine returns the caller's preference given 300 srcDepth and hasAlpha, or kNo_Config if there is no preference. 301 302 Note: this also takes into account GetDeviceConfig(), so the subclass 303 need not call that. 304 */ 305 SkBitmap::Config getPrefConfig(SrcDepth, bool hasAlpha) const; 306 307 private: 308 Peeker* fPeeker; 309 Chooser* fChooser; 310 SkBitmap::Allocator* fAllocator; 311 int fSampleSize; 312 SkBitmap::Config fDefaultPref; // use if fUsePrefTable is false 313 SkBitmap::Config fPrefTable[6]; // use if fUsePrefTable is true 314 bool fDitherImage; 315 bool fUsePrefTable; 316 mutable bool fShouldCancelDecode; 317 318 // illegal 319 SkImageDecoder(const SkImageDecoder&); 320 SkImageDecoder& operator=(const SkImageDecoder&); 321 }; 322 323 /** Calling newDecoder with a stream returns a new matching imagedecoder 324 instance, or NULL if none can be found. The caller must manage its ownership 325 of the stream as usual, calling unref() when it is done, as the returned 326 decoder may have called ref() (and if so, the decoder is responsible for 327 balancing its ownership when it is destroyed). 328 */ 329 class SkImageDecoderFactory : public SkRefCnt { 330 public: 331 virtual SkImageDecoder* newDecoder(SkStream*) = 0; 332 }; 333 334 class SkDefaultImageDecoderFactory : SkImageDecoderFactory { 335 public: 336 // calls SkImageDecoder::Factory(stream) 337 virtual SkImageDecoder* newDecoder(SkStream* stream) { 338 return SkImageDecoder::Factory(stream); 339 } 340 }; 341 342 343 #endif 344
