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 Imager's existing methods, such as
34           filter 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       This contains the dimensions of the image ("xsize", "ysize",
58       "channels"), image metadata ("ch_mask", "bits", "type", "virtual"),
59       potentially image data ("idata") and the a function table, with
60       pointers to functions to perform various low level image operations.
61
62       The only time you should directly write to any value in this type is if
63       you're implementing your own image type.
64
65       The typemap includes type names Imager and Imager::ImgRaw as typedefs
66       for "i_img *".
67
68       For incoming parameters the typemap will accept either Imager or
69       Imager::ImgRaw objects.
70
71       For return values the typemap will produce a full Imager object for an
72       Imager return type and a raw image object for an Imager::ImgRaw return
73       type.
74
75   "i_color" - 8-bit color
76       Represents an 8-bit per sample color.  This is a union containing
77       several different structs for access to components of a color:
78
79       ·   "gray" - single member "gray_color".
80
81       ·   "rgb" - "r", "g", "b" members.
82
83       ·   "rgba" - "r", "g", "b", "a" members.
84
85       ·   "channels" - array of channels.
86
87       Use Imager::Color for parameter and return value types.
88
89   "i_fcolor" - floating point color
90       Similar to "i_color" except that each component is a double instead of
91       an unsigned char.
92
93       Use Imager::Color::Float for parameter and return value types.
94
95   "i_fill_t" - fill objects
96       Abstract type containing pointers called to perform low level fill
97       operations.
98
99       Unless you're defining your own fill objects you should treat this as
100       an opaque type.
101
102       Use Imager::FillHandle for parameter and return value types.  At the
103       Perl level this is stored in the "fill" member of the Perl level
104       Imager::Fill object.
105

Create an XS module using the Imager API

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

AUTHOR

170       Tony Cook <tonyc@cpan.org>
171