doc/context.txt

   1 Drawing Context
   2 ---------------
   3
   4 GP_Context is data structure for storing 'in memory' bitmaps.
   5
   6 Data Structure
   7 ~~~~~~~~~~~~~~
   8
   9 [source,c]
  10 -------------------------------------------------------------------------------
  11 typedef struct GP_Context {
  12         uint8_t *pixels;         /* Pointer to array of pixels              */
  13         uint8_t  bpp;            /* Bits per pixel, always be power of two  */
  14         uint32_t bytes_per_row;  /* Bytes per row, rows are padded to bytes */
  15         uint32_t w;              /* Width in pixels                         */
  16         uint32_t h;              /* Height in pixels                        */
  17
  18         GP_PixelType pixel_type; /* Enum, bitmap pixel type id              */
  19
  20         int axes_swap:1;         /* Context rotation and mirroring          */
  21         int x_swap:1;
  22         int y_swap:1;
  23
  24         uint32_t clip_w_min;     /* Clipping rectanle                       */
  25         uint32_t clip_w_max;
  26         uint32_t clip_h_min;
  27         uint32_t clip_h_max;
  28 } GP_Context;
  29 -------------------------------------------------------------------------------
  30
  31 The 'GP_Context' holds metadata needed for bitmaps. The values of pixels
  32 are stored as bitmap lines (aligned to bytes) in one dimensional array.
  33 The addres of pixel could be determined by GP_PIXEL_ADDRESS(context, x, y)
  34 which returns byte aligned addres for the pixel.
  35
  36 Rotation
  37 ^^^^^^^^
  38
  39 Rotation and mirroring is honored only by functions starting with extra T.
  40 So GP_TLine() is equal to GP_Line(), when all axes_sawp, x_swap and y_swap are
  41 set to zero.
  42
  43 There are various macros for transforming coordinates and sizes in
  44 'core/GP_Transform.h'.
  45
  46 * *GP_TRANSFORM_POINT(x, y)*
  47 * *GP_TRANSFORM_RECT(x, y, w, h)*
  48 * *GP_RETRANSFORM_POINT(x, y)*
  49
  50 Clipping rectangle
  51 ^^^^^^^^^^^^^^^^^^
  52
  53 All drawing functions honor the clipping rectangle, eg. no pixels are put,
  54 even when the coordinates are inside the bitmap, if they are outside of
  55 clipping rectangle.
  56
  57 Functions
  58 ~~~~~~~~~
  59
  60 [source,c]
  61 -------------------------------------------------------------------------------
  62 #include <GP.h>
  63
  64 uint32_t GP_ContextW(struct GP_Context *context);
  65 uint32_t GP_ContextH(struct GP_Context *context);
  66 uint32_t GP_TContextW(struct GP_Context *context);
  67 uint32_t GP_TContextH(struct GP_Context *context);
  68 -------------------------------------------------------------------------------
  69
  70 Functions to get context width and height. Functions with 'T' prefix do honour
  71 rotation flags (swaps W and H if axes_swap is set).
  72
  73 [source,c]
  74 -------------------------------------------------------------------------------
  75 #include <GP.h>
  76
  77 void GP_ContextFlagsRotateCW(struct GP_Context *context);
  78 void GP_ContextFlagsRotateCCW(struct GP_Context *context);
  79 -------------------------------------------------------------------------------
  80
  81 Rotate context flags (x_swap, y_swap and axes_swap) clock wise, respectively
  82 counter clock wise.
  83
  84 [source,c]
  85 -------------------------------------------------------------------------------
  86 #include <GP.h>
  87
  88 GP_Context *GP_ContextAlloc(uint32_t w, uint32_t h, GP_PixelType type);
  89 -------------------------------------------------------------------------------
  90
  91 Allocates and initalizes the 'GP_Context' structure. The size for pixels is
  92 computed from width, height and pixel type. Moreover the rotation flags are
  93 set to zero and clipping rectangle is set to whole bitmap.
  94
  95 The newly allocated context should be later freed with 'GP_ContextFree()'.
  96
  97 [source,c]
  98 -------------------------------------------------------------------------------
  99 #include <GP.h>
 100
 101 void GP_ContextFree(GP_Context *context);
 102 -------------------------------------------------------------------------------
 103
 104 Free the context allocated memory.
 105
 106 [source,c]
 107 -------------------------------------------------------------------------------
 108 #include <GP.h>
 109
 110 GP_Context *GP_ContextCopy(GP_Context *context, int flag);
 111 -------------------------------------------------------------------------------
 112
 113 Copy a context. Allocates and initalizes a 'GP_Context'. If flag is set to
 114 GP_CONTEXT_WITH_PIXELS, the actuall bitmap is copied from contex to newly
 115 allocated context, otherwise only context metadata are copied.
 116
 117 The newly created context should be later freed with 'GP_ContextFree()'.
 118