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