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