/*

* Copyright (C) 2006 The Android Open Source Project

*

* Licensed under the Apache License, Version 2.0 (the "License");

* you may not use this file except in compliance with the License.

* You may obtain a copy of the License at

*

* http://www.apache.org/licenses/LICENSE-2.0

*

* Unless required by applicable law or agreed to in writing, software

* distributed under the License is distributed on an "AS IS" BASIS,

* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

* See the License for the specific language governing permissions and

* limitations under the License.

*/

package android.graphics;

import android.annotation.IntDef;

import android.annotation.NonNull;

import android.annotation.Nullable;

import android.text.GraphicsOperations;

import android.text.SpannableString;

import android.text.SpannedString;

import android.text.TextUtils;

import java.lang.annotation.Retention;

import java.lang.annotation.RetentionPolicy;

import javax.microedition.khronos.opengles.GL;

/**

* The Canvas class holds the "draw" calls. To draw something, you need

* 4 basic components: A Bitmap to hold the pixels, a Canvas to host

* the draw calls (writing into the bitmap), a drawing primitive (e.g. Rect,

* Path, text, Bitmap), and a paint (to describe the colors and styles for the

* drawing).

*

* <div class="special reference">

* <h3>Developer Guides</h3>

* <p>For more information about how to use Canvas, read the

* <a href="{@docRoot}guide/topics/graphics/2d-graphics.html">

* Canvas and Drawables</a> developer guide.</p></div>

*/

