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