From 7571542c9d54fa3501e3ce9d50d3625e22f39e81 Mon Sep 17 00:00:00 2001 From: kmccormick Date: Mon, 4 Mar 2013 15:25:40 -0800 Subject: Doc update: Add memory mgt lesson to bitmaps class Change-Id: If780ad8bfabd66de21842bdb465d86ab24b2940c --- docs/downloads/training/BitmapFun.zip | Bin 438123 -> 437585 bytes .../training/displaying-bitmaps/cache-bitmap.jd | 4 - .../training/displaying-bitmaps/display-bitmap.jd | 2 - docs/html/training/displaying-bitmaps/index.jd | 5 +- .../training/displaying-bitmaps/load-bitmap.jd | 4 +- .../training/displaying-bitmaps/manage-memory.jd | 297 +++++++++++++++++++++ .../training/displaying-bitmaps/process-bitmap.jd | 4 - docs/html/training/training_toc.cs | 4 + 8 files changed, 306 insertions(+), 14 deletions(-) create mode 100644 docs/html/training/displaying-bitmaps/manage-memory.jd diff --git a/docs/downloads/training/BitmapFun.zip b/docs/downloads/training/BitmapFun.zip index 61b537d..48bea78 100644 Binary files a/docs/downloads/training/BitmapFun.zip and b/docs/downloads/training/BitmapFun.zip differ diff --git a/docs/html/training/displaying-bitmaps/cache-bitmap.jd b/docs/html/training/displaying-bitmaps/cache-bitmap.jd index 417ec5b..b1608c3 100644 --- a/docs/html/training/displaying-bitmaps/cache-bitmap.jd +++ b/docs/html/training/displaying-bitmaps/cache-bitmap.jd @@ -3,10 +3,6 @@ parent.title=Displaying Bitmaps Efficiently parent.link=index.html trainingnavtop=true -next.title=Displaying Bitmaps in Your UI -next.link=display-bitmap.html -previous.title=Processing Bitmaps Off the UI Thread -previous.link=process-bitmap.html @jd:body diff --git a/docs/html/training/displaying-bitmaps/display-bitmap.jd b/docs/html/training/displaying-bitmaps/display-bitmap.jd index 4572c42..ed1836c 100644 --- a/docs/html/training/displaying-bitmaps/display-bitmap.jd +++ b/docs/html/training/displaying-bitmaps/display-bitmap.jd @@ -3,8 +3,6 @@ parent.title=Displaying Bitmaps Efficiently parent.link=index.html trainingnavtop=true -previous.title=Caching Bitmaps -previous.link=cache-bitmap.html @jd:body diff --git a/docs/html/training/displaying-bitmaps/index.jd b/docs/html/training/displaying-bitmaps/index.jd index b91172b..a828291 100644 --- a/docs/html/training/displaying-bitmaps/index.jd +++ b/docs/html/training/displaying-bitmaps/index.jd @@ -26,7 +26,7 @@ next.link=load-bitmap.html -

