doc/context.txt

   1 Drawing Context
   2 ---------------
   3
   4 The 'GP_Context' structure describes an 'in memory' memory. It contains all
   5 metadata needed for drawing into a bitmap.
   6
   7 Data Structure
   8 ~~~~~~~~~~~~~~
   9
  10 [source,c]
  11 -------------------------------------------------------------------------------
  12 typedef struct GP_Context {
  13         uint8_t *pixels;         /* pointer to image pixels */
  14         uint8_t  bpp;            /* pixel length in bits */
  15         uint32_t bytes_per_row;
  16         uint32_t w;              /* width in pixels */
  17         uint32_t h;              /* height in pixels */
  18         /*
  19          * Row bit offset. The offset is ignored for byte aligned pixels.
  20          * Basically it's used for non aligned pixels with combination
  21          * with subcontextes.
  22          */
  23         uint8_t offset;
  24
  25         enum GP_PixelType pixel_type; /* pixel format */
  26
  27         uint8_t axes_swap:1;         /* swap axes */
  28         uint8_t x_swap:1;            /* mirror x */
  29         uint8_t y_swap:1;            /* mirror y */
  30         uint8_t bit_endian:1;        /* GP_BIT_ENDIAN */
  31         uint8_t free_pixels:1;       /* if set GP_ContextFree() calls free on context->pixels */
  32 } GP_Context;
  33 -------------------------------------------------------------------------------
  34
  35 The 'pixels' field points to the image data, stored as a one-dimensional
  36 array of byte-aligned lines. (There can be some unused space at the end of
  37 each line; this is reflected by the 'bytes_per_row' value being greater
  38 than what would be needed for that pixel format).
  39
  40 Rotation
  41 ^^^^^^^^
  42
  43 The orientation flags affects the gfx and text drawing functions and blits. If
  44 some of the flags is changed the origin and direction of the drawing is
  45 changed accordingly. Note that the image pixels are not affected by this at
  46 all only the coordinates passed to drawing functions are transformed.
  47
  48 If you don't need this functionality just don't touch the flags the as
  49 overhead of these transformations is not measurable.
  50
  51 If you really need drawing primitives that do not use the orientation flags,
  52 you could use variants with _Raw suffix (although this is not recommended).
  53
  54 There are various helper macros for transforming coordinates and sizes in
  55 'core/GP_Transform.h'. And context helper functions to "rotate" the flags
  56 clock wise and counter clock wise as well as functions to get the context size
  57 when taking into the account the width and height.
  58
  59 [source,c]
  60 -------------------------------------------------------------------------------
  61 #include <core/GP_Transform.h>
  62 /* or */
  63 #include <GP.h>
  64
  65 /* Transforms point user coordinates to bitmap coordinates */
  66 GP_TRANSFORM_POINT(context, x, y)
  67
  68 /* Transforms rectangular area coordinates and size */
  69 GP_TRANSFORM_RECT(context, x, y, w, h)
  70
  71 /* Inverse transformation, bitmap coordinates to user coordinates */
  72 GP_RETRANSFORM_POINT(context, x, y)
  73 -------------------------------------------------------------------------------
  74
  75 [source,c]
  76 ------------------------------------------------------------------------------
  77 #include <core/GP_Context.h>
  78 /* or */
  79 #include <GP.h>
  80
  81 /*
  82  * Rotate context flags clock wise.
  83  */
  84 void GP_ContextRotateCW(GP_Context *context);
  85
  86 /*
  87  * Rotate context flags counter clock wise.
  88  */
  89 void GP_ContextRotateCCW(GP_Context *context);
  90
  91 /*
  92  * Retruns 1 if rotation flags are equal.
  93  */
  94 int GP_ContextRotationEqual(const GP_Context *c1, const GP_Context *c2);
  95
  96 /*
  97  * Sets context rotation flags.
  98  */
  99 void GP_ContextSetRotation(GP_Context *dst, int axes_swap,
 100                            int x_swap, int y_swap);
 101
 102 /*
 103  * Copies rotation flags.
 104  */
 105 void GP_ContextCopyRotation(const GP_Context *src, GP_Context *dst);
 106
 107 /*
 108  * Returns context width and height taking the rotation flags into the account.
 109  */
 110 GP_Size GP_ContextW(const GP_Context *context);
 111 GP_Size GP_ContextH(const GP_Context *context);
 112 -------------------------------------------------------------------------------
 113
 114 Basic context functions
 115 ~~~~~~~~~~~~~~~~~~~~~~~
 116
 117 [source,c]
 118 -------------------------------------------------------------------------------
 119 #include <core/GP_Context.h>
 120 /* or */
 121 #include <GP.h>
 122
 123 GP_Context *GP_ContextInit(GP_Context *context, GP_Size w, GP_Size h,
 124                            GP_PixelType type, void *pixels);
 125 -------------------------------------------------------------------------------
 126
 127 Initialize given context accordingly to parameters, the rest of context
 128 parameters are set to the default values (i.e. rotation flags are all set to
 129 zero, 'free_pixels' flag is not set). Number of bits per pixel and
 130 bytes per row are computed from the given pixel type and size.
 131
 132 The 'pixels' pointer can be 'NULL' and can be changed later manually (the call
 133 will *not* try to allocate the pixel memory automatically).
 134
 135 The function returns a pointer to the initialized context (i.e. the same
 136 pointer you passed as second argument).
 137
 138 [source,c]
 139 -------------------------------------------------------------------------------
 140 #include <core/GP_Context.h>
 141 /* or */
 142 #include <GP.h>
 143
 144 GP_Context *GP_ContextAlloc(GP_Size w, GP_Size h, GP_PixelType type);
 145 -------------------------------------------------------------------------------
 146
 147 The 'GP_ContextAlloc()' allocates and initializes a context.
 148
 149 The orientation flags are all set to zero, the 'free_pixels' flag is set and the
 150 rest of the metadata are calculated accordingly to width, height and
 151 pixel_type.The 'pixels' pointer will point to a newly allocated bitmap with
 152 appropriate size; the initial contents of the bitmap are undefined.
 153
 154 [source,c]
 155 -------------------------------------------------------------------------------
 156 #include <core/GP_Context.h>
 157 /* or */
 158 #include <GP.h>
 159
 160 enum GP_ContextCopyFlags {
 161         /*
 162          * Copy bitmap pixels too. If not set pixels are uninitialized.
 163          */
 164         GP_COPY_WITH_PIXELS   = 0x01,
 165         /*
 166          * Copy image rotation flags. If not set flags are set to (0, 0, 0).
 167          */
 168         GP_COPY_WITH_ROTATION = 0x02,
 169 };
 170
 171 GP_Context *GP_ContextCopy(const GP_Context *src, int flags);
 172 -------------------------------------------------------------------------------
 173
 174 The 'GP_ContextCopy()' allocates and initializes a copy of the context passed
 175 as arguments.
 176
 177 The call returns pointer to newly allocated context or in case of 'malloc()'
 178 failure NULL.
 179
 180 If 'GP_COPY_WITH_PIXELS' is set, the bitmap contents ('src->pixels') are also
 181 copied; otherwise the copy will have the same dimensions but undefined
 182 contents.
 183
 184 If 'GP_COPY_WITH_ROTATION' is set rotation flags are copied; otherwise rotation
 185 flags are set to zero.
 186
 187 The 'free_pixels' flag for the resulting context is set.
 188
 189 [source,c]
 190 -------------------------------------------------------------------------------
 191 #include <core/GP_Context.h>
 192 /* or */
 193 #include <GP.h>
 194
 195 void GP_ContextFree(GP_Context *context);
 196 -------------------------------------------------------------------------------
 197
 198 Frees the context memory. If 'free_pixels' flag is set, the pixels buffer is
 199 freed too.
 200
 201 Subcontext
 202 ~~~~~~~~~~
 203
 204 A subcontext is a context that refers to a rectangular area within another
 205 context. Subcontexts can be used as any other context (including creating
 206 another subcontexts). Generally the subcontexts behave exactly as any other
 207 contexts with one exception, if you create several overlapping subcontexts the
 208 results may be unexpected.
 209
 210 Calling 'GP_ContextFree()' on a allocated subcontext is safe; the bitmap is not
 211 freed as it belongs to another context; it will be freed with the hosting
 212 context (i.e. the 'free_pixels' flag is not set when creating subcontext). On
 213 the other hand, the subcontext doesn't hold a reference to the original
 214 context, so once the parent context is freed the subcontext pixel pointer is
 215 not valid anymore.
 216
 217 [source,c]
 218 -------------------------------------------------------------------------------
 219 #include <core/GP_Context.h>
 220 /* or */
 221 #include <GP.h>
 222
 223 GP_Context *GP_SubContext(const GP_Context *context, GP_Context *subcontext,
 224                           GP_Coord x, GP_Coord y, GP_Size w, GP_Size h);
 225
 226 GP_Context *GP_SubContextAlloc(const GP_Context *context,
 227                                GP_Coord x, GP_Coord y, GP_Size w, GP_Size h);
 228 -------------------------------------------------------------------------------
 229
 230 Creates subcontext of a context. The rectangular area must fit into the context.
 231
 232 The 'GP_SubContext()' function initializes the passed pointer as a subcontext
 233 of a context and returns pointer to initialized subcontext (i.e. the same
 234 pointer you passed as the subcontext parameter).
 235
 236 The 'GP_SubContextAlloc()' function allocates 'GP_Context' structure and
 237 initializes it as a subcontext. This function may return NULL in case of
 238 'malloc()' failure and the newly created context should be later freed with
 239 'GP_ContextFree()'.
 240
 241 Conversions
 242 ~~~~~~~~~~~
 243
 244 [source,c]
 245 -------------------------------------------------------------------------------
 246 #include <core/GP_Context.h>
 247 /* or */
 248 #include <GP.h>
 249
 250 GP_Context *GP_ContextConvertAlloc(const GP_Context *src,
 251                                    GP_PixelType dst_pixel_type);
 252
 253 GP_Context *GP_ContextConvert(const GP_Context *src, GP_Context *dst);
 254
 255 -------------------------------------------------------------------------------
 256
 257 Converts a context to different pixel type.
 258
 259 This is naive implementation that only multiplies/divides the pixel values.
 260
 261 To get a better result use dithering filters instead.
 262
 263 Misc
 264 ~~~~
 265
 266 [source,c]
 267 -------------------------------------------------------------------------------
 268 #include <core/GP_Context.h>
 269 /* or */
 270 #include <GP.h>
 271
 272 void GP_ContextPrintInfo(const GP_Context *self);
 273 -------------------------------------------------------------------------------
 274
 275 This function prints the content of 'GP_Context' structure, in a readable
 276 format, into the stdout.