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 } GP_Context;
  24 -------------------------------------------------------------------------------
  25
  26 The 'GP_Context' holds meta-data needed for bitmaps. The values of pixels
  27 are stored as bitmap lines (aligned to bytes) in one dimensional array.
  28 The address of pixel could be determined by GP_PIXEL_ADDRESS(context, x, y)
  29 which returns byte aligned address for the pixel.
  30
  31 Rotation
  32 ^^^^^^^^
  33 All gfx functions does honor rotation and mirroring. If you really need drawing
  34 primitives without it use variants with _Raw suffix.
  35
  36 So GP_Line() is equal to GP_Line_Raw(), when all axes_swap, x_swap and y_swap
  37 are set to zero.
  38
  39 There are various macros for transforming coordinates and sizes in
  40 'core/GP_Transform.h'.
  41
  42 * *GP_TRANSFORM_POINT(x, y)*
  43 * *GP_TRANSFORM_RECT(x, y, w, h)*
  44 * *GP_RETRANSFORM_POINT(x, y)*
  45
  46 Functions
  47 ~~~~~~~~~
  48
  49 [source,c]
  50 -------------------------------------------------------------------------------
  51 #include <GP.h>
  52
  53 uint32_t GP_ContextW(struct GP_Context *context);
  54 uint32_t GP_ContextH(struct GP_Context *context);
  55 -------------------------------------------------------------------------------
  56
  57 Functions to get context width and height that do honor rotation flags (swaps
  58 W and H if axes_swap is set).
  59
  60 [source,c]
  61 -------------------------------------------------------------------------------
  62 #include <GP.h>
  63
  64 void GP_ContextFlagsRotateCW(struct GP_Context *context);
  65 void GP_ContextFlagsRotateCCW(struct GP_Context *context);
  66 -------------------------------------------------------------------------------
  67
  68 Rotate context flags (x_swap, y_swap and axes_swap) clock wise, respectively
  69 counter clock wise.
  70
  71 [source,c]
  72 -------------------------------------------------------------------------------
  73 #include <GP.h>
  74
  75 GP_Context *GP_ContextAlloc(uint32_t w, uint32_t h, GP_PixelType type);
  76 -------------------------------------------------------------------------------
  77
  78 Allocates and initializes the 'GP_Context' structure. The size for pixels is
  79 computed from width, height and pixel type. Moreover the rotation flags are
  80 set to zero and clipping rectangle is set to whole bitmap.
  81
  82 The newly allocated context should be later freed with 'GP_ContextFree()'.
  83
  84 [source,c]
  85 -------------------------------------------------------------------------------
  86 #include <GP.h>
  87
  88 void GP_ContextFree(GP_Context *context);
  89 -------------------------------------------------------------------------------
  90
  91 Free the context allocated memory.
  92
  93 [source,c]
  94 -------------------------------------------------------------------------------
  95 #include <GP.h>
  96
  97 GP_Context *GP_ContextCopy(GP_Context *context, int flag);
  98 -------------------------------------------------------------------------------
  99
 100 Copy a context. Allocates and initializes a 'GP_Context'. If flag is set to
 101 GP_CONTEXT_WITH_PIXELS, the actual bitmap is copied from context to newly
 102 allocated context, otherwise only context meta-data are copied.
 103
 104 The newly created context should be later freed with 'GP_ContextFree()'.
 105