From c9119060a0a2739f53b8e966e8fcd9ff58024580 Mon Sep 17 00:00:00 2001 From: halcanary Date: Tue, 1 Sep 2015 10:45:09 -0700 Subject: [PATCH] Documentation: C API comments Review URL: https://codereview.chromium.org/1271023002 --- include/c/sk_canvas.h | 108 ++++++++++++++++++++++++++++++++++++++ include/c/sk_data.h | 39 ++++++++++++++ include/c/sk_image.h | 28 ++++++++++ include/c/sk_maskfilter.h | 15 ++++++ include/c/sk_matrix.h | 19 +++++++ include/c/sk_paint.h | 70 ++++++++++++++++++++++++ include/c/sk_path.h | 36 +++++++++++++ include/c/sk_picture.h | 38 ++++++++++++++ include/c/sk_surface.h | 36 +++++++++++++ include/c/sk_types.h | 54 +++++++++++++++++++ 10 files changed, 443 insertions(+) diff --git a/include/c/sk_canvas.h b/include/c/sk_canvas.h index f65d3aa5c9..f6c0d4e1c1 100644 --- a/include/c/sk_canvas.h +++ b/include/c/sk_canvas.h @@ -15,29 +15,137 @@ SK_C_PLUS_PLUS_BEGIN_GUARD +/** + Save the current matrix and clip on the canvas. When the + balancing call to sk_canvas_restore() is made, the previous matrix + and clip are restored. +*/ SK_API void sk_canvas_save(sk_canvas_t*); +/** + This behaves the same as sk_canvas_save(), but in addition it + allocates an offscreen surface. All drawing calls are directed + there, and only when the balancing call to sk_canvas_restore() is + made is that offscreen transfered to the canvas (or the previous + layer). + + @param sk_rect_t* (may be null) This rect, if non-null, is used as + a hint to limit the size of the offscreen, and + thus drawing may be clipped to it, though that + clipping is not guaranteed to happen. If exact + clipping is desired, use sk_canvas_clip_rect(). + @param sk_paint_t* (may be null) The paint is copied, and is applied + to the offscreen when sk_canvas_restore() is + called. +*/ SK_API void sk_canvas_save_layer(sk_canvas_t*, const sk_rect_t*, const sk_paint_t*); +/** + This call balances a previous call to sk_canvas_save() or + sk_canvas_save_layer(), and is used to remove all modifications to + the matrix and clip state since the last save call. It is an + error to call sk_canvas_restore() more times than save and + save_layer were called. +*/ SK_API void sk_canvas_restore(sk_canvas_t*); +/** + Preconcat the current coordinate transformation matrix with the + specified translation. +*/ SK_API void sk_canvas_translate(sk_canvas_t*, float dx, float dy); +/** + Preconcat the current coordinate transformation matrix with the + specified scale. +*/ SK_API void sk_canvas_scale(sk_canvas_t*, float sx, float sy); +/** + Preconcat the current coordinate transformation matrix with the + specified rotation in degrees. +*/ SK_API void sk_canvas_rotate_degrees(sk_canvas_t*, float degrees); +/** + Preconcat the current coordinate transformation matrix with the + specified rotation in radians. +*/ SK_API void sk_canvas_rotate_radians(sk_canvas_t*, float radians); +/** + Preconcat the current coordinate transformation matrix with the + specified skew. +*/ SK_API void sk_canvas_skew(sk_canvas_t*, float sx, float sy); +/** + Preconcat the current coordinate transformation matrix with the + specified matrix. +*/ SK_API void sk_canvas_concat(sk_canvas_t*, const sk_matrix_t*); +/** + Modify the current clip with the specified rectangle. The new + current clip will be the intersection of the old clip and the + rectange. +*/ SK_API void sk_canvas_clip_rect(sk_canvas_t*, const sk_rect_t*); +/** + Modify the current clip with the specified path. The new + current clip will be the intersection of the old clip and the + path. +*/ SK_API void sk_canvas_clip_path(sk_canvas_t*, const sk_path_t*); +/** + Fill the entire canvas (restricted to the current clip) with the + specified paint. +*/ SK_API void sk_canvas_draw_paint(sk_canvas_t*, const sk_paint_t*); +/** + Draw the specified rectangle using the specified paint. The + rectangle will be filled or stroked based on the style in the + paint. +*/ SK_API void sk_canvas_draw_rect(sk_canvas_t*, const sk_rect_t*, const sk_paint_t*); +/** + Draw the specified oval using the specified paint. The oval will be + filled or framed based on the style in the paint +*/ SK_API void sk_canvas_draw_oval(sk_canvas_t*, const sk_rect_t*, const sk_paint_t*); +/** + Draw the specified path using the specified paint. The path will be + filled or framed based on the style in the paint +*/ SK_API void sk_canvas_draw_path(sk_canvas_t*, const sk_path_t*, const sk_paint_t*); +/** + Draw the specified image, with its top/left corner at (x,y), using + the specified paint, transformed by the current matrix. + + @param sk_paint_t* (may be NULL) the paint used to draw the image. +*/ SK_API void sk_canvas_draw_image(sk_canvas_t*, const sk_image_t*, float x, float y, const sk_paint_t*); +/** + Draw the specified image, scaling and translating so that it fills + the specified dst rect. If the src rect is non-null, only that + subset of the image is transformed and drawn. + + @param sk_paint_t* (may be NULL) The paint used to draw the image. +*/ SK_API void sk_canvas_draw_image_rect(sk_canvas_t*, const sk_image_t*, const sk_rect_t* src, const sk_rect_t* dst, const sk_paint_t*); + +/** + Draw the picture into this canvas (replay the pciture's drawing commands). + + @param sk_matrix_t* If non-null, apply that matrix to the CTM when + drawing this picture. This is logically + equivalent to: save, concat, draw_picture, + restore. + + @param sk_paint_t* If non-null, draw the picture into a temporary + buffer, and then apply the paint's alpha, + colorfilter, imagefilter, and xfermode to that + buffer as it is drawn to the canvas. This is + logically equivalent to save_layer(paint), + draw_picture, restore. +*/ SK_API void sk_canvas_draw_picture(sk_canvas_t*, const sk_picture_t*, const sk_matrix_t*, const sk_paint_t*); diff --git a/include/c/sk_data.h b/include/c/sk_data.h index 95b7f5eb0b..90333bba5f 100644 --- a/include/c/sk_data.h +++ b/include/c/sk_data.h @@ -15,15 +15,54 @@ SK_C_PLUS_PLUS_BEGIN_GUARD +/** + Returns a new empty sk_data_t. This call must be balanced with a call to + sk_data_unref(). +*/ SK_API sk_data_t* sk_data_new_empty(); +/** + Returns a new sk_data_t by copying the specified source data. + This call must be balanced with a call to sk_data_unref(). +*/ SK_API sk_data_t* sk_data_new_with_copy(const void* src, size_t length); +/** + Pass ownership of the given memory to a new sk_data_t, which will + call free() when the refernce count of the data goes to zero. For + example: + size_t length = 1024; + void* buffer = malloc(length); + memset(buffer, 'X', length); + sk_data_t* data = sk_data_new_from_malloc(buffer, length); + This call must be balanced with a call to sk_data_unref(). +*/ SK_API sk_data_t* sk_data_new_from_malloc(const void* memory, size_t length); +/** + Returns a new sk_data_t using a subset of the data in the + specified source sk_data_t. This call must be balanced with a + call to sk_data_unref(). +*/ SK_API sk_data_t* sk_data_new_subset(const sk_data_t* src, size_t offset, size_t length); +/** + Increment the reference count on the given sk_data_t. Must be + balanced by a call to sk_data_unref(). +*/ SK_API void sk_data_ref(const sk_data_t*); +/** + Decrement the reference count. If the reference count is 1 before + the decrement, then release both the memory holding the sk_data_t + and the memory it is managing. New sk_data_t are created with a + reference count of 1. +*/ SK_API void sk_data_unref(const sk_data_t*); +/** + Returns the number of bytes stored. +*/ SK_API size_t sk_data_get_size(const sk_data_t*); +/** + Returns the pointer to the data. + */ SK_API const void* sk_data_get_data(const sk_data_t*); SK_C_PLUS_PLUS_END_GUARD diff --git a/include/c/sk_image.h b/include/c/sk_image.h index e6f49b74ee..e90649d75d 100644 --- a/include/c/sk_image.h +++ b/include/c/sk_image.h @@ -30,12 +30,40 @@ SK_API sk_image_t* sk_image_new_raster_copy(const sk_imageinfo_t*, const void* p */ SK_API sk_image_t* sk_image_new_from_encoded(const sk_data_t* encoded, const sk_irect_t* subset); +/** + * Encode the image's pixels and return the result as a new PNG in a + * sk_data_t, which the caller must manage: call sk_data_unref() when + * they are done. + * + * If the image type cannot be encoded, this will return NULL. + */ SK_API sk_data_t* sk_image_encode(const sk_image_t*); +/** + * Increment the reference count on the given sk_image_t. Must be + * balanced by a call to sk_image_unref(). +*/ SK_API void sk_image_ref(const sk_image_t*); +/** + * Decrement the reference count. If the reference count is 1 before + * the decrement, then release both the memory holding the sk_image_t + * and the memory it is managing. New sk_image_t are created with a + reference count of 1. +*/ SK_API void sk_image_unref(const sk_image_t*); + +/** + * Return the width of the sk_image_t/ + */ SK_API int sk_image_get_width(const sk_image_t*); +/** + * Return the height of the sk_image_t/ + */ SK_API int sk_image_get_height(const sk_image_t*); + +/** + * Returns a non-zero value unique among all images. + */ SK_API uint32_t sk_image_get_unique_id(const sk_image_t*); SK_C_PLUS_PLUS_END_GUARD diff --git a/include/c/sk_maskfilter.h b/include/c/sk_maskfilter.h index ce38605a85..5c22a06391 100644 --- a/include/c/sk_maskfilter.h +++ b/include/c/sk_maskfilter.h @@ -22,9 +22,24 @@ typedef enum { SK_C_PLUS_PLUS_BEGIN_GUARD +/** + Increment the reference count on the given sk_maskfilter_t. Must be + balanced by a call to sk_maskfilter_unref(). +*/ void sk_maskfilter_ref(sk_maskfilter_t*); +/** + Decrement the reference count. If the reference count is 1 before + the decrement, then release both the memory holding the + sk_maskfilter_t and any other associated resources. New + sk_maskfilter_t are created with a reference count of 1. +*/ void sk_maskfilter_unref(sk_maskfilter_t*); +/** + Create a blur maskfilter. + @param sk_blurstyle_t The SkBlurStyle to use + @param sigma Standard deviation of the Gaussian blur to apply. Must be > 0. +*/ sk_maskfilter_t* sk_maskfilter_new_blur(sk_blurstyle_t, float sigma); SK_C_PLUS_PLUS_END_GUARD diff --git a/include/c/sk_matrix.h b/include/c/sk_matrix.h index 12d946547f..83f0122b00 100644 --- a/include/c/sk_matrix.h +++ b/include/c/sk_matrix.h @@ -15,14 +15,33 @@ SK_C_PLUS_PLUS_BEGIN_GUARD +/** Set the matrix to identity */ void sk_matrix_set_identity(sk_matrix_t*); +/** Set the matrix to translate by (tx, ty). */ void sk_matrix_set_translate(sk_matrix_t*, float tx, float ty); +/** + Preconcats the matrix with the specified translation. + M' = M * T(dx, dy) +*/ void sk_matrix_pre_translate(sk_matrix_t*, float tx, float ty); +/** + Postconcats the matrix with the specified translation. + M' = T(dx, dy) * M +*/ void sk_matrix_post_translate(sk_matrix_t*, float tx, float ty); +/** Set the matrix to scale by sx and sy. */ void sk_matrix_set_scale(sk_matrix_t*, float sx, float sy); +/** + Preconcats the matrix with the specified scale. + M' = M * S(sx, sy) +*/ void sk_matrix_pre_scale(sk_matrix_t*, float sx, float sy); +/** + Postconcats the matrix with the specified scale. + M' = S(sx, sy) * M +*/ void sk_matrix_post_scale(sk_matrix_t*, float sx, float sy); SK_C_PLUS_PLUS_END_GUARD diff --git a/include/c/sk_paint.h b/include/c/sk_paint.h index 6699fb4f6f..e0886ad349 100644 --- a/include/c/sk_paint.h +++ b/include/c/sk_paint.h @@ -15,24 +15,78 @@ SK_C_PLUS_PLUS_BEGIN_GUARD +/** + Create a new paint with default settings: + antialias : false + stroke : false + stroke width : 0.0f (hairline) + stroke miter : 4.0f + stroke cap : BUTT_SK_STROKE_CAP + stroke join : MITER_SK_STROKE_JOIN + color : opaque black + shader : NULL + maskfilter : NULL + xfermode_mode : SRCOVER_SK_XFERMODE_MODE +*/ SK_API sk_paint_t* sk_paint_new(); +/** + Release the memory storing the sk_paint_t and unref() all + associated objects. +*/ SK_API void sk_paint_delete(sk_paint_t*); +/** + Return true iff the paint has antialiasing enabled. +*/ SK_API bool sk_paint_is_antialias(const sk_paint_t*); +/** + Set to true to enable antialiasing, false to disable it on this + sk_paint_t. +*/ SK_API void sk_paint_set_antialias(sk_paint_t*, bool); +/** + Return the paint's curent drawing color. +*/ SK_API sk_color_t sk_paint_get_color(const sk_paint_t*); +/** + Set the paint's curent drawing color. +*/ SK_API void sk_paint_set_color(sk_paint_t*, sk_color_t); /* stroke settings */ +/** + Return true iff stroking is enabled rather than filling on this + sk_paint_t. +*/ SK_API bool sk_paint_is_stroke(const sk_paint_t*); +/** + Set to true to enable stroking rather than filling with this + sk_paint_t. +*/ SK_API void sk_paint_set_stroke(sk_paint_t*, bool); +/** + Return the width for stroking. A value of 0 strokes in hairline mode. + */ SK_API float sk_paint_get_stroke_width(const sk_paint_t*); +/** + Set the width for stroking. A value of 0 strokes in hairline mode + (always draw 1-pixel wide, regardless of the matrix). + */ SK_API void sk_paint_set_stroke_width(sk_paint_t*, float width); +/** + Return the paint's stroke miter value. This is used to control the + behavior of miter joins when the joins angle is sharp. +*/ SK_API float sk_paint_get_stroke_miter(const sk_paint_t*); +/** + Set the paint's stroke miter value. This is used to control the + behavior of miter joins when the joins angle is sharp. This value + must be >= 0. +*/ SK_API void sk_paint_set_stroke_miter(sk_paint_t*, float miter); typedef enum { @@ -41,7 +95,15 @@ typedef enum { SQUARE_SK_STROKE_CAP } sk_stroke_cap_t; +/** + Return the paint's stroke cap type, controlling how the start and + end of stroked lines and paths are treated. +*/ SK_API sk_stroke_cap_t sk_paint_get_stroke_cap(const sk_paint_t*); +/** + Set the paint's stroke cap type, controlling how the start and + end of stroked lines and paths are treated. +*/ SK_API void sk_paint_set_stroke_cap(sk_paint_t*, sk_stroke_cap_t); typedef enum { @@ -50,7 +112,15 @@ typedef enum { BEVEL_SK_STROKE_JOIN } sk_stroke_join_t; +/** + Return the paint's stroke join type, specifies the treatment that + is applied to corners in paths and rectangles + */ SK_API sk_stroke_join_t sk_paint_get_stroke_join(const sk_paint_t*); +/** + Set the paint's stroke join type, specifies the treatment that + is applied to corners in paths and rectangles + */ SK_API void sk_paint_set_stroke_join(sk_paint_t*, sk_stroke_join_t); /** diff --git a/include/c/sk_path.h b/include/c/sk_path.h index d13a11219f..6b4e83d3b2 100644 --- a/include/c/sk_path.h +++ b/include/c/sk_path.h @@ -20,20 +20,56 @@ typedef enum { CCW_SK_PATH_DIRECTION, } sk_path_direction_t; +/** Create a new, empty path. */ SK_API sk_path_t* sk_path_new(); +/** Release the memory used by a sk_path_t. */ SK_API void sk_path_delete(sk_path_t*); +/** Set the beginning of the next contour to the point (x,y). */ SK_API void sk_path_move_to(sk_path_t*, float x, float y); +/** + Add a line from the last point to the specified point (x,y). If no + sk_path_move_to() call has been made for this contour, the first + point is automatically set to (0,0). +*/ SK_API void sk_path_line_to(sk_path_t*, float x, float y); +/** + Add a quadratic bezier from the last point, approaching control + point (x0,y0), and ending at (x1,y1). If no sk_path_move_to() call + has been made for this contour, the first point is automatically + set to (0,0). +*/ SK_API void sk_path_quad_to(sk_path_t*, float x0, float y0, float x1, float y1); +/** + Add a conic curve from the last point, approaching control point + (x0,y01), and ending at (x1,y1) with weight w. If no + sk_path_move_to() call has been made for this contour, the first + point is automatically set to (0,0). +*/ SK_API void sk_path_conic_to(sk_path_t*, float x0, float y0, float x1, float y1, float w); +/** + Add a cubic bezier from the last point, approaching control points + (x0,y0) and (x1,y1), and ending at (x2,y2). If no + sk_path_move_to() call has been made for this contour, the first + point is automatically set to (0,0). +*/ SK_API void sk_path_cubic_to(sk_path_t*, float x0, float y0, float x1, float y1, float x2, float y2); +/** + Close the current contour. If the current point is not equal to the + first point of the contour, a line segment is automatically added. +*/ SK_API void sk_path_close(sk_path_t*); +/** + Add a closed rectangle contour to the path. +*/ SK_API void sk_path_add_rect(sk_path_t*, const sk_rect_t*, sk_path_direction_t); +/** + Add a closed oval contour to the path +*/ SK_API void sk_path_add_oval(sk_path_t*, const sk_rect_t*, sk_path_direction_t); /** diff --git a/include/c/sk_picture.h b/include/c/sk_picture.h index f062d32e69..338b7d906a 100644 --- a/include/c/sk_picture.h +++ b/include/c/sk_picture.h @@ -15,16 +15,54 @@ SK_C_PLUS_PLUS_BEGIN_GUARD +/** + Create a new sk_picture_recorder_t. Its resources should be + released with a call to sk_picture_recorder_delete(). +*/ sk_picture_recorder_t* sk_picture_recorder_new(); +/** + Release the memory and other resources used by this + sk_picture_recorder_t. +*/ void sk_picture_recorder_delete(sk_picture_recorder_t*); +/** + Returns the canvas that records the drawing commands + + @param sk_rect_t* the cull rect used when recording this + picture. Any drawing the falls outside of this + rect is undefined, and may be drawn or it may not. +*/ sk_canvas_t* sk_picture_recorder_begin_recording(sk_picture_recorder_t*, const sk_rect_t*); +/** + Signal that the caller is done recording. This invalidates the + canvas returned by begin_recording. Ownership of the sk_picture_t + is passed to the caller, who must call sk_picture_unref() when + they are done using it. The returned picture is immutable. +*/ sk_picture_t* sk_picture_recorder_end_recording(sk_picture_recorder_t*); +/** + Increment the reference count on the given sk_picture_t. Must be + balanced by a call to sk_picture_unref(). +*/ void sk_picture_ref(sk_picture_t*); +/** + Decrement the reference count. If the reference count is 1 before + the decrement, then release both the memory holding the + sk_picture_t and any resouces it may be managing. New + sk_picture_t are created with a reference count of 1. +*/ void sk_picture_unref(sk_picture_t*); +/** + Returns a non-zero value unique among all pictures. + */ uint32_t sk_picture_get_unique_id(sk_picture_t*); + +/** + Return the cull rect specified when this picture was recorded. +*/ sk_rect_t sk_picture_get_bounds(sk_picture_t*); SK_C_PLUS_PLUS_END_GUARD diff --git a/include/c/sk_surface.h b/include/c/sk_surface.h index f3c17d075d..d634185eec 100644 --- a/include/c/sk_surface.h +++ b/include/c/sk_surface.h @@ -15,10 +15,46 @@ SK_C_PLUS_PLUS_BEGIN_GUARD +/** + Return a new surface, with the memory for the pixels automatically + allocated. If the requested surface cannot be created, or the + request is not a supported configuration, NULL will be returned. + + @param sk_imageinfo_t* Specify the width, height, color type, and + alpha type for the surface. + + @param sk_surfaceprops_t* If not NULL, specify additional non-default + properties of the surface. +*/ SK_API sk_surface_t* sk_surface_new_raster(const sk_imageinfo_t*, const sk_surfaceprops_t*); + +/** + Create a new surface which will draw into the specified pixels + with the specified rowbytes. If the requested surface cannot be + created, or the request is not a supported configuration, NULL + will be returned. + + @param sk_imageinfo_t* Specify the width, height, color type, and + alpha type for the surface. + @param void* pixels Specify the location in memory where the + destination pixels are. This memory must + outlast this surface. + @param size_t rowBytes Specify the difference, in bytes, between + each adjacent row. Should be at least + (width * sizeof(one pixel)). + @param sk_surfaceprops_t* If not NULL, specify additional non-default + properties of the surface. +*/ SK_API sk_surface_t* sk_surface_new_raster_direct(const sk_imageinfo_t*, void* pixels, size_t rowBytes, const sk_surfaceprops_t* props); + +/** + Decrement the reference count. If the reference count is 1 before + the decrement, then release both the memory holding the + sk_surface_t and any pixel memory it may be managing. New + sk_surface_t are created with a reference count of 1. +*/ SK_API void sk_surface_unref(sk_surface_t*); /** diff --git a/include/c/sk_types.h b/include/c/sk_types.h index f6d73df94d..41dd2715b0 100644 --- a/include/c/sk_types.h +++ b/include/c/sk_types.h @@ -33,6 +33,7 @@ SK_C_PLUS_PLUS_BEGIN_GUARD typedef uint32_t sk_color_t; +/* This macro assumes all arguments are >=0 and <=255. */ #define sk_color_set_argb(a, r, g, b) (((a) << 24) | ((r) << 16) | ((g) << 8) | (b)) #define sk_color_get_a(c) (((c) >> 24) & 0xFF) #define sk_color_get_r(c) (((c) >> 16) & 0xFF) @@ -65,6 +66,9 @@ typedef enum { BGR_V_SK_PIXELGEOMETRY, } sk_pixelgeometry_t; +/** + Return the default sk_colortype_t; this is operating-system dependent. +*/ SK_API sk_colortype_t sk_colortype_get_default_8888(); typedef struct { @@ -101,15 +105,65 @@ typedef struct { float mat[9]; } sk_matrix_t; +/** + A sk_canvas_t encapsulates all of the state about drawing into a + destination This includes a reference to the destination itself, + and a stack of matrix/clip values. +*/ typedef struct sk_canvas_t sk_canvas_t; +/** + A sk_data_ holds an immutable data buffer. +*/ typedef struct sk_data_t sk_data_t; +/** + A sk_image_t is an abstraction for drawing a rectagle of pixels. + The content of the image is always immutable, though the actual + storage may change, if for example that image can be re-created via + encoded data or other means. +*/ typedef struct sk_image_t sk_image_t; +/** + A sk_maskfilter_t is an object that perform transformations on an + alpha-channel mask before drawing it; it may be installed into a + sk_paint_t. Each time a primitive is drawn, it is first + scan-converted into a alpha mask, which os handed to the + maskfilter, which may create a new mask is to render into the + destination. + */ typedef struct sk_maskfilter_t sk_maskfilter_t; +/** + A sk_paint_t holds the style and color information about how to + draw geometries, text and bitmaps. +*/ typedef struct sk_paint_t sk_paint_t; +/** + A sk_path_t encapsulates compound (multiple contour) geometric + paths consisting of straight line segments, quadratic curves, and + cubic curves. +*/ typedef struct sk_path_t sk_path_t; +/** + A sk_picture_t holds recorded canvas drawing commands to be played + back at a later time. +*/ typedef struct sk_picture_t sk_picture_t; +/** + A sk_picture_recorder_t holds a sk_canvas_t that records commands + to create a sk_picture_t. +*/ typedef struct sk_picture_recorder_t sk_picture_recorder_t; +/** + A sk_shader_t specifies the source color(s) for what is being drawn. If a + paint has no shader, then the paint's color is used. If the paint + has a shader, then the shader's color(s) are use instead, but they + are modulated by the paint's alpha. +*/ typedef struct sk_shader_t sk_shader_t; +/** + A sk_surface_t holds the destination for drawing to a canvas. For + raster drawing, the destination is an array of pixels in memory. + For GPU drawing, the destination is a texture or a framebuffer. +*/ typedef struct sk_surface_t sk_surface_t; typedef enum {