Imager::API - Imager's C API - introduction.
#include "imext.h" #include "imperl.h" DEFINE_IMAGER_CALLBACKS; MODULE = Your::Module PACKAGE = Your::Module ... BOOT: PERL_INITIALIZE_IMAGER_CALLBACKS;
The API allows you to access Imager functions at the C level from XS and from Inline::C.
The intent is to allow users to:
write C code that does Imager operations the user might do from Perl, but faster, for example, the Imager::CountColor example.
write C code that implements an application specific version of some core Imager object, for example, Imager::SDL.
write C code that hooks into Imager's existing methods, such as filter or file format handlers.
See Imager::Inline for information on using Imager's Inline::C support.
don't return an object you received as a parameter - this will cause the object to be freed twice.
The API makes the following types visible:
i_img - used to represent an image
i_color - used to represent a color with up to 8 bits per sample.
i_fcolor - used to represent a color with a double per sample.
i_fill_t - an abstract fill
At this point there is no consolidated font object type, and hence the font functions are not visible through Imager's API.
This contains the dimensions of the image (xsize, ysize, channels), image metadata (ch_mask, bits, type, virtual), potentially image data (idata) and the a function table, with pointers to functions to perform various low level image operations.
xsize
ysize
channels
ch_mask
bits
type
virtual
idata
The only time you should directly write to any value in this type is if you're implementing your own image type.
The typemap includes type names Imager and Imager::ImgRaw as typedefs for i_img *.
i_img *
For incoming parameters the typemap will accept either Imager or Imager::ImgRaw objects.
For return values the typemap will produce a full Imager object for an Imager return type and a raw image object for an Imager::ImgRaw return type.
i_color
Represents an 8-bit per sample color. This is a union containing several different structs for access to components of a color:
gray - single member gray_color.
gray
gray_color
rgb - r, g, b members.
rgb
r
g
b
rgba - r, g, b, a members.
rgba
a
channels - array of channels.
Use Imager::Color for parameter and return value types.
i_fcolor
Similar to i_color except that each component is a double instead of an unsigned char.
Use Imager::Color::Float for parameter and return value types.
i_fill_t
Abstract type containing pointers called to perform low level fill operations.
Unless you're defining your own fill objects you should treat this as an opaque type.
Use Imager::FillHandle for parameter and return value types. At the Perl level this is stored in the fill member of the Perl level Imager::Fill object.
fill
Load Imager:
use Imager 0.48;
and bootstrap your XS code - see XSLoader or DynaLoader.
Foo.xs
You'll need the following in your XS source:
include the Imager external API header, and the perl interface header:
#include "imext.h" #include "imperl.h"
create the variables used to hold the callback table:
DEFINE_IMAGER_CALLBACKS;
initialize the callback table in your BOOT code:
BOOT
BOOT: PERL_INITIALIZE_IMAGER_CALLBACKS;
In any other source files where you want to access the Imager API, you'll need to:
include the Imager external API header:
#include "imext.h"
Makefile.PL
If you're creating an XS module that depends on Imager's API your Makefile.PL will need to do the following:
use Imager::ExtUtils;
include Imager's include directory in INC:
INC => Imager::ExtUtils->includes
use Imager's typemap:
TYPEMAPS => [ Imager::ExtUtils->typemap ]
include Imager 0.48 as a PREREQ_PM:
PREREQ_PM => { Imager => 0.48, },
Since you use Imager::ExtUtils in Makefile.PL (or Build.PL) you should include Imager in your configure_requires:
Build.PL
META_MERGE => { configure_requires => { Imager => "0.48" } },
Tony Cook <tony@imager.perl.org>
Imager, Imager::ExtUtils, Imager::APIRef, Imager::Inline
To install Imager, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Imager
CPAN shell
perl -MCPAN -e shell install Imager
For more information on module installation, please visit the detailed CPAN module installation guide.