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           PERL_INITIALIZE_IMAGER_CALLBACKS;
20

DESCRIPTION

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       ·   write C code that does Imager operations the user might do from
28           Perl, but faster, for example, the Imager::CountColor example.
29
30       ·   write C code that implements an application specific version of
31           some core Imager object, for example, Imager::SDL.
32
33       ·   write C code that hooks into Imagers existing methods, such as fil‐
34           ter or file format handlers.
35
36       See Imager::Inline for information on using Imager's Inline::C support.
37

Beware

39       ·   don't return an object you received as a parameter - this will
40           cause the object to be freed twice.
41

Types

43       The API makes the following types visible:
44
45       ·   i_img - used to represent an image
46
47       ·   i_color - used to represent a color with up to 8 bits per sample.
48
49       ·   i_fcolor - used to represent a color with a double per sample.
50
51       ·   i_fill_t - an abstract fill
52
53       At this point there is no consolidated font object type, and hence the
54       font functions are not visible through Imager's API.
55
56       i_img - images
57
58       This contains the dimensions of the image (xsize, ysize, channels),
59       image metadata (ch_mask, bits, type, virtual), potentially image data
60       (idata) and the a function table, with pointers to functions to perform
61       various low level image operations.
62
63       The only time you should directly write to any value in this type is if
64       you're implementing your own image type.
65
66       The typemap includes typenames Imager and Imager::ImgRaw as typedefs
67       for "i_img *".
68
69       For incoming parameters the typemap will accept either Imager or
70       Imager::ImgRaw objects.
71
72       For return values the typemap will produce a full Imager object for an
73       Imager return type and a raw image object for an Imager::ImgRaw return
74       type.
75
76       i_color - 8-bit color
77
78       Represents an 8-bit per sample color.  This is a union containing sev‐
79       eral different structs for access to components of a color:
80
81       ·   gray - single member gray_color.
82
83       ·   rgb - r, g, b members.
84
85       ·   rgba - r, g, b, a members.
86
87       ·   channels - array of channels.
88
89       Use Imager::Color for parameter and return value types.
90
91       i_fcolor - floating point color
92
93       Similar to i_color except that each component is a double instead of an
94       unsigned char.
95
96       Use Imager::Color::Float for parameter and return value types.
97
98       i_fill_t - fill objects
99
100       Abstract type containing pointers called to perform low level fill
101       operations.
102
103       Unless you're defining your own fill objects you should treat this as
104       an opaque type.
105
106       Use Imager::FillHandle for parameter and return value types.  At the
107       Perl level this is stored in the "fill" member of the Perl level
108       Imager::Fill object.
109

Create an XS module using the Imager API

111       Foo.pm
112
113       Load Imager:
114
115         use Imager 0.48;
116
117       and bootstrap your XS code - see XSLoader or DynaLoader.
118
119       Foo.xs
120
121       You'll need the following in your XS source:
122
123       ·   include the Imager external API header, and the perl interface
124           header:
125
126             #include "imext.h"
127             #include "imperl.h"
128
129       ·   create the variables used to hold the callback table:
130
131             DEFINE_IMAGER_CALLBACKS;
132
133       ·   initialize the callback table in your BOOT code:
134
135             BOOT:
136               PERL_INITIALIZE_IMAGER_CALLBACKS;
137
138       foo.c
139
140       In any other source files where you want to access the Imager API,
141       you'll need to:
142
143       ·   include the Imager external API header:
144
145             #include "imext.h"
146
147       Makefile.PL
148
149       If you're creating an XS module that depends on Imager's API your Make‐
150       file.PL will need to do the following:
151
152       ·   "use Imager::ExtUtils;"
153
154       ·   include Imager's include directory in INC:
155
156             INC => Imager::ExtUtils->includes
157
158       ·   use Imager's typemap:
159
160             TYPEMAPS => [ Imager::ExtUtils->typemap ]
161
162       ·   include Imager 0.48 as a PREREQ_PM:
163
164              PREREQ_PM =>
165              {
166               Imager => 0.48,
167              },
168

AUTHOR

170       Tony Cook <tony@imager.perl.org>
171