1Imager::interface(3) User Contributed Perl Documentation Imager::interface(3)
2
6 Imager::interface.pod - decribes 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:
20 · 8-bit/sample direct images
22 · 16-bit/sample direct images
24 · double/sample direct images
26 · 8-bit/sample 8-bit/index paletted images
28 Currently there is only one virtual image type:
30 · masked images, where a mask image can control write access to an
32 underlying image.
33 Other possible concrete images include:
35 · "bitmaps", 1 bit/sample images (perhaps limited to a single chan‐
37 nel)
38 · 16-bit/index paletted images
40 Some other possible virtual images:
42 · image alpha combining, where the combining function can be speci‐
44 fied (see the layer modes in graphical editors like the GIMP or
45 photoshop.
46
48 Each image type needs to define a number of functions which implement
49 the image operations.
50 The image structure includes information describes the image, which can
52 be used to determine the structure of the image:
53 channels
55 the number of samples kept for each pixel in the image. For palet‐
56 ted images the samples are kept for each entry in the palette.
57 xsize, ysize
59 the dimensions of the image in pixels.
60 bytes
62 the number of bytes of data kept for the image. Zero for virtual
63 images. Does not include the space required for the palette for
64 paletted images.
65 ch_mask
67 controls which samples will be written to for direct images.
68 bits
70 the number of bits kept for each sample. There are enum values
71 i_8_bits, i_16_bits and i_double_bits (64).
72 type
74 the type of image, either i_direct_type or i_palette_type. Direct
75 images keep the samples for every pixel image, while i_palette_type
76 images keep an index into a color table for each pixel.
77 virtual
79 whether the image keeps any pixel data. If this is non-zero then
80 idata points to image data, otherwise it points to implementation
81 defined data, though ext_data is more likely to be used for that.
82 idata
84 image data. If the image is 8-bit direct, non-virtual, then this
85 consists of each sample of the image stored one after another, oth‐
86 erwise it is implementation defined.
87 tags
89 will be used to store meta-data for an image, eg. tags from a TIFF
90 file, or animation information from a GIF file. This should be
91 initialized with a call to i_tags_new() in your image constructor
92 if creating a new image type.
93 ext_data
95 for internal use of image types. This is not released by the stan‐
96 dard i_img_exorcise() function. If you create a new image type and
97 want to store a pointer to allocated memory here you should point
98 i_f_destroy at a function that will release the data.
99 If a caller has no knowledge of the internal format of an image, the
101 caller must call the appropriate image function pointer. Imager pro‐
102 vides macros that wrap these functions, so it isn't necessary to call
103 them directly.
104 Many functions have a similar function with an 'f' suffix, these take
106 or return samples specified with floating point values rather than
107 8-bit integers (unsigned char). Floating point samples are returned in
108 the range 0 to 1 inclusive.
109 i_f_ppix(im, x, y, color)
111 i_f_ppixf(im, x, y, fcolor)
112 stores the specified color at pixel (x,y) in the image. If the
113 pixel can be stored return 0, otherwise -1. An image type may
114 choose to return 0 under some circumstances, eg. writing to a
115 masked area of an image. The color or fcolor always contains the
116 actual samples to be written, rather than a palette index.
117 i_f_plin(im, l, r, y, colors)
119 i_f_plinf(im, l, r, y, fcolors)
120 stores (r-l) pixels at positions (l,y) ... (r-1, y) from the array
121 specified by colors (or fcolors). Returns the number of pixels
122 written to. If l is negative it will return 0. If r > im->xsize
123 then only (im->xsize - l) will be written.
124 i_f_gpix(im, x, y, color)
126 i_f_gpixf(im, x, y, fcolor)
127 retrieves a single pixel from position (x,y). This returns the
128 samples rather than the index for paletted images.
129 i_f_glin(im, l, r, y, colors)
131 i_f_glinf(im, l, r, y, fcolors)
132 retrieves (r-l) pixels from positions (l, y) through (r-1, y) into
133 the array specified by colors. Returns the number of pixels
134 retrieved. If l < 0 no pixels are retrieved. If r > im->xsize
135 then pixels (l, y) ... (im->xsize-1, y) are retrieved. Retrieves
136 the samples rather than the color indexes for paletted images.
137 i_f_gsamp(im, l, r, y, samples, chans, chan_count)
139 i_f_gsampf(im, l, r, y, fsamples, chans, chan_count)
140 Retrieves samples from channels specified by chans (for length
141 chan_count) from pixels at positions (l,y) ... (r-1, y). If chans
142 is NULL then samples from channels 0 ... chan_count-1 will be
143 retrieved. Returns the number of sample retrieved (_not_ the num‐
144 ber of channels). If a channel in chans is not present in the
145 image or l < 0, returns 0. If r > im->xsize, then the samples from
146 (l,y) ... (im->xsize-1, y) are returned.
147 The following are for images where type == i_palette_type only.
149 i_f_gpal(im, l, r, y, vals)
151 Retrieves color indexes from the image for pixels (l, y) ... (r-1,
152 y) into vals. Returns the number of indexes retrieved.
153 i_f_ppal(im, l, r, y, vals)
155 Stores color indexes into the image for pixels (l, y) ... (r-1, y)
156 from vals. Returns the number of indexes retrieved. If indices
157 are outside the range of the images palette, then you may have
158 problems reading those pixels with i_gpix() or i_glin().
159 i_f_addcolors(im, colors, count)
161 Adds the count colors to the image's palette. Returns the index of
162 the first color added, or -1 if there is not enough space for count
163 colors.
164 i_f_getcolors(im, index, colors, count)
166 Retrieves count colors from the image's palette starting from entry
167 index in the palette. Returns non-zero on success.
168 i_f_colorcount(im)
170 Returns the number of colors in the image's palette. Returns -1 if
171 this is not a paletted image.
172 i_f_maxcolors(im)
174 Returns the maximum number of colors that can fit in the image's
175 palette. Returns -1 if this is not a paletted image.
176 i_f_findcolor(im, color, entry)
178 Searches the image's palette for the specified color, setting
179 *entry to the index and returning non-zero. Returns zero if the
180 color is not found.
181 i_f_setcolors_t(im, index, colors, count)
183 Sets count colors starting from index in the image from the array
184 colors. The colors to be set must already have entries in the
185 image's palette. Returns non-zero on success.
186 Finally, the i_f_destroy function pointer can be set which is called
188 when the image is destroyed. This can be used to release memory
189 pointed to by ext_data or release any other resources.
190 When writing to a paletted image with i_ppix() or i_plin() and the
192 color you are writing doesn't exist in the image, then it's possible
193 that the image will be internally converted to a direct image with the
194 same number of channels.
195
197 Several functions have been written to simplify creating new image
198 types.
199 These tools are available by including imagei.h.
201 Floating point wrappers
203 These functions implement the floating point sample versions of each
205 interface function in terms of the integer sample version.
206 These are:
208 i_ppixf_fp
210 i_gpixf_fp
211 i_plinf_fp
212 i_glinf_fp
213 i_gsampf_fp
214 Forwarding functions
216 These functions are used in virtual images where the call should simply
218 be forwarded to the underlying image. The underlying image is assumed
219 to be the first pointer in a structure pointed at by ext_data.
220 If this is not the case then these functions will just crash :)
222 i_addcolors_forward
224 i_getcolors_forward
225 i_colorcount_forward
226 i_maxcolors_forward
227 i_findcolor_forward
228 i_setcolors_forward
229 Sample macros
231 Imagei.h defines several macros for converting samples between differ‐
233 ent sizes.
234 Each macro is of the form SamplesizeTosize where size is one of 8, 16,
236 or F (for floating-point samples).
237 SampleFTo16(sample)
239 Sample16ToF(sample)
240 SampleFTo8(sample)
241 Sample8ToF(sample)
242 Sample16To8(num)
243 Sample8To16(num)
244perl v5.8.8 2008-03-28 Imager::interface(3)