am 9750c696: am 075b2b4f: Merge "Add details and performance warnings to save flag docs" into lmp-mr1-dev
* commit '9750c6961c5cbe5600ee96efbdfd3cffe0b2a778':
Add details and performance warnings to save flag docs
diff --git a/graphics/java/android/graphics/Canvas.java b/graphics/java/android/graphics/Canvas.java
index 6baf1aa..8279a51 100644
--- a/graphics/java/android/graphics/Canvas.java
+++ b/graphics/java/android/graphics/Canvas.java
@@ -362,25 +362,51 @@
@Retention(RetentionPolicy.SOURCE)
public @interface Saveflags {}
- /** restore the current matrix when restore() is called */
+ /**
+ * Restore the current matrix when restore() is called.
+ */
public static final int MATRIX_SAVE_FLAG = 0x01;
- /** restore the current clip when restore() is called */
+
+ /**
+ * Restore the current clip when restore() is called.
+ */
public static final int CLIP_SAVE_FLAG = 0x02;
- /** the layer needs to per-pixel alpha */
+
+ /**
+ * The layer requires a per-pixel alpha channel.
+ */
public static final int HAS_ALPHA_LAYER_SAVE_FLAG = 0x04;
- /** the layer needs to 8-bits per color component */
+
+ /**
+ * The layer requires full 8-bit precision for each color channel.
+ */
public static final int FULL_COLOR_LAYER_SAVE_FLAG = 0x08;
- /** clip against the layer's bounds */
+
+ /**
+ * Clip drawing to the bounds of the offscreen layer, omit at your own peril.
+ * <p class="note"><strong>Note:</strong> it is strongly recommended to not
+ * omit this flag for any call to <code>saveLayer()</code> and
+ * <code>saveLayerAlpha()</code> variants. Not passing this flag generally
+ * triggers extremely poor performance with hardware accelerated rendering.
+ */
public static final int CLIP_TO_LAYER_SAVE_FLAG = 0x10;
- /** restore everything when restore() is called */
+
+ /**
+ * Restore everything when restore() is called (standard save flags).
+ * <p class="note"><strong>Note:</strong> for performance reasons, it is
+ * strongly recommended to pass this - the complete set of flags - to any
+ * call to <code>saveLayer()</code> and <code>saveLayerAlpha()</code>
+ * variants.
+ */
public static final int ALL_SAVE_FLAG = 0x1F;
/**
- * Saves the current matrix and clip onto a private stack. Subsequent
- * calls to translate,scale,rotate,skew,concat or clipRect,clipPath
- * will all operate as usual, but when the balancing call to restore()
- * is made, those calls will be forgotten, and the settings that existed
- * before the save() will be reinstated.
+ * Saves the current matrix and clip onto a private stack.
+ * <p>
+ * Subsequent calls to translate,scale,rotate,skew,concat or clipRect,
+ * clipPath will all operate as usual, but when the balancing call to
+ * restore() is made, those calls will be forgotten, and the settings that
+ * existed before the save() will be reinstated.
*
* @return The value to pass to restoreToCount() to balance this save()
*/
@@ -390,10 +416,15 @@
/**
* Based on saveFlags, can save the current matrix and clip onto a private
- * stack. Subsequent calls to translate,scale,rotate,skew,concat or
- * clipRect,clipPath will all operate as usual, but when the balancing
- * call to restore() is made, those calls will be forgotten, and the
- * settings that existed before the save() will be reinstated.
+ * stack.
+ * <p class="note"><strong>Note:</strong> if possible, use the
+ * parameter-less save(). It is simpler and faster than individually
+ * disabling the saving of matrix or clip with this method.
+ * <p>
+ * Subsequent calls to translate,scale,rotate,skew,concat or clipRect,
+ * clipPath will all operate as usual, but when the balancing call to
+ * restore() is made, those calls will be forgotten, and the settings that
+ * existed before the save() will be reinstated.
*
* @param saveFlags flag bits that specify which parts of the Canvas state
* to save/restore
@@ -404,19 +435,33 @@
}
/**
- * This behaves the same as save(), but in addition it allocates an
- * offscreen bitmap. All drawing calls are directed there, and only when
- * the balancing call to restore() is made is that offscreen transfered to
- * the canvas (or the previous layer). Subsequent calls to translate,
- * scale, rotate, skew, concat or clipRect, clipPath all operate on this
- * copy. When the balancing call to restore() is made, this copy is
- * deleted and the previous matrix/clip state is restored.
+ * This behaves the same as save(), but in addition it allocates and
+ * redirects drawing to an offscreen bitmap.
+ * <p class="note"><strong>Note:</strong> this method is very expensive,
+ * incurring more than double rendering cost for contained content. Avoid
+ * using this method, especially if the bounds provided are large, or if
+ * the {@link #CLIP_TO_LAYER_SAVE_FLAG} is omitted from the
+ * {@code saveFlags} parameter. It is recommended to use a
+ * {@link android.view.View#LAYER_TYPE_HARDWARE hardware layer} on a View
+ * to apply an xfermode, color filter, or alpha, as it will perform much
+ * better than this method.
+ * <p>
+ * All drawing calls are directed to a newly allocated offscreen bitmap.
+ * Only when the balancing call to restore() is made, is that offscreen
+ * buffer drawn back to the current target of the Canvas (either the
+ * screen, it's target Bitmap, or the previous layer).
+ * <p>
+ * Attributes of the Paint - {@link Paint#getAlpha() alpha},
+ * {@link Paint#getXfermode() Xfermode}, and
+ * {@link Paint#getColorFilter() ColorFilter} are applied when the
+ * offscreen bitmap is drawn back when restore() is called.
*
* @param bounds May be null. The maximum size the offscreen bitmap
* needs to be (in local coordinates)
* @param paint This is copied, and is applied to the offscreen when
* restore() is called.
- * @param saveFlags see _SAVE_FLAG constants
+ * @param saveFlags see _SAVE_FLAG constants, generally {@link #ALL_SAVE_FLAG} is recommended
+ * for performance reasons.
* @return value to pass to restoreToCount() to balance this save()
*/
public int saveLayer(@Nullable RectF bounds, @Nullable Paint paint, @Saveflags int saveFlags) {
@@ -451,19 +496,31 @@
}
/**
- * This behaves the same as save(), but in addition it allocates an
- * offscreen bitmap. All drawing calls are directed there, and only when
- * the balancing call to restore() is made is that offscreen transfered to
- * the canvas (or the previous layer). Subsequent calls to translate,
- * scale, rotate, skew, concat or clipRect, clipPath all operate on this
- * copy. When the balancing call to restore() is made, this copy is
- * deleted and the previous matrix/clip state is restored.
+ * This behaves the same as save(), but in addition it allocates and
+ * redirects drawing to an offscreen bitmap.
+ * <p class="note"><strong>Note:</strong> this method is very expensive,
+ * incurring more than double rendering cost for contained content. Avoid
+ * using this method, especially if the bounds provided are large, or if
+ * the {@link #CLIP_TO_LAYER_SAVE_FLAG} is omitted from the
+ * {@code saveFlags} parameter. It is recommended to use a
+ * {@link android.view.View#LAYER_TYPE_HARDWARE hardware layer} on a View
+ * to apply an xfermode, color filter, or alpha, as it will perform much
+ * better than this method.
+ * <p>
+ * All drawing calls are directed to a newly allocated offscreen bitmap.
+ * Only when the balancing call to restore() is made, is that offscreen
+ * buffer drawn back to the current target of the Canvas (either the
+ * screen, it's target Bitmap, or the previous layer).
+ * <p>
+ * The {@code alpha} parameter is applied when the offscreen bitmap is
+ * drawn back when restore() is called.
*
* @param bounds The maximum size the offscreen bitmap needs to be
* (in local coordinates)
* @param alpha The alpha to apply to the offscreen when when it is
drawn during restore()
- * @param saveFlags see _SAVE_FLAG constants
+ * @param saveFlags see _SAVE_FLAG constants, generally {@link #ALL_SAVE_FLAG} is recommended
+ * for performance reasons.
* @return value to pass to restoreToCount() to balance this call
*/
public int saveLayerAlpha(@Nullable RectF bounds, int alpha, @Saveflags int saveFlags) {