AuroraMiddleware/skia2
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Documentation: C API comments

Browse Source 
Review URL: https://codereview.chromium.org/1271023002
This commit is contained in:
halcanary 2015-09-01 10:45:09 -07:00 committed by Commit bot
parent 2a4a4219aa
commit c9119060a0
10 changed files with 443 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

108
include/c/sk_canvas.h
View File

@ -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*);

39
include/c/sk_data.h
View File

@ -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

28
include/c/sk_image.h
View File

@ -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

15
include/c/sk_maskfilter.h
View File

@ -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

19
include/c/sk_matrix.h
View File

@ -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

70
include/c/sk_paint.h
View File

@ -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);
/**

36
include/c/sk_path.h
View File

@ -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);
/**

38
include/c/sk_picture.h
View File

@ -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

36
include/c/sk_surface.h
View File

@ -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*);
/**

54
include/c/sk_types.h
View File

@ -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 {