Imager::API(3pm)
NAME
Imager::API - Imager's C API - introduction.
SYNOPSIS
#include "imext.h" #include "imperl.h" DEFINE_IMAGER_CALLBACKS; MODULE = Your::Module PACKAGE = Your::Module ... BOOT: PERL_INITIALIZE_IMAGER_CALLBACKS;
DESCRIPTION
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:
- o write C code that does Imager operations the user might do from
- Perl, but faster, for example, the Imager::CountColor example.
- o write C code that implements an application specific version of
- some core Imager object, for example, Imager::SDL.
- o 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.
Beware
- o don't return an object you received as a parameter - this will
- cause the object to be freed twice.
Types
The API makes the following types visible:
o i_img - used to represent an image
o i_color - used to represent a color with up to 8 bits per sample.
o i_fcolor - used to represent a color with a double per sample.
o 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.
- i_img - images
- 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. - 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 *". - 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" - 8-bit color
- Represents an 8-bit per sample color. This is a union containing
several different structs for access to components of a color: - o "gray" - single member "gray_color".
- o "rgb" - "r", "g", "b" members.
- o "rgba" - "r", "g", "b", "a" members.
- o "channels" - array of channels.
- Use Imager::Color for parameter and return value types.
- "i_fcolor" - floating point color
- 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" - fill objects
- 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.
Create an XS module using the Imager API
- Foo.pm
- 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:
- o include the Imager external API header, and the perl interface
header:
#include "imext.h"
#include "imperl.h"o create the variables used to hold the callback table:
DEFINE_IMAGER_CALLBACKS;o initialize the callback table in your "BOOT" code:
BOOT:PERL_INITIALIZE_IMAGER_CALLBACKS; - foo.c
- In any other source files where you want to access the Imager API,
you'll need to: - o 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: - o "use Imager::ExtUtils;"
- o include Imager's include directory in INC:
INC => Imager::ExtUtils->includes - o use Imager's typemap:
TYPEMAPS => [ Imager::ExtUtils->typemap ] - o include Imager 0.48 as a PREREQ_PM:
PREREQ_PM =>
{Imager => 0.48,}, - o Since you use Imager::ExtUtils in "Makefile.PL" (or "Build.PL") you
should include Imager in your configure_requires:
META_MERGE =>
{configure_requires => { Imager => "0.48" }},
AUTHOR
Tony Cook <tony@imager.perl.org>
SEE ALSO
- Imager, Imager::ExtUtils, Imager::APIRef, Imager::Inline