dbe6414b6ffceb033982d52e7ac6e99af7d9d188
[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 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 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 i_img - used to represent an image
74
75 =item *
76
77 i_color - used to represent a color with up to 8 bits per sample.
78
79 =item *
80
81 i_fcolor - used to represent a color with a double per sample.
82
83 =item *
84
85 i_fill_t - an abstract fill
86
87 =back
88
89 At this point there is no consolidated font object type, and hence the
90 font functions are not visible through Imager's API.
91
92 =head2 i_img - images
93
94 This contains the dimensions of the image (C<xsize>, C<ysize>,
95 C<channels>), image metadata (C<ch_mask>, C<bits>, C<type>,
96 C<virtual>), potentially image data (C<idata>) and the a function
97 table, with pointers to functions to perform various low level image
98 operations.
99
100 The only time you should directly write to any value in this type is
101 if you're implementing your own image type.
102
103 The typemap includes type names Imager and Imager::ImgRaw as typedefs
104 for C<i_img *>.
105
106 For incoming parameters the typemap will accept either Imager or
107 Imager::ImgRaw objects.
108
109 For return values the typemap will produce a full Imager object for an
110 Imager return type and a raw image object for an Imager::ImgRaw return
111 type.
112
113 =head2 C<i_color> - 8-bit color
114
115 Represents an 8-bit per sample color.  This is a union containing
116 several different structs for access to components of a color:
117
118 =over
119
120 =item *
121
122 C<gray> - single member C<gray_color>.
123
124 =item *
125
126 C<rgb> - C<r>, C<g>, C<b> members.
127
128 =item *
129
130 C<rgba> - C<r>, C<g>, C<b>, C<a> members.
131
132 =item *
133
134 C<channels> - array of channels.
135
136 =back
137
138 Use Imager::Color for parameter and return value types.
139
140 =head2 C<i_fcolor> - floating point color
141
142 Similar to C<i_color> except that each component is a double instead of
143 an unsigned char.
144
145 Use Imager::Color::Float for parameter and return value types.
146
147 =head2 C<i_fill_t> - fill objects
148
149 Abstract type containing pointers called to perform low level fill
150 operations.
151
152 Unless you're defining your own fill objects you should treat this as
153 an opaque type.
154
155 Use Imager::FillHandle for parameter and return value types.  At the
156 Perl level this is stored in the C<fill> member of the Perl level
157 Imager::Fill object.
158
159 =head1 Create an XS module using the Imager API
160
161 =head2 Foo.pm
162
163 Load Imager:
164
165   use Imager 0.48;
166
167 and bootstrap your XS code - see L<XSLoader> or L<DynaLoader>.
168
169 =head2 C<Foo.xs>
170
171 You'll need the following in your XS source:
172
173 =over
174
175 =item *
176
177 include the Imager external API header, and the perl interface header:
178
179   #include "imext.h"
180   #include "imperl.h"
181
182 =item *
183
184 create the variables used to hold the callback table:
185
186   DEFINE_IMAGER_CALLBACKS;
187
188 =item *
189
190 initialize the callback table in your C<BOOT> code:
191
192   BOOT:
193     PERL_INITIALIZE_IMAGER_CALLBACKS;
194
195 From Imager 0.91 you can supply your module name to improve error
196 reporting:
197
198   BOOT:
199     PERL_INITIALIZE_IMAGER_CALLBACKS_NAME("My::Module");
200
201 =back
202
203 =head2 foo.c
204
205 In any other source files where you want to access the Imager API,
206 you'll need to:
207
208 =over
209
210 =item *
211
212 include the Imager external API header:
213
214   #include "imext.h"
215
216 =back
217
218 =head2 C<Makefile.PL>
219
220 If you're creating an XS module that depends on Imager's API your
221 C<Makefile.PL> will need to do the following:
222
223 =over
224
225 =item *
226
227 C<use Imager::ExtUtils;>
228
229 =item *
230
231 include Imager's include directory in INC:
232
233   INC => Imager::ExtUtils->includes
234
235 =item *
236
237 use Imager's typemap:
238
239   TYPEMAPS => [ Imager::ExtUtils->typemap ]
240
241 =item *
242
243 include Imager 0.48 as a PREREQ_PM:
244
245    PREREQ_PM =>
246    {
247     Imager => 0.48,
248    },
249
250 =item *
251
252 Since you use Imager::ExtUtils in C<Makefile.PL> (or C<Build.PL>) you
253 should include Imager in your configure_requires:
254
255    META_MERGE =>
256    {
257      configure_requires => { Imager => "0.48" }
258    },
259
260 =back
261
262 =head1 AUTHOR
263
264 Tony Cook <tonyc@cpan.org>
265
266 =head1 SEE ALSO
267
268 Imager, Imager::ExtUtils, Imager::APIRef, Imager::Inline
269
270 =cut