FileDocCategorySizeDatePackage
Canvas.javaAPI DocAndroid 1.5 API67275Wed May 06 22:42:00 BST 2009android.graphics

Canvas

public class Canvas extends Object
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).

Fields Summary
final int
mNativeCanvas
private Bitmap
mBitmap
private javax.microedition.khronos.opengles.GL
mGL
private DrawFilter
mDrawFilter
private int
mSurfaceFormat
private float
mDensityScale
public static final int
MATRIX_SAVE_FLAG
restore the current matrix when restore() is called
public static final int
CLIP_SAVE_FLAG
restore the current clip when restore() is called
public static final int
HAS_ALPHA_LAYER_SAVE_FLAG
the layer needs to per-pixel alpha
public static final int
FULL_COLOR_LAYER_SAVE_FLAG
the layer needs to 8-bits per color component
public static final int
CLIP_TO_LAYER_SAVE_FLAG
clip against the layer's bounds
public static final int
ALL_SAVE_FLAG
restore everything when restore() is called
Constructors Summary
public Canvas()
Construct an empty raster canvas. Use setBitmap() to specify a bitmap to draw into.


                       
      
        // 0 means no native bitmap
        mNativeCanvas = initRaster(0);
public Canvas(Bitmap bitmap)
Construct a canvas with the specified bitmap to draw into. The bitmap must be mutable.

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

        if (!bitmap.isMutable()) {
            throw new IllegalStateException(
                            "Immutable bitmap passed to Canvas constructor");
        }
        throwIfRecycled(bitmap);
        mNativeCanvas = initRaster(bitmap.ni());
        mBitmap = bitmap;
        mDensityScale = bitmap.getDensityScale();
        if (mDensityScale == Bitmap.DENSITY_SCALE_UNKNOWN) mDensityScale = 1.0f;
Canvas(int nativeCanvas)

        if (nativeCanvas == 0) {
            throw new IllegalStateException();
        }
        mNativeCanvas = nativeCanvas;
public Canvas(javax.microedition.khronos.opengles.GL gl)
Construct a canvas with the specified gl context. All drawing through this canvas will be redirected to OpenGL. Note: some features may not be supported in this mode (e.g. some GL implementations may not support antialiasing or certain effects like ColorMatrix or certain Xfermodes). However, no exception will be thrown in those cases.

        mNativeCanvas = initGL();
        mGL = gl;
Methods Summary
private static voidcheckRange(int length, int offset, int count)

        if ((offset | count) < 0 || offset + count > length) {
            throw new ArrayIndexOutOfBoundsException();
        }
public booleanclipPath(Path path, Region.Op op)
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

        return native_clipPath(mNativeCanvas, path.ni(), op.nativeInt);
public booleanclipPath(Path path)
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

        return clipPath(path, Region.Op.INTERSECT);
public booleanclipRect(RectF rect, Region.Op op)
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

        return native_clipRect(mNativeCanvas,
                               rect.left, rect.top, rect.right, rect.bottom,
                               op.nativeInt);
public booleanclipRect(Rect rect, Region.Op op)
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

        return native_clipRect(mNativeCanvas,
                               rect.left, rect.top, rect.right, rect.bottom,
                               op.nativeInt);
public native booleanclipRect(RectF rect)
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 native booleanclipRect(Rect rect)
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 booleanclipRect(float left, float top, float right, float bottom, Region.Op op)
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
        return native_clipRect(mNativeCanvas, left, top, right, bottom,
                               op.nativeInt);
    
public native booleanclipRect(float left, float top, float right, float bottom)
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 native booleanclipRect(int left, int top, int right, int bottom)
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 booleanclipRegion(Region region, Region.Op op)
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
        return native_clipRegion(mNativeCanvas, region.ni(), op.nativeInt);
    
public booleanclipRegion(Region region)
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
        return clipRegion(region, Region.Op.INTERSECT);
    
public voidconcat(Matrix matrix)
Preconcat the current matrix with the specified matrix.
param
matrix The matrix to preconcatenate with the current matrix
        native_concat(mNativeCanvas, matrix.native_instance);
    
