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