This class covers some common techniques for processing and loading {@link +

Learn how to use common techniques to process and load {@link android.graphics.Bitmap} objects in a way that keeps your user interface (UI) components responsive and avoids exceeding your application memory limit. If you're not careful, bitmaps can quickly consume your available memory budget leading to an application crash due to the dreaded @@ -70,6 +70,9 @@ exception:
{@code java.lang.OutofMemoryError: bitmap size exceeds VM budget

This lesson walks you through using a memory and disk bitmap cache to improve the responsiveness and fluidity of your UI when loading multiple bitmaps.
+
Managing Bitmap Memory
+
This lesson explains how to manage bitmap memory to maximize your app's performance.
+
Displaying Bitmaps in Your UI
This lesson brings everything together, showing you how to load multiple bitmaps into components like {@link android.support.v4.view.ViewPager} and {@link android.widget.GridView} diff --git a/docs/html/training/displaying-bitmaps/load-bitmap.jd b/docs/html/training/displaying-bitmaps/load-bitmap.jd index 283f272..633ffd2 100644 --- a/docs/html/training/displaying-bitmaps/load-bitmap.jd +++ b/docs/html/training/displaying-bitmaps/load-bitmap.jd @@ -3,8 +3,6 @@ parent.title=Displaying Bitmaps Efficiently parent.link=index.html trainingnavtop=true -next.title=Processing Bitmaps Off the UI Thread -next.link=process-bitmap.html @jd:body @@ -167,4 +165,4 @@ mImageView.setImageBitmap(

You can follow a similar process to decode bitmaps from other sources, by substituting the appropriate {@link android.graphics.BitmapFactory#decodeByteArray(byte[],int,int,android.graphics.BitmapFactory.Options) -BitmapFactory.decode*} method as needed.

\ No newline at end of file +BitmapFactory.decode*} method as needed.

diff --git a/docs/html/training/displaying-bitmaps/manage-memory.jd b/docs/html/training/displaying-bitmaps/manage-memory.jd new file mode 100644 index 0000000..60ac2e6 --- /dev/null +++ b/docs/html/training/displaying-bitmaps/manage-memory.jd @@ -0,0 +1,297 @@ +page.title=Managing Bitmap Memory +parent.title=Displaying Bitmaps Efficiently +parent.link=index.html + +trainingnavtop=true + +@jd:body + +
+
+ +

This lesson teaches you to

+
    +
  1. Manage Memory on Android 2.3.3 and Lower
    2. +
  2. Manage Memory on Android 3.0 and Higher
    3. +
+ +

You should also read

+ + +

Try it out

+ +
+ Download the sample +

BitmapFun.zip

+
+ +
+
+ +

In addition to the steps described in Caching Bitmaps, +there are specific things you can do to facilitate garbage collection +and bitmap reuse. The recommended strategy depends on which version(s) +of Android you are targeting. The {@code BitmapFun} sample app included with +this class shows you how to design your app to work efficiently across +different versions of Android.

+ +

To set the stage for this lesson, here is how Android's management of +bitmap memory has evolved:

+ + +

The following sections describe how to optimize bitmap memory +management for different Android versions.

+ +

Manage Memory on Android 2.3.3 and Lower

+ +

On Android 2.3.3 (API level 10) and lower, using +{@link android.graphics.Bitmap#recycle recycle()} +is recommended. If you're displaying large amounts of bitmap data in your app, +you're likely to run into +{@link java.lang.OutOfMemoryError} errors. The +{@link android.graphics.Bitmap#recycle recycle()} method allows an app +to reclaim memory as soon as possible.

+ +

Caution: You should use +{@link android.graphics.Bitmap#recycle recycle()} only when you are sure that the +bitmap is no longer being used. If you call {@link android.graphics.Bitmap#recycle recycle()} +and later attempt to draw the bitmap, you will get the error: +{@code "Canvas: trying to use a recycled bitmap"}.

+ +

The following code snippet gives an example of calling +{@link android.graphics.Bitmap#recycle recycle()}. It uses reference counting +(in the variables {@code mDisplayRefCount} and {@code mCacheRefCount}) to track +whether a bitmap is currently being displayed or in the cache. The +code recycles the bitmap when these conditions are met:

+ + + +
private int mCacheRefCount = 0;
+private int mDisplayRefCount = 0;
+...
+// Notify the drawable that the displayed state has changed.
+// Keep a count to determine when the drawable is no longer displayed.
+public void setIsDisplayed(boolean isDisplayed) {
+    synchronized (this) {
+        if (isDisplayed) {
+            mDisplayRefCount++;
+            mHasBeenDisplayed = true;
+        } else {
+            mDisplayRefCount--;
+        }
+    }
+    // Check to see if recycle() can be called.
+    checkState();
+}
+
+// Notify the drawable that the cache state has changed.
+// Keep a count to determine when the drawable is no longer being cached.
+public void setIsCached(boolean isCached) {
+    synchronized (this) {
+        if (isCached) {
+            mCacheRefCount++;
+        } else {
+            mCacheRefCount--;
+        }
+    }
+    // Check to see if recycle() can be called.
+    checkState();
+}
+
+private synchronized void checkState() {
+    // If the drawable cache and display ref counts = 0, and this drawable
+    // has been displayed, then recycle.
+    if (mCacheRefCount <= 0 && mDisplayRefCount <= 0 && mHasBeenDisplayed
+            && hasValidBitmap()) {
+        getBitmap().recycle();
+    }
+}
+
+private synchronized boolean hasValidBitmap() {
+    Bitmap bitmap = getBitmap();
+    return bitmap != null && !bitmap.isRecycled();
+}
+ +

Manage Memory on Android 3.0 and Higher

+ +

Android 3.0 (API Level 11) introduces the +{@link android.graphics.BitmapFactory.Options#inBitmap BitmapFactory.Options.inBitmap} +field. If this option is set, decode methods that take the +{@link android.graphics.BitmapFactory.Options Options} object +will attempt to reuse an existing bitmap when loading content. This means +that the bitmap's memory is reused, resulting in improved performance, and +removing both memory allocation and de-allocation. There are some caveats in using +{@link android.graphics.BitmapFactory.Options#inBitmap}:

+