include/c/sk_canvas.h

   1 /*
   2  * Copyright 2014 Google Inc.
   3  *
   4  * Use of this source code is governed by a BSD-style license that can be
   5  * found in the LICENSE file.
   6  */
   7
   8 // EXPERIMENTAL EXPERIMENTAL EXPERIMENTAL EXPERIMENTAL
   9 // DO NOT USE -- FOR INTERNAL TESTING ONLY
  10
  11 #ifndef sk_canvas_DEFINED
  12 #define sk_canvas_DEFINED
  13
  14 #include "sk_types.h"
  15
  16 SK_C_PLUS_PLUS_BEGIN_GUARD
  17
  18 /**
  19     Save the current matrix and clip on the canvas.  When the
  20     balancing call to sk_canvas_restore() is made, the previous matrix
  21     and clip are restored.
  22 */
  23 SK_API int sk_canvas_save(sk_canvas_t*);
  24 /**
  25     This behaves the same as sk_canvas_save(), but in addition it
  26     allocates an offscreen surface. All drawing calls are directed
  27     there, and only when the balancing call to sk_canvas_restore() is
  28     made is that offscreen transfered to the canvas (or the previous
  29     layer).
  30
  31     @param sk_rect_t* (may be null) This rect, if non-null, is used as
  32                       a hint to limit the size of the offscreen, and
  33                       thus drawing may be clipped to it, though that
  34                       clipping is not guaranteed to happen. If exact
  35                       clipping is desired, use sk_canvas_clip_rect().
  36     @param sk_paint_t* (may be null) The paint is copied, and is applied
  37                        to the offscreen when sk_canvas_restore() is
  38                        called.
  39 */
  40 SK_API int sk_canvas_save_layer(sk_canvas_t*, const sk_rect_t*, const sk_paint_t*);
  41 /**
  42     This call balances a previous call to sk_canvas_save() or
  43     sk_canvas_save_layer(), and is used to remove all modifications to
  44     the matrix and clip state since the last save call.  It is an
  45     error to call sk_canvas_restore() more times than save and
  46     save_layer were called.
  47 */
  48 SK_API void sk_canvas_restore(sk_canvas_t*);
  49 /**
  50     Preconcat the current coordinate transformation matrix with the
  51     specified translation.
  52 */
  53 SK_API void sk_canvas_translate(sk_canvas_t*, float dx, float dy);
  54 /**
  55     Preconcat the current coordinate transformation matrix with the
  56     specified scale.
  57 */
  58 SK_API void sk_canvas_scale(sk_canvas_t*, float sx, float sy);
  59 /**
  60     Preconcat the current coordinate transformation matrix with the
  61     specified rotation in degrees.
  62 */
  63 SK_API void sk_canvas_rotate_degrees(sk_canvas_t*, float degrees);
  64 /**
  65     Preconcat the current coordinate transformation matrix with the
  66     specified rotation in radians.
  67 */
  68 SK_API void sk_canvas_rotate_radians(sk_canvas_t*, float radians);
  69 /**
  70     Preconcat the current coordinate transformation matrix with the
  71     specified skew.
  72 */
  73 SK_API void sk_canvas_skew(sk_canvas_t*, float sx, float sy);
  74 /**
  75     Preconcat the current coordinate transformation matrix with the
  76     specified matrix.
  77 */
  78 SK_API void sk_canvas_concat(sk_canvas_t*, const sk_matrix_t*);
  79
  80 /**
  81     Modify the current clip with the specified rectangle.  The new
  82     current clip will be the intersection of the old clip and the
  83     rectange.
  84 */
  85 SK_API void sk_canvas_clip_rect(sk_canvas_t*, const sk_rect_t*);
  86 /**
  87     Modify the current clip with the specified path.  The new
  88     current clip will be the intersection of the old clip and the
  89     path.
  90 */
  91 SK_API void sk_canvas_clip_path(sk_canvas_t*, const sk_path_t*);
  92
  93 /**
  94     Fill the entire canvas (restricted to the current clip) with the
  95     specified paint.
  96 */
  97 SK_API void sk_canvas_draw_paint(sk_canvas_t*, const sk_paint_t*);
  98 /**
  99     Draw the specified rectangle using the specified paint. The
 100     rectangle will be filled or stroked based on the style in the
 101     paint.
 102 */
 103 SK_API void sk_canvas_draw_rect(sk_canvas_t*, const sk_rect_t*, const sk_paint_t*);
 104 /**
 105  *  Draw the circle centered at (cx, cy) with radius rad using the specified paint.
 106  *  The circle will be filled or framed based on the style in the paint
 107  */
 108 SK_API void sk_canvas_draw_circle(sk_canvas_t*, float cx, float cy, float rad, const sk_paint_t*);
 109 /**
 110     Draw the specified oval using the specified paint. The oval will be
 111     filled or framed based on the style in the paint
 112 */
 113 SK_API void sk_canvas_draw_oval(sk_canvas_t*, const sk_rect_t*, const sk_paint_t*);
 114 /**
 115     Draw the specified path using the specified paint. The path will be
 116     filled or framed based on the style in the paint
 117 */
 118 SK_API void sk_canvas_draw_path(sk_canvas_t*, const sk_path_t*, const sk_paint_t*);
 119 /**
 120     Draw the specified image, with its top/left corner at (x,y), using
 121     the specified paint, transformed by the current matrix.
 122
 123     @param sk_paint_t* (may be NULL) the paint used to draw the image.
 124 */
 125 SK_API void sk_canvas_draw_image(sk_canvas_t*, const sk_image_t*,
 126                                  float x, float y, const sk_paint_t*);
 127 /**
 128     Draw the specified image, scaling and translating so that it fills
 129     the specified dst rect. If the src rect is non-null, only that
 130     subset of the image is transformed and drawn.
 131
 132     @param sk_paint_t* (may be NULL) The paint used to draw the image.
 133 */
 134 SK_API void sk_canvas_draw_image_rect(sk_canvas_t*, const sk_image_t*,
 135                                       const sk_rect_t* src,
 136                                       const sk_rect_t* dst, const sk_paint_t*);
 137 /**
 138     Draw the picture into this canvas (replay the pciture's drawing commands).
 139
 140     @param sk_matrix_t* If non-null, apply that matrix to the CTM when
 141                         drawing this picture. This is logically
 142                         equivalent to: save, concat, draw_picture,
 143                         restore.
 144
 145     @param sk_paint_t* If non-null, draw the picture into a temporary
 146                        buffer, and then apply the paint's alpha,
 147                        colorfilter, imagefilter, and xfermode to that
 148                        buffer as it is drawn to the canvas.  This is
 149                        logically equivalent to save_layer(paint),
 150                        draw_picture, restore.
 151 */
 152 SK_API void sk_canvas_draw_picture(sk_canvas_t*, const sk_picture_t*,
 153                                    const sk_matrix_t*, const sk_paint_t*);
 154 /**
 155    Helper method for drawing a color in SRC mode, completely replacing all the pixels
 156    in the current clip with this color.
 157  */
 158 SK_API void sk_canvas_clear(sk_canvas_t*, sk_color_t);
 159 /**
 160    This makes the contents of the canvas undefined. Subsequent calls that
 161    require reading the canvas contents will produce undefined results. Examples
 162    include blending and readPixels. The actual implementation is backend-
 163    dependent and one legal implementation is to do nothing. Like clear(), this
 164    ignores the clip.
 165
 166    This function should only be called if the caller intends to subsequently
 167    draw to the canvas. The canvas may do real work at discard() time in order
 168    to optimize performance on subsequent draws. Thus, if you call this and then
 169    never draw to the canvas subsequently you may pay a perfomance penalty.
 170 */
 171 SK_API void sk_canvas_discard(sk_canvas_t*);
 172 /**
 173     Returns the number of matrix/clip states on the SkCanvas' private stack.
 174     This will equal # save() calls - # restore() calls + 1. The save count on
 175     a new canvas is 1.
 176 */
 177 SK_API int sk_canvas_get_save_count(sk_canvas_t*);
 178 /**
 179     Efficient way to pop any calls to sk_canvas_save() that happened after the save
 180     count reached saveCount. It is an error for saveCount to be greater than
 181     getSaveCount(). To pop all the way back to the initial matrix/clip context
 182     pass saveCount == 1.
 183 */
 184 SK_API void sk_canvas_restore_to_count(sk_canvas_t*, int saveCount);
 185 /**
 186     Draws with the specified color and mode.
 187 **/
 188 SK_API void sk_canvas_draw_color(sk_canvas_t* ccanvas, sk_color_t color, sk_blendmode_t mode);
 189 /**
 190    Draw a series of points, interpreted based on the sk_point_mode_t mode. For
 191    all modes, the count parameter is interpreted as the total number of
 192    points. For LINES_SK_POINT_MODE mode, count/2 line segments are drawn.
 193    For POINTS_SK_POINT_MODE mode, each point is drawn centered at its coordinate, and its
 194    size is specified by the paint's stroke-width. It draws as a square,
 195    unless the paint's cap-type is round, in which the points are drawn as
 196    circles.
 197    For LINES_SK_POINT_MODE mode, each pair of points is drawn as a line segment,
 198    respecting the paint's settings for cap/join/width.
 199    For POLYGON_SK_POINT_MODE mode, the entire array is drawn as a series of connected
 200    line segments.
 201    Note that, while similar, LINES_SK_POINT_MODE and POLYGON_SK_POINT_MODE modes draw slightly
 202    differently than the equivalent path built with a series of moveto,
 203    lineto calls, in that the path will draw all of its contours at once,
 204    with no interactions if contours intersect each other (think XOR
 205    xfermode). sk_canvas_draw_paint always draws each element one at a time.
 206 */
 207 SK_API void sk_canvas_draw_points(sk_canvas_t*, sk_point_mode_t, size_t, const sk_point_t[], const sk_paint_t*);
 208 /**
 209    Draws a single point with the specified paint
 210 */
 211 SK_API void sk_canvas_draw_point(sk_canvas_t*, float, float, const sk_paint_t*);
 212 /**
 213    Draws a single point with the specified paint
 214 */
 215 SK_API void sk_canvas_draw_point_color(sk_canvas_t*, float, float, sk_color_t);
 216 /**
 217    Draws a line from x0,y0 to x1,y1
 218 */
 219 SK_API void sk_canvas_draw_line(sk_canvas_t* ccanvas, float x0, float y0, float x1, float y1, sk_paint_t* cpaint);
 220 /**
 221     Draw the text, with origin at (x,y), using the specified paint.
 222     The origin is interpreted based on the Align setting in the paint.
 223
 224     @param text The text to be drawn
 225     @param byteLength   The number of bytes to read from the text parameter
 226     @param x        The x-coordinate of the origin of the text being drawn
 227     @param y        The y-coordinate of the origin of the text being drawn
 228     @param paint    The paint used for the text (e.g. color, size, style)
 229 */
 230 SK_API void sk_canvas_draw_text (sk_canvas_t*, const char *text, size_t byteLength, float x, float y, const sk_paint_t* paint);
 231 /**
 232     Draw the text, with each character/glyph origin specified by the pos[]
 233     array. The origin is interpreted by the Align setting in the paint.
 234
 235     @param text The text to be drawn
 236     @param byteLength   The number of bytes to read from the text parameter
 237     @param pos      Array of positions, used to position each character
 238     @param paint    The paint used for the text (e.g. color, size, style)
 239 */
 240 SK_API void sk_canvas_draw_pos_text (sk_canvas_t*, const char *text, size_t byteLength, const sk_point_t[], const sk_paint_t* paint);
 241 /**
 242     Draw the text, with origin at (x,y), using the specified paint, along
 243     the specified path. The paint's Align setting determins where along the
 244     path to start the text.
 245
 246     @param text The text to be drawn
 247     @param byteLength   The number of bytes to read from the text parameter
 248     @param path         The path the text should follow for its baseline
 249     @param hOffset      The distance along the path to add to the text's
 250                         starting position
 251     @param vOffset      The distance above(-) or below(+) the path to
 252                         position the text
 253     @param paint        The paint used for the text
 254 */
 255 SK_API void sk_canvas_draw_text_on_path (sk_canvas_t*, const char *text, size_t byteLength, const sk_path_t*path, float hOffset, float vOffset, const sk_paint_t* paint);
 256 /**
 257     Draw the specified bitmap, with its top/left corner at (x,y), using the
 258     specified paint, transformed by the current matrix. Note: if the paint
 259     contains a maskfilter that generates a mask which extends beyond the
 260     bitmap's original width/height, then the bitmap will be drawn as if it
 261     were in a Shader with CLAMP mode. Thus the color outside of the original
 262     width/height will be the edge color replicated.
 263
 264     If a shader is present on the paint it will be ignored, except in the
 265     case where the bitmap is kAlpha_8_SkColorType. In that case, the color is
 266     generated by the shader.
 267
 268     @param bitmap   The bitmap to be drawn
 269     @param left     The position of the left side of the bitmap being drawn
 270     @param top      The position of the top side of the bitmap being drawn
 271     @param paint    The paint used to draw the bitmap, or NULL
 272 */
 273 SK_API void sk_canvas_draw_bitmap(sk_canvas_t* ccanvas, const sk_bitmap_t* bitmap, float left, float top, const sk_paint_t* paint);
 274 /** Draw the specified bitmap, scaling and translating so that it fills the specified
 275     dst rect. If the src rect is non-null, only that subset of the bitmap is transformed
 276     and drawn.
 277
 278     @param bitmap     The bitmap to be drawn
 279     @param src        Optional: specify the subset of the bitmap to be drawn
 280     @param dst        The destination rectangle where the scaled/translated
 281                       bitmap will be drawn
 282     @param paint      The paint used to draw the bitmap, or NULL
 283 */
 284 SK_API void sk_canvas_draw_bitmap_rect(sk_canvas_t* ccanvas, const sk_bitmap_t* bitmap, const sk_rect_t* src, const sk_rect_t* dst, const sk_paint_t* paint);
 285 /**
 286     Helper for setMatrix(identity). Sets the current matrix to identity.
 287 */
 288 SK_API void sk_canvas_reset_matrix(sk_canvas_t* ccanvas);
 289 /**
 290     Replace the current matrix with a copy of the specified matrix.
 291
 292     @param matrix The matrix that will be copied into the current matrix.
 293 */
 294 SK_API void sk_canvas_set_matrix(sk_canvas_t* ccanvas, const sk_matrix_t* matrix);
 295 /**
 296     Return the current matrix on the canvas.
 297     This does not account for the translate in any of the devices.
 298
 299     @param matrix The current matrix on the canvas.
 300 */
 301 SK_API void sk_canvas_get_total_matrix(sk_canvas_t* ccanvas, sk_matrix_t* matrix);
 302 /**
 303     Draw the specified rounded rectangle using the specified paint. The
 304     rectangle will be filled or stroked based on the style in the
 305     paint.
 306 */
 307 SK_API void sk_canvas_draw_round_rect(sk_canvas_t*, const sk_rect_t*, float rx, float ry, const sk_paint_t*);
 308 /**
 309     Modify the current clip with the specified rectangle.
 310 */
 311 SK_API void sk_canvas_clip_rect_with_operation(sk_canvas_t* t, const sk_rect_t* crect, sk_clipop_t op, bool doAA);
 312 /**
 313     Modify the current clip with the specified path.
 314 */
 315 SK_API void sk_canvas_clip_path_with_operation(sk_canvas_t* t, const sk_path_t* crect, sk_clipop_t op, bool doAA);
 316
 317 /**
 318     Return the bounds of the current clip (in local coordinates) in the
 319     bounds parameter, and return true if it is non-empty. This can be useful
 320     in a way similar to quickReject, in that it tells you that drawing
 321     outside of these bounds will be clipped out.
 322 */
 323 SK_API bool sk_canvas_get_clip_bounds(sk_canvas_t* t, sk_rect_t* cbounds);
 324 /**
 325     Return the bounds of the current clip, in device coordinates; returns
 326     true if non-empty. Maybe faster than getting the clip explicitly and
 327     then taking its bounds.
 328 */
 329 SK_API bool sk_canvas_get_clip_device_bounds(sk_canvas_t* t, sk_irect_t* cbounds);
 330
 331 /**
 332     Trigger the immediate execution of all pending draw operations. For the GPU
 333     backend this will resolve all rendering to the GPU surface backing the
 334     SkSurface that owns this canvas.
 335 */
 336 SK_API void sk_canvas_flush(sk_canvas_t* ccanvas);
 337
 338 SK_API sk_canvas_t* sk_canvas_new_from_bitmap(const sk_bitmap_t* bitmap);
 339
 340 SK_API void sk_canvas_draw_bitmap_lattice(sk_canvas_t* t, const sk_bitmap_t* bitmap, const sk_lattice_t* lattice, const sk_rect_t* dst, const sk_paint_t* paint);
 341 SK_API void sk_canvas_draw_image_lattice(sk_canvas_t* t, const sk_image_t* image, const sk_lattice_t* lattice, const sk_rect_t* dst, const sk_paint_t* paint);
 342
 343 SK_C_PLUS_PLUS_END_GUARD
 344
 345 #endif