Imager::API(3pm)

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

NAME

6       Imager::API - Imager's C API - introduction.
7

SYNOPSIS

9         #include "imext.h"
10         #include "imperl.h"
11
12         DEFINE_IMAGER_CALLBACKS;
13
14         MODULE = Your::Module  PACKAGE = Your::Module
15
16         ...
17
18         BOOT:
19           /* any release with the API */
20           PERL_INITIALIZE_IMAGER_CALLBACKS;
21           /* preferred from Imager 0.91 */
22           PERL_INITIALIZE_IMAGER_CALLBACKS_NAME("My::Module");
23

DESCRIPTION

25       The API allows you to access Imager functions at the C level from XS
26       and from "Inline::C".
27
28       The intent is to allow users to:
29
30       ·   write C code that does Imager operations the user might do from
31           Perl, but faster, for example, the Imager::CountColor example.
32
33       ·   write C code that implements an application specific version of
34           some core Imager object, for example, Imager::SDL.
35
36       ·   write C code that hooks into Imager's existing methods, such as
37           filter or file format handlers.
38
39       See Imager::Inline for information on using Imager's Inline::C support.
40

Beware

42       ·   don't return an object you received as a parameter - this will
43           cause the object to be freed twice.
44

Types

46       The API makes the following types visible:
47
48       ·   "i_img" - used to represent an image
49
50       ·   "i_color" - used to represent a color with up to 8 bits per sample.
51
52       ·   "i_fcolor" - used to represent a color with a double per sample.
53
54       ·   "i_fill_t" - fill objects>> - an abstract fill
55
56       ·   "im_context_t" - Imager's per-thread state.
57
58       At this point there is no consolidated font object type, and hence the
59       font functions are not visible through Imager's API.
60
61   i_img
62       This contains the dimensions of the image ("xsize", "ysize",
63       "channels"), image metadata ("ch_mask", "bits", "type", "virtual"),
64       potentially image data ("idata") and a function table, with pointers to
65       functions to perform various low level image operations.
66
67       The only time you should directly write to any value in this type is if
68       you're implementing your own image type.
69
70       The typemap includes type names Imager and Imager::ImgRaw as typedefs
71       for "i_img *".
72
73       For incoming parameters the typemap will accept either Imager or
74       Imager::ImgRaw objects.
75
76       For return values the typemap will produce a full Imager object for an
77       Imager return type and a raw image object for an Imager::ImgRaw return
78       type.
79
80   i_color
81       Represents an 8-bit per sample color.  This is a union containing
82       several different structs for access to components of a color:
83
84       ·   "gray" - single member "gray_color".
85
86       ·   "rgb" - "r", "g", "b" members.
87
88       ·   "rgba" - "r", "g", "b", "a" members.
89
90       ·   "channels" - array of channels.
91
92       Use "Imager::Color" for parameter and return value types.
93
94   i_fcolor
95       Similar to "i_color" except that each component is a double instead of
96       an unsigned char.
97
98       Use Imager::Color::Float for parameter and return value types.
99
100   i_fill_t
101       Abstract type containing pointers called to perform low level fill
102       operations.
103
104       Unless you're defining your own fill objects you should treat this as
105       an opaque type.
106
107       Use Imager::FillHandle for parameter and return value types.  At the
108       Perl level this is stored in the "fill" member of the Perl level
109       Imager::Fill object.
110
111   i_io_glue_t
112       "i_io_glue_t" is Imager's I/O abstraction.
113
114       Historically named "io_glue", and this name is available for backward
115       compatibility.
116
117   im_context_t
118       This new type is an opaque type that stores Imager's per-thread state,
119       including the error message stack, the current log file state and image
120       size file limits.
121
122       While Imager's internal typemap provides a "T_PTROBJ" mapping and a
123       DESTROY method for this type you must never return objects of this type
124       back to perl.
125
126       See "Context objects" for more information.
127
128   i_polygon_t
129       Represents a single polygon supplied to i_poly_poly_aa() and
130       i_poly_poly_aa_cfill().
131
132       This is a structure with 3 members:
133
134       ·   "x", "y" - pointers to the first elements of arrays of doubles that
135           define the vertices of the polygon.
136
137       ·   "count" - the number of values in each of the "x" and "y" arrays.
138
139   i_poly_fill_mode_t
140       An enumerated type of the possible fill modes for polygons:
141
142       ·   "i_pfm_evenodd" - if areas overlap an odd number of times, they are
143           filled, and are otherwise unfilled.
144
145       ·   "i_pfm_nonzero" - areas that have an unbalanced clockwise and anti-
146           clockwise boundary are filled.  This is the same as "WindingRule"
147           for X and "WINDING" for Win32 GDI.
148

Create an XS module using the Imager API

