doc/pixmap.txt

   1 Drawing Pixmap
   2 ---------------
   3
   4 The 'GP_Pixmap' 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_Pixmap {
  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 subpixmapes.
  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_PixmapFree() calls free on pixmap->pixels */
  37 } GP_Pixmap;
  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_Pixmap,subpixmaps>> 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_Pixmap, subpixmaps>>.
  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 pixmap helper functions to "rotate" the flags
  80 clock wise and counter clock wise as well as functions to get the pixmap 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(pixmap, x, y)
  91
  92 /* Transforms rectangular area coordinates and size */
  93 GP_TRANSFORM_RECT(pixmap, x, y, w, h)
  94
  95 /* Inverse transformation, bitmap coordinates to user coordinates */
  96 GP_RETRANSFORM_POINT(pixmap, x, y)
  97 -------------------------------------------------------------------------------
  98
  99 [source,c]
 100 ------------------------------------------------------------------------------
 101 #include <core/GP_Pixmap.h>
 102 /* or */
 103 #include <GP.h>
 104
 105 /*
 106  * Rotate pixmap flags clock wise.
 107  */
 108 void GP_PixmapRotateCW(GP_Pixmap *pixmap);
 109
 110 /*
 111  * Rotate pixmap flags counter clock wise.
 112  */
 113 void GP_PixmapRotateCCW(GP_Pixmap *pixmap);
 114
 115 /*
 116  * Retruns 1 if rotation flags are equal.
 117  */
 118 int GP_PixmapRotationEqual(const GP_Pixmap *c1, const GP_Pixmap *c2);
 119
 120 /*
 121  * Sets pixmap rotation flags.
 122  */
 123 void GP_PixmapSetRotation(GP_Pixmap *dst, int axes_swap,
 124                            int x_swap, int y_swap);
 125
 126 /*
 127  * Copies rotation flags.
 128  */
 129 void GP_PixmapCopyRotation(const GP_Pixmap *src, GP_Pixmap *dst);
 130
 131 /*
 132  * Returns pixmap width and height taking the rotation flags into the account.
 133  */
 134 GP_Size GP_PixmapW(const GP_Pixmap *pixmap);
 135 GP_Size GP_PixmapH(const GP_Pixmap *pixmap);
 136 -------------------------------------------------------------------------------
 137
 138 Basic pixmap functions
 139 ~~~~~~~~~~~~~~~~~~~~~~~
 140
 141 [source,c]
 142 -------------------------------------------------------------------------------
 143 #include <core/GP_Pixmap.h>
 144 /* or */
 145 #include <GP.h>
 146
 147 GP_Pixmap *GP_PixmapInit(GP_Pixmap *pixmap, GP_Size w, GP_Size h,
 148                            GP_PixelType type, void *pixels);
 149 -------------------------------------------------------------------------------
 150
 151 Initialize given pixmap accordingly to parameters, the rest of pixmap
 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 pixmap (i.e. the same
 160 pointer you passed as second argument).
 161
 162 [source,c]
 163 -------------------------------------------------------------------------------
 164 #include <core/GP_Pixmap.h>
 165 /* or */
 166 #include <GP.h>
 167
 168 GP_Pixmap *GP_PixmapAlloc(GP_Size w, GP_Size h, GP_PixelType type);
 169 -------------------------------------------------------------------------------
 170
 171 The 'GP_PixmapAlloc()' allocates and initializes a pixmap.
 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_Pixmap.h>
 181 /* or */
 182 #include <GP.h>
 183
 184 enum GP_PixmapCopyFlags {
 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_Pixmap *GP_PixmapCopy(const GP_Pixmap *src, int flags);
 196 -------------------------------------------------------------------------------
 197
 198 The 'GP_PixmapCopy()' allocates and initializes a copy of the pixmap passed
 199 as arguments.
 200
 201 The call returns pointer to newly allocated pixmap 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 pixmap is set.
 212
 213 [[PixmapFree]]
 214 [source,c]
 215 -------------------------------------------------------------------------------
 216 #include <core/GP_Pixmap.h>
 217 /* or */
 218 #include <GP.h>
 219
 220 void GP_PixmapFree(GP_Pixmap *pixmap);
 221 -------------------------------------------------------------------------------
 222
 223 Frees the pixmap 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_Pixmap]]
 230 Subpixmap
 231 ~~~~~~~~~~
 232
 233 A subpixmap is a pixmap that refers to a rectangular area within another
 234 pixmap. Subpixmaps can be used as any other pixmaps (including subpixmap
 235 creation).
 236
 237 WARNING: If you create overlaping subpixmaps the result is undefined.
 238
 239 Calling 'GP_PixmapFree()' on a allocated subpixmap is safe; the bitmap is
 240 not freed as it belongs to another pixmap; it will be freed when the parent
 241 pixmap is freed (i.e. the 'free_pixels' flag is not set when creating
 242 subpixmap).
 243
 244 CAUTION: The subpixmap doesn't hold a reference to the original pixmap, so
 245          once the parent pixmap is freed the subpixmap pixels pointer is not
 246          valid anymore.
 247
 248 [source,c]
 249 -------------------------------------------------------------------------------
 250 #include <core/GP_Pixmap.h>
 251 /* or */
 252 #include <GP.h>
 253
 254 GP_Pixmap *GP_SubPixmap(const GP_Pixmap *pixmap, GP_Pixmap *subpixmap,
 255                           GP_Coord x, GP_Coord y, GP_Size w, GP_Size h);
 256
 257 GP_Pixmap *GP_SubPixmapAlloc(const GP_Pixmap *pixmap,
 258                                GP_Coord x, GP_Coord y, GP_Size w, GP_Size h);
 259 -------------------------------------------------------------------------------
 260
 261 Creates subpixmap of a pixmap. The rectangular area must fit into the parent
 262 pixmap.
 263
 264 The 'GP_SubPixmap()' function initializes the passed pointer as a subpixmap
 265 of a pixmap and returns pointer to the initialized subpixmap (i.e. the same
 266 pointer you passed as the subpixmap parameter).
 267
 268 The 'GP_SubPixmapAlloc()' function allocates 'GP_Pixmap' structure and
 269 initializes it as a subpixmap. This function may return NULL in case of
 270 'malloc()' failure and the newly created pixmap should be later freed with
 271 'GP_PixmapFree()'.
 272
 273 Conversions
 274 ~~~~~~~~~~~
 275
 276 [source,c]
 277 -------------------------------------------------------------------------------
 278 #include <core/GP_Pixmap.h>
 279 /* or */
 280 #include <GP.h>
 281
 282 GP_Pixmap *GP_PixmapConvertAlloc(const GP_Pixmap *src,
 283                                    GP_PixelType dst_pixel_type);
 284
 285 GP_Pixmap *GP_PixmapConvert(const GP_Pixmap *src, GP_Pixmap *dst);
 286
 287 -------------------------------------------------------------------------------
 288
 289 Converts a pixmap 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_Pixmap.h>
 301 /* or */
 302 #include <GP.h>
 303
 304 void GP_PixmapPrintInfo(const GP_Pixmap *self);
 305 -------------------------------------------------------------------------------
 306
 307 This function prints the content of a 'GP_Pixmap' structure, in a readable
 308 format, into the stdout.
 309