public voiddrawARGB(int a, int r, int g, int 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
        native_drawARGB(mNativeCanvas, a, r, g, b);
    
public voiddrawArc(RectF oval, float startAngle, float sweepAngle, boolean useCenter, Paint paint)
Draw the specified arc, which will be scaled to fit inside the
specified oval. If the sweep angle is >= 360, then the oval is drawn
completely. Note that this differs slightly from SkPath::arcTo, which
treats the sweep angle mod 360.
param
oval The bounds of oval used to define the shape and size
of the arc
param
startAngle Starting angle (in degrees) where the arc begins
param
sweepAngle Sweep angle (in degrees) measured clockwise
param
useCenter If true, include the center of the oval in the arc, and
close it if it is being stroked. This will draw a wedge
param
paint The paint used to draw the arc
        if (oval == null) {
            throw new NullPointerException();
        }
        native_drawArc(mNativeCanvas, oval, startAngle, sweepAngle,
                       useCenter, paint.mNativePaint);
    
public voiddrawBitmap(Bitmap bitmap, float left, float top, Paint paint)
Draw the specified bitmap, with its top/left corner at (x,y), using
the specified paint, transformed by the current matrix.
Note: if the paint contains a maskfilter that generates a mask which
extends beyond the bitmap's original width/height (e.g. BlurMaskFilter),
then the bitmap will be drawn as if it were in a Shader with CLAMP mode.
Thus the color outside of the original width/height will be the edge
color replicated.
param
bitmap The bitmap to be drawn
param
left The position of the left side of the bitmap being drawn
param
top The position of the top side of the bitmap being drawn
param
paint The paint used to draw the bitmap (may be null)
        throwIfRecycled(bitmap);
        native_drawBitmap(mNativeCanvas, bitmap.ni(), left, top,
                paint != null ? paint.mNativePaint : 0, bitmap.isAutoScalingEnabled(),
                bitmap.getDensityScale());
    
public voiddrawBitmap(Bitmap bitmap, Rect src, RectF dst, Paint paint)
Draw the specified bitmap, scaling/translating automatically to fill
the destination rectangle. If the source rectangle is not null, it
specifies the subset of the bitmap to draw.
Note: if the paint contains a maskfilter that generates a mask which
extends beyond the bitmap's original width/height (e.g. BlurMaskFilter),
then the bitmap will be drawn as if it were in a Shader with CLAMP mode.
Thus the color outside of the original width/height will be the edge
color replicated.
param
bitmap The bitmap to be drawn
param
src May be null. The subset of the bitmap to be drawn
param
dst The rectangle that the bitmap will be scaled/translated
to fit into
param
paint May be null. The paint used to draw the bitmap
        if (dst == null) {
            throw new NullPointerException();
        }
        throwIfRecycled(bitmap);
        native_drawBitmap(mNativeCanvas, bitmap.ni(), src, dst,
                          paint != null ? paint.mNativePaint : 0);
    
public voiddrawBitmap(Bitmap bitmap, Rect src, Rect dst, Paint paint)
Draw the specified bitmap, scaling/translating automatically to fill
the destination rectangle. If the source rectangle is not null, it
specifies the subset of the bitmap to draw.
Note: if the paint contains a maskfilter that generates a mask which
extends beyond the bitmap's original width/height (e.g. BlurMaskFilter),
then the bitmap will be drawn as if it were in a Shader with CLAMP mode.
Thus the color outside of the original width/height will be the edge
color replicated.
param
bitmap The bitmap to be drawn
param
src May be null. The subset of the bitmap to be drawn
param
dst The rectangle that the bitmap will be scaled/translated
to fit into
param
paint May be null. The paint used to draw the bitmap
        if (dst == null) {
            throw new NullPointerException();
        }
        throwIfRecycled(bitmap);
        native_drawBitmap(mNativeCanvas, bitmap.ni(), src, dst,
                          paint != null ? paint.mNativePaint : 0);
    
public voiddrawBitmap(int[] colors, int offset, int stride, float x, float y, int width, int height, boolean hasAlpha, Paint paint)
Treat the specified array of colors as a bitmap, and draw it. This gives
the same result as first creating a bitmap from the array, and then
drawing it, but this method avoids explicitly creating a bitmap object
which can be more efficient if the colors are changing often.
param
colors Array of colors representing the pixels of the bitmap
param
offset Offset into the array of colors for the first pixel
param
stride The number of of colors in the array between rows (must be
>= width or <= -width).
param
x The X coordinate for where to draw the bitmap
param
y The Y coordinate for where to draw the bitmap
param
width The width of the bitmap
param
height The height of the bitmap
param
hasAlpha True if the alpha channel of the colors contains valid
values. If false, the alpha byte is ignored (assumed to
be 0xFF for every pixel).
param
paint May be null. The paint used to draw the bitmap
        // check for valid input
        if (width < 0) {
            throw new IllegalArgumentException("width must be >= 0");
        }
        if (height < 0) {
            throw new IllegalArgumentException("height must be >= 0");
        }
        if (Math.abs(stride) < width) {
            throw new IllegalArgumentException("abs(stride) must be >= width");
        }
        int lastScanline = offset + (height - 1) * stride;
        int length = colors.length;
        if (offset < 0 || (offset + width > length) || lastScanline < 0
                || (lastScanline + width > length)) {
            throw new ArrayIndexOutOfBoundsException();
        }
        // quick escape if there's nothing to draw
        if (width == 0 || height == 0) {
            return;
        }
        // punch down to native for the actual draw
        native_drawBitmap(mNativeCanvas, colors, offset, stride, x, y, width, height, hasAlpha,
                paint != null ? paint.mNativePaint : 0);
    
public voiddrawBitmap(int[] colors, int offset, int stride, int x, int y, int width, int height, boolean hasAlpha, Paint paint)
Legacy version of drawBitmap(int[] colors, ...) that took ints for x,y
        // call through to the common float version
        drawBitmap(colors, offset, stride, (float)x, (float)y, width, height,
                   hasAlpha, paint);
    
public voiddrawBitmap(Bitmap bitmap, Matrix matrix, Paint paint)
Draw the bitmap using the specified matrix.
param
bitmap The bitmap to draw
param
matrix The matrix used to transform the bitmap when it is drawn
param
paint May be null. The paint used to draw the bitmap
        nativeDrawBitmapMatrix(mNativeCanvas, bitmap.ni(), matrix.ni(),
                paint != null ? paint.mNativePaint : 0);
    
public voiddrawBitmapMesh(Bitmap bitmap, int meshWidth, int meshHeight, float[] verts, int vertOffset, int[] colors, int colorOffset, Paint paint)
Draw the bitmap through the mesh, where mesh vertices are evenly
distributed across the bitmap. There are meshWidth+1 vertices across, and
meshHeight+1 vertices down. The verts array is accessed in row-major
order, so that the first meshWidth+1 vertices are distributed across the
top of the bitmap from left to right. A more general version of this
methid is drawVertices().
param
bitmap The bitmap to draw using the mesh
param
meshWidth The number of columns in the mesh. Nothing is drawn if
this is 0
param
meshHeight The number of rows in the mesh. Nothing is drawn if
this is 0
param
verts Array of x,y pairs, specifying where the mesh should be
drawn. There must be at least
(meshWidth+1) * (meshHeight+1) * 2 + meshOffset values
in the array
param
vertOffset Number of verts elements to skip before drawing
param
colors May be null. Specifies a color at each vertex, which is
interpolated across the cell, and whose values are
multiplied by the corresponding bitmap colors. If not null,
there must be at least (meshWidth+1) * (meshHeight+1) +
colorOffset values in the array.
param
colorOffset Number of color elements to skip before drawing
param
paint May be null. The paint used to draw the bitmap
        if ((meshWidth | meshHeight | vertOffset | colorOffset) < 0) {
            throw new ArrayIndexOutOfBoundsException();
        }
        if (meshWidth == 0 || meshHeight == 0) {
            return;
        }
        int count = (meshWidth + 1) * (meshHeight + 1);
        // we mul by 2 since we need two floats per vertex
        checkRange(verts.length, vertOffset, count * 2);
        if (colors != null) {
            // no mul by 2, since we need only 1 color per vertex
            checkRange(colors.length, colorOffset, count);
        }
        nativeDrawBitmapMesh(mNativeCanvas, bitmap.ni(), meshWidth, meshHeight,
                             verts, vertOffset, colors, colorOffset,
                             paint != null ? paint.mNativePaint : 0);
    
public voiddrawCircle(float cx, float cy, float radius, Paint paint)
Draw the specified circle using the specified paint. If radius is <= 0,
then nothing will be drawn. The circle will be filled or framed based
on the Style in the paint.
param
cx The x-coordinate of the center of the cirle to be drawn
param
cy The y-coordinate of the center of the cirle to be drawn
param
radius The radius of the cirle to be drawn
param
paint The paint used to draw the circle
        native_drawCircle(mNativeCanvas, cx, cy, radius,
                          paint.mNativePaint);
    
public voiddrawColor(int color)
Fill the entire canvas' bitmap (restricted to the current clip) with the
specified color, using srcover porterduff mode.
param
color the color to draw onto the canvas
        native_drawColor(mNativeCanvas, color);
    
public voiddrawColor(int color, PorterDuff.Mode mode)
Fill the entire canvas' bitmap (restricted to the current clip) with the
specified color and porter-duff xfermode.
param
color the color to draw with
param
mode the porter-duff mode to apply to the color
        native_drawColor(mNativeCanvas, color, mode.nativeInt);
    
public voiddrawLine(float startX, float startY, float stopX, float stopY, Paint paint)
Draw a line segment with the specified start and stop x,y coordinates,
using the specified paint. NOTE: since a line is always "framed", the
Style is ignored in the paint.
param
startX The x-coordinate of the start point of the line
param
startY The y-coordinate of the start point of the line
param
paint The paint used to draw the line
        native_drawLine(mNativeCanvas, startX, startY, stopX, stopY,
                        paint.mNativePaint);
    
public native voiddrawLines(float[] pts, int offset, int count, Paint paint)
Draw a series of lines. Each line is taken from 4 consecutive values
in the pts array. Thus to draw 1 line, the array must contain at least 4
values. This is logically the same as drawing the array as follows:
drawLine(pts[0], pts[1], pts[2], pts[3]) followed by
drawLine(pts[4], pts[5], pts[6], pts[7]) and so on.
param
pts Array of points to draw [x0 y0 x1 y1 x2 y2 ...]
param
offset Number of values in the array to skip before drawing.
param
count The number of values in the array to process, after
skipping "offset" of them. Since each line uses 4 values,
the number of "lines" that are drawn is really
(count >> 2).
param
paint The paint used to draw the points
public voiddrawLines(float[] pts, Paint paint)
        drawLines(pts, 0, pts.length, paint);
    
public voiddrawOval(RectF oval, Paint paint)
Draw the specified oval using the specified paint. The oval will be
filled or framed based on the Style in the paint.
param
oval The rectangle bounds of the oval to be drawn
        if (oval == null) {
            throw new NullPointerException();
        }
        native_drawOval(mNativeCanvas, oval, paint.mNativePaint);
    
public voiddrawPaint(Paint paint)
Fill the entire canvas' bitmap (restricted to the current clip) with
the specified paint. This is equivalent (but faster) to drawing an
infinitely large rectangle with the specified paint.
param
paint The paint used to draw onto the canvas
        native_drawPaint(mNativeCanvas, paint.mNativePaint);
    
public voiddrawPath(Path path, Paint paint)
Draw the specified path using the specified paint. The path will be
filled or framed based on the Style in the paint.
param
path The path to be drawn
param
paint The paint used to draw the path
        native_drawPath(mNativeCanvas, path.ni(), paint.mNativePaint);
    
public voiddrawPicture(Picture picture)
Save the canvas state, draw the picture, and restore the canvas state.
This differs from picture.draw(canvas), which does not perform any
save/restore.
param
picture The picture to be drawn
        picture.endRecording();
        native_drawPicture(mNativeCanvas, picture.ni());
    
public voiddrawPicture(Picture picture, RectF dst)
Draw the picture, stretched to fit into the dst rectangle.
        save();
        translate(dst.left, dst.top);
        if (picture.getWidth() > 0 && picture.getHeight() > 0) {
            scale(dst.width() / picture.getWidth(),
                  dst.height() / picture.getHeight());
        }
        drawPicture(picture);
        restore();
    
public voiddrawPicture(Picture picture, Rect dst)
Draw the picture, stretched to fit into the dst rectangle.
        save();
        translate(dst.left, dst.top);
        if (picture.getWidth() > 0 && picture.getHeight() > 0) {
            scale((float)dst.width() / picture.getWidth(),
                  (float)dst.height() / picture.getHeight());
        }
        drawPicture(picture);
        restore();
    
public native voiddrawPoint(float x, float y, Paint paint)
Helper for drawPoints() for drawing a single point.
public native voiddrawPoints(float[] pts, int offset, int count, Paint paint)
Draw a series of points. Each point is centered at the coordinate
specified by pts[], and its diameter is specified by the paint's stroke
width (as transformed by the canvas' CTM), with special treatment for
a stroke width of 0, which always draws exactly 1 pixel (or at most 4
if antialiasing is enabled). The shape of the point is controlled by
the paint's Cap type. The shape is a square, unless the cap type is
Round, in which case the shape is a circle.
param
pts Array of points to draw [x0 y0 x1 y1 x2 y2 ...]
param
offset Number of values to skip before starting to draw.
param
count The number of values to process, after skipping offset
of them. Since one point uses two values, the number of
"points" that are drawn is really (count >> 1).
param
paint The paint used to draw the points
public voiddrawPoints(float[] pts, Paint paint)
Helper for drawPoints() that assumes you want to draw the entire array
        drawPoints(pts, 0, pts.length, paint);
    
public voiddrawPosText(char[] text, int index, int count, float[] pos, Paint paint)
Draw the text in the array, with each character's origin specified by
the pos array.
param
text The text to be drawn
param
index The index of the first character to draw
param
count The number of characters to draw, starting from index.
param
pos Array of [x,y] positions, used to position each
character
param
paint The paint used for the text (e.g. color, size, style)
        if (index < 0 || index + count > text.length || count*2 > pos.length) {
            throw new IndexOutOfBoundsException();
        }
        native_drawPosText(mNativeCanvas, text, index, count, pos,
                           paint.mNativePaint);
    
public voiddrawPosText(java.lang.String text, float[] pos, Paint paint)
Draw the text in the array, with each character's origin specified by
the pos array.
param
text The text to be drawn
param
pos Array of [x,y] positions, used to position each character
param
paint The paint used for the text (e.g. color, size, style)
        if (text.length()*2 > pos.length) {
            throw new ArrayIndexOutOfBoundsException();
        }
        native_drawPosText(mNativeCanvas, text, pos, paint.mNativePaint);
    
public voiddrawRGB(int r, int g, int b)
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
        native_drawRGB(mNativeCanvas, r, g, b);
    
public voiddrawRect(RectF rect, Paint paint)
Draw the specified Rect using the specified paint. The rectangle will
be filled or framed based on the Style in the paint.
param
rect The rect to be drawn
param
paint The paint used to draw the rect
        native_drawRect(mNativeCanvas, rect, paint.mNativePaint);
    
public voiddrawRect(Rect r, Paint paint)
Draw the specified Rect using the specified Paint. The rectangle
will be filled or framed based on the Style in the paint.
param
r The rectangle to be drawn.
param
paint The paint used to draw the rectangle
        drawRect(r.left, r.top, r.right, r.bottom, paint);
    
public voiddrawRect(float left, float top, float right, float bottom, Paint paint)
Draw the specified Rect using the specified paint. The rectangle will
be filled or framed based on the Style in the paint.
param
left The left side of the rectangle to be drawn
param
top The top side of the rectangle to be drawn
param
right The right side of the rectangle to be drawn
param
bottom The bottom side of the rectangle to be drawn
param
paint The paint used to draw the rect
        native_drawRect(mNativeCanvas, left, top, right, bottom,
                        paint.mNativePaint);
    
public voiddrawRoundRect(RectF rect, float rx, float ry, Paint paint)
Draw the specified round-rect using the specified paint. The roundrect
will be filled or framed based on the Style in the paint.
param
rect The rectangular bounds of the roundRect to be drawn
param
rx The x-radius of the oval used to round the corners
param
ry The y-radius of the oval used to round the corners
param
paint The paint used to draw the roundRect
        if (rect == null) {
            throw new NullPointerException();
        }
        native_drawRoundRect(mNativeCanvas, rect, rx, ry,
                             paint.mNativePaint);
    
public voiddrawText(char[] text, int index, int count, float x, float y, Paint paint)
Draw the text, with origin at (x,y), using the specified paint. The
origin is interpreted based on the Align setting in the paint.
param
text The text to be drawn
param
x The x-coordinate of the origin of the text being drawn
param
y The y-coordinate of the origin of the text being drawn
param
paint The paint used for the text (e.g. color, size, style)
        if ((index | count | (index + count) |
            (text.length - index - count)) < 0) {
            throw new IndexOutOfBoundsException();
        }
        native_drawText(mNativeCanvas, text, index, count, x, y,
                        paint.mNativePaint);
    
public native voiddrawText(java.lang.String text, float x, float y, Paint paint)
Draw the text, with origin at (x,y), using the specified paint. The
origin is interpreted based on the Align setting in the paint.
param
text The text to be drawn
param
x The x-coordinate of the origin of the text being drawn
param
y The y-coordinate of the origin of the text being drawn
param
paint The paint used for the text (e.g. color, size, style)
public voiddrawText(java.lang.String text, int start, int end, float x, float y, Paint paint)
Draw the text, with origin at (x,y), using the specified paint.
The origin is interpreted based on the Align setting in the paint.
param
text The text to be drawn
param
start The index of the first character in text to draw
param
end (end - 1) is the index of the last character in text to draw
param
x The x-coordinate of the origin of the text being drawn
param
y The y-coordinate of the origin of the text being drawn
param
paint The paint used for the text (e.g. color, size, style)
        if ((start | end | (end - start) | (text.length() - end)) < 0) {
            throw new IndexOutOfBoundsException();
        }
        native_drawText(mNativeCanvas, text, start, end, x, y,
                        paint.mNativePaint);
    
public voiddrawText(java.lang.CharSequence text, int start, int end, float x, float y, Paint paint)
Draw the specified range of text, specified by start/end, with its
origin at (x,y), in the specified Paint. The origin is interpreted
based on the Align setting in the Paint.
param
text The text to be drawn
param
start The index of the first character in text to draw
param
end (end - 1) is the index of the last character in text
to draw
param
x The x-coordinate of origin for where to draw the text
param
y The y-coordinate of origin for where to draw the text
param
paint The paint used for the text (e.g. color, size, style)
        if (text instanceof String || text instanceof SpannedString ||
            text instanceof SpannableString) {
            native_drawText(mNativeCanvas, text.toString(), start, end, x, y,
                            paint.mNativePaint);
        }
        else if (text instanceof GraphicsOperations) {
            ((GraphicsOperations) text).drawText(this, start, end, x, y,
                                                     paint);
        }
        else {
            char[] buf = TemporaryBuffer.obtain(end - start);
            TextUtils.getChars(text, start, end, buf, 0);
            drawText(buf, 0, end - start, x, y, paint);
            TemporaryBuffer.recycle(buf);
        }
    
public voiddrawTextOnPath(char[] text, int index, int count, Path path, float hOffset, float vOffset, Paint paint)
Draw the text, with origin at (x,y), using the specified paint, along
the specified path. The paint's Align setting determins where along the
path to start the text.
param
text The text to be drawn
param
path The path the text should follow for its baseline
param
hOffset The distance along the path to add to the text's
starting position
param
vOffset The distance above(-) or below(+) the path to position
the text
param
paint The paint used for the text (e.g. color, size, style)
        if (index < 0 || index + count > text.length) {
            throw new ArrayIndexOutOfBoundsException();
        }
        native_drawTextOnPath(mNativeCanvas, text, index, count,
                              path.ni(), hOffset, vOffset,
                              paint.mNativePaint);
    
public voiddrawTextOnPath(java.lang.String text, Path path, float hOffset, float vOffset, Paint paint)
Draw the text, with origin at (x,y), using the specified paint, along
the specified path. The paint's Align setting determins where along the
path to start the text.
param
text The text to be drawn
param
path The path the text should follow for its baseline
param
hOffset The distance along the path to add to the text's
starting position
param
vOffset The distance above(-) or below(+) the path to position
the text
param
paint The paint used for the text (e.g. color, size, style)
        if (text.length() > 0) {
            native_drawTextOnPath(mNativeCanvas, text, path.ni(),
                                  hOffset, vOffset, paint.mNativePaint);
        }
    
public voiddrawVertices(android.graphics.Canvas$VertexMode mode, int vertexCount, float[] verts, int vertOffset, float[] texs, int texOffset, int[] colors, int colorOffset, short[] indices, int indexOffset, int indexCount, Paint paint)
Draw the array of vertices, interpreted as triangles (based on mode). The
verts array is required, and specifies the x,y pairs for each vertex. If
texs is non-null, then it is used to specify the coordinate in shader
coordinates to use at each vertex (the paint must have a shader in this
case). If there is no texs array, but there is a color array, then each
color is interpolated across its corresponding triangle in a gradient. If
both texs and colors arrays are present, then they behave as before, but
the resulting color at each pixels is the result of multiplying the
colors from the shader and the color-gradient together. The indices array
is optional, but if it is present, then it is used to specify the index
of each triangle, rather than just walking through the arrays in order.
param
mode How to interpret the array of vertices
param
vertexCount The number of values in the vertices array (and
corresponding texs and colors arrays if non-null). Each logical
vertex is two values (x, y), vertexCount must be a multiple of 2.
param
verts Array of vertices for the mesh
param
vertOffset Number of values in the verts to skip before drawing.
param
texs May be null. If not null, specifies the coordinates to sample
into the current shader (e.g. bitmap tile or gradient)
param
texOffset Number of values in texs to skip before drawing.
param
colors May be null. If not null, specifies a color for each
vertex, to be interpolated across the triangle.
param
colorOffset Number of values in colors to skip before drawing.
param
indices If not null, array of indices to reference into the
vertex (texs, colors) array.
param
indexCount number of entries in the indices array (if not null).
param
paint Specifies the shader to use if the texs array is non-null.
        checkRange(verts.length, vertOffset, vertexCount);
        if (texs != null) {
            checkRange(texs.length, texOffset, vertexCount);
        }
        if (colors != null) {
            checkRange(colors.length, colorOffset, vertexCount);
        }
        if (indices != null) {
            checkRange(indices.length, indexOffset, indexCount);
        }
        nativeDrawVertices(mNativeCanvas, mode.nativeInt, vertexCount, verts,
                           vertOffset, texs, texOffset, colors, colorOffset,
                          indices, indexOffset, indexCount, paint.mNativePaint);
    
protected voidfinalize()
        super.finalize();
        finalizer(mNativeCanvas);
    
private static native voidfinalizer(int nativeCanvas)
public static native voidfreeGlCaches()
Call this to free up OpenGL resources that may be cached or allocated
on behalf of the Canvas. Any subsequent drawing with a GL-backed Canvas
will have to recreate those resources.
public booleangetClipBounds(Rect bounds)
Retrieve the clip bounds, returning true if they are non-empty.
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.
        return native_getClipBounds(mNativeCanvas, bounds);
    
public final RectgetClipBounds()
Retrieve the clip bounds.
return
the clip bounds, or [0, 0, 0, 0] if the clip is empty.
        Rect r = new Rect();
        getClipBounds(r);
        return r;
    
public floatgetDensityScale()
Returns the density scale for this Canvas' backing bitmap, expressed as a
factor of the default density (160dpi.) For instance, a bitmap designed for
240dpi displays will have a density scale of 1.5 whereas a bitmap
designed for 160dpi will have a density scale of 1.0.



The default density scale is {@link Bitmap#DENSITY_SCALE_UNKNOWN}.
return
A scaling factor of the default density (160dpi) or
{@link Bitmap#DENSITY_SCALE_UNKNOWN} if the scaling factor is unknown.
see
#setDensityScale(float)
see
Bitmap#getDensityScale()
hide
pending API council approval
        if (mBitmap != null) {
            return mBitmap.getDensityScale();
        }
        return mDensityScale;
    
public DrawFiltergetDrawFilter()
        return mDrawFilter;
    
public javax.microedition.khronos.opengles.GLgetGL()
Return the GL object associated with this canvas, or null if it is not
backed by GL.
        return mGL;
    
public native intgetHeight()
Returns the height of the current drawing layer
return
the height of the current drawing layer
public voidgetMatrix(Matrix ctm)
Return, in ctm, the current transformation matrix. This does not alter
the matrix in the canvas, but just returns a copy of it.
        native_getCTM(mNativeCanvas, ctm.native_instance);
    
public final MatrixgetMatrix()
Return a new matrix with a copy of the canvas' current transformation
matrix.
        Matrix m = new Matrix();
        getMatrix(m);
        return m;
    
public native intgetSaveCount()
Returns the number of matrix/clip states on the Canvas' private stack.
This will equal # save() calls - # restore() calls.
public native intgetWidth()
Returns the width of the current drawing layer
return
the width of the current drawing layer
private static native intinitGL()
private static native intinitRaster(int nativeBitmapOrZero)
public native booleanisOpaque()
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
private static native voidnativeDrawBitmapMatrix(int nCanvas, int nBitmap, int nMatrix, int nPaint)
private static native voidnativeDrawBitmapMesh(int nCanvas, int nBitmap, int meshWidth, int meshHeight, float[] verts, int vertOffset, int[] colors, int colorOffset, int nPaint)
private static native voidnativeDrawVertices(int nCanvas, int mode, int n, float[] verts, int vertOffset, float[] texs, int texOffset, int[] colors, int colorOffset, short[] indices, int indexOffset, int indexCount, int nPaint)
private static native voidnativeSetDrawFilter(int nativeCanvas, int nativeFilter)
private static native voidnativeSetViewport(int nCanvas, int w, int h)
private static native booleannative_clipPath(int nativeCanvas, int nativePath, int regionOp)
private static native booleannative_clipRect(int nCanvas, float left, float top, float right, float bottom, int regionOp)
private static native booleannative_clipRegion(int nativeCanvas, int nativeRegion, int regionOp)
private static native voidnative_concat(int nCanvas, int nMatrix)
private static native voidnative_drawARGB(int nativeCanvas, int a, int r, int g, int b)
private static native voidnative_drawArc(int nativeCanvas, RectF oval, float startAngle, float sweep, boolean useCenter, int paint)
private native voidnative_drawBitmap(int nativeCanvas, int bitmap, float left, float top, int nativePaintOrZero, boolean autoScale, float densityScale)
private native voidnative_drawBitmap(int nativeCanvas, int bitmap, Rect src, RectF dst, int nativePaintOrZero)
private static native voidnative_drawBitmap(int nativeCanvas, int bitmap, Rect src, Rect dst, int nativePaintOrZero)
private static native voidnative_drawBitmap(int nativeCanvas, int[] colors, int offset, int stride, float x, float y, int width, int height, boolean hasAlpha, int nativePaintOrZero)
private static native voidnative_drawCircle(int nativeCanvas, float cx, float cy, float radius, int paint)
private static native voidnative_drawColor(int nativeCanvas, int color)
private static native voidnative_drawColor(int nativeCanvas, int color, int mode)
private static native voidnative_drawLine(int nativeCanvas, float startX, float startY, float stopX, float stopY, int paint)
private static native voidnative_drawOval(int nativeCanvas, RectF oval, int paint)
private static native voidnative_drawPaint(int nativeCanvas, int paint)
private static native voidnative_drawPath(int nativeCanvas, int path, int paint)
private static native voidnative_drawPicture(int nativeCanvas, int nativePicture)
private static native voidnative_drawPosText(int nativeCanvas, char[] text, int index, int count, float[] pos, int paint)
private static native voidnative_drawPosText(int nativeCanvas, java.lang.String text, float[] pos, int paint)
private static native voidnative_drawRGB(int nativeCanvas, int r, int g, int b)
private static native voidnative_drawRect(int nativeCanvas, RectF rect, int paint)
private static native voidnative_drawRect(int nativeCanvas, float left, float top, float right, float bottom, int paint)
private static native voidnative_drawRoundRect(int nativeCanvas, RectF rect, float rx, float ry, int paint)
private static native voidnative_drawText(int nativeCanvas, char[] text, int index, int count, float x, float y, int paint)
private static native voidnative_drawText(int nativeCanvas, java.lang.String text, int start, int end, float x, float y, int paint)
private static native voidnative_drawTextOnPath(int nativeCanvas, char[] text, int index, int count, int path, float hOffset, float vOffset, int paint)
private static native voidnative_drawTextOnPath(int nativeCanvas, java.lang.String text, int path, float hOffset, float vOffset, int paint)
private static native voidnative_getCTM(int canvas, int matrix)
private static native booleannative_getClipBounds(int nativeCanvas, Rect bounds)
private static native booleannative_quickReject(int nativeCanvas, RectF rect, int native_edgeType)
private static native booleannative_quickReject(int nativeCanvas, int path, int native_edgeType)
private static native booleannative_quickReject(int nativeCanvas, float left, float top, float right, float bottom, int native_edgeType)
private static native intnative_saveLayer(int nativeCanvas, RectF bounds, int paint, int layerFlags)
private static native intnative_saveLayer(int nativeCanvas, float l, float t, float r, float b, int paint, int layerFlags)
private static native intnative_saveLayerAlpha(int nativeCanvas, RectF bounds, int alpha, int layerFlags)
private static native intnative_saveLayerAlpha(int nativeCanvas, float l, float t, float r, float b, int alpha, int layerFlags)
private static native voidnative_setBitmap(int nativeCanvas, int bitmap)
private static native voidnative_setMatrix(int nCanvas, int nMatrix)
public booleanquickReject(RectF rect, android.graphics.Canvas$EdgeType type)
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 specifies how to treat the edges (BW or antialiased)
return
true if the rect (transformed by the canvas' matrix)
does not intersect with the canvas' clip
        return native_quickReject(mNativeCanvas, rect, type.nativeInt);
    
public booleanquickReject(Path path, android.graphics.Canvas$EdgeType type)
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 true if the path should be considered antialiased,
since that means it may
affect a larger area (more pixels) than
non-antialiased.
return
true if the path (transformed by the canvas' matrix)
does not intersect with the canvas' clip
        return native_quickReject(mNativeCanvas, path.ni(), type.nativeInt);
    
public booleanquickReject(float left, float top, float right, float bottom, android.graphics.Canvas$EdgeType type)
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 true if the rect should be considered antialiased,
since that means it may affect a larger area (more
pixels) than non-antialiased.
return
true if the rect (transformed by the canvas' matrix)
does not intersect with the canvas' clip
        return native_quickReject(mNativeCanvas, left, top, right, bottom,
                                  type.nativeInt);
    
public native voidrestore()
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 native voidrestoreToCount(int saveCount)
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 native voidrotate(float degrees)
Preconcat the current matrix with the specified rotation.
param
degrees The amount to rotate, in degrees
public final voidrotate(float degrees, float px, float py)
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)
        translate(px, py);
        rotate(degrees);
        translate(-px, -py);
    
public native intsave()
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.
return
The value to pass to restoreToCount() to balance this save()
public native intsave(int saveFlags)
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.
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 intsaveLayer(RectF bounds, Paint paint, int saveFlags)
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.
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
return
value to pass to restoreToCount() to balance this save()
 
    
                                                                  
       
    
                                                                                                     
        

                                                                                                                                                                        
            
        return native_saveLayer(mNativeCanvas, bounds,
                                paint != null ? paint.mNativePaint : 0,
                                saveFlags);
    
public intsaveLayer(float left, float top, float right, float bottom, Paint paint, int saveFlags)
Helper version of saveLayer() that takes 4 values rather than a RectF.
        return native_saveLayer(mNativeCanvas, left, top, right, bottom,
                                paint != null ? paint.mNativePaint : 0,
                                saveFlags);
    
public intsaveLayerAlpha(RectF bounds, int alpha, int saveFlags)
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.
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
return
value to pass to restoreToCount() to balance this call
        alpha = Math.min(255, Math.max(0, alpha));
        return native_saveLayerAlpha(mNativeCanvas, bounds, alpha, saveFlags);
    
public intsaveLayerAlpha(float left, float top, float right, float bottom, int alpha, int saveFlags)
Helper for saveLayerAlpha() that takes 4 values instead of a RectF.
        return native_saveLayerAlpha(mNativeCanvas, left, top, right, bottom,
                                     alpha, saveFlags);
    
public native voidscale(float sx, float 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
public final voidscale(float sx, float sy, float px, float py)
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 rotation)
param
py The y-coord for the pivot point (unchanged by the rotation)
        translate(px, py);
        scale(sx, sy);
        translate(-px, -py);
    
public voidsetBitmap(Bitmap bitmap)
Specify a bitmap for the canvas to draw into.
param
bitmap Specifies a mutable bitmap for the canvas to draw into.
        if (!bitmap.isMutable()) {
            throw new IllegalStateException();
        }
        if (mGL != null) {
            throw new RuntimeException("Can't set a bitmap device on a GL canvas");
        }
        throwIfRecycled(bitmap);

        native_setBitmap(mNativeCanvas, bitmap.ni());
        mBitmap = bitmap;
        mDensityScale = bitmap.getDensityScale();
        if (mDensityScale == Bitmap.DENSITY_SCALE_UNKNOWN) mDensityScale = 1.0f;
    
public voidsetDensityScale(float densityScale)
Specifies the density scale for this Canvas' backing bitmap, expressed as a
factor of the default density (160dpi.) For instance, a bitmap designed for
240dpi displays will have a density scale of 1.5 whereas a bitmap
designed for 160dpi will have a density scale of 1.0.
param
densityScale The density scaling factor to use with this bitmap or
{@link Bitmap#DENSITY_SCALE_UNKNOWN} if the factor is unknown.
see
#getDensityScale()
see
Bitmap#setDensityScale(float)
hide
pending API council approval
        if (mBitmap != null) {
            mBitmap.setDensityScale(densityScale);
        }
        mDensityScale = densityScale;
        if (mDensityScale == Bitmap.DENSITY_SCALE_UNKNOWN) mDensityScale = 1.0f;
    
public voidsetDrawFilter(DrawFilter filter)
        int nativeFilter = 0;
        if (filter != null) {
            nativeFilter = filter.mNativeInt;
        }
        mDrawFilter = filter;
        nativeSetDrawFilter(mNativeCanvas, nativeFilter);
    
public voidsetMatrix(Matrix matrix)
Completely replace the current matrix with the specified matrix. If the
matrix parameter is null, then the current matrix is reset to identity.
param
matrix The matrix to replace the current matrix with. If it is
null, set the current matrix to identity.
        native_setMatrix(mNativeCanvas,
                         matrix == null ? 0 : matrix.native_instance);
    
public voidsetViewport(int width, int height)
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
        if (mGL != null) {
            nativeSetViewport(mNativeCanvas, width, height);
        }
    
public native voidskew(float sx, float sy)
Preconcat the current matrix with the specified skew.
param
sx The amount to skew in X
param
sy The amount to skew in Y
private static voidthrowIfRecycled(Bitmap bitmap)
        if (bitmap.isRecycled()) {
            throw new RuntimeException(
                        "Canvas: trying to use a recycled bitmap " + bitmap);
        }
    
public native voidtranslate(float dx, float dy)
Preconcat the current matrix with the specified translation
param
dx The distance to translate in X
param
dy The distance to translate in Y