doc/context.txt

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