1Imager::interface(3) User Contributed Perl Documentation Imager::interface(3)
2
6 Imager::interface.pod - describes the C level virtual image interface
7
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 This is a C level interface rather than Perl.
16 Existing Images
18 As of this writing we have the following concrete image types:
19 • 8-bit/sample direct images
21 • 16-bit/sample direct images
23 • double/sample direct images
25 • 8-bit/sample 8-bit/index paletted images
27 Currently there is only one virtual image type:
29 • masked images, where a mask image can control write access to an
31 underlying image.
32 Other possible concrete images include:
34 • "bitmaps", 1 bit/sample images (perhaps limited to a single
36 channel)
37 • 16-bit/index paletted images
39 Some other possible virtual images:
41 • image alpha combining, where the combining function can be
43 specified (see the layer modes in graphical editors like the GIMP
44 or Photoshop.
45
47 Each image type needs to define a number of functions which implement
48 the image operations.
49 The image structure includes information describes the image, which can
51 be used to determine the structure of the image:
52 • "channels" - the number of samples kept for each pixel in the
54 image. For paletted images the samples are kept for each entry in
55 the palette.
56 • "xsize", "ysize" - the dimensions of the image in pixels.
58 • "bytes" - the number of bytes of data kept for the image. Zero for
60 virtual images. Does not include the space required for the
61 palette for paletted images.
62 • "ch_mask" - controls which samples will be written to for direct
64 images.
65 • "bits" - the number of bits kept for each sample. There are enum
67 values i_8_bits, i_16_bits and i_double_bits (64).
68 • "type" - the type of image, either i_direct_type or i_palette_type.
70 Direct images keep the samples for every pixel image, while
71 i_palette_type images keep an index into a color table for each
72 pixel.
73 • "virtual" - whether the image keeps any pixel data. If this is
75 non-zero then "idata" points to image data, otherwise it points to
76 implementation defined data, though "ext_data" is more likely to be
77 used for that.
78 • "idata" - image data. If the image is 8-bit direct, non-virtual,
80 then this consists of each sample of the image stored one after
81 another, otherwise it is implementation defined.
82 • "tags" - will be used to store meta-data for an image, eg. tags
84 from a TIFF file, or animation information from a GIF file. This
85 should be initialized with a call to i_tags_new() in your image
86 constructor if creating a new image type.
87 • "ext_data" - for internal use of image types. This is not released
89 by the standard i_img_exorcise() function. If you create a new
90 image type and want to store a pointer to allocated memory here you
91 should point i_f_destroy at a function that will release the data.
92 If a caller has no knowledge of the internal format of an image, the
94 caller must call the appropriate image function pointer. Imager
95 provides macros that wrap these functions, so it isn't necessary to
96 call them directly.
97 Many functions have a similar function with an 'f' suffix, these take
99 or return samples specified with floating point values rather than
100 8-bit integers (unsigned char). Floating point samples are returned in
101 the range 0 to 1 inclusive.
102 i_f_ppix(im,x,y,color)
104 i_f_ppixf(im,x,y,fcolor)
105 stores the specified color at pixel (x,y) in the image. If the
106 pixel can be stored return 0, otherwise -1. An image type may
107 choose to return 0 under some circumstances, eg. writing to a
108 masked area of an image. The "color" or "fcolor" always contains
109 the actual samples to be written, rather than a palette index.
110 i_f_plin(im,l,r,y,colors)
112 i_f_plinf(im,l,r,y,fcolors)
113 stores (r-l) pixels at positions (l,y) ... (r-1, y) from the array
114 specified by "colors" (or "fcolors"). Returns the number of pixels
115 written to. If l is negative it will return 0. If "r > im->xsize"
116 then only "(im->xsize - l)" will be written.
117 i_f_gpix(im,x,y,color)
119 i_f_gpixf(im,x,y,fcolor)
120 retrieves a single pixel from position (x,y). This returns the
121 samples rather than the index for paletted images.
122 i_f_glin(im,l,r,y,colors)
124 i_f_glinf(im,l,r,y,fcolors)
125 retrieves (r-l) pixels from positions (l, y) through (r-1, y) into
126 the array specified by colors. Returns the number of pixels
127 retrieved. If l < 0 no pixels are retrieved. If "r > im->xsize"
128 then pixels "(l, y)" ... "(im->xsize-1, y)" are retrieved.
129 Retrieves the samples rather than the color indexes for paletted
130 images.
131 i_f_gsamp(im,l,r,y,samples,chans,chan_count)
133 i_f_gsampf(im,l,r,y,fsamples,chans,chan_count)
134 Retrieves samples from channels specified by "chans" (for length
135 "chan_count") from pixels at positions (l,y) ... (r-1, y). If
136 "chans" is NULL then samples from channels 0 ... "chan_count-1"
137 will be retrieved. Returns the number of sample retrieved (not the
138 number of channels). If a channel in "chans" is not present in the
139 image or l < 0, returns 0. If "r > im->xsize", then the samples
140 from "(l,y)" ... "(im->xsize-1, y)" are returned.
141 The following are for images where type == i_palette_type only.
143 i_f_gpal(im,l,r,y,vals)
145 Retrieves color indexes from the image for pixels (l, y) ... (r-1,
146 y) into "vals". Returns the number of indexes retrieved.
147 i_f_ppal(im,l,r,y,vals)
149 Stores color indexes into the image for pixels (l, y) ... (r-1, y)
150 from "vals". Returns the number of indexes retrieved. If indexes
151 are outside the range of the images palette, then you may have
152 problems reading those pixels with i_gpix() or i_glin().
153 i_f_addcolors(im,colors,count)
155 Adds the count colors to the image's palette. Returns the index of
156 the first color added, or -1 if there is not enough space for count
157 colors.
158 i_f_getcolors(im,index,colors,count)
160 Retrieves count colors from the image's palette starting from entry
161 index in the palette. Returns non-zero on success.
162 i_f_colorcount(im)
164 Returns the number of colors in the image's palette. Returns -1 if
165 this is not a paletted image.
166 i_f_maxcolors(im)
168 Returns the maximum number of colors that can fit in the image's
169 palette. Returns -1 if this is not a paletted image.
170 i_f_findcolor(im,color,entry)
172 Searches the image's palette for the specified color, setting
173 *entry to the index and returning non-zero. Returns zero if the
174 color is not found.
175 i_f_setcolors_t(im,index,colors,count)
177 Sets count colors starting from index in the image from the array
178 colors. The colors to be set must already have entries in the
179 image's palette. Returns non-zero on success.
180 Finally, the i_f_destroy function pointer can be set which is called
182 when the image is destroyed. This can be used to release memory
183 pointed to by ext_data or release any other resources.
184 When writing to a paletted image with i_ppix() or i_plin() and the
186 color you are writing doesn't exist in the image, then it's possible
187 that the image will be internally converted to a direct image with the
188 same number of channels.
189
191 Several functions have been written to simplify creating new image
192 types.
193 These tools are available by including imagei.h.
195 Floating point wrappers
197 These functions implement the floating point sample versions of each
198 interface function in terms of the integer sample version.
199 These are:
201 i_ppixf_fp
203 i_gpixf_fp
204 i_plinf_fp
205 i_glinf_fp
206 i_gsampf_fp
207 Forwarding functions
209 These functions are used in virtual images where the call should simply
210 be forwarded to the underlying image. The underlying image is assumed
211 to be the first pointer in a structure pointed at by ext_data.
212 If this is not the case then these functions will just crash :)
214 i_addcolors_forward
216 i_getcolors_forward
217 i_colorcount_forward
218 i_maxcolors_forward
219 i_findcolor_forward
220 i_setcolors_forward
221 Sample macros
223 "imagei.h" defines several macros for converting samples between
224 different sizes.
225 Each macro is of the form "Sample"size"To"size where size is one of 8,
227 16, or F (for floating-point samples).
228 SampleFTo16(sample)
230 Sample16ToF(sample)
231 SampleFTo8(sample)
232 Sample8ToF(sample)
233 Sample16To8(num)
234 Sample8To16(num)
235
237 Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson
238perl v5.32.1 2021-01-27 Imager::interface(3)