This is an automated email from the git hooks/post-receive script. It was generated because a ref change was pushed to the repository containing the project gfxprim.git. The branch, master has been updated via ee7841b92486c22488a2efcb8fe29ea8642f863c (commit) from c2d53d78b138cc441a28c025b8899f6d3b80f29e (commit) Those revisions listed above that are new to this repository have not appeared on any other notification email; so we list those revisions in full, below. - Log ----------------------------------------------------------------- http://repo.or.cz/w/gfxprim.git/commit/ee7841b92486c22488a2efcb8fe29ea8642f8... commit ee7841b92486c22488a2efcb8fe29ea8642f863c Author: BlueBear <jiri.bluebear.dluhos@gmail.com> Date: Sun Nov 27 20:23:07 2011 +0100 More precise documentation of line drawing functions and subcontexts. diff --git a/doc/context.txt b/doc/context.txt index a98d21a..38a8efb 100644 --- a/doc/context.txt +++ b/doc/context.txt @@ -99,8 +99,9 @@ void GP_ContextFree(GP_Context *context); The 'GP_ContextAlloc()' allocates context and initalizes the context structure. The orientation flags are all set to 0 and the rest of the metadata -are calculated accordingly to width, height and pixel_type. The bitmap -(context->pixels) is not initalized. +are calculated accordingly to width, height and pixel_type. A bitmap with +appropriate size is allocated and stored in context->pixels; the initial +contents of the bitmap are undefined. The 'GP_ContextCopy()' allocates and initalizes a copy of the context passed as argument. If 'flag' is not zero, the bitmap (context->pixels) is copied @@ -112,12 +113,12 @@ In both cases the resulting context should later be freed with Subcontext ~~~~~~~~~~ -Given a rectangular area inside of any context subcontext could be created. -The resulting context could be used for all context operations (including -subcontext creation). The only difference between allocated context and -subcontext of such context is that the 'GP_ContextFree()' doesn't call -'free()' on subcontext pixels (which as a matter of a fact is a pointer that -points somewhere into to allocated area). +A subcontext is a context that refers to a rectangular area within another +context. Subcontexts can be used as any other context (including creating +another subcontexts). + +Calling GP_ContextFree() on a subcontext is safe; the bitmap is not freed as +it belongs to another context; it will be freed with the hosting context. [source,c] ------------------------------------------------------------------------------- @@ -129,12 +130,12 @@ GP_Context *GP_ContextSubContext(GP_Context *context, GP_Context *subcontext, Creates subcontext of a context. The rectangular area must fit into the context. -If subcontext pointer is 'NULL' the context structure is allocated otherwise +If subcontext pointer is 'NULL', the context structure is allocated; otherwise the metadata are filled into the context structure pointed by subcontext pointer. -In both cases pointer to subcontext or NULL (in case of 'malloc(2)' failure) is -returned. +In both cases, the call returns either a pointer to the new subcontext, +or NULL on failure (when there is not enough memory). Conversions ~~~~~~~~~~~ diff --git a/doc/drawing_api.txt b/doc/drawing_api.txt index 6cfd7e8..75a67e4 100644 --- a/doc/drawing_api.txt +++ b/doc/drawing_api.txt @@ -9,8 +9,8 @@ Fill void GP_Fill(GP_Context *context, GP_Pixel pixel); -------------------------------------------------------------------------------- -Fills the context bitmap. This has the same effect as calling -'GP_FillRect(context, 0, 0, context->w, context->h, pixel)'. +Fills the whole context bitmap with the specified pixel value. This has the +same effect as calling 'GP_FillRect(context, 0, 0, context->w, context->h, pixel)'. Lines ~~~~~ @@ -20,30 +20,45 @@ Lines void GP_HLineXXY(GP_Context *context, GP_Coord x0, GP_Coord x1, GP_Coord y, GP_Pixel pixel); -void GP_HLineXYW(GP_Context *context, GP_Coord x, GP_Coord y, GP_Size w, - GP_Pixel pixel); - void GP_HLine(GP_Context *context, GP_Coord x0, GP_Coord x1, GP_Coord y, GP_Pixel pixel); -------------------------------------------------------------------------------- -Draws a horizontal line. The 'GP_HLine()' function is an alias for -'GP_HLineXXY()'. +Draws a horizontal line from (x0, y) to (x1, y), inclusive. The coordinates +x0, x1 can be specified in any order. + +'GP_HLine()' is an alias for 'GP_HLineXXY()'. [source,c] -------------------------------------------------------------------------------- -void GP_VLineXYY(GP_Context *context, GP_Coord x, GP_Coord y0, GP_Coord y1, +void GP_HLineXYW(GP_Context *context, GP_Coord x, GP_Coord y, GP_Size w, GP_Pixel pixel); +-------------------------------------------------------------------------------- -void GP_VLineXYH(GP_Context *context, GP_Coord x, GP_Coord y, GP_Size h, +Draws a horizontal line from (x, y) to (x+w-1, y), inclusive. + + +[source,c] +-------------------------------------------------------------------------------- +void GP_VLineXYY(GP_Context *context, GP_Coord x, GP_Coord y0, GP_Coord y1, GP_Pixel pixel); void GP_VLine(GP_Context *context, GP_Coord x, GP_Coord y0, GP_Coord y1, GP_Pixel pixel); -------------------------------------------------------------------------------- -Draws a vertical line. The 'GP_VLine()' function is an alias for -'GP_VLineXYY()'. +Draws a vertical line from (x, y0) to (x, y1), inclusive. The coordinates +y0, y1 can be specified in any order. + +'GP_VLine()' is an alias for 'GP_VLineXYY()'. + +-------------------------------------------------------------------------------- +void GP_VLineXYH(GP_Context *context, GP_Coord x, GP_Coord y, GP_Size h, + GP_Pixel pixel); + +-------------------------------------------------------------------------------- + +Draws a vertical line from (x, y) to (x, y+h-1), inclusive. [source,c] -------------------------------------------------------------------------------- @@ -51,7 +66,9 @@ void GP_Line(GP_Context *context, GP_Coord x0, GP_Coord y0, GP_Coord x1, GP_Coord y1, GP_Pixel pixel); -------------------------------------------------------------------------------- -Draws a line from (x0, y0) to (x1, y1), inclusive. +Draws a line from (x0, y0) to (x1, y1), inclusive. The starting and ending +point can be specified in any order (the implementation guarantees that +exactly the same set of pixels will be drawn in both cases). Circles ~~~~~~~ ----------------------------------------------------------------------- Summary of changes: doc/context.txt | 23 ++++++++++++----------- doc/drawing_api.txt | 41 +++++++++++++++++++++++++++++------------ 2 files changed, 41 insertions(+), 23 deletions(-) repo.or.cz automatic notification. Contact project admin jiri.bluebear.dluhos@gmail.com if you want to unsubscribe, or site admin admin@repo.or.cz if you receive no reply. -- gfxprim.git ("A simple 2D graphics library with emphasis on correctness and well-defined operation.")