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.xs
 156
 157 You'll need the following in your XS source:
 158
 159 =over
 160
 161 =item *
 162
 163 include the Imager external API header, and the perl interface header:
 164
 165   #include "imext.h"
 166   #include "imperl.h"
 167
 168 =item *
 169
 170 create the variables used to hold the callback table:
 171
 172   DEFINE_IMAGER_CALLBACKS;
 173
 174 =item *
 175
 176 initialize the callback table in your BOOT code:
 177
 178   BOOT:
 179     PERL_INITIALIZE_IMAGER_CALLBACKS;
 180
 181 =back
 182
 183 =head2 foo.c
 184
 185 In any other source files where you want to access the Imager API,
 186 you'll need to:
 187
 188 =over
 189
 190 =item *
 191
 192 include the Imager external API header:
 193
 194   #include "imext.h"
 195
 196 =back
 197
 198 =head2 Makefile.PL
 199
 200 If you're creating an XS module that depends on Imager's API your
 201 Makefile.PL will need to do the following:
 202
 203 =over
 204
 205 =item *
 206
 207 C<use Imager::ExtUtils;>
 208
 209 =item *
 210
 211 include Imager's include directory in INC:
 212
 213   INC => Imager::ExtUtils->includes
 214
 215 =item *
 216
 217 use Imager's typemap:
 218
 219   TYPEMAPS => [ Imager::ExtUtils->typemap ]
 220
 221 =item *
 222
 223 include Imager 0.48 as a PREREQ_PM:
 224
 225    PREREQ_PM =>
 226    {
 227     Imager => 0.48,
 228    },
 229
 230 =back
 231
 232 =head1 AUTHOR
 233
 234 Tony Cook <tony@imager.perl.org>
 235
 236 =head1 SEE ALSO
 237
 238 Imager, Imager::ExtUtils, Imager::APIRef, Imager::Inline
 239
 240 =cut