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 17package android.graphics; 18 19/** 20 * LargeBitmap can be used to decode a rectangle region from an image. 21 * LargeBimap is particularly useful when an original image is large and 22 * you only need parts of the image. 23 * 24 * To create a LargeBitmap, call BitmapFactory.createLargeBitmap(). 25 * Given a LargeBitmap, users can call decodeRegion() repeatedly 26 * to get a decoded Bitmap of the specified region. 27 * @hide 28 */ 29public final class LargeBitmap { 30 private long mNativeLargeBitmap; 31 private boolean mRecycled; 32 33 /* Private constructor that must received an already allocated native 34 large bitmap int (pointer). 35 36 This can be called from JNI code. 37 */ 38 private LargeBitmap(long nativeLbm) { 39 mNativeLargeBitmap = nativeLbm; 40 mRecycled = false; 41 } 42 43 /** 44 * Decodes a rectangle region in the image specified by rect. 45 * 46 * @param rect The rectangle that specified the region to be decode. 47 * @param opts null-ok; Options that control downsampling. 48 * inPurgeable is not supported. 49 * @return The decoded bitmap, or null if the image data could not be 50 * decoded. 51 */ 52 public Bitmap decodeRegion(Rect rect, BitmapFactory.Options options) { 53 checkRecycled("decodeRegion called on recycled large bitmap"); 54 if (rect.left < 0 || rect.top < 0 || rect.right > getWidth() || rect.bottom > getHeight()) 55 throw new IllegalArgumentException("rectangle is not inside the image"); 56 return nativeDecodeRegion(mNativeLargeBitmap, rect.left, rect.top, 57 rect.right - rect.left, rect.bottom - rect.top, options); 58 } 59 60 /** Returns the original image's width */ 61 public int getWidth() { 62 checkRecycled("getWidth called on recycled large bitmap"); 63 return nativeGetWidth(mNativeLargeBitmap); 64 } 65 66 /** Returns the original image's height */ 67 public int getHeight() { 68 checkRecycled("getHeight called on recycled large bitmap"); 69 return nativeGetHeight(mNativeLargeBitmap); 70 } 71 72 /** 73 * Frees up the memory associated with this large bitmap, and mark the 74 * large bitmap as "dead", meaning it will throw an exception if decodeRegion(), 75 * getWidth() or getHeight() is called. 76 * This operation cannot be reversed, so it should only be called if you are 77 * sure there are no further uses for the large bitmap. This is an advanced call, 78 * and normally need not be called, since the normal GC process will free up this 79 * memory when there are no more references to this bitmap. 80 */ 81 public void recycle() { 82 if (!mRecycled) { 83 nativeClean(mNativeLargeBitmap); 84 mRecycled = true; 85 } 86 } 87 88 /** 89 * Returns true if this large bitmap has been recycled. 90 * If so, then it is an error to try use its method. 91 * 92 * @return true if the large bitmap has been recycled 93 */ 94 public final boolean isRecycled() { 95 return mRecycled; 96 } 97 98 /** 99 * Called by methods that want to throw an exception if the bitmap 100 * has already been recycled. 101 */ 102 private void checkRecycled(String errorMessage) { 103 if (mRecycled) { 104 throw new IllegalStateException(errorMessage); 105 } 106 } 107 108 protected void finalize() { 109 recycle(); 110 } 111 112 private static native Bitmap nativeDecodeRegion(long nativeLbm, 113 int start_x, int start_y, int width, int height, 114 BitmapFactory.Options options); 115 private static native int nativeGetWidth(long nativeLbm); 116 private static native int nativeGetHeight(long nativeLbm); 117 private static native void nativeClean(long nativeLbm); 118} 119