Better documentation for FLAG_HARDWARE_ACCELERATED
Bug #3154883
Change-Id: I2062781ba3b447b8ec4e0836b9ddeaa97c7aa60e
diff --git a/core/java/android/view/WindowManager.java b/core/java/android/view/WindowManager.java
index c435c43..c54a3cf 100644
--- a/core/java/android/view/WindowManager.java
+++ b/core/java/android/view/WindowManager.java
@@ -636,8 +636,33 @@
public static final int FLAG_SPLIT_TOUCH = 0x00800000;
/**
- * Indicates whether this window should be hardware accelerated.
- * Requesting hardware acceleration does not guarantee it will happen.
+ * <p>Indicates whether this window should be hardware accelerated.
+ * Requesting hardware acceleration does not guarantee it will happen.</p>
+ *
+ * <p>This flag can be controlled programmatically <em>only</em> to enable
+ * hardware acceleration. To enable hardware acceleration for a given
+ * window programmatically, do the following:</p>
+ *
+ * <pre>
+ * Window w = activity.getWindow(); // in Activity's onCreate() for instance
+ * w.setFlags(WindowManager.LayoutParams.FLAG_HARDWARE_ACCELERATED,
+ * WindowManager.LayoutParams.FLAG_HARDWARE_ACCELERATED);
+ * </pre>
+ *
+ * <p>It is important to remember that this flag <strong>must</strong>
+ * be set before setting the content view of your activity or dialog.</p>
+ *
+ * <p>This flag cannot be used to disable hardware acceleration after it
+ * was enabled in your manifest using
+ * {@link android.R.attr#hardwareAccelerated}. If you need to selectively
+ * and programmatically disable hardware acceleration (for automated testing
+ * for instance), make sure it is turned off in your manifest and enable it
+ * on your activity or dialog when you need it instead, using the method
+ * described above.</p>
+ *
+ * <p>This flag is automatically set by the system if the
+ * {@link android.R.attr#hardwareAccelerated android:hardwareAccelerated}
+ * XML attribute is set to true on an activity or on the application.</p>
*/
public static final int FLAG_HARDWARE_ACCELERATED = 0x01000000;
diff --git a/core/res/res/values/attrs_manifest.xml b/core/res/res/values/attrs_manifest.xml
index fe6176d..5ff6212 100644
--- a/core/res/res/values/attrs_manifest.xml
+++ b/core/res/res/values/attrs_manifest.xml
@@ -234,8 +234,20 @@
the safe mode. -->
<attr name="vmSafeMode" format="boolean" />
- <!-- Flag indicating whether the application's rendering should be hardware
- accelerated if possible. -->
+ <!-- <p>Flag indicating whether the application's rendering should be hardware
+ accelerated if possible. This flag is turned off by default, both for
+ applications and activities.</p>
+ <p>This flag can be set on the application and any activity declared
+ in the manifest. When enabled for the application, each activity is
+ automatically assumed to be hardware accelerated. This flag can be
+ overriden in the activity tags, either turning it off (if on for the
+ application) or on (if off for the application.)</p>
+ <p>When this flag is turned on for an activity (either directly or via
+ the application tag), every window created from the activity, including
+ the activity's own window, will be hardware accelerated, if possible.</p>
+ <p>Please refer to the documentation of
+ {@link android.view.WindowManager.LayoutParams#FLAG_HARDWARE_ACCELERATED}
+ for more information on how to control this flag programmatically.</p> -->
<attr name="hardwareAccelerated" format="boolean" />
<!-- Flag indicating whether the given application component is available