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 image pixels */
  13         uint8_t  bpp;            /* pixel length in bits */
  14         uint32_t bytes_per_row;
  15         uint32_t w;              /* width in pixels */
  16         uint32_t h;              /* height in pixels */
  17         /*
  18          * Row bit offset. The offset is ignored for byte aligned pixels.
  19          * Basically it's used for non aligned pixels with combination
  20          * with subcontextes.
  21          */
  22         uint8_t offset;
  23
  24         GP_PixelType pixel_type; /* pixel format enum */
  25
  26         uint8_t axes_swap:1;         /* swap axes */
  27         uint8_t x_swap:1;            /* mirror x */
  28         uint8_t y_swap:1;            /* mirror y */
  29         uint8_t free_pixels:1;       /* if set GP_ContextFree() calls free on context->pixels */
  30 } GP_Context;
  31 -------------------------------------------------------------------------------
  32
  33 The 'GP_Context' holds meta-data needed for bitmap drawing. The bitmap is
  34 stored in one dimensional array in byte-aligned lines.
  35
  36 Rotation
  37 ^^^^^^^^
  38
  39 The orientation flags affects the gfx and text drawing functions. If some of
  40 the flags is changed the origin and direction of the drawing is changed. Note
  41 that the image pixels are not affected by this at all only the coordinates
  42 passed to drawing functions are transformed accordingly.
  43
  44 If you don't need this functionality just don't touch these flags the as
  45 overhead of these transformations is not measurable.
  46
  47 If you really need drawing primitives that do not use the orientation flags,
  48 you could use variants with _Raw suffix (altghoug this is not recommended).
  49
  50 There are various helper macros for transforming coordinates and sizes in
  51 'core/GP_Transform.h'. And helper functions to "rotate" the context flags
  52 clock wise and counter clock wise as well as functions to get the context size
  53 when taking into the accout the widht and height.
  54
  55 [source,c]
  56 -------------------------------------------------------------------------------
  57 /* Transforms point user coordinates to bitmap coordinates */
  58 GP_TRANSFORM_POINT(context, x, y)
  59
  60 /* Transforms rectangular area coordinates and size */
  61 GP_TRANSFORM_RECT(context, x, y, w, h)
  62
  63 /* Inverse transformation, bitmap coordinates to user coordinates */
  64 GP_RETRANSFORM_POINT(context, x, y)
  65 -------------------------------------------------------------------------------
  66
  67 [source,c]
  68 -------------------------------------------------------------------------------
  69 /*
  70  * Rotate context flags clock wise.
  71  */
  72 void GP_ContextFlagsRotateCW(GP_Context *context);
  73
  74 /*
  75  * Rotate context flags counter clock wise.
  76  */
  77 void GP_ContextFlagsRotateCCW(GP_Context *context);
  78
  79 /*
  80  * Returns context W and H taking the rotation flags into the account.
  81  */
  82 GP_Size GP_ContextW(const GP_Context *context);
  83 GP_Size GP_ContextH(const GP_Context *context);
  84 -------------------------------------------------------------------------------
  85
  86 Context base functions
  87 ~~~~~~~~~~~~~~~~~~~~~~
  88
  89 [source,c]
  90 -------------------------------------------------------------------------------
  91 #include <GP.h>
  92
  93 GP_Context *GP_ContextAlloc(GP_Size w, GP_Size h, GP_PixelType type);
  94
  95 GP_Context *GP_ContextCopy(const GP_Context *src, int flag);
  96
  97 void GP_ContextFree(GP_Context *context);
  98 -------------------------------------------------------------------------------
  99
 100 The 'GP_ContextAlloc()' allocates context and initalizes the context
 101 structure. The orientation flags are all set to 0 and the rest of the metadata
 102 are calculated accordingly to width, height and pixel_type.  The bitmap
 103 (context->pixels) is not initalized.
 104
 105 The 'GP_ContextCopy()' allocates and initalizes a copy of the context passed
 106 as argument. If 'flag' is not zero, the bitmap (context->pixels) is copied
 107 otherwise it's left uninitalized.
 108
 109 In both cases the resulting context should later be freed with
 110 'GP_ContextFree()'.
 111
 112 Subcontext
 113 ~~~~~~~~~~
 114
 115 Given a rectangular area inside of any context subcontext could be created.
 116 The resulting context could be used for all context operations (including
 117 subcontext creation). The only difference between allocated context and
 118 subcontext of such context is that the 'GP_ContextFree()' doesn't call
 119 'free()' on subcontext pixels (which as a matter of a fact is a pointer that
 120 points somewhere into to allocated area).
 121
 122 [source,c]
 123 -------------------------------------------------------------------------------
 124 #include <GP.h>
 125
 126 GP_Context *GP_ContextSubContext(GP_Context *context, GP_Context *subcontext,
 127                                  GP_Coord x, GP_Coord y, GP_Size w, GP_Size h);
 128 -------------------------------------------------------------------------------
 129
 130 Creates subcontext of a context. The rectangular area must fit into the context.
 131
 132 If subcontext pointer is 'NULL' the context structure is allocated otherwise
 133 the metadata are filled into the context structure pointed by subcontext
 134 pointer.
 135
 136 In both cases pointer to subcontext or NULL (in case of 'malloc(2)' failure) is
 137 returned.
 138