150   Foo.pm
151       Load Imager:
152
153         use Imager 0.48;
154
155       and bootstrap your XS code - see XSLoader or DynaLoader.
156
157   "Foo.xs"
158       You'll need the following in your XS source:
159
160       ·   include the Imager external API header, and the perl interface
161           header:
162
163             #include "imext.h"
164             #include "imperl.h"
165
166       ·   create the variables used to hold the callback table:
167
168             DEFINE_IMAGER_CALLBACKS;
169
170       ·   initialize the callback table in your "BOOT" code:
171
172             BOOT:
173               PERL_INITIALIZE_IMAGER_CALLBACKS;
174
175           From Imager 0.91 you can supply your module name to improve error
176           reporting:
177
178             BOOT:
179               PERL_INITIALIZE_IMAGER_CALLBACKS_NAME("My::Module");
180
181   foo.c
182       In any other source files where you want to access the Imager API,
183       you'll need to:
184
185       ·   include the Imager external API header:
186
187             #include "imext.h"
188
189   "Makefile.PL"
190       If you're creating an XS module that depends on Imager's API your
191       "Makefile.PL" will need to do the following:
192
193       ·   "use Imager::ExtUtils;"
194
195       ·   include Imager's include directory in INC:
196
197             INC => Imager::ExtUtils->includes
198
199       ·   use Imager's typemap:
200
201             TYPEMAPS => [ Imager::ExtUtils->typemap ]
202
203       ·   include Imager 0.48 as a PREREQ_PM:
204
205              PREREQ_PM =>
206              {
207               Imager => 0.48,
208              },
209
210       ·   Since you use Imager::ExtUtils in "Makefile.PL" (or "Build.PL") you
211           should include Imager in your configure_requires:
212
213              META_MERGE =>
214              {
215                configure_requires => { Imager => "0.48" }
216              },
217

Context objects

219       Starting with Imager 0.93, Imager keeps some state per-thread rather
220       than storing it in global (or static) variables.  The intent is to
221       improve support for multi-threaded perl programs.
222
223       For the typical XS or Inline::C module using Imager's API this won't
224       matter - the changes are hidden behind macros and rebuilding your
225       module should require no source code changes.
226
227       Some operations will be slightly slower, these include:
228
229       ·   creating an image
230
231       ·   reporting errors
232
233       ·   creating I/O objects
234
235       ·   setting/getting/testing image file limits
236
237       ·   logging
238
239       You can avoid this fairly minor overhead by adding a "#define":
240
241         #define IMAGER_NO_CONTEXT
242
243       before including any Imager header files, but you will need to manage
244       context objects yourself.
245
246       Some functions and macros that are available without
247       "IMAGER_NO_CONTEXT" are not available with it defined, these are:
248
249       ·   mm_log() - to avoid using a different context object for the line
250           header and the line text you need to use im_log() instead, with a
251           context object visible in scope.
252
253   "aIMCTX"
254       With "IMAGER_NO_CONTEXT" defined, "aIMCTX" refers to the locally
255       defined context object, either via one the of the "dIMCTX" macros or as
256       a parameter with the "pIMCTX" macro.
257
258       Without "IMAGER_NO_CONTEXT", "aIMCTX" is a call to "im_get_context()"
259       which retrieves the context object for the current thread.
260
261       There is no "aIMCTX_" macro, any Imager function that can accept a
262       context parameter always accepts it.
263
264   "pIMCTX"
265       This macro declares a variable of type "im_context_t" that's accessible
266       via the "aIMCTX" macro.  This is intended for use as a parameter
267       declaration for functions:
268
269         void f(pIMCTX) {
270           ... use aIMCTX here
271         }
272
273         void g(...) {
274           ...
275           f(aIMCTX);
276         }
277
278   "dIMCTX"
279       Defines a local context variable and initializes it via
280       im_get_context().
281
282   "dIMCTXim"
283       Defines a local context variable and initializes it from the context
284       stored in an image object, eg:
285
286         void f(i_img *im) {
287           dIMCTXim(im);
288           ...
289         }
290
291   "dIMCTXio"
292       Defines a local context variable and initializes it from the context
293       stored in an I/O object object.
294
295         void f(i_io_glue_t *io) {
296           dIMCTXio(io);
297           ...
298         }
299
300   "dIMCTXctx"
301       Defines a local context variable accessible via "aIMCTX" in terms of an
302       expression you supply:
303
304         void f(my_object *p) {
305           dIMCTXctx(p->context);
306           ...
307         }
308
309       This can be used to define your own local context macro:
310
311         #define dIMCTXmine(mine) ((mine)->context)
312
313         void f(my_object *p) {
314           dIMCTXmine(p);
315           ...
316         }
317

Mutex Functions

319       Since some libraries are not thread safe, Imager's API includes some
320       simple mutex functions.
321
322       To create a mutex:
323
324         i_mutex_t m = i_mutex_new();
325
326       To control or lock the mutex:
327
328         i_mutex_lock(m);
329
330       To release or unlock the mutex:
331
332         i_mutex_unlock(m);
333
334       To free any resources used by the mutex:
335
336         i_mutex_destroy(m);
337
338       I most cases where you'd use these functions, your code would create
339       the mutex in your BOOT section, then lock and unlock the mutex as
340       needed to control access to the library.
341

Context slots

343       To avoid abstracting the platform TLS and thread clean up handling,
344       Imager provides simple APIs for storing per-context information.
345
346       To allocate a slot:
347
348         im_slot_t slot = im_context_slot_new(callback)
349
350       where callback is a (possibly NULL) function pointer called when the
351       context object is destroyed.
352
353       By default, the stored value for a slot is NULL, whether for a new
354       context or for a cloned context.
355
356       To store a value:
357
358         im_context_slot_set(aIMCTX, slot, somevalue);
359
360       where "somevalue" can be represented as a "void *".
361
362       To retrieve the value:
363
364         value = im_context_slot_get(aIMCTX, slot);
365

AUTHOR

367       Tony Cook <tonyc@cpan.org>
368