lib/Imager/interface.pod

   1 =head1 NAME
   2
   3 Imager::interface.pod - decribes the C level virtual image interface
   4
   5 =head1 SYNOPSIS
   6
   7
   8 =head1 DESCRIPTION
   9
  10 The Imager virtual interface aims to allow image types to be created
  11 for special purposes, both to allow consistent access to images with
  12 different sample sizes, and organizations, but also to allow creation
  13 of synthesized or virtual images.
  14
  15 This is a C level interface rather than Perl.
  16
  17 =head2 Existing Images
  18
  19 As of this writing we have the following concrete image types:
  20
  21 =over
  22
  23 =item *
  24
  25 8-bit/sample direct images
  26
  27 =item *
  28
  29 16-bit/sample direct images
  30
  31 =item *
  32
  33 double/sample direct images
  34
  35 =item *
  36
  37 8-bit/sample 8-bit/index paletted images
  38
  39 =back
  40
  41 Currently there is only one virtual image type:
  42
  43 =over
  44
  45 =item *
  46
  47 masked images, where a mask image can control write access to an
  48 underlying image.
  49
  50 =back
  51
  52 Other possible concrete images include:
  53
  54 =over
  55
  56 =item *
  57
  58 "bitmaps", 1 bit/sample images (perhaps limited to a single channel)
  59
  60 =item *
  61
  62 16-bit/index paletted images
  63
  64 =back
  65
  66 Some other possible virtual images:
  67
  68 =over
  69
  70 =item *
  71
  72 image alpha combining, where the combining function can be specified
  73 (see the layer modes in graphical editors like the GIMP or photoshop.
  74
  75 =back
  76
  77 =head1 THE INTERFACE
  78
  79 Each image type needs to define a number of functions which implement
  80 the image operations.
  81
  82 The image structure includes information describes the image, which
  83 can be used to determine the structure of the image:
  84
  85 =over
  86
  87 =item channels
  88
  89 the number of samples kept for each pixel in the image.  For paletted
  90 images the samples are kept for each entry in the palette.
  91
  92 =item xsize, ysize
  93
  94 the dimensions of the image in pixels.
  95
  96 =item bytes
  97
  98 the number of bytes of data kept for the image.  Zero for virtual
  99 images.  Does not include the space required for the palette for
 100 paletted images.
 101
 102 =item ch_mask
 103
 104 controls which samples will be written to for direct images.
 105
 106 =item bits
 107
 108 the number of bits kept for each sample.  There are enum values
 109 i_8_bits, i_16_bits and i_double_bits (64).
 110
 111 =item type
 112
 113 the type of image, either i_direct_type or i_palette_type.  Direct
 114 images keep the samples for every pixel image, while i_palette_type
 115 images keep an index into a color table for each pixel.
 116
 117 =item virtual
 118
 119 whether the image keeps any pixel data.  If this is non-zero then
 120 idata points to image data, otherwise it points to implementation
 121 defined data, though ext_data is more likely to be used for that.
 122
 123 =item idata
 124
 125 image data.  If the image is 8-bit direct, non-virtual, then this
 126 consists of each sample of the image stored one after another,
 127 otherwise it is implementation defined.
 128
 129 =item tags
 130
 131 will be used to store meta-data for an image, eg. tags from a TIFF
 132 file, or animation information from a GIF file.  This should be
 133 initialized with a call to i_tags_new() in your image constructor if
 134 creating a new image type.
 135
 136 =item ext_data
 137
 138 for internal use of image types.  This is not released by the standard
 139 i_img_exorcise() function.  If you create a new image type and want to
 140 store a pointer to allocated memory here you should point i_f_destroy
 141 at a function that will release the data.
 142
 143 =back
 144
 145 If a caller has no knowledge of the internal format of an image, the
 146 caller must call the appropriate image function pointer.  Imager
 147 provides macros that wrap these functions, so it isn't necessary to
 148 call them directly.
 149
 150 Many functions have a similar function with an 'f' suffix, these take
 151 or return samples specified with floating point values rather than
 152 8-bit integers (unsigned char).  Floating point samples are returned
 153 in the range 0 to 1 inclusive.
 154
 155 =over
 156
 157 =item i_f_ppix(im, x, y, color)
 158
 159 =item i_f_ppixf(im, x, y, fcolor)
 160
 161 stores the specified color at pixel (x,y) in the image.  If the pixel
 162 can be stored return 0, otherwise -1.  An image type may choose to
 163 return 0 under some circumstances, eg. writing to a masked area of an
 164 image.  The color or fcolor always contains the actual samples to be
 165 written, rather than a palette index.
 166
 167 =item i_f_plin(im, l, r, y, colors)
 168
 169 =item i_f_plinf(im, l, r, y, fcolors)
 170
 171 stores (r-l) pixels at positions (l,y) ... (r-1, y) from the array
 172 specified by colors (or fcolors).  Returns the number of pixels
 173 written to.  If l is negative it will return 0.  If r > im->xsize then
 174 only (im->xsize - l) will be written.
 175
 176 =item i_f_gpix(im, x, y, color)
 177
 178 =item i_f_gpixf(im, x, y, fcolor)
 179
 180 retrieves a single pixel from position (x,y).  This returns the
 181 samples rather than the index for paletted images.
 182
 183 =item i_f_glin(im, l, r, y, colors)
 184
 185 =item i_f_glinf(im, l, r, y, fcolors)
 186
 187 retrieves (r-l) pixels from positions (l, y) through (r-1, y) into the
 188 array specified by colors.  Returns the number of pixels retrieved.
 189 If l < 0 no pixels are retrieved.  If r > im->xsize then pixels (l, y)
 190 ... (im->xsize-1, y) are retrieved.  Retrieves the samples rather than
 191 the color indexes for paletted images.
 192
 193 =item i_f_gsamp(im, l, r, y, samples, chans, chan_count)
 194
 195 =item i_f_gsampf(im, l, r, y, fsamples, chans, chan_count)
 196
 197 Retrieves samples from channels specified by chans (for length
 198 chan_count) from pixels at positions (l,y) ... (r-1, y).  If chans is
 199 NULL then samples from channels 0 ... chan_count-1 will be retrieved.
 200 Returns the number of sample retrieved (_not_ the number of channels).
 201 If a channel in chans is not present in the image or l < 0, returns 0.
 202 If r > im->xsize, then the samples from (l,y) ... (im->xsize-1, y) are
 203 returned.
 204
 205 =back
 206
 207 The following are for images where type == i_palette_type only.
 208
 209 =over
 210
 211 =item i_f_gpal(im, l, r, y, vals)
 212
 213 Retrieves color indexes from the image for pixels (l, y) ... (r-1, y)
 214 into vals.  Returns the number of indexes retrieved.
 215
 216 =item i_f_ppal(im, l, r, y, vals)
 217
 218 Stores color indexes into the image for pixels (l, y) ... (r-1, y)
 219 from vals.  Returns the number of indexes retrieved.  If indices are
 220 outside the range of the images palette, then you may have problems
 221 reading those pixels with i_gpix() or i_glin().
 222
 223 =item i_f_addcolors(im, colors, count)
 224
 225 Adds the count colors to the image's palette.  Returns the index of
 226 the first color added, or -1 if there is not enough space for count
 227 colors.
 228
 229 =item i_f_getcolors(im, index, colors, count)
 230
 231 Retrieves count colors from the image's palette starting from entry
 232 index in the palette.  Returns non-zero on success.
 233
 234 =item i_f_colorcount(im)
 235
 236 Returns the number of colors in the image's palette.  Returns -1 if
 237 this is not a paletted image.
 238
 239 =item i_f_maxcolors(im)
 240
 241 Returns the maximum number of colors that can fit in the image's
 242 palette.  Returns -1 if this is not a paletted image.
 243
 244 =item i_f_findcolor(im, color, entry)
 245
 246 Searches the image's palette for the specified color, setting *entry
 247 to the index and returning non-zero.  Returns zero if the color is not
 248 found.
 249
 250 =item i_f_setcolors_t(im, index, colors, count)
 251
 252 Sets count colors starting from index in the image from the array
 253 colors.  The colors to be set must already have entries in the image's
 254 palette.  Returns non-zero on success.
 255
 256 =back
 257
 258 Finally, the i_f_destroy function pointer can be set which is called
 259 when the image is destroyed.  This can be used to release memory
 260 pointed to by ext_data or release any other resources.
 261
 262 When writing to a paletted image with i_ppix() or i_plin() and the
 263 color you are writing doesn't exist in the image, then it's possible
 264 that the image will be internally converted to a direct image with the
 265 same number of channels.
 266
 267 =head1 TOOLS
 268
 269 Several functions have been written to simplify creating new image types.
 270
 271 These tools are available by including imagei.h.
 272
 273 =head2 Floating point wrappers
 274
 275 These functions implement the floating point sample versions of each
 276 interface function in terms of the integer sample version.
 277
 278 These are:
 279
 280 =over
 281
 282 =item i_ppixf_fp
 283
 284 =item i_gpixf_fp
 285
 286 =item i_plinf_fp
 287
 288 =item i_glinf_fp
 289
 290 =item i_gsampf_fp
 291
 292 =back
 293
 294
 295 =head2 Forwarding functions
 296
 297 These functions are used in virtual images where the call should
 298 simply be forwarded to the underlying image.  The underlying image is
 299 assumed to be the first pointer in a structure pointed at by ext_data.
 300
 301 If this is not the case then these functions will just crash :)
 302
 303 =over
 304
 305 =item i_addcolors_forward
 306
 307 =item i_getcolors_forward
 308
 309 =item i_colorcount_forward
 310
 311 =item i_maxcolors_forward
 312
 313 =item i_findcolor_forward
 314
 315 =item i_setcolors_forward
 316
 317 =back
 318
 319 =head2 Sample macros
 320
 321 Imagei.h defines several macros for converting samples between
 322 different sizes.
 323
 324 Each macro is of the form SampleI<size>ToI<size> where I<size> is one
 325 of 8, 16, or F (for floating-point samples).
 326
 327 =over
 328
 329 =item SampleFTo16(sample)
 330
 331 =item Sample16ToF(sample)
 332
 333 =item SampleFTo8(sample)
 334
 335 =item Sample8ToF(sample)
 336
 337 =item Sample16To8(num)
 338
 339 =item Sample8To16(num)
 340
 341 =back
 342
 343 =cut