- start of external Imager API access:
[imager.git] / lib / Imager / API.pm
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     PERL_INITIALIZE_IMAGER_CALLBACKS;
18   
19
20 =head1 DESCRIPTION
21
22 The API allows you to access Imager functions at the C level from XS
23 and from Inline::C.
24
25 The intent is to allow users to:
26
27 =over
28
29 =item *
30
31 write C code that does Imager operations the user might do from Perl,
32 but faster, for example, the Imager::CountColor example.
33
34 =item *
35
36 write C code that implements an application specific version of some
37 core Imager object, for example, Imager::SDL.
38
39 =item *
40
41 write C code that hooks into Imagers existing methods, such as filter
42 or file format handlers.
43
44 =back
45
46 See L<Imager::Inline> for information on using Imager's Inline::C
47 support.
48
49 =head1 Types
50
51 The API makes the following types visible:
52
53 =over
54
55 =item *
56
57 i_img - used to represent an image
58
59 =item *
60
61 i_color - used to represent a color with up to 8 bits per sample.
62
63 =item *
64
65 i_fcolor - used to represent a color with a double per sample.
66
67 =item *
68
69 i_fill_t - an abstract fill
70
71 =back
72
73 At this point there is no consolidated font object type, and hence the
74 font functions are not visible through Imager's API.
75
76 =head2 i_img - images
77
78 This contains the dimensions of the image (xsize, ysize, channels),
79 image metadata (ch_mask, bits, type, virtual), potentially image data
80 (idata) and the a function table, with pointers to functions to
81 perform various low level image operations.
82
83 The only time you should directly write to any value in this type is
84 if you're implementing your own image type.
85
86 =head2 i_color - 8-bit color
87
88 Represents an 8-bit per sample color.  This is a union containing
89 several different structs for access to components of a color:
90
91 =over
92
93 =item *
94
95 gray - single member gray_color.
96
97 =item *
98
99 rgb - r, g, b members.
100
101 =item *
102
103 rgba - r, g, b, a members.
104
105 =item *
106
107 channels - array of channels.
108
109 =back
110
111 =head2 i_fcolor - floating point color
112
113 Similar to i_fcolor except that each component is a double instead of
114 an unsigned char.
115
116 =head2 i_fill_t - fill objects
117
118 Abstract type containing pointers called to perform low level fill
119 operations.
120
121 Unless you're defining your own fill objects you should treat this as
122 an opaque type.
123
124 =head1 Create an XS module using the Imager API
125
126 =head2 Foo.xs
127
128 You'll need the following in your XS source:
129
130 =over
131
132 =item *
133
134 include the Imager external API header, and the perl interface header:
135
136   #include "imext.h"
137   #include "imperl.h"
138
139 =item *
140
141 create the variables used to hold the callback table:
142
143   DEFINE_IMAGER_CALLBACKS;
144
145 =item *
146
147 initialize the callback table in your BOOT code:
148
149   BOOT:
150     PERL_INITIALIZE_IMAGER_CALLBACKS;
151
152 =back
153
154 =head2 foo.c
155
156 In any other source files where you want to access the Imager API,
157 you'll need to:
158
159 =over
160
161 =item *
162
163 include the Imager external API header:
164
165   #include "imext.h"
166
167 =back
168
169 =head2 Makefile.PL
170
171 If you're creating an XS module that depends on Imager's API your
172 Makefile.PL will need to do the following:
173
174 =over
175
176 =item *
177
178 C<use Imager::ExtUtils;>
179
180 =item *
181
182 include Imager's include directory in INC:
183
184   INC => Imager::ExtUtils->includes
185
186 =item *
187
188 use Imager's typemap:
189
190   TYPEMAPS => [ Imager::ExtUtils->typemap ]
191
192 =item *
193
194 include Imager 0.48 as a PREREQ_PM:
195
196    PREREQ_PM =>
197    {
198     Imager => 0.48,
199    },
200
201 =back
202
203 =head1 AUTHOR
204
205 Tony Cook <tony@imager.perl.org>
206
207 =head1 SEE ALSO
208
209 Imager, Imager::ExtUtils, Imager::APIRef, Imager::Inline
210
211 =cut