doc/basic_types.txt

   1 Basic types
   2 -----------
   3 Coordinates and Size/Length
   4 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
   5
   6 Most of the drawing functions use typedefed 'GP_Coord' and 'GP_Size' integer
   7 types for parameters.
   8
   9 The 'GP_Coord' is signed integer which is used for coordinates and the
  10 'GP_Size' is unsigned integer type used for object size, length and so.
  11
  12 Pixel
  13 ~~~~~
  14
  15 Pixel value in 'GFXprim' is an integer big enough to hold the actual pixel
  16 values. The default typedef for 'GP_Pixel' is set to 32 bit integer, which may
  17 be changed at compile time to support colors with more than 10 bits per
  18 channel. The 'GP_Pixel' is thus used as opaque value big enough to hold any
  19 supported pixel value.
  20
  21 Color
  22 ~~~~~
  23
  24 The 'GP_Color' enumeration holds symbolic constants for basic colors.
  25
  26 A 'GP_Color' can be converted into a 'GP_Pixel' for a given 'GP_PixelType'.
  27 Symbolic values can also be converted to/from strings (color name in English).
  28
  29 The 'GP_Color' enum is defined as follows:
  30
  31 [source,c]
  32 --------------------------------------------------------------------------------
  33 typedef enum GP_Color {
  34         GP_COL_INVALID = -1,
  35
  36         /* full-intensity RGB and CMYK */
  37         GP_COL_BLACK,
  38         GP_COL_RED,
  39         GP_COL_GREEN,
  40         GP_COL_BLUE,
  41         GP_COL_YELLOW,
  42         GP_COL_CYAN,
  43         GP_COL_MAGENTA,
  44
  45         /* various common mixes */
  46         GP_COL_BROWN,
  47         GP_COL_ORANGE,
  48         GP_COL_GRAY_DARK,       /* exactly half RGB values of white */
  49         GP_COL_GRAY_LIGHT,
  50         GP_COL_PURPLE,
  51
  52         GP_COL_WHITE,           /* full-intensity white */
  53         GP_COL_MAX,
  54 } GP_Color;
  55 --------------------------------------------------------------------------------
  56
  57 [source,c]
  58 --------------------------------------------------------------------------------
  59 #include <core/GP_Color.h>
  60 /* or */
  61 #include <GP.h>
  62
  63 GP_Pixel GP_ColorToPixel(GP_Color color, GP_PixelType pixel_type);
  64 GP_Pixel GP_ColorToContextPixel(GP_Color color, GP_Context *context);
  65
  66 GP_Color GP_ColorNameToColor(const char *color_name);
  67 const char *GP_ColorToColorName(GP_Color color);
  68
  69 bool GP_ColorNameToPixel(const char *color_name, GP_PixelType pixel_type,
  70                          GP_Pixel *pixel);
  71 bool GP_ColorNameToContextPixel(const char *color_name, GP_Context *context,
  72                                 GP_Pixel *pixel);
  73 --------------------------------------------------------------------------------
  74
  75 Functions for conversion between colors, pixels and color names. The last two
  76 returns true if color with such name was found.
  77
  78 [source,c]
  79 --------------------------------------------------------------------------------
  80 #include <core/GP_Color.h>
  81 /* or */
  82 #include <GP.h>
  83
  84 void GP_ColorLoadPixels(GP_Pixel pixels[], GP_PixelType pixel_type);
  85 void GP_ColorLoadContextPixels(GP_Pixel pixels[], GP_Context *context);
  86 --------------------------------------------------------------------------------
  87
  88 Loads array of 'GP_Pixel' of size 'GP_COL_MAX', the array is then used with
  89 the GP_Color enum as 'pixels[GP_COL_BLACK]'.
  90
  91 Progress Callback
  92 ~~~~~~~~~~~~~~~~~
  93
  94 The 'GP_ProgressCallback' is a structure that stores user-defined callback
  95 function and user-defined pointer and percentage.
  96
  97 It is passed as last parameter to functions that would take some time to
  98 complete and adds capability to track the operation progress as well as to
  99 abort the operation.
 100
 101 Currently it's used for filters and loaders.
 102
 103 [source,c]
 104 -------------------------------------------------------------------------------
 105 typdedef struct GP_ProgressCallback {
 106         float percentage;
 107         int (*callback)(struct GP_ProgressCallback *self);
 108         void *priv;
 109 } GP_ProgressCallback;
 110 -------------------------------------------------------------------------------
 111
 112 If non 'NULL' progress callback structure is passed to a function, the
 113 callback function is periodically called and the percentage is updated.
 114
 115 The return value from callback could abort the function execution. If non zero
 116 value is returned operation is aborted, all memory freed etc. and in case of
 117 bitmap loaders 'errno' is set to 'ECANCELED'.
 118
 119 The callback, if supported, is the last parameter of a function.
 120