From 1cd5016b247b64d2d0b7b7c6791d5f730248ec64 Mon Sep 17 00:00:00 2001 From: Cyril Hrubis Date: Fri, 29 Jul 2011 21:24:06 +0000 Subject: [PATCH] Updated docs to match the code. --- doc/Makefile | 3 +- doc/basic_types.txt | 84 ++++++++++++++----------------------- doc/context.txt | 39 ++++++------------ doc/drawing_api.txt | 117 +++++++++++++++++++++++++++++++++------------------- doc/filters.txt | 14 +++---- 5 files changed, 125 insertions(+), 132 deletions(-) diff --git a/doc/Makefile b/doc/Makefile index 4307a8ce..fd95a7b0 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -1,6 +1,7 @@ all: api.html -api.html: general.txt api.txt context.txt loaders.txt filters.txt +api.html: general.txt api.txt context.txt loaders.txt filters.txt \ + basic_types.txt drawing_api.txt asciidoc -a toc api.txt api.pdf: api.txt diff --git a/doc/basic_types.txt b/doc/basic_types.txt index 9bcba9ee..efc9c7bd 100644 --- a/doc/basic_types.txt +++ b/doc/basic_types.txt @@ -3,7 +3,8 @@ Basic types Return Code ~~~~~~~~~~~ -Basically each gfxprim function returns one of following return codes: +Some gfxprim function returns one of following return codes (may be removed in +future): [source,c] -------------------------------------------------------------------------------- @@ -29,74 +30,51 @@ Return codes could be translated into an error messages. const char *GP_RetCodeName(GP_RetCode code); -------------------------------------------------------------------------------- +Coord and Size +~~~~~~~~~~~~~~ +For drawing API there are two integer types defined the 'GP_Coord' for +coordinates and 'GP_Size' for size, length or so. + + Color and pixel types ~~~~~~~~~~~~~~~~~~~~~ -The color, in gfxprim is abstract value that represents color in some format, -while pixel is color in format of the target bitmap. - -Color and pixel types could be converted between each other but certain -conversions lose information. +The color, in gfxprim is enumeration of symbolic color names while pixel is +integer value or you may say color in format of the target bitmap. -Color types are defined in 'core/GP_Color.h' and pixels in 'core/GP_Pixel.h'. -The color is union of structures so that is easy to manipulate with each color -types, the pixel is basically sequence of bytes stored in long enough integer -number. +Color could be converted into given pixel type which will result in integer +value suitable for usage with drawing functions. The color could be also +converted to color name (C string in English language) and C string may be +matched against table of color names. -Before drawing a shape into a bitmap, color must be converted into pixel as -all drawing functions takes pixel rather than color. +As all drawing functions works with pixel rather than color the color must be +converted before using function to draw a shape into a bitmap. -The color types: +The color is defined as follows: [source,c] -------------------------------------------------------------------------------- -typedef enum GP_ColorType { - GP_NOCOLOR = 0, - GP_COLNAME, - GP_PALETTE, - GP_PAL4, - GP_PAL8, - GP_G1, - GP_G2, - GP_G4, - GP_G8, - GP_RGB555, - GP_RGB565, - GP_RGB666, - GP_RGB888, - GP_RGBA8888, - GP_COLMAX, -} GP_ColorType; +typedef enum GP_Color { + GP_COL_INVALID = -1, + GP_COL_BLACK, + ... +} GP_Color; -------------------------------------------------------------------------------- -Predefined names are provided for the most basic colors: +Color and Pixel conversion functions, the last one returns 'true' in case of +successful match and conversion and false otherwise. [source,c] -------------------------------------------------------------------------------- -typedef enum GP_ColorName { - GP_COL_BLACK, - GP_COL_RED, - GP_COL_GREEN, - GP_COL_BLUE, - GP_COL_YELLOW, - GP_COL_BROWN, - GP_COL_ORANGE, - GP_COL_GRAY_DARK, - GP_COL_GRAY_LIGHT, - GP_COL_PURPLE, - GP_COL_WHITE, - GP_COL_MAX, -} GP_ColorName; --------------------------------------------------------------------------------- +#include -To convert color to context pixel type use: +GP_Pixel GP_ColorToPixel(GP_Context *context, GP_Color color); -[source,c] --------------------------------------------------------------------------------- -GP_RetCode GP_ColorToPixel(struct GP_Context *context, GP_Color color, - GP_Pixel *pixel); +GP_Color GP_ColorNameToColor(const char *color_name); + +const char *GP_ColorToColorName(GP_Color color); -GP_RetCode GP_ColorNameToPixel(struct GP_Context *context, GP_ColorName name, - GP_Pixel *pixel); +bool GP_ColorNameToPixel(GP_Context *context, const char *color_name, + GP_Pixel *pixel); -------------------------------------------------------------------------------- diff --git a/doc/context.txt b/doc/context.txt index b3156a0f..42c9f8cb 100644 --- a/doc/context.txt +++ b/doc/context.txt @@ -20,25 +20,21 @@ typedef struct GP_Context { int axes_swap:1; /* Context rotation and mirroring */ int x_swap:1; int y_swap:1; - - uint32_t clip_w_min; /* Clipping rectanle */ - uint32_t clip_w_max; - uint32_t clip_h_min; - uint32_t clip_h_max; } GP_Context; ------------------------------------------------------------------------------- -The 'GP_Context' holds metadata needed for bitmaps. The values of pixels +The 'GP_Context' holds meta-data needed for bitmaps. The values of pixels are stored as bitmap lines (aligned to bytes) in one dimensional array. -The addres of pixel could be determined by GP_PIXEL_ADDRESS(context, x, y) -which returns byte aligned addres for the pixel. +The address of pixel could be determined by GP_PIXEL_ADDRESS(context, x, y) +which returns byte aligned address for the pixel. Rotation ^^^^^^^^ +All gfx functions does honor rotation and mirroring. If you really need drawing +primitives without it use variants with _Raw suffix. -Rotation and mirroring is honored only by functions starting with extra T. -So GP_TLine() is equal to GP_Line(), when all axes_sawp, x_swap and y_swap are -set to zero. +So GP_Line() is equal to GP_Line_Raw(), when all axes_swap, x_swap and y_swap +are set to zero. There are various macros for transforming coordinates and sizes in 'core/GP_Transform.h'. @@ -47,13 +43,6 @@ There are various macros for transforming coordinates and sizes in * *GP_TRANSFORM_RECT(x, y, w, h)* * *GP_RETRANSFORM_POINT(x, y)* -Clipping rectangle -^^^^^^^^^^^^^^^^^^ - -All drawing functions honor the clipping rectangle, eg. no pixels are put, -even when the coordinates are inside the bitmap, if they are outside of -clipping rectangle. - Functions ~~~~~~~~~ @@ -63,12 +52,10 @@ Functions uint32_t GP_ContextW(struct GP_Context *context); uint32_t GP_ContextH(struct GP_Context *context); -uint32_t GP_TContextW(struct GP_Context *context); -uint32_t GP_TContextH(struct GP_Context *context); ------------------------------------------------------------------------------- -Functions to get context width and height. Functions with 'T' prefix do honour -rotation flags (swaps W and H if axes_swap is set). +Functions to get context width and height that do honor rotation flags (swaps +W and H if axes_swap is set). [source,c] ------------------------------------------------------------------------------- @@ -88,7 +75,7 @@ counter clock wise. GP_Context *GP_ContextAlloc(uint32_t w, uint32_t h, GP_PixelType type); ------------------------------------------------------------------------------- -Allocates and initalizes the 'GP_Context' structure. The size for pixels is +Allocates and initializes the 'GP_Context' structure. The size for pixels is computed from width, height and pixel type. Moreover the rotation flags are set to zero and clipping rectangle is set to whole bitmap. @@ -110,9 +97,9 @@ Free the context allocated memory. GP_Context *GP_ContextCopy(GP_Context *context, int flag); ------------------------------------------------------------------------------- -Copy a context. Allocates and initalizes a 'GP_Context'. If flag is set to -GP_CONTEXT_WITH_PIXELS, the actuall bitmap is copied from contex to newly -allocated context, otherwise only context metadata are copied. +Copy a context. Allocates and initializes a 'GP_Context'. If flag is set to +GP_CONTEXT_WITH_PIXELS, the actual bitmap is copied from context to newly +allocated context, otherwise only context meta-data are copied. The newly created context should be later freed with 'GP_ContextFree()'. diff --git a/doc/drawing_api.txt b/doc/drawing_api.txt index 707ad710..6cfd7e85 100644 --- a/doc/drawing_api.txt +++ b/doc/drawing_api.txt @@ -9,42 +9,46 @@ Fill void GP_Fill(GP_Context *context, GP_Pixel pixel); -------------------------------------------------------------------------------- -Fills the context bitmap, respecting the clipping rect. This has the same effect -as calling 'GP_FillRect(context, 0, 0, context->w, context->h, pixel)'. - -This functions doesn't have rotate friendly variant. +Fills the context bitmap. This has the same effect as calling +'GP_FillRect(context, 0, 0, context->w, context->h, pixel)'. Lines ~~~~~ [source,c] -------------------------------------------------------------------------------- -void GP_HLineXXY(GP_Context *context, int x0, int x1, int y, GP_Pixel pixel); +void GP_HLineXXY(GP_Context *context, GP_Coord x0, GP_Coord x1, GP_Coord y, + GP_Pixel pixel); -void GP_HLineXYW(GP_Context *context, int x, int y, unsigned int w, +void GP_HLineXYW(GP_Context *context, GP_Coord x, GP_Coord y, GP_Size w, GP_Pixel pixel); -void GP_HLine(GP_Context *context, int x0, int x1, int y, 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. The 'GP_HLine()' function is an alias for +'GP_HLineXXY()'. [source,c] -------------------------------------------------------------------------------- -void GP_VLineXYY(GP_Context *context, int x, int y0, int y1, GP_Pixel pixel); +void GP_VLineXYY(GP_Context *context, GP_Coord x, GP_Coord y0, GP_Coord y1, + GP_Pixel pixel); -void GP_VLineXYH(GP_Context *context, int x, int y, - unsigned int height, GP_Pixel pixel); +void GP_VLineXYH(GP_Context *context, GP_Coord x, GP_Coord y, GP_Size h, + GP_Pixel pixel); -void GP_VLine(GP_Context *context, int x, int y0, int 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. The 'GP_VLine()' function is an alias for +'GP_VLineXYY()'. [source,c] -------------------------------------------------------------------------------- -void GP_Line(GP_Context *context, int x0, int y0, int x1, int y1, - GP_Pixel pixel); +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. @@ -54,35 +58,56 @@ Circles [source,c] -------------------------------------------------------------------------------- -void GP_Circle(GP_Context *context, int xcenter, int ycenter, - unsigned int r, GP_Pixel pixel); +void GP_Circle(GP_Context *context, GP_Coord xcenter, GP_Coord ycenter, + GP_Size r, GP_Pixel pixel); -------------------------------------------------------------------------------- Draws a circle. [source,c] -------------------------------------------------------------------------------- -void GP_FillCircle(GP_Context *context, int xcenter, int ycenter, - unsigned int r, GP_Pixel pixel); +void GP_FillCircle(GP_Context *context, GP_Coord xcenter, GP_Coord ycenter, + GP_Size r, GP_Pixel pixel); -------------------------------------------------------------------------------- Draws a filled circle. +Rings +~~~~~ +[source,c] +-------------------------------------------------------------------------------- +void GP_Ring(GP_Context *context, GP_Coord xcenter, GP_Coord ycenter, + GP_Size r1, GP_Size r2, GP_Pixel pixel); +-------------------------------------------------------------------------------- + +Draws a ring. + +[source,c] +-------------------------------------------------------------------------------- +void GP_FillRing(GP_Context *context, GP_Coord xcenter, GP_Coord ycenter, + GP_Size r1, GP_Size r2, GP_Pixel pixel); +-------------------------------------------------------------------------------- + +Draws a filled ring. + +The smaller of r1 and r2 is used for inner radius and bigger one for outer +radius. + Ellipses ~~~~~~~~ [source,c] -------------------------------------------------------------------------------- -void GP_Ellipse(GP_Context *context, int xcenter, int ycenter, - unsigned int a, unsigned int b, GP_Pixel pixel); +void GP_Ellipse(GP_Context *context, GP_Coord xcenter, GP_Coord ycenter, + GP_Size a, GP_Size b, GP_Pixel pixel); -------------------------------------------------------------------------------- Draws an ellipse. [source,c] -------------------------------------------------------------------------------- -void GP_FillEllipse(GP_Context *context, int xcenter, int ycenter, - unsigned int a, unsigned int b, GP_Pixel pixel); +void GP_FillEllipse(GP_Context *context, GP_Coord xcenter, GP_Coord ycenter, + GP_Size a, GP_Size b, GP_Pixel pixel); -------------------------------------------------------------------------------- Draws a filled ellipse. @@ -92,16 +117,18 @@ Triangles [source,c] -------------------------------------------------------------------------------- -void GP_Triangle(GP_Context *context, int x0, int y0, int x1, int y1, - int x2, int y2, GP_Pixel pixel); +void GP_Triangle(GP_Context *context, GP_Coord x0, GP_Coord y0, + GP_Coord x1, GP_Coord y1, GP_Coord x2, GP_Coord y2, + GP_Pixel pixel); -------------------------------------------------------------------------------- Draws a triangle. [source,c] -------------------------------------------------------------------------------- -void GP_FillTriangle(GP_Context *context, int x0, int y0, int x1, int y1, - int x2, int y2, GP_Pixel pixel); +void GP_FillTriangle(GP_Context *context, GP_Coord x0, GP_Coord y0, + GP_Coord x1, GP_Coord y1, GP_Coord x2, GP_Coord y2, + GP_Pixel pixel); -------------------------------------------------------------------------------- Draws a filled triangle. @@ -111,34 +138,36 @@ Rects [source,c] -------------------------------------------------------------------------------- -void GP_RectXYXY(GP_Context *context, int x0, int y0, int x1, int y1, - GP_Pixel pixel); +void GP_RectXYXY(GP_Context *context, GP_Coord x0, GP_Coord y0, + GP_Coord x1, GP_Coord y1, GP_Pixel pixel); -void GP_RectXYWH(GP_Context *context, int x, int y, - unsigned int w, unsigned int h, GP_Pixel pixel); +void GP_RectXYWH(GP_Context *context, GP_Coord x, GP_Coord y, + GP_Size w, GP_Size h, GP_Pixel pixel); -void GP_Rect(GP_Context *context, int x0, int y0, int x1, int y1, - GP_Pixel pixel); +void GP_Rect(GP_Context *context, GP_Coord x0, GP_Coord y0, + GP_Coord x1, GP_Coord y1, GP_Pixel pixel); -------------------------------------------------------------------------------- Draws a rectangle. + The 'GP_RectXYXY()' expects two corner points (x0, y0), and (x1, y1). The 'GP_RectXYWH()' expects a corner point (x0, y0), width and height. The 'GP_Rect()' function is an alias for 'GP_RectXYXY()'. [source,c] -------------------------------------------------------------------------------- -void GP_FillRectXYXY(GP_Context *context, int x0, int y0, int x1, int y1, - GP_Pixel pixel); +void GP_FillRectXYXY(GP_Context *context, GP_Coord x0, GP_Coord y0, + GP_Coord x1, GP_Coord y1, GP_Pixel pixel); -void GP_FillRectXYWH(GP_Context *context, int x, int y, - unsigned int w, unsigned int h, GP_Pixel pixel); +void GP_FillRectXYWH(GP_Context *context, GP_Coord x, GP_Coord y, + GP_Size w, GP_Size h, GP_Pixel pixel); -void GP_FillRect(GP_Context *context, int x0, int y0, int x1, int y1, - GP_Pixel pixel); +void GP_FillRect(GP_Context *context, GP_Coord x0, GP_Coord y0, + GP_Coord x1, GP_Coord y1, GP_Pixel pixel); -------------------------------------------------------------------------------- Draws a filled rectangle. + The 'GP_RectXYXY' fills an area between corner points (x0, y0) and (x1, y1), inclusive. The 'GP_RectXYWH' fills an area starting from (x0, y0) with specified width @@ -150,16 +179,18 @@ Tetragons [source,c] -------------------------------------------------------------------------------- -void GP_Tetragon(GP_Context *context, int x0, int y0, int x1, int y1, - int x2, int y2, int x3, int y3, GP_Pixel pixel); +void GP_Tetragon(GP_Context *context, GP_Coord x0, GP_Coord y0, + GP_Coord x1, GP_Coord y1, GP_Coord x2, GP_Coord y2, + GP_Coord x3, GP_Coord y3, GP_Pixel pixel); -------------------------------------------------------------------------------- Draws a tetragon. [source,c] -------------------------------------------------------------------------------- -void GP_FillTetragon(GP_Context *context, int x0, int y0, int x1, int y1, - int x2, int y2, int x3, int y3, GP_Pixel pixel); +void GP_FillTetragon(GP_Context *context, GP_Coord x0, GP_Coord y0, + GP_Coord x1, GP_Coord y1, GP_Coord x2, GP_Coord y2, + GP_Coord x3, GP_Coord y3, GP_Pixel pixel); -------------------------------------------------------------------------------- Draws a filled tetragon. diff --git a/doc/filters.txt b/doc/filters.txt index 707a6214..d741abb8 100644 --- a/doc/filters.txt +++ b/doc/filters.txt @@ -1,7 +1,7 @@ Context filters --------------- -Pixel filters for 'GP_Context'. +Pixel filters for 'GP_Context'. The context filter is basially an function that modifies context somehow (may even allocate new context to store result). Rotation ~~~~~~~~ @@ -13,8 +13,7 @@ Rotation GP_RetCode GP_MirrorH(GP_Context *context); ------------------------------------------------------------------------------- -Mirrors context pixels horizontaly and updates the context metadata (mirrors -cliping rectangle too). +Mirrors context pixels horizontaly and updates the context metadata. [source,c] ------------------------------------------------------------------------------- @@ -23,8 +22,7 @@ cliping rectangle too). GP_RetCode GP_MirrorV(GP_Context *context); ------------------------------------------------------------------------------- -Mirrors context pixels verticaly and updates the context metadata (mirrors -cliping rectangle too). +Mirrors context pixels verticaly and updates the context metadata. [source,c] ------------------------------------------------------------------------------- @@ -33,8 +31,7 @@ cliping rectangle too). GP_RetCode GP_RotateCW(GP_Context *context); ------------------------------------------------------------------------------- -Rotates context clock wise and updates the context metadata (rotates cliping -rectangle too). +Rotates context clock wise and updates the context metadata. [source,c] ------------------------------------------------------------------------------- @@ -43,6 +40,5 @@ rectangle too). GP_RetCode GP_RotateCCW(GP_Context *context); ------------------------------------------------------------------------------- -Rotates context counter clock wise and updates the context metadata (rotates -cliping rectangle too). +Rotates context counter clock wise and updates the context metadata. -- 2.11.4.GIT