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 void sk_canvas_clear(sk_canvas_t*);
  24 /**
  25    This makes the contents of the canvas undefined. Subsequent calls that
  26    require reading the canvas contents will produce undefined results. Examples
  27    include blending and readPixels. The actual implementation is backend-
  28    dependent and one legal implementation is to do nothing. Like clear(), this
  29    ignores the clip.
  30
  31    This function should only be called if the caller intends to subsequently
  32    draw to the canvas. The canvas may do real work at discard() time in order
  33    to optimize performance on subsequent draws. Thus, if you call this and then
  34    never draw to the canvas subsequently you may pay a perfomance penalty.
  35 */
  36 SK_API void sk_canvas_discard(sk_canvas_t*);
  37 /**
  38     Save the current matrix and clip on the canvas.  When the
  39     balancing call to sk_canvas_restore() is made, the previous matrix
  40     and clip are restored.
  41 */
  42 SK_API void sk_canvas_save(sk_canvas_t*);
  43 /**
  44     This behaves the same as sk_canvas_save(), but in addition it
  45     allocates an offscreen surface. All drawing calls are directed
  46     there, and only when the balancing call to sk_canvas_restore() is
  47     made is that offscreen transfered to the canvas (or the previous
  48     layer).
  49
  50     @param sk_rect_t* (may be null) This rect, if non-null, is used as
  51                       a hint to limit the size of the offscreen, and
  52                       thus drawing may be clipped to it, though that
  53                       clipping is not guaranteed to happen. If exact
  54                       clipping is desired, use sk_canvas_clip_rect().
  55     @param sk_paint_t* (may be null) The paint is copied, and is applied
  56                        to the offscreen when sk_canvas_restore() is
  57                        called.
  58 */
  59 SK_API void sk_canvas_save_layer(sk_canvas_t*, const sk_rect_t*, const sk_paint_t*);
  60 /**
  61     This call balances a previous call to sk_canvas_save() or
  62     sk_canvas_save_layer(), and is used to remove all modifications to
  63     the matrix and clip state since the last save call.  It is an
  64     error to call sk_canvas_restore() more times than save and
  65     save_layer were called.
  66 */
  67 SK_API void sk_canvas_restore(sk_canvas_t*);
  68 /**
  69     Returns the number of matrix/clip states on the SkCanvas' private stack.
  70     This will equal # save() calls - # restore() calls + 1. The save count on
  71     a new canvas is 1.
  72 */
  73 SK_API int sk_canvas_get_save_count(sk_canvas_t*);
  74 /**
  75     Efficient way to pop any calls to sk_canvas_save() that happened after the save
  76     count reached saveCount. It is an error for saveCount to be greater than
  77     getSaveCount(). To pop all the way back to the initial matrix/clip context
  78     pass saveCount == 1.
  79 */
  80 SK_API void sk_canvas_restore_to_count(sk_canvas_t*, int saveCount);
  81
  82 /**
  83     Preconcat the current coordinate transformation matrix with the
  84     specified translation.
  85 */
  86 SK_API void sk_canvas_translate(sk_canvas_t*, float dx, float dy);
  87 /**
  88     Preconcat the current coordinate transformation matrix with the
  89     specified scale.
  90 */
  91 SK_API void sk_canvas_scale(sk_canvas_t*, float sx, float sy);
  92 /**
  93     Preconcat the current coordinate transformation matrix with the
  94     specified rotation in degrees.
  95 */
  96 SK_API void sk_canvas_rotate_degrees(sk_canvas_t*, float degrees);
  97 /**
  98     Preconcat the current coordinate transformation matrix with the
  99     specified rotation in radians.
 100 */
 101 SK_API void sk_canvas_rotate_radians(sk_canvas_t*, float radians);
 102 /**
 103     Preconcat the current coordinate transformation matrix with the
 104     specified skew.
 105 */
 106 SK_API void sk_canvas_skew(sk_canvas_t*, float sx, float sy);
 107 /**
 108     Preconcat the current coordinate transformation matrix with the
 109     specified matrix.
 110 */
 111 SK_API void sk_canvas_concat(sk_canvas_t*, const sk_matrix_t*);
 112
 113 /**
 114     Modify the current clip with the specified rectangle.  The new
 115     current clip will be the intersection of the old clip and the
 116     rectange.
 117 */
 118 SK_API void sk_canvas_clip_rect(sk_canvas_t*, const sk_rect_t*);
 119 /**
 120     Modify the current clip with the specified path.  The new
 121     current clip will be the intersection of the old clip and the
 122     path.
 123 */
 124 SK_API void sk_canvas_clip_path(sk_canvas_t*, const sk_path_t*);
 125
 126 /**
 127     Fill the entire canvas (restricted to the current clip) with the
 128     specified paint.
 129 */
 130 SK_API void sk_canvas_draw_paint(sk_canvas_t*, const sk_paint_t*);
 131 /**
 132     Draws with the specified color and mode.
 133 **/
 134 SK_API void sk_canvas_draw_color(sk_canvas_t* ccanvas, sk_color_t color, sk_xfermode_mode_t mode);
 135 /**
 136    Draw a series of points, interpreted based on the sk_point_mode_t mode. For
 137    all modes, the count parameter is interpreted as the total number of
 138    points. For LINES_SK_POINT_MODE mode, count/2 line segments are drawn.
 139    For POINTS_SK_POINT_MODE mode, each point is drawn centered at its coordinate, and its
 140    size is specified by the paint's stroke-width. It draws as a square,
 141    unless the paint's cap-type is round, in which the points are drawn as
 142    circles.
 143    For LINES_SK_POINT_MODE mode, each pair of points is drawn as a line segment,
 144    respecting the paint's settings for cap/join/width.
 145    For POLYGON_SK_POINT_MODE mode, the entire array is drawn as a series of connected
 146    line segments.
 147    Note that, while similar, LINES_SK_POINT_MODE and POLYGON_SK_POINT_MODE modes draw slightly
 148    differently than the equivalent path built with a series of moveto,
 149    lineto calls, in that the path will draw all of its contours at once,
 150    with no interactions if contours intersect each other (think XOR
 151    xfermode). sk_canvas_draw_paint always draws each element one at a time.
 152 */
 153 SK_API void sk_canvas_draw_points(sk_canvas_t*, sk_point_mode_t, size_t, const sk_point_t[], const sk_paint_t*);
 154 /**
 155    Draws a single point with the specified paint
 156 */
 157 SK_API void sk_canvas_draw_point(sk_canvas_t*, float, float, const sk_paint_t*);
 158 /**
 159    Draws a single point with the specified paint
 160 */
 161 SK_API void sk_canvas_draw_point_color(sk_canvas_t*, float, float, sk_color_t);
 162 /**
 163    Draws a line from x0,y0 to x1,y1
 164 */
 165 SK_API void sk_canvas_draw_line(sk_canvas_t* ccanvas, float x0, float y0, float x1, float y1, sk_paint_t* cpaint);
 166 /**
 167     Draw the specified rectangle using the specified paint. The
 168     rectangle will be filled or stroked based on the style in the
 169     paint.
 170 */
 171 SK_API void sk_canvas_draw_rect(sk_canvas_t*, const sk_rect_t*, const sk_paint_t*);
 172 /**
 173     Draw the specified oval using the specified paint. The oval will be
 174     filled or framed based on the style in the paint
 175 */
 176 SK_API void sk_canvas_draw_oval(sk_canvas_t*, const sk_rect_t*, const sk_paint_t*);
 177 /**
 178     Draw the specified path using the specified paint. The path will be
 179     filled or framed based on the style in the paint
 180 */
 181 SK_API void sk_canvas_draw_path(sk_canvas_t*, const sk_path_t*, const sk_paint_t*);
 182 /**
 183     Draw the specified image, with its top/left corner at (x,y), using
 184     the specified paint, transformed by the current matrix.
 185
 186     @param sk_paint_t* (may be NULL) the paint used to draw the image.
 187 */
 188 SK_API void sk_canvas_draw_image(sk_canvas_t*, const sk_image_t*,
 189                                  float x, float y, const sk_paint_t*);
 190 /**
 191     Draw the specified image, scaling and translating so that it fills
 192     the specified dst rect. If the src rect is non-null, only that
 193     subset of the image is transformed and drawn.
 194
 195     @param sk_paint_t* (may be NULL) The paint used to draw the image.
 196 */
 197 SK_API void sk_canvas_draw_image_rect(sk_canvas_t*, const sk_image_t*,
 198                                       const sk_rect_t* src,
 199                                       const sk_rect_t* dst, const sk_paint_t*);
 200
 201 /**
 202     Draw the picture into this canvas (replay the pciture's drawing commands).
 203
 204     @param sk_matrix_t* If non-null, apply that matrix to the CTM when
 205                         drawing this picture. This is logically
 206                         equivalent to: save, concat, draw_picture,
 207                         restore.
 208
 209     @param sk_paint_t* If non-null, draw the picture into a temporary
 210                        buffer, and then apply the paint's alpha,
 211                        colorfilter, imagefilter, and xfermode to that
 212                        buffer as it is drawn to the canvas.  This is
 213                        logically equivalent to save_layer(paint),
 214                        draw_picture, restore.
 215 */
 216 SK_API void sk_canvas_draw_picture(sk_canvas_t*, const sk_picture_t*,
 217                                    const sk_matrix_t*, const sk_paint_t*);
 218
 219 /**
 220    Draw the text, with origin at (x,y), using the specified paint.
 221    The origin is interpreted based on the Align setting in the paint.
 222
 223    @param text The text to be drawn
 224    @param byteLength   The number of bytes to read from the text parameter
 225    @param x        The x-coordinate of the origin of the text being drawn
 226    @param y        The y-coordinate of the origin of the text being drawn
 227    @param paint    The paint used for the text (e.g. color, size, style)
 228 */
 229 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);
 230 /**
 231     Draw the text, with each character/glyph origin specified by the pos[]
 232     array. The origin is interpreted by the Align setting in the paint.
 233     @param text The text to be drawn
 234     @param byteLength   The number of bytes to read from the text parameter
 235     @param pos      Array of positions, used to position each character
 236     @param paint    The paint used for the text (e.g. color, size, style)
 237 */
 238 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);
 239
 240 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);
 241
 242 SK_API void sk_canvas_draw_bitmap(sk_canvas_t* ccanvas, const sk_bitmap_t& cbitmap, float x, float y, const sk_paint_t* cpaint);
 243
 244 SK_API void sk_canvas_draw_bitmap_rect(sk_canvas_t* ccanvas, const sk_bitmap_t& cbitmap, const sk_rect_t* csrcR, const sk_rect_t* cdstR, const sk_paint_t* cpaint);
 245
 246 SK_C_PLUS_PLUS_END_GUARD
 247
 248 #endif