public class Canvas {

// assigned in constructors or setBitmap, freed in finalizer

private long mNativeCanvasWrapper;

/** @hide */

public long getNativeCanvasWrapper() {

return mNativeCanvasWrapper;

}

/** @hide */

public boolean isRecordingFor(Object o) { return false; }

// may be null

private Bitmap mBitmap;

// optional field set by the caller

private DrawFilter mDrawFilter;

/**

* @hide

*/

protected int mDensity = Bitmap.DENSITY_NONE;

/**

* Used to determine when compatibility scaling is in effect.

*

* @hide

*/

protected int mScreenDensity = Bitmap.DENSITY_NONE;

// Used by native code

@SuppressWarnings("UnusedDeclaration")

private int mSurfaceFormat;

/**

* Flag for drawTextRun indicating left-to-right run direction.

* @hide

*/

public static final int DIRECTION_LTR = 0;

/**

* Flag for drawTextRun indicating right-to-left run direction.

* @hide

*/

public static final int DIRECTION_RTL = 1;

// Maximum bitmap size as defined in Skia's native code

// (see SkCanvas.cpp, SkDraw.cpp)

private static final int MAXMIMUM_BITMAP_SIZE = 32766;

// This field is used to finalize the native Canvas properly

private final CanvasFinalizer mFinalizer;

private static final class CanvasFinalizer {

private long mNativeCanvasWrapper;

public CanvasFinalizer(long nativeCanvas) {

mNativeCanvasWrapper = nativeCanvas;

}

@Override

protected void finalize() throws Throwable {

try {

dispose();

} finally {

super.finalize();

}

}

public void dispose() {

if (mNativeCanvasWrapper != 0) {

finalizer(mNativeCanvasWrapper);

mNativeCanvasWrapper = 0;

}

}

}

/**

* Construct an empty raster canvas. Use setBitmap() to specify a bitmap to

* draw into. The initial target density is {@link Bitmap#DENSITY_NONE};

* this will typically be replaced when a target bitmap is set for the

* canvas.

*/

public Canvas() {

if (!isHardwareAccelerated()) {

// 0 means no native bitmap

mNativeCanvasWrapper = initRaster(0);

mFinalizer = new CanvasFinalizer(mNativeCanvasWrapper);

} else {

mFinalizer = null;

}

}

/**

* Construct a canvas with the specified bitmap to draw into. The bitmap

* must be mutable.

*

* <p>The initial target density of the canvas is the same as the given

* bitmap's density.

*

* @param bitmap Specifies a mutable bitmap for the canvas to draw into.

*/

public Canvas(@NonNull Bitmap bitmap) {

if (!bitmap.isMutable()) {

throw new IllegalStateException("Immutable bitmap passed to Canvas constructor");

}

throwIfCannotDraw(bitmap);

mNativeCanvasWrapper = initRaster(bitmap.ni());

mFinalizer = new CanvasFinalizer(mNativeCanvasWrapper);

mBitmap = bitmap;

mDensity = bitmap.mDensity;

}

/** @hide */

public Canvas(long nativeCanvas) {

if (nativeCanvas == 0) {

throw new IllegalStateException();

}

mNativeCanvasWrapper = nativeCanvas;

mFinalizer = new CanvasFinalizer(mNativeCanvasWrapper);

mDensity = Bitmap.getDefaultDensity();

}

/**

* Returns null.

*

* @deprecated This method is not supported and should not be invoked.

*

* @hide

*/

@Deprecated

protected GL getGL() {

return null;

}

/**

* Indicates whether this Canvas uses hardware acceleration.

*

* Note that this method does not define what type of hardware acceleration

* may or may not be used.

*

* @return True if drawing operations are hardware accelerated,

* false otherwise.

*/

public boolean isHardwareAccelerated() {

return false;

}

/**

* Specify a bitmap for the canvas to draw into. All canvas state such as

* layers, filters, and the save/restore stack are reset with the exception

* of the current matrix and clip stack. Additionally, as a side-effect

* the canvas' target density is updated to match that of the bitmap.

*

* @param bitmap Specifies a mutable bitmap for the canvas to draw into.

* @see #setDensity(int)

* @see #getDensity()

*/

public void setBitmap(@Nullable Bitmap bitmap) {

if (isHardwareAccelerated()) {

throw new RuntimeException("Can't set a bitmap device on a HW accelerated canvas");

}

if (bitmap == null) {

native_setBitmap(mNativeCanvasWrapper, 0, false);

mDensity = Bitmap.DENSITY_NONE;

} else {

if (!bitmap.isMutable()) {

throw new IllegalStateException();

}

throwIfCannotDraw(bitmap);

native_setBitmap(mNativeCanvasWrapper, bitmap.ni(), true);

mDensity = bitmap.mDensity;

}

mBitmap = bitmap;

}

/**

* setBitmap() variant for native callers with a raw bitmap handle.

*/

private void setNativeBitmap(long bitmapHandle) {

native_setBitmap(mNativeCanvasWrapper, bitmapHandle, false);

}

/**

* Set the viewport dimensions if this canvas is GL based. If it is not,

* this method is ignored and no exception is thrown.

*

* @param width The width of the viewport

* @param height The height of the viewport

*

* @hide

*/

public void setViewport(int width, int height) {}

/** @hide */

public void setHighContrastText(boolean highContrastText) {}

/** @hide */

public void insertReorderBarrier() {}

/** @hide */

public void insertInorderBarrier() {}

/**

* Return true if the device that the current layer draws into is opaque

* (i.e. does not support per-pixel alpha).

*

* @return true if the device that the current layer draws into is opaque

*/

public boolean isOpaque() {

return native_isOpaque(mNativeCanvasWrapper);

}

/**

* Returns the width of the current drawing layer

*

* @return the width of the current drawing layer

*/

public int getWidth() {

return native_getWidth(mNativeCanvasWrapper);

}

/**

* Returns the height of the current drawing layer

*

* @return the height of the current drawing layer

*/

public int getHeight() {

return native_getHeight(mNativeCanvasWrapper);

}

/**

* <p>Returns the target density of the canvas. The default density is

* derived from the density of its backing bitmap, or

* {@link Bitmap#DENSITY_NONE} if there is not one.</p>

*

* @return Returns the current target density of the canvas, which is used

* to determine the scaling factor when drawing a bitmap into it.

*

* @see #setDensity(int)

* @see Bitmap#getDensity()

*/

public int getDensity() {

return mDensity;

}

/**

* <p>Specifies the density for this Canvas' backing bitmap. This modifies

* the target density of the canvas itself, as well as the density of its

* backing bitmap via {@link Bitmap#setDensity(int) Bitmap.setDensity(int)}.

*

* @param density The new target density of the canvas, which is used

* to determine the scaling factor when drawing a bitmap into it. Use

* {@link Bitmap#DENSITY_NONE} to disable bitmap scaling.

*

* @see #getDensity()

* @see Bitmap#setDensity(int)

*/

public void setDensity(int density) {

if (mBitmap != null) {

mBitmap.setDensity(density);

}

mDensity = density;

}

/** @hide */

public void setScreenDensity(int density) {

mScreenDensity = density;

}

/**

* Returns the maximum allowed width for bitmaps drawn with this canvas.

* Attempting to draw with a bitmap wider than this value will result

* in an error.

*

* @see #getMaximumBitmapHeight()

*/

public int getMaximumBitmapWidth() {

return MAXMIMUM_BITMAP_SIZE;

}

/**

* Returns the maximum allowed height for bitmaps drawn with this canvas.

* Attempting to draw with a bitmap taller than this value will result

* in an error.

*

* @see #getMaximumBitmapWidth()

*/

public int getMaximumBitmapHeight() {

return MAXMIMUM_BITMAP_SIZE;

}

// the SAVE_FLAG constants must match their native equivalents

/** @hide */

@IntDef(flag = true,

value = {

MATRIX_SAVE_FLAG,

CLIP_SAVE_FLAG,

HAS_ALPHA_LAYER_SAVE_FLAG,

FULL_COLOR_LAYER_SAVE_FLAG,

CLIP_TO_LAYER_SAVE_FLAG,

ALL_SAVE_FLAG

})

@Retention(RetentionPolicy.SOURCE)

public @interface Saveflags {}

/**

* Restore the current matrix when restore() is called.

*/

public static final int MATRIX_SAVE_FLAG = 0x01;

/**

* Restore the current clip when restore() is called.

*/

public static final int CLIP_SAVE_FLAG = 0x02;

/**

* The layer requires a per-pixel alpha channel.

*/

public static final int HAS_ALPHA_LAYER_SAVE_FLAG = 0x04;

/**

* The layer requires full 8-bit precision for each color channel.

*/

public static final int FULL_COLOR_LAYER_SAVE_FLAG = 0x08;

/**

* 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 (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.

* <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()

*/

public int save() {

return native_save(mNativeCanvasWrapper, MATRIX_SAVE_FLAG | CLIP_SAVE_FLAG);

}

/**

* Based on saveFlags, can save the current matrix and clip onto a private

* 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

* @return The value to pass to restoreToCount() to balance this save()

*/

public int save(@Saveflags int saveFlags) {

return native_save(mNativeCanvasWrapper, saveFlags);

}

/**

* 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, 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) {

if (bounds == null) {

bounds = new RectF(getClipBounds());

}

return saveLayer(bounds.left, bounds.top, bounds.right, bounds.bottom, paint, saveFlags);

}

/**

* Convenience for saveLayer(bounds, paint, {@link #ALL_SAVE_FLAG})

*/

public int saveLayer(@Nullable RectF bounds, @Nullable Paint paint) {

return saveLayer(bounds, paint, ALL_SAVE_FLAG);

}

/**

* Helper version of saveLayer() that takes 4 values rather than a RectF.

*/

public int saveLayer(float left, float top, float right, float bottom, @Nullable Paint paint,

@Saveflags int saveFlags) {

return native_saveLayer(mNativeCanvasWrapper, left, top, right, bottom,

paint != null ? paint.mNativePaint : 0,

saveFlags);

}

/**

* Convenience for saveLayer(left, top, right, bottom, paint, {@link #ALL_SAVE_FLAG})

*/

public int saveLayer(float left, float top, float right, float bottom, @Nullable Paint paint) {

return saveLayer(left, top, right, bottom, paint, ALL_SAVE_FLAG);

}

/**

* 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, 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) {

if (bounds == null) {

bounds = new RectF(getClipBounds());

}

return saveLayerAlpha(bounds.left, bounds.top, bounds.right, bounds.bottom, alpha, saveFlags);

}

/**

* Convenience for saveLayerAlpha(bounds, alpha, {@link #ALL_SAVE_FLAG})

*/

public int saveLayerAlpha(@Nullable RectF bounds, int alpha) {

return saveLayerAlpha(bounds, alpha, ALL_SAVE_FLAG);

}

/**

* Helper for saveLayerAlpha() that takes 4 values instead of a RectF.

*/

public int saveLayerAlpha(float left, float top, float right, float bottom, int alpha,

@Saveflags int saveFlags) {

alpha = Math.min(255, Math.max(0, alpha));

return native_saveLayerAlpha(mNativeCanvasWrapper, left, top, right, bottom,

alpha, saveFlags);

}

/**

* Helper for saveLayerAlpha(left, top, right, bottom, alpha, {@link #ALL_SAVE_FLAG})

*/

public int saveLayerAlpha(float left, float top, float right, float bottom, int alpha) {

return saveLayerAlpha(left, top, right, bottom, alpha, ALL_SAVE_FLAG);

}

/**

* This call balances a previous call to save(), and is used to remove all

* modifications to the matrix/clip state since the last save call. It is

* an error to call restore() more times than save() was called.

*/

public void restore() {

native_restore(mNativeCanvasWrapper);

}

/**

* Returns the number of matrix/clip states on the Canvas' private stack.

* This will equal # save() calls - # restore() calls.

*/

public int getSaveCount() {

return native_getSaveCount(mNativeCanvasWrapper);

}

/**

* Efficient way to pop any calls to save() that happened after the save

* count reached saveCount. It is an error for saveCount to be less than 1.

*

* Example:

* int count = canvas.save();

* ... // more calls potentially to save()

* canvas.restoreToCount(count);

* // now the canvas is back in the same state it was before the initial

* // call to save().

*

* @param saveCount The save level to restore to.

*/

public void restoreToCount(int saveCount) {

native_restoreToCount(mNativeCanvasWrapper, saveCount);

}

/**

* Preconcat the current matrix with the specified translation

*

* @param dx The distance to translate in X

* @param dy The distance to translate in Y

*/

public void translate(float dx, float dy) {

native_translate(mNativeCanvasWrapper, dx, dy);

}

/**

* Preconcat the current matrix with the specified scale.

*

* @param sx The amount to scale in X

* @param sy The amount to scale in Y

*/

public void scale(float sx, float sy) {

native_scale(mNativeCanvasWrapper, sx, sy);

}

/**

* Preconcat the current matrix with the specified scale.

*

* @param sx The amount to scale in X

* @param sy The amount to scale in Y

* @param px The x-coord for the pivot point (unchanged by the scale)

* @param py The y-coord for the pivot point (unchanged by the scale)

*/

public final void scale(float sx, float sy, float px, float py) {

translate(px, py);

scale(sx, sy);

translate(-px, -py);

}

/**

* Preconcat the current matrix with the specified rotation.

*

* @param degrees The amount to rotate, in degrees

*/

public void rotate(float degrees) {

native_rotate(mNativeCanvasWrapper, degrees);

}

/**

* Preconcat the current matrix with the specified rotation.

*

* @param degrees The amount to rotate, in degrees

* @param px The x-coord for the pivot point (unchanged by the rotation)

* @param py The y-coord for the pivot point (unchanged by the rotation)

*/

public final void rotate(float degrees, float px, float py) {

translate(px, py);

rotate(degrees);

translate(-px, -py);

}

/**

* Preconcat the current matrix with the specified skew.

*

* @param sx The amount to skew in X

* @param sy The amount to skew in Y

*/

public void skew(float sx, float sy) {

native_skew(mNativeCanvasWrapper, sx, sy);

}

/**

* Preconcat the current matrix with the specified matrix. If the specified

* matrix is null, this method does nothing.

*

* @param matrix The matrix to preconcatenate with the current matrix

*/

public void concat(@Nullable Matrix matrix) {

if (matrix != null) native_concat(mNativeCanvasWrapper, matrix.native_instance);

}

/**

* Completely replace the current matrix with the specified matrix. If the

* matrix parameter is null, then the current matrix is reset to identity.

*

* <strong>Note:</strong> it is recommended to use {@link #concat(Matrix)},

* {@link #scale(float, float)}, {@link #translate(float, float)} and

* {@link #rotate(float)} instead of this method.

*

* @param matrix The matrix to replace the current matrix with. If it is

* null, set the current matrix to identity.

*

* @see #concat(Matrix)

*/

public void setMatrix(@Nullable Matrix matrix) {

native_setMatrix(mNativeCanvasWrapper,

matrix == null ? 0 : matrix.native_instance);

}

/**

* Return, in ctm, the current transformation matrix. This does not alter

* the matrix in the canvas, but just returns a copy of it.

*/

@Deprecated

public void getMatrix(@NonNull Matrix ctm) {

native_getCTM(mNativeCanvasWrapper, ctm.native_instance);

}

/**

* Return a new matrix with a copy of the canvas' current transformation

* matrix.

*/

@Deprecated

public final @NonNull Matrix getMatrix() {

Matrix m = new Matrix();

//noinspection deprecation

getMatrix(m);

return m;

}

/**

* Modify the current clip with the specified rectangle.

*

* @param rect The rect to intersect with the current clip

* @param op How the clip is modified

* @return true if the resulting clip is non-empty

*/

public boolean clipRect(@NonNull RectF rect, @NonNull Region.Op op) {

return native_clipRect(mNativeCanvasWrapper, rect.left, rect.top, rect.right, rect.bottom,

op.nativeInt);

}

/**

* Modify the current clip with the specified rectangle, which is

* expressed in local coordinates.

*

* @param rect The rectangle to intersect with the current clip.

* @param op How the clip is modified

* @return true if the resulting clip is non-empty

*/

public boolean clipRect(@NonNull Rect rect, @NonNull Region.Op op) {

return native_clipRect(mNativeCanvasWrapper, rect.left, rect.top, rect.right, rect.bottom,

op.nativeInt);

}

/**

* Intersect the current clip with the specified rectangle, which is

* expressed in local coordinates.

*

* @param rect The rectangle to intersect with the current clip.

* @return true if the resulting clip is non-empty

*/

public boolean clipRect(@NonNull RectF rect) {

return native_clipRect(mNativeCanvasWrapper, rect.left, rect.top, rect.right, rect.bottom,

Region.Op.INTERSECT.nativeInt);

}

/**

* Intersect the current clip with the specified rectangle, which is

* expressed in local coordinates.

*

* @param rect The rectangle to intersect with the current clip.

* @return true if the resulting clip is non-empty

*/

public boolean clipRect(@NonNull Rect rect) {

return native_clipRect(mNativeCanvasWrapper, rect.left, rect.top, rect.right, rect.bottom,

Region.Op.INTERSECT.nativeInt);

}

/**

* Modify the current clip with the specified rectangle, which is

* expressed in local coordinates.

*

* @param left The left side of the rectangle to intersect with the

* current clip

* @param top The top of the rectangle to intersect with the current

* clip

* @param right The right side of the rectangle to intersect with the

* current clip

* @param bottom The bottom of the rectangle to intersect with the current

* clip

* @param op How the clip is modified

* @return true if the resulting clip is non-empty

*/

public boolean clipRect(float left, float top, float right, float bottom,

@NonNull Region.Op op) {

return native_clipRect(mNativeCanvasWrapper, left, top, right, bottom, op.nativeInt);

}

/**

* Intersect the current clip with the specified rectangle, which is

* expressed in local coordinates.

*

* @param left The left side of the rectangle to intersect with the

* current clip

* @param top The top of the rectangle to intersect with the current clip

* @param right The right side of the rectangle to intersect with the

* current clip

* @param bottom The bottom of the rectangle to intersect with the current

* clip

* @return true if the resulting clip is non-empty

*/

public boolean clipRect(float left, float top, float right, float bottom) {

return native_clipRect(mNativeCanvasWrapper, left, top, right, bottom,

Region.Op.INTERSECT.nativeInt);

}

/**

* Intersect the current clip with the specified rectangle, which is

* expressed in local coordinates.

*

* @param left The left side of the rectangle to intersect with the

* current clip

* @param top The top of the rectangle to intersect with the current clip

* @param right The right side of the rectangle to intersect with the

* current clip

* @param bottom The bottom of the rectangle to intersect with the current

* clip

* @return true if the resulting clip is non-empty

*/

public boolean clipRect(int left, int top, int right, int bottom) {

return native_clipRect(mNativeCanvasWrapper, left, top, right, bottom,

Region.Op.INTERSECT.nativeInt);

}

/**

* Modify the current clip with the specified path.

*

* @param path The path to operate on the current clip

* @param op How the clip is modified

* @return true if the resulting is non-empty

*/

public boolean clipPath(@NonNull Path path, @NonNull Region.Op op) {

return native_clipPath(mNativeCanvasWrapper, path.ni(), op.nativeInt);

}

/**

* Intersect the current clip with the specified path.

*

* @param path The path to intersect with the current clip

* @return true if the resulting is non-empty

*/

public boolean clipPath(@NonNull Path path) {

return clipPath(path, Region.Op.INTERSECT);

}

/**

* Modify the current clip with the specified region. Note that unlike

* clipRect() and clipPath() which transform their arguments by the

* current matrix, clipRegion() assumes its argument is already in the

* coordinate system of the current layer's bitmap, and so not

* transformation is performed.

*

* @param region The region to operate on the current clip, based on op

* @param op How the clip is modified

* @return true if the resulting is non-empty

*

* @deprecated Unlike all other clip calls this API does not respect the

* current matrix. Use {@link #clipRect(Rect)} as an alternative.

*/

public boolean clipRegion(@NonNull Region region, @NonNull Region.Op op) {

return native_clipRegion(mNativeCanvasWrapper, region.ni(), op.nativeInt);

}

/**

* Intersect the current clip with the specified region. Note that unlike

* clipRect() and clipPath() which transform their arguments by the

* current matrix, clipRegion() assumes its argument is already in the

* coordinate system of the current layer's bitmap, and so not

* transformation is performed.

*

* @param region The region to operate on the current clip, based on op

* @return true if the resulting is non-empty

*

* @deprecated Unlike all other clip calls this API does not respect the

* current matrix. Use {@link #clipRect(Rect)} as an alternative.

*/

public boolean clipRegion(@NonNull Region region) {

return clipRegion(region, Region.Op.INTERSECT);

}

public @Nullable DrawFilter getDrawFilter() {

return mDrawFilter;

}

public void setDrawFilter(@Nullable DrawFilter filter) {

long nativeFilter = 0;

if (filter != null) {

nativeFilter = filter.mNativeInt;

}

mDrawFilter = filter;

nativeSetDrawFilter(mNativeCanvasWrapper, nativeFilter);

}

public enum EdgeType {

/**

* Black-and-White: Treat edges by just rounding to nearest pixel boundary

*/

BW(0), //!< treat edges by just rounding to nearest pixel boundary

/**

* Antialiased: Treat edges by rounding-out, since they may be antialiased

*/

AA(1);

EdgeType(int nativeInt) {

this.nativeInt = nativeInt;

}

/**

* @hide

*/

public final int nativeInt;

}

/**

* Return true if the specified rectangle, after being transformed by the

* current matrix, would lie completely outside of the current clip. Call

* this to check if an area you intend to draw into is clipped out (and

* therefore you can skip making the draw calls).

*

* @param rect the rect to compare with the current clip

* @param type {@link Canvas.EdgeType#AA} if the path should be considered antialiased,

* since that means it may affect a larger area (more pixels) than

* non-antialiased ({@link Canvas.EdgeType#BW}).

* @return true if the rect (transformed by the canvas' matrix)

* does not intersect with the canvas' clip

*/

public boolean quickReject(@NonNull RectF rect, @NonNull EdgeType type) {

return native_quickReject(mNativeCanvasWrapper,

rect.left, rect.top, rect.right, rect.bottom);

}

/**

* Return true if the specified path, after being transformed by the

* current matrix, would lie completely outside of the current clip. Call

* this to check if an area you intend to draw into is clipped out (and

* therefore you can skip making the draw calls). Note: for speed it may

* return false even if the path itself might not intersect the clip

* (i.e. the bounds of the path intersects, but the path does not).

*

* @param path The path to compare with the current clip

* @param type {@link Canvas.EdgeType#AA} if the path should be considered antialiased,

* since that means it may affect a larger area (more pixels) than

* non-antialiased ({@link Canvas.EdgeType#BW}).

* @return true if the path (transformed by the canvas' matrix)

* does not intersect with the canvas' clip

*/

public boolean quickReject(@NonNull Path path, @NonNull EdgeType type) {

return native_quickReject(mNativeCanvasWrapper, path.ni());

}

/**

* Return true if the specified rectangle, after being transformed by the

* current matrix, would lie completely outside of the current clip. Call

* this to check if an area you intend to draw into is clipped out (and

* therefore you can skip making the draw calls).

*

* @param left The left side of the rectangle to compare with the

* current clip

* @param top The top of the rectangle to compare with the current

* clip

* @param right The right side of the rectangle to compare with the

* current clip

* @param bottom The bottom of the rectangle to compare with the

* current clip

* @param type {@link Canvas.EdgeType#AA} if the path should be considered antialiased,

* since that means it may affect a larger area (more pixels) than

* non-antialiased ({@link Canvas.EdgeType#BW}).

* @return true if the rect (transformed by the canvas' matrix)

* does not intersect with the canvas' clip

*/

public boolean quickReject(float left, float top, float right, float bottom,

@NonNull EdgeType type) {

return native_quickReject(mNativeCanvasWrapper, left, top, right, bottom);

}

/**

* Return the bounds of the current clip (in local coordinates) in the

* bounds parameter, and return true if it is non-empty. This can be useful

* in a way similar to quickReject, in that it tells you that drawing

* outside of these bounds will be clipped out.

*

* @param bounds Return the clip bounds here. If it is null, ignore it but

* still return true if the current clip is non-empty.

* @return true if the current clip is non-empty.

*/

public boolean getClipBounds(@Nullable Rect bounds) {

return native_getClipBounds(mNativeCanvasWrapper, bounds);

}

/**

* Retrieve the bounds of the current clip (in local coordinates).

*

* @return the clip bounds, or [0, 0, 0, 0] if the clip is empty.

*/

public final @NonNull Rect getClipBounds() {

Rect r = new Rect();

getClipBounds(r);

return r;

}

/**

* Fill the entire canvas' bitmap (restricted to the current clip) with the

* specified RGB color, using srcover porterduff mode.

*

* @param r red component (0..255) of the color to draw onto the canvas

* @param g green component (0..255) of the color to draw onto the canvas

* @param b blue component (0..255) of the color to draw onto the canvas

*/

public void drawRGB(int r, int g, int b) {

drawColor(Color.rgb(r, g, b));

}

/**

* Fill the entire canvas' bitmap (restricted to the current clip) with the

* specified ARGB color, using srcover porterduff mode.

*

* @param a alpha component (0..255) of the color to draw onto the canvas

* @param r red component (0..255) of the color to draw onto the canvas

* @param g green component (0..255) of the color to draw onto the canvas

* @param b blue component (0..255) of the color to draw onto the canvas

*/