1Imager::interface(3)  User Contributed Perl Documentation Imager::interface(3)
2
3
4

NAME

6       Imager::interface.pod - describes the C level virtual image interface
7

SYNOPSIS

DESCRIPTION

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   Existing Images
18       As of this writing we have the following concrete image types:
19
20       •   8-bit/sample direct images
21
22       •   16-bit/sample direct images
23
24       •   double/sample direct images
25
26       •   8-bit/sample 8-bit/index paletted images
27
28       Currently there is only one virtual image type:
29
30       •   masked images, where a mask image can control write access to an
31           underlying image.
32
33       Other possible concrete images include:
34
35       •   "bitmaps", 1 bit/sample images (perhaps limited to a single
36           channel)
37
38       •   16-bit/index paletted images
39
40       Some other possible virtual images:
41
42       •   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

THE INTERFACE

47       Each image type needs to define a number of functions which implement
48       the image operations.
49
50       The image structure includes information describes the image, which can
51       be used to determine the structure of the image:
52
53       •   "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
57       •   "xsize", "ysize" - the dimensions of the image in pixels.
58
59       •   "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
63       •   "ch_mask" - controls which samples will be written to for direct
64           images.
65
66       •   "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
69       •   "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
74       •   "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
79       •   "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
83       •   "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
88       •   "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
93       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
98       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
103       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
111       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
118       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
123       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
132       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
142       The following are for images where type == i_palette_type only.
143
144       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
148       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
154       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
159       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
163       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
167       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
171       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
176       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
181       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
185       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

TOOLS

191       Several functions have been written to simplify creating new image
192       types.
193
194       These tools are available by including imagei.h.
195
196   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
200       These are:
201
202       i_ppixf_fp
203       i_gpixf_fp
204       i_plinf_fp
205       i_glinf_fp
206       i_gsampf_fp
207
208   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
213       If this is not the case then these functions will just crash :)
214
215       i_addcolors_forward
216       i_getcolors_forward
217       i_colorcount_forward
218       i_maxcolors_forward
219       i_findcolor_forward
220       i_setcolors_forward
221
222   Sample macros
223       "imagei.h" defines several macros for converting samples between
224       different sizes.
225
226       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
229       SampleFTo16(sample)
230       Sample16ToF(sample)
231       SampleFTo8(sample)
232       Sample8ToF(sample)
233       Sample16To8(num)
234       Sample8To16(num)
235

AUTHOR

237       Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson
238
239
240
241perl v5.34.0                      2021-07-22              Imager::interface(3)
Impressum