lib/Imager/interface.pod

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