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