add the context slot APIs
[imager.git] / lib / Imager / API.pod
1 =head1 NAME
2
3 Imager::API - Imager's C API - introduction.
4
5 =head1 SYNOPSIS
6
7   #include "imext.h"
8   #include "imperl.h"
9
10   DEFINE_IMAGER_CALLBACKS;
11
12   MODULE = Your::Module  PACKAGE = Your::Module
13
14   ...
15
16   BOOT:
17     /* any release with the API */
18     PERL_INITIALIZE_IMAGER_CALLBACKS;
19     /* preferred from Imager 0.91 */
20     PERL_INITIALIZE_IMAGER_CALLBACKS_NAME("My::Module");
21   
22
23 =head1 DESCRIPTION
24
25 =for stopwords XS
26
27 The API allows you to access Imager functions at the C level from XS
28 and from C<Inline::C>.
29
30 The intent is to allow users to:
31
32 =over
33
34 =item *
35
36 write C code that does Imager operations the user might do from Perl,
37 but faster, for example, the L<Imager::CountColor> example.
38
39 =item *
40
41 write C code that implements an application specific version of some
42 core Imager object, for example, Imager::SDL.
43
44 =item *
45
46 write C code that hooks into Imager's existing methods, such as filter
47 or file format handlers.
48
49 =back
50
51 See L<Imager::Inline> for information on using Imager's Inline::C
52 support.
53
54 =head1 Beware
55
56 =over
57
58 =item *
59
60 don't return an object you received as a parameter - this will cause
61 the object to be freed twice.
62
63 =back
64
65 =head1 Types
66
67 The API makes the following types visible:
68
69 =over
70
71 =item *
72
73 L</i_img> - used to represent an image
74
75 =item *
76
77 L</i_color> - used to represent a color with up
78 to 8 bits per sample.
79
80 =item *
81
82 L</i_fcolor> - used to represent
83 a color with a double per sample.
84
85 =item *
86
87 L</i_fill_t> - fill objects>> - an abstract fill
88
89 =item *
90
91 L</im_context_t> - Imager's per-thread state.
92
93 =back
94
95 At this point there is no consolidated font object type, and hence the
96 font functions are not visible through Imager's API.
97
98 =head2 i_img
99
100 This contains the dimensions of the image (C<xsize>, C<ysize>,
101 C<channels>), image metadata (C<ch_mask>, C<bits>, C<type>,
102 C<virtual>), potentially image data (C<idata>) and a function table,
103 with pointers to functions to perform various low level image
104 operations.
105
106 The only time you should directly write to any value in this type is
107 if you're implementing your own image type.
108
109 The typemap includes type names Imager and Imager::ImgRaw as typedefs
110 for C<i_img *>.
111
112 For incoming parameters the typemap will accept either Imager or
113 Imager::ImgRaw objects.
114
115 For return values the typemap will produce a full Imager object for an
116 Imager return type and a raw image object for an Imager::ImgRaw return
117 type.
118
119 =head2 i_color
120
121 Represents an 8-bit per sample color.  This is a union containing
122 several different structs for access to components of a color:
123
124 =over
125
126 =item *
127
128 C<gray> - single member C<gray_color>.
129
130 =item *
131
132 C<rgb> - C<r>, C<g>, C<b> members.
133
134 =item *
135
136 C<rgba> - C<r>, C<g>, C<b>, C<a> members.
137
138 =item *
139
140 C<channels> - array of channels.
141
142 =back
143
144 Use C<Imager::Color> for parameter and return value types.
145
146 =head2 i_fcolor
147
148 Similar to C<i_color> except that each component is a double instead of
149 an unsigned char.
150
151 Use Imager::Color::Float for parameter and return value types.
152
153 =head2 i_fill_t
154
155 Abstract type containing pointers called to perform low level fill
156 operations.
157
158 Unless you're defining your own fill objects you should treat this as
159 an opaque type.
160
161 Use Imager::FillHandle for parameter and return value types.  At the
162 Perl level this is stored in the C<fill> member of the Perl level
163 Imager::Fill object.
164
165 =head2 i_io_glue_t
166
167 C<i_io_glue_t> is Imager's I/O abstraction.
168
169 Historically named C<io_glue>, and this name is available for backward
170 compatibility.
171
172 =head2 im_context_t
173
174 This new type is an opaque type that stores Imager's per-thread state,
175 including the error message stack, the current log file state and
176 image size file limits.
177
178 While Imager's internal typemap provides a C<T_PTROBJ> mapping and a
179 DESTROY method for this type you B<must> never return objects of this
180 type back to perl.
181
182 See L</Context objects> for more information.
183
184 =head1 Create an XS module using the Imager API
185
186 =head2 Foo.pm
187
188 Load Imager:
189
190   use Imager 0.48;
191
192 and bootstrap your XS code - see L<XSLoader> or L<DynaLoader>.
193
194 =head2 C<Foo.xs>
195
196 You'll need the following in your XS source:
197
198 =over
199
200 =item *
201
202 include the Imager external API header, and the perl interface header:
203
204   #include "imext.h"
205   #include "imperl.h"
206
207 =item *
208
209 create the variables used to hold the callback table:
210
211   DEFINE_IMAGER_CALLBACKS;
212
213 =item *
214
215 initialize the callback table in your C<BOOT> code:
216
217   BOOT:
218     PERL_INITIALIZE_IMAGER_CALLBACKS;
219
220 From Imager 0.91 you can supply your module name to improve error
221 reporting:
222
223   BOOT:
224     PERL_INITIALIZE_IMAGER_CALLBACKS_NAME("My::Module");
225
226 =back
227
228 =head2 foo.c
229
230 In any other source files where you want to access the Imager API,
231 you'll need to:
232
233 =over
234
235 =item *
236
237 include the Imager external API header:
238
239   #include "imext.h"
240
241 =back
242
243 =head2 C<Makefile.PL>
244
245 If you're creating an XS module that depends on Imager's API your
246 C<Makefile.PL> will need to do the following:
247
248 =over
249
250 =item *
251
252 C<use Imager::ExtUtils;>
253
254 =item *
255
256 include Imager's include directory in INC:
257
258   INC => Imager::ExtUtils->includes
259
260 =item *
261
262 use Imager's typemap:
263
264   TYPEMAPS => [ Imager::ExtUtils->typemap ]
265
266 =item *
267
268 include Imager 0.48 as a PREREQ_PM:
269
270    PREREQ_PM =>
271    {
272     Imager => 0.48,
273    },
274
275 =item *
276
277 Since you use Imager::ExtUtils in C<Makefile.PL> (or C<Build.PL>) you
278 should include Imager in your configure_requires:
279
280    META_MERGE =>
281    {
282      configure_requires => { Imager => "0.48" }
283    },
284
285 =back
286
287 =head1 Context objects
288
289 Starting with Imager 0.93, Imager keeps some state per-thread rather
290 than storing it in global (or static) variables.  The intent is to
291 improve support for multi-threaded perl programs.
292
293 For the typical XS or Inline::C module using Imager's API this won't
294 matter - the changes are hidden behind macros and rebuilding your
295 module should require no source code changes.
296
297 Some operations will be slightly slower, these include:
298
299 =over
300
301 =item *
302
303 creating an image
304
305 =item *
306
307 reporting errors
308
309 =item *
310
311 creating I/O objects
312
313 =item *
314
315 setting/getting/testing image file limits
316
317 =item *
318
319 logging
320
321 =back
322
323 You can avoid this fairly minor overhead by adding a C<#define>:
324
325   #define IMAGER_NO_CONTEXT
326
327 before including any Imager header files, but you will need to manage
328 context objects yourself.
329
330 Some functions and macros that are available without
331 C<IMAGER_NO_CONTEXT> are not available with it defined, these are:
332
333 =over
334
335 =item *
336
337 mm_log() - to avoid using a different context object for the line
338 header and the line text you need to use im_log() instead, with a
339 context object visible in scope.
340
341 =back
342
343 =head2 C<aIMCTX>
344
345 With C<IMAGER_NO_CONTEXT> defined, C<aIMCTX> refers to the locally
346 defined context object, either via one the of the C<dIMCTX> macros or
347 as a parameter with the C<pIMCTX> macro.
348
349 Without C<IMAGER_NO_CONTEXT>, C<aIMCTX> is a call to
350 C<im_get_context()> which retrieves the context object for the current
351 thread.
352
353 There is no C<aIMCTX_> macro, any Imager function that can accept a
354 context parameter always accepts it.
355
356 =head2 C<pIMCTX>
357
358 This macro declares a variable of type L</im_context_t> that's
359 accessible via the C<aIMCTX> macro.  This is intended for use as a
360 parameter declaration for functions:
361
362   void f(pIMCTX) {
363     ... use aIMCTX here
364   }
365
366   void g(...) {
367     ...
368     f(aIMCTX);
369   }
370
371 =head2 C<dIMCTX>
372
373 Defines a local context variable and initializes it via
374 L<im_get_context()|Imager::APIRef/im_get_context()>.
375
376 =head2 C<dIMCTXim>
377
378 Defines a local context variable and initializes it from the context
379 stored in an L<image object|/i_img>, eg:
380
381   void f(i_img *im) {
382     dIMCTXim(im);
383     ...
384   }
385
386 =head2 C<dIMCTXio>
387
388 Defines a local context variable and initializes it from the context
389 stored in an L<I/O object|/i_io_glue_t> object.
390
391   void f(i_io_glue_t *io) {
392     dIMCTXio(io);
393     ...
394   }
395
396 =head2 C<dIMCTXctx>
397
398 Defines a local context variable accessible via C<aIMCTX> in terms of
399 an expression you supply:
400
401   void f(my_object *p) {
402     dIMCTXctx(p->context);
403     ...
404   }
405
406 This can be used to define your own local context macro:
407
408   #define dIMCTXmine(mine) ((mine)->context)
409
410   void f(my_object *p) {
411     dIMCTXmine(p);
412     ...
413   }
414
415 =head1 Mutex Functions
416
417 Since some libraries are not thread safe, Imager's API includes some
418 simple mutex functions.
419
420 To create a mutex:
421
422   i_mutex_t m = i_mutex_new();
423
424 To control or lock the mutex:
425
426   i_mutex_lock(m);
427
428 To release or unlock the mutex:
429
430   i_mutex_unlock(m);
431
432 To free any resources used by the mutex:
433
434   i_mutex_destroy(m);
435
436 I most cases where you'd use these functions, your code would create
437 the mutex in your BOOT section, then lock and unlock the mutex as
438 needed to control access to the library.
439
440 =head1 Context slots
441
442 =for stopwords
443 TLS APIs
444
445 To avoid abstracting the platform TLS and thread clean up handling,
446 Imager provides simple APIs for storing per-context information.
447
448 To allocate a slot:
449
450   im_slot_t slot = im_context_slot_new(callback)
451
452 where callback is a (possibly NULL) function pointer called when the
453 context object is destroyed.
454
455 By default, the stored value for a slot is NULL, whether for a new
456 context or for a cloned context.
457
458 To store a value:
459
460   im_context_slot_set(aIMCTX, slot, somevalue);
461
462 where C<somevalue> can be represented as a C<void *>.
463
464 To retrieve the value:
465
466   value = im_context_slot_get(aIMCTX, slot);
467
468 =head1 AUTHOR
469
470 Tony Cook <tonyc@cpan.org>
471
472 =head1 SEE ALSO
473
474 Imager, Imager::ExtUtils, Imager::APIRef, Imager::Inline
475
476 =cut