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