BitmapFactory.java revision 5e2496bcee239ce9ebeff6022b7badf81d87492c
1/* 2 * Copyright (C) 2007 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 17package android.graphics; 18 19import android.content.res.AssetManager; 20import android.content.res.Resources; 21import android.os.Trace; 22import android.util.DisplayMetrics; 23import android.util.Log; 24import android.util.TypedValue; 25 26import java.io.FileDescriptor; 27import java.io.FileInputStream; 28import java.io.IOException; 29import java.io.InputStream; 30 31/** 32 * Creates Bitmap objects from various sources, including files, streams, 33 * and byte-arrays. 34 */ 35public class BitmapFactory { 36 private static final int DECODE_BUFFER_SIZE = 16 * 1024; 37 38 public static class Options { 39 /** 40 * Create a default Options object, which if left unchanged will give 41 * the same result from the decoder as if null were passed. 42 */ 43 public Options() { 44 inDither = false; 45 inScaled = true; 46 inPremultiplied = true; 47 } 48 49 /** 50 * If set, decode methods that take the Options object will attempt to 51 * reuse this bitmap when loading content. If the decode operation 52 * cannot use this bitmap, the decode method will return 53 * <code>null</code> and will throw an IllegalArgumentException. The 54 * current implementation necessitates that the reused bitmap be 55 * mutable, and the resulting reused bitmap will continue to remain 56 * mutable even when decoding a resource which would normally result in 57 * an immutable bitmap.</p> 58 * 59 * <p>You should still always use the returned Bitmap of the decode 60 * method and not assume that reusing the bitmap worked, due to the 61 * constraints outlined above and failure situations that can occur. 62 * Checking whether the return value matches the value of the inBitmap 63 * set in the Options structure will indicate if the bitmap was reused, 64 * but in all cases you should use the Bitmap returned by the decoding 65 * function to ensure that you are using the bitmap that was used as the 66 * decode destination.</p> 67 * 68 * <h3>Usage with BitmapFactory</h3> 69 * 70 * <p>As of {@link android.os.Build.VERSION_CODES#KITKAT}, any 71 * mutable bitmap can be reused by {@link BitmapFactory} to decode any 72 * other bitmaps as long as the resulting {@link Bitmap#getByteCount() 73 * byte count} of the decoded bitmap is less than or equal to the {@link 74 * Bitmap#getAllocationByteCount() allocated byte count} of the reused 75 * bitmap. This can be because the intrinsic size is smaller, or its 76 * size post scaling (for density / sample size) is smaller.</p> 77 * 78 * <p class="note">Prior to {@link android.os.Build.VERSION_CODES#KITKAT} 79 * additional constraints apply: The image being decoded (whether as a 80 * resource or as a stream) must be in jpeg or png format. Only equal 81 * sized bitmaps are supported, with {@link #inSampleSize} set to 1. 82 * Additionally, the {@link android.graphics.Bitmap.Config 83 * configuration} of the reused bitmap will override the setting of 84 * {@link #inPreferredConfig}, if set.</p> 85 * 86 * <h3>Usage with BitmapRegionDecoder</h3> 87 * 88 * <p>BitmapRegionDecoder will draw its requested content into the Bitmap 89 * provided, clipping if the output content size (post scaling) is larger 90 * than the provided Bitmap. The provided Bitmap's width, height, and 91 * {@link Bitmap.Config} will not be changed. 92 * 93 * <p class="note">BitmapRegionDecoder support for {@link #inBitmap} was 94 * introduced in {@link android.os.Build.VERSION_CODES#JELLY_BEAN}. All 95 * formats supported by BitmapRegionDecoder support Bitmap reuse via 96 * {@link #inBitmap}.</p> 97 * 98 * @see Bitmap#reconfigure(int,int, android.graphics.Bitmap.Config) 99 */ 100 public Bitmap inBitmap; 101 102 /** 103 * If set, decode methods will always return a mutable Bitmap instead of 104 * an immutable one. This can be used for instance to programmatically apply 105 * effects to a Bitmap loaded through BitmapFactory. 106 */ 107 @SuppressWarnings({"UnusedDeclaration"}) // used in native code 108 public boolean inMutable; 109 110 /** 111 * If set to true, the decoder will return null (no bitmap), but 112 * the out... fields will still be set, allowing the caller to query 113 * the bitmap without having to allocate the memory for its pixels. 114 */ 115 public boolean inJustDecodeBounds; 116 117 /** 118 * If set to a value > 1, requests the decoder to subsample the original 119 * image, returning a smaller image to save memory. The sample size is 120 * the number of pixels in either dimension that correspond to a single 121 * pixel in the decoded bitmap. For example, inSampleSize == 4 returns 122 * an image that is 1/4 the width/height of the original, and 1/16 the 123 * number of pixels. Any value <= 1 is treated the same as 1. Note: the 124 * decoder uses a final value based on powers of 2, any other value will 125 * be rounded down to the nearest power of 2. 126 */ 127 public int inSampleSize; 128 129 /** 130 * If this is non-null, the decoder will try to decode into this 131 * internal configuration. If it is null, or the request cannot be met, 132 * the decoder will try to pick the best matching config based on the 133 * system's screen depth, and characteristics of the original image such 134 * as if it has per-pixel alpha (requiring a config that also does). 135 * 136 * Image are loaded with the {@link Bitmap.Config#ARGB_8888} config by 137 * default. 138 */ 139 public Bitmap.Config inPreferredConfig = Bitmap.Config.ARGB_8888; 140 141 /** 142 * If true (which is the default), the resulting bitmap will have its 143 * color channels pre-multipled by the alpha channel. 144 * 145 * <p>This should NOT be set to false for images to be directly drawn by 146 * the view system or through a {@link Canvas}. The view system and 147 * {@link Canvas} assume all drawn images are pre-multiplied to simplify 148 * draw-time blending, and will throw a RuntimeException when 149 * un-premultiplied are drawn.</p> 150 * 151 * <p>This is likely only useful if you want to manipulate raw encoded 152 * image data, e.g. with RenderScript or custom OpenGL.</p> 153 * 154 * <p>This does not affect bitmaps without an alpha channel.</p> 155 * 156 * <p>Setting this flag to false while setting {@link #inScaled} to true 157 * may result in incorrect colors.</p> 158 * 159 * @see Bitmap#hasAlpha() 160 * @see Bitmap#isPremultiplied() 161 * @see #inScaled 162 */ 163 public boolean inPremultiplied; 164 165 /** 166 * @deprecated As of {@link android.os.Build.VERSION_CODES#N}, this is 167 * ignored. 168 * 169 * In {@link android.os.Build.VERSION_CODES#M} and below, if dither is 170 * true, the decoder will attempt to dither the decoded image. 171 */ 172 public boolean inDither; 173 174 /** 175 * The pixel density to use for the bitmap. This will always result 176 * in the returned bitmap having a density set for it (see 177 * {@link Bitmap#setDensity(int) Bitmap.setDensity(int)}). In addition, 178 * if {@link #inScaled} is set (which it is by default} and this 179 * density does not match {@link #inTargetDensity}, then the bitmap 180 * will be scaled to the target density before being returned. 181 * 182 * <p>If this is 0, 183 * {@link BitmapFactory#decodeResource(Resources, int)}, 184 * {@link BitmapFactory#decodeResource(Resources, int, android.graphics.BitmapFactory.Options)}, 185 * and {@link BitmapFactory#decodeResourceStream} 186 * will fill in the density associated with the resource. The other 187 * functions will leave it as-is and no density will be applied. 188 * 189 * @see #inTargetDensity 190 * @see #inScreenDensity 191 * @see #inScaled 192 * @see Bitmap#setDensity(int) 193 * @see android.util.DisplayMetrics#densityDpi 194 */ 195 public int inDensity; 196 197 /** 198 * The pixel density of the destination this bitmap will be drawn to. 199 * This is used in conjunction with {@link #inDensity} and 200 * {@link #inScaled} to determine if and how to scale the bitmap before 201 * returning it. 202 * 203 * <p>If this is 0, 204 * {@link BitmapFactory#decodeResource(Resources, int)}, 205 * {@link BitmapFactory#decodeResource(Resources, int, android.graphics.BitmapFactory.Options)}, 206 * and {@link BitmapFactory#decodeResourceStream} 207 * will fill in the density associated the Resources object's 208 * DisplayMetrics. The other 209 * functions will leave it as-is and no scaling for density will be 210 * performed. 211 * 212 * @see #inDensity 213 * @see #inScreenDensity 214 * @see #inScaled 215 * @see android.util.DisplayMetrics#densityDpi 216 */ 217 public int inTargetDensity; 218 219 /** 220 * The pixel density of the actual screen that is being used. This is 221 * purely for applications running in density compatibility code, where 222 * {@link #inTargetDensity} is actually the density the application 223 * sees rather than the real screen density. 224 * 225 * <p>By setting this, you 226 * allow the loading code to avoid scaling a bitmap that is currently 227 * in the screen density up/down to the compatibility density. Instead, 228 * if {@link #inDensity} is the same as {@link #inScreenDensity}, the 229 * bitmap will be left as-is. Anything using the resulting bitmap 230 * must also used {@link Bitmap#getScaledWidth(int) 231 * Bitmap.getScaledWidth} and {@link Bitmap#getScaledHeight 232 * Bitmap.getScaledHeight} to account for any different between the 233 * bitmap's density and the target's density. 234 * 235 * <p>This is never set automatically for the caller by 236 * {@link BitmapFactory} itself. It must be explicitly set, since the 237 * caller must deal with the resulting bitmap in a density-aware way. 238 * 239 * @see #inDensity 240 * @see #inTargetDensity 241 * @see #inScaled 242 * @see android.util.DisplayMetrics#densityDpi 243 */ 244 public int inScreenDensity; 245 246 /** 247 * When this flag is set, if {@link #inDensity} and 248 * {@link #inTargetDensity} are not 0, the 249 * bitmap will be scaled to match {@link #inTargetDensity} when loaded, 250 * rather than relying on the graphics system scaling it each time it 251 * is drawn to a Canvas. 252 * 253 * <p>BitmapRegionDecoder ignores this flag, and will not scale output 254 * based on density. (though {@link #inSampleSize} is supported)</p> 255 * 256 * <p>This flag is turned on by default and should be turned off if you need 257 * a non-scaled version of the bitmap. Nine-patch bitmaps ignore this 258 * flag and are always scaled. 259 * 260 * <p>If {@link #inPremultiplied} is set to false, and the image has alpha, 261 * setting this flag to true may result in incorrect colors. 262 */ 263 public boolean inScaled; 264 265 /** 266 * @deprecated As of {@link android.os.Build.VERSION_CODES#LOLLIPOP}, this is 267 * ignored. 268 * 269 * In {@link android.os.Build.VERSION_CODES#KITKAT} and below, if this 270 * is set to true, then the resulting bitmap will allocate its 271 * pixels such that they can be purged if the system needs to reclaim 272 * memory. In that instance, when the pixels need to be accessed again 273 * (e.g. the bitmap is drawn, getPixels() is called), they will be 274 * automatically re-decoded. 275 * 276 * <p>For the re-decode to happen, the bitmap must have access to the 277 * encoded data, either by sharing a reference to the input 278 * or by making a copy of it. This distinction is controlled by 279 * inInputShareable. If this is true, then the bitmap may keep a shallow 280 * reference to the input. If this is false, then the bitmap will 281 * explicitly make a copy of the input data, and keep that. Even if 282 * sharing is allowed, the implementation may still decide to make a 283 * deep copy of the input data.</p> 284 * 285 * <p>While inPurgeable can help avoid big Dalvik heap allocations (from 286 * API level 11 onward), it sacrifices performance predictability since any 287 * image that the view system tries to draw may incur a decode delay which 288 * can lead to dropped frames. Therefore, most apps should avoid using 289 * inPurgeable to allow for a fast and fluid UI. To minimize Dalvik heap 290 * allocations use the {@link #inBitmap} flag instead.</p> 291 * 292 * <p class="note"><strong>Note:</strong> This flag is ignored when used 293 * with {@link #decodeResource(Resources, int, 294 * android.graphics.BitmapFactory.Options)} or {@link #decodeFile(String, 295 * android.graphics.BitmapFactory.Options)}.</p> 296 */ 297 @Deprecated 298 public boolean inPurgeable; 299 300 /** 301 * @deprecated As of {@link android.os.Build.VERSION_CODES#LOLLIPOP}, this is 302 * ignored. 303 * 304 * In {@link android.os.Build.VERSION_CODES#KITKAT} and below, this 305 * field works in conjuction with inPurgeable. If inPurgeable is false, 306 * then this field is ignored. If inPurgeable is true, then this field 307 * determines whether the bitmap can share a reference to the input 308 * data (inputstream, array, etc.) or if it must make a deep copy. 309 */ 310 @Deprecated 311 public boolean inInputShareable; 312 313 /** 314 * @deprecated As of {@link android.os.Build.VERSION_CODES#N}, this is 315 * ignored. The output will always be high quality. 316 * 317 * In {@link android.os.Build.VERSION_CODES#M} and below, if 318 * inPreferQualityOverSpeed is set to true, the decoder will try to 319 * decode the reconstructed image to a higher quality even at the 320 * expense of the decoding speed. Currently the field only affects JPEG 321 * decode, in the case of which a more accurate, but slightly slower, 322 * IDCT method will be used instead. 323 */ 324 public boolean inPreferQualityOverSpeed; 325 326 /** 327 * The resulting width of the bitmap. If {@link #inJustDecodeBounds} is 328 * set to false, this will be width of the output bitmap after any 329 * scaling is applied. If true, it will be the width of the input image 330 * without any accounting for scaling. 331 * 332 * <p>outWidth will be set to -1 if there is an error trying to decode.</p> 333 */ 334 public int outWidth; 335 336 /** 337 * The resulting height of the bitmap. If {@link #inJustDecodeBounds} is 338 * set to false, this will be height of the output bitmap after any 339 * scaling is applied. If true, it will be the height of the input image 340 * without any accounting for scaling. 341 * 342 * <p>outHeight will be set to -1 if there is an error trying to decode.</p> 343 */ 344 public int outHeight; 345 346 /** 347 * If known, this string is set to the mimetype of the decoded image. 348 * If not know, or there is an error, it is set to null. 349 */ 350 public String outMimeType; 351 352 /** 353 * Temp storage to use for decoding. Suggest 16K or so. 354 */ 355 public byte[] inTempStorage; 356 357 /** 358 * Flag to indicate that cancel has been called on this object. This 359 * is useful if there's an intermediary that wants to first decode the 360 * bounds and then decode the image. In that case the intermediary 361 * can check, inbetween the bounds decode and the image decode, to see 362 * if the operation is canceled. 363 */ 364 public boolean mCancel; 365 366 /** 367 * @deprecated As of {@link android.os.Build.VERSION_CODES#N}, this 368 * will not affect the decode, though it will still set mCancel. 369 * 370 * In {@link android.os.Build.VERSION_CODES#M} and below, if this can 371 * be called from another thread while this options object is inside 372 * a decode... call. Calling this will notify the decoder that it 373 * should cancel its operation. This is not guaranteed to cancel the 374 * decode, but if it does, the decoder... operation will return null, 375 * or if inJustDecodeBounds is true, will set outWidth/outHeight 376 * to -1 377 */ 378 public void requestCancelDecode() { 379 mCancel = true; 380 } 381 } 382 383 /** 384 * Decode a file path into a bitmap. If the specified file name is null, 385 * or cannot be decoded into a bitmap, the function returns null. 386 * 387 * @param pathName complete path name for the file to be decoded. 388 * @param opts null-ok; Options that control downsampling and whether the 389 * image should be completely decoded, or just is size returned. 390 * @return The decoded bitmap, or null if the image data could not be 391 * decoded, or, if opts is non-null, if opts requested only the 392 * size be returned (in opts.outWidth and opts.outHeight) 393 */ 394 public static Bitmap decodeFile(String pathName, Options opts) { 395 Bitmap bm = null; 396 InputStream stream = null; 397 try { 398 stream = new FileInputStream(pathName); 399 bm = decodeStream(stream, null, opts); 400 } catch (Exception e) { 401 /* do nothing. 402 If the exception happened on open, bm will be null. 403 */ 404 Log.e("BitmapFactory", "Unable to decode stream: " + e); 405 } finally { 406 if (stream != null) { 407 try { 408 stream.close(); 409 } catch (IOException e) { 410 // do nothing here 411 } 412 } 413 } 414 return bm; 415 } 416 417 /** 418 * Decode a file path into a bitmap. If the specified file name is null, 419 * or cannot be decoded into a bitmap, the function returns null. 420 * 421 * @param pathName complete path name for the file to be decoded. 422 * @return the resulting decoded bitmap, or null if it could not be decoded. 423 */ 424 public static Bitmap decodeFile(String pathName) { 425 return decodeFile(pathName, null); 426 } 427 428 /** 429 * Decode a new Bitmap from an InputStream. This InputStream was obtained from 430 * resources, which we pass to be able to scale the bitmap accordingly. 431 */ 432 public static Bitmap decodeResourceStream(Resources res, TypedValue value, 433 InputStream is, Rect pad, Options opts) { 434 435 if (opts == null) { 436 opts = new Options(); 437 } 438 439 if (opts.inDensity == 0 && value != null) { 440 final int density = value.density; 441 if (density == TypedValue.DENSITY_DEFAULT) { 442 opts.inDensity = DisplayMetrics.DENSITY_DEFAULT; 443 } else if (density != TypedValue.DENSITY_NONE) { 444 opts.inDensity = density; 445 } 446 } 447 448 if (opts.inTargetDensity == 0 && res != null) { 449 opts.inTargetDensity = res.getDisplayMetrics().densityDpi; 450 } 451 452 return decodeStream(is, pad, opts); 453 } 454 455 /** 456 * Synonym for opening the given resource and calling 457 * {@link #decodeResourceStream}. 458 * 459 * @param res The resources object containing the image data 460 * @param id The resource id of the image data 461 * @param opts null-ok; Options that control downsampling and whether the 462 * image should be completely decoded, or just is size returned. 463 * @return The decoded bitmap, or null if the image data could not be 464 * decoded, or, if opts is non-null, if opts requested only the 465 * size be returned (in opts.outWidth and opts.outHeight) 466 */ 467 public static Bitmap decodeResource(Resources res, int id, Options opts) { 468 Bitmap bm = null; 469 InputStream is = null; 470 471 try { 472 final TypedValue value = new TypedValue(); 473 is = res.openRawResource(id, value); 474 475 bm = decodeResourceStream(res, value, is, null, opts); 476 } catch (Exception e) { 477 /* do nothing. 478 If the exception happened on open, bm will be null. 479 If it happened on close, bm is still valid. 480 */ 481 } finally { 482 try { 483 if (is != null) is.close(); 484 } catch (IOException e) { 485 // Ignore 486 } 487 } 488 489 if (bm == null && opts != null && opts.inBitmap != null) { 490 throw new IllegalArgumentException("Problem decoding into existing bitmap"); 491 } 492 493 return bm; 494 } 495 496 /** 497 * Synonym for {@link #decodeResource(Resources, int, android.graphics.BitmapFactory.Options)} 498 * with null Options. 499 * 500 * @param res The resources object containing the image data 501 * @param id The resource id of the image data 502 * @return The decoded bitmap, or null if the image could not be decoded. 503 */ 504 public static Bitmap decodeResource(Resources res, int id) { 505 return decodeResource(res, id, null); 506 } 507 508 /** 509 * Decode an immutable bitmap from the specified byte array. 510 * 511 * @param data byte array of compressed image data 512 * @param offset offset into imageData for where the decoder should begin 513 * parsing. 514 * @param length the number of bytes, beginning at offset, to parse 515 * @param opts null-ok; Options that control downsampling and whether the 516 * image should be completely decoded, or just is size returned. 517 * @return The decoded bitmap, or null if the image data could not be 518 * decoded, or, if opts is non-null, if opts requested only the 519 * size be returned (in opts.outWidth and opts.outHeight) 520 */ 521 public static Bitmap decodeByteArray(byte[] data, int offset, int length, Options opts) { 522 if ((offset | length) < 0 || data.length < offset + length) { 523 throw new ArrayIndexOutOfBoundsException(); 524 } 525 526 Bitmap bm; 527 528 Trace.traceBegin(Trace.TRACE_TAG_GRAPHICS, "decodeBitmap"); 529 try { 530 bm = nativeDecodeByteArray(data, offset, length, opts); 531 532 if (bm == null && opts != null && opts.inBitmap != null) { 533 throw new IllegalArgumentException("Problem decoding into existing bitmap"); 534 } 535 setDensityFromOptions(bm, opts); 536 } finally { 537 Trace.traceEnd(Trace.TRACE_TAG_GRAPHICS); 538 } 539 540 return bm; 541 } 542 543 /** 544 * Decode an immutable bitmap from the specified byte array. 545 * 546 * @param data byte array of compressed image data 547 * @param offset offset into imageData for where the decoder should begin 548 * parsing. 549 * @param length the number of bytes, beginning at offset, to parse 550 * @return The decoded bitmap, or null if the image could not be decoded. 551 */ 552 public static Bitmap decodeByteArray(byte[] data, int offset, int length) { 553 return decodeByteArray(data, offset, length, null); 554 } 555 556 /** 557 * Set the newly decoded bitmap's density based on the Options. 558 */ 559 private static void setDensityFromOptions(Bitmap outputBitmap, Options opts) { 560 if (outputBitmap == null || opts == null) return; 561 562 final int density = opts.inDensity; 563 if (density != 0) { 564 outputBitmap.setDensity(density); 565 final int targetDensity = opts.inTargetDensity; 566 if (targetDensity == 0 || density == targetDensity || density == opts.inScreenDensity) { 567 return; 568 } 569 570 byte[] np = outputBitmap.getNinePatchChunk(); 571 final boolean isNinePatch = np != null && NinePatch.isNinePatchChunk(np); 572 if (opts.inScaled || isNinePatch) { 573 outputBitmap.setDensity(targetDensity); 574 } 575 } else if (opts.inBitmap != null) { 576 // bitmap was reused, ensure density is reset 577 outputBitmap.setDensity(Bitmap.getDefaultDensity()); 578 } 579 } 580 581 /** 582 * Decode an input stream into a bitmap. If the input stream is null, or 583 * cannot be used to decode a bitmap, the function returns null. 584 * The stream's position will be where ever it was after the encoded data 585 * was read. 586 * 587 * @param is The input stream that holds the raw data to be decoded into a 588 * bitmap. 589 * @param outPadding If not null, return the padding rect for the bitmap if 590 * it exists, otherwise set padding to [-1,-1,-1,-1]. If 591 * no bitmap is returned (null) then padding is 592 * unchanged. 593 * @param opts null-ok; Options that control downsampling and whether the 594 * image should be completely decoded, or just is size returned. 595 * @return The decoded bitmap, or null if the image data could not be 596 * decoded, or, if opts is non-null, if opts requested only the 597 * size be returned (in opts.outWidth and opts.outHeight) 598 * 599 * <p class="note">Prior to {@link android.os.Build.VERSION_CODES#KITKAT}, 600 * if {@link InputStream#markSupported is.markSupported()} returns true, 601 * <code>is.mark(1024)</code> would be called. As of 602 * {@link android.os.Build.VERSION_CODES#KITKAT}, this is no longer the case.</p> 603 */ 604 public static Bitmap decodeStream(InputStream is, Rect outPadding, Options opts) { 605 // we don't throw in this case, thus allowing the caller to only check 606 // the cache, and not force the image to be decoded. 607 if (is == null) { 608 return null; 609 } 610 611 Bitmap bm = null; 612 613 Trace.traceBegin(Trace.TRACE_TAG_GRAPHICS, "decodeBitmap"); 614 try { 615 if (is instanceof AssetManager.AssetInputStream) { 616 final long asset = ((AssetManager.AssetInputStream) is).getNativeAsset(); 617 bm = nativeDecodeAsset(asset, outPadding, opts); 618 } else { 619 bm = decodeStreamInternal(is, outPadding, opts); 620 } 621 622 if (bm == null && opts != null && opts.inBitmap != null) { 623 throw new IllegalArgumentException("Problem decoding into existing bitmap"); 624 } 625 626 setDensityFromOptions(bm, opts); 627 } finally { 628 Trace.traceEnd(Trace.TRACE_TAG_GRAPHICS); 629 } 630 631 return bm; 632 } 633 634 /** 635 * Private helper function for decoding an InputStream natively. Buffers the input enough to 636 * do a rewind as needed, and supplies temporary storage if necessary. is MUST NOT be null. 637 */ 638 private static Bitmap decodeStreamInternal(InputStream is, Rect outPadding, Options opts) { 639 // ASSERT(is != null); 640 byte [] tempStorage = null; 641 if (opts != null) tempStorage = opts.inTempStorage; 642 if (tempStorage == null) tempStorage = new byte[DECODE_BUFFER_SIZE]; 643 return nativeDecodeStream(is, tempStorage, outPadding, opts); 644 } 645 646 /** 647 * Decode an input stream into a bitmap. If the input stream is null, or 648 * cannot be used to decode a bitmap, the function returns null. 649 * The stream's position will be where ever it was after the encoded data 650 * was read. 651 * 652 * @param is The input stream that holds the raw data to be decoded into a 653 * bitmap. 654 * @return The decoded bitmap, or null if the image data could not be decoded. 655 */ 656 public static Bitmap decodeStream(InputStream is) { 657 return decodeStream(is, null, null); 658 } 659 660 /** 661 * Decode a bitmap from the file descriptor. If the bitmap cannot be decoded 662 * return null. The position within the descriptor will not be changed when 663 * this returns, so the descriptor can be used again as-is. 664 * 665 * @param fd The file descriptor containing the bitmap data to decode 666 * @param outPadding If not null, return the padding rect for the bitmap if 667 * it exists, otherwise set padding to [-1,-1,-1,-1]. If 668 * no bitmap is returned (null) then padding is 669 * unchanged. 670 * @param opts null-ok; Options that control downsampling and whether the 671 * image should be completely decoded, or just its size returned. 672 * @return the decoded bitmap, or null 673 */ 674 public static Bitmap decodeFileDescriptor(FileDescriptor fd, Rect outPadding, Options opts) { 675 Bitmap bm; 676 677 Trace.traceBegin(Trace.TRACE_TAG_GRAPHICS, "decodeFileDescriptor"); 678 try { 679 if (nativeIsSeekable(fd)) { 680 bm = nativeDecodeFileDescriptor(fd, outPadding, opts); 681 } else { 682 FileInputStream fis = new FileInputStream(fd); 683 try { 684 bm = decodeStreamInternal(fis, outPadding, opts); 685 } finally { 686 try { 687 fis.close(); 688 } catch (Throwable t) {/* ignore */} 689 } 690 } 691 692 if (bm == null && opts != null && opts.inBitmap != null) { 693 throw new IllegalArgumentException("Problem decoding into existing bitmap"); 694 } 695 696 setDensityFromOptions(bm, opts); 697 } finally { 698 Trace.traceEnd(Trace.TRACE_TAG_GRAPHICS); 699 } 700 return bm; 701 } 702 703 /** 704 * Decode a bitmap from the file descriptor. If the bitmap cannot be decoded 705 * return null. The position within the descriptor will not be changed when 706 * this returns, so the descriptor can be used again as is. 707 * 708 * @param fd The file descriptor containing the bitmap data to decode 709 * @return the decoded bitmap, or null 710 */ 711 public static Bitmap decodeFileDescriptor(FileDescriptor fd) { 712 return decodeFileDescriptor(fd, null, null); 713 } 714 715 private static native Bitmap nativeDecodeStream(InputStream is, byte[] storage, 716 Rect padding, Options opts); 717 private static native Bitmap nativeDecodeFileDescriptor(FileDescriptor fd, 718 Rect padding, Options opts); 719 private static native Bitmap nativeDecodeAsset(long nativeAsset, Rect padding, Options opts); 720 private static native Bitmap nativeDecodeByteArray(byte[] data, int offset, 721 int length, Options opts); 722 private static native boolean nativeIsSeekable(FileDescriptor fd); 723} 724