lib/Imager/interface.pod

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