AI 148470: add documentation about aapt image optimization

  BUG=1735176

Automated import of CL 148470

2 files changed, 26 insertions, 8 deletions

diff --git a/docs/html/guide/topics/graphics/2d-graphics.jd b/docs/html/guide/topics/graphics/2d-graphics.jd
index 1f62f3d..af584a2 100644
--- a/docs/html/guide/topics/graphics/2d-graphics.jd
+++ b/docs/html/guide/topics/graphics/2d-graphics.jd
@@ -10,8 +10,8 @@ parent.link=index.html
     <ol>
       <li><a href="#drawables">Drawables</a>
         <ol>
-          <li><a href="#drawable-images">Creating from resource images</a></li>
-          <li><a href="#drawable-xml">Creating from resource XML</a></li>
+          <li><a href="#drawables-from-images">Creating from resource images</a></li>
+          <li><a href="#drawables-from-xml">Creating from resource XML</a></li>
         </ol>
       </li>
       <li><a href="#shape-drawable">ShapeDrawable</a></li>
@@ -59,6 +59,15 @@ From there, you can reference it from your code or your XML layout.
 Either way, it is referred using a resource ID, which is the file name without the file type
 extension (E.g., <code>my_image.png</code> is referenced as <var>my_image</var>).</p>
 
+<p class="note"><strong>Note:</strong> Image resources placed in <code>res/drawable/</code> may be 
+automatically optimized with lossless image compression by the 
+<a href="{@docRoot}guide/developing/tools/aapt.html">aapt</a> tool. For example, a true-color PNG that does
+not require more than 256 colors may be converted to an 8-bit PNG with a color palette. This 
+will result in an image of equal quality but which requires less memory. So be aware that the
+image binaries placed in this directory can change during the build. If you plan on reading
+an image as a bit stream in order to convert it to a bitmap, put your images in the <code>res/raw/</code>
+folder instead, where they will not be optimized.</p>
+
 <h4>Example code</h4>
 <p>The following code snippet demonstrates how to build an {@link android.widget.ImageView} that uses an image
 from drawable resources and add it to the layout.</p>
@@ -90,7 +99,7 @@ Resources res = mContext.getResources();
 Drawable myImage = res.getDrawable(R.drawable.my_image);
 </pre>
 
-<p class="caution"><strong>Caution:</strong> Each unique resource in your project can maintain only one
+<p class="warning"><strong>Note:</strong> Each unique resource in your project can maintain only one
 state, no matter how many different objects you may instantiate for it. For example, if you instantiate two
 Drawable objects from the same image resource, then change a property (such as the alpha) for one of the 
 Drawables, then it will also affect the other. So when dealing with multiple instances of an image resource, 
diff --git a/docs/html/guide/topics/resources/resources-i18n.jd b/docs/html/guide/topics/resources/resources-i18n.jd
index b1da4cd..4bbb44a 100644
--- a/docs/html/guide/topics/resources/resources-i18n.jd
+++ b/docs/html/guide/topics/resources/resources-i18n.jd
@@ -111,21 +111,30 @@ the containing file.</p>
         <td><code>res/drawable/</code></td>
         <td><p>.png, .9.png, .jpg files that are compiled into the following
                 Drawable resource subtypes:</p>
-            <p>To get a resource of this type, use <code>Resource.getDrawable(<em>id</em>)</code>
-            <ul>
+            <ul class="nolist">
                 <li><a href="available-resources.html#imagefileresources">bitmap files</a></li>
                 <li><a href="available-resources.html#ninepatch">9-patches (resizable bitmaps)</a></li>
-            </ul></td>
+            </ul>
+            <p>To get a resource of this type, use <code>mContext.getResources().getDrawable(R.drawable.<em>imageId</em>)</code></p>
+            <p class="note"><strong>Note:</strong> Image resources placed in here may 
+              be automatically optimized with lossless image compression by the 
+              <a href="{@docRoot}guide/developing/tools/aapt.html">aapt</a> tool. For example, a true-color PNG 
+              that does not require more than 256 colors may be converted to an 8-bit PNG with a color palette.
+              This will result in an image of equal quality but which requires less memory. So be aware that the
+              image binaries placed in this directory can change during the build. If you plan on reading
+              an image as a bit stream in order to convert it to a bitmap, put your images in the 
+              <code>res/raw/</code> folder instead, where they will not be optimized.</p>
+        </td>
     </tr>
     <tr>
         <td><code>res/layout/</code></td>
         <td>XML files that are compiled into screen layouts (or part of a screen).
-            See <a href="{@docRoot}guide/topics/ui/declaring-layout.html">Declaring Layout</a></td>
+            See <a href="{@docRoot}guide/topics/ui/declaring-layout.html">Declaring Layout</a>.</td>
     </tr>
     <tr>
         <td><code>res/values/</code></td>
         <td><p>XML files that can be compiled into many kinds of resource.</p>
-            <p class="note"><strong>Note:</strong> unlike the other res/ folders, this one
+            <p class="note"><strong>Note:</strong> Unlike the other res/ folders, this one
             can hold any number of files that hold descriptions of resources to create
             rather than the resources themselves. The XML element types control
             where these resources are placed under the R class.</p>