.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Imager::API 3pm"
.TH Imager::API 3pm "2012-05-24" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Imager::API \- Imager's C API \- introduction.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  #include "imext.h"
\&  #include "imperl.h"
\&
\&  DEFINE_IMAGER_CALLBACKS;
\&
\&  MODULE = Your::Module  PACKAGE = Your::Module
\&
\&  ...
\&
\&  BOOT:
\&    /* any release with the API */
\&    PERL_INITIALIZE_IMAGER_CALLBACKS;
\&    /* preferred from Imager 0.91 */
\&    PERL_INITIALIZE_IMAGER_CALLBACKS_NAME("My::Module");
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \s-1API\s0 allows you to access Imager functions at the C level from \s-1XS\s0
and from Inline::C.
.PP
The intent is to allow users to:
.IP "\(bu" 4
write C code that does Imager operations the user might do from Perl,
but faster, for example, the Imager::CountColor example.
.IP "\(bu" 4
write C code that implements an application specific version of some
core Imager object, for example, Imager::SDL.
.IP "\(bu" 4
write C code that hooks into Imager's existing methods, such as filter
or file format handlers.
.PP
See Imager::Inline for information on using Imager's Inline::C
support.
.SH "Beware"
.IX Header "Beware"
.IP "\(bu" 4
don't return an object you received as a parameter \- this will cause
the object to be freed twice.
.SH "Types"
.IX Header "Types"
The \s-1API\s0 makes the following types visible:
.IP "\(bu" 4
i_img \- used to represent an image
.IP "\(bu" 4
i_color \- used to represent a color with up to 8 bits per sample.
.IP "\(bu" 4
i_fcolor \- used to represent a color with a double per sample.
.IP "\(bu" 4
i_fill_t \- an abstract fill
.PP
At this point there is no consolidated font object type, and hence the
font functions are not visible through Imager's \s-1API\s0.
.SS "i_img \- images"
.IX Subsection "i_img - images"
This contains the dimensions of the image (\f(CW\*(C`xsize\*(C'\fR, \f(CW\*(C`ysize\*(C'\fR,
\&\f(CW\*(C`channels\*(C'\fR), image metadata (\f(CW\*(C`ch_mask\*(C'\fR, \f(CW\*(C`bits\*(C'\fR, \f(CW\*(C`type\*(C'\fR,
\&\f(CW\*(C`virtual\*(C'\fR), potentially image data (\f(CW\*(C`idata\*(C'\fR) and the a function
table, with pointers to functions to perform various low level image
operations.
.PP
The only time you should directly write to any value in this type is
if you're implementing your own image type.
.PP
The typemap includes type names Imager and Imager::ImgRaw as typedefs
for \f(CW\*(C`i_img *\*(C'\fR.
.PP
For incoming parameters the typemap will accept either Imager or
Imager::ImgRaw objects.
.PP
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.
.ie n .SS """i_color"" \- 8\-bit color"
.el .SS "\f(CWi_color\fP \- 8\-bit color"
.IX Subsection "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:
.IP "\(bu" 4
\&\f(CW\*(C`gray\*(C'\fR \- single member \f(CW\*(C`gray_color\*(C'\fR.
.IP "\(bu" 4
\&\f(CW\*(C`rgb\*(C'\fR \- \f(CW\*(C`r\*(C'\fR, \f(CW\*(C`g\*(C'\fR, \f(CW\*(C`b\*(C'\fR members.
.IP "\(bu" 4
\&\f(CW\*(C`rgba\*(C'\fR \- \f(CW\*(C`r\*(C'\fR, \f(CW\*(C`g\*(C'\fR, \f(CW\*(C`b\*(C'\fR, \f(CW\*(C`a\*(C'\fR members.
.IP "\(bu" 4
\&\f(CW\*(C`channels\*(C'\fR \- array of channels.
.PP
Use Imager::Color for parameter and return value types.
.ie n .SS """i_fcolor"" \- floating point color"
.el .SS "\f(CWi_fcolor\fP \- floating point color"
.IX Subsection "i_fcolor - floating point color"
Similar to \f(CW\*(C`i_color\*(C'\fR except that each component is a double instead of
an unsigned char.
.PP
Use Imager::Color::Float for parameter and return value types.
.ie n .SS """i_fill_t"" \- fill objects"
.el .SS "\f(CWi_fill_t\fP \- fill objects"
.IX Subsection "i_fill_t - fill objects"
Abstract type containing pointers called to perform low level fill
operations.
.PP
Unless you're defining your own fill objects you should treat this as
an opaque type.
.PP
Use Imager::FillHandle for parameter and return value types.  At the
Perl level this is stored in the \f(CW\*(C`fill\*(C'\fR member of the Perl level
Imager::Fill object.
.SH "Create an XS module using the Imager API"
.IX Header "Create an XS module using the Imager API"
.SS "Foo.pm"
.IX Subsection "Foo.pm"
Load Imager:
.PP
.Vb 1
\&  use Imager 0.48;
.Ve
.PP
and bootstrap your \s-1XS\s0 code \- see XSLoader or DynaLoader.
.ie n .SS """Foo.xs"""
.el .SS "\f(CWFoo.xs\fP"
.IX Subsection "Foo.xs"
You'll need the following in your \s-1XS\s0 source:
.IP "\(bu" 4
include the Imager external \s-1API\s0 header, and the perl interface header:
.Sp
.Vb 2
\&  #include "imext.h"
\&  #include "imperl.h"
.Ve
.IP "\(bu" 4
create the variables used to hold the callback table:
.Sp
.Vb 1
\&  DEFINE_IMAGER_CALLBACKS;
.Ve
.IP "\(bu" 4
initialize the callback table in your \f(CW\*(C`BOOT\*(C'\fR code:
.Sp
.Vb 2
\&  BOOT:
\&    PERL_INITIALIZE_IMAGER_CALLBACKS;
.Ve
.Sp
From Imager 0.91 you can supply your module name to improve error
reporting:
.Sp
.Vb 2
\&  BOOT:
\&    PERL_INITIALIZE_IMAGER_CALLBACKS_NAME("My::Module");
.Ve
.SS "foo.c"
.IX Subsection "foo.c"
In any other source files where you want to access the Imager \s-1API\s0,
you'll need to:
.IP "\(bu" 4
include the Imager external \s-1API\s0 header:
.Sp
.Vb 1
\&  #include "imext.h"
.Ve
.ie n .SS """Makefile.PL"""
.el .SS "\f(CWMakefile.PL\fP"
.IX Subsection "Makefile.PL"
If you're creating an \s-1XS\s0 module that depends on Imager's \s-1API\s0 your
\&\f(CW\*(C`Makefile.PL\*(C'\fR will need to do the following:
.IP "\(bu" 4
\&\f(CW\*(C`use Imager::ExtUtils;\*(C'\fR
.IP "\(bu" 4
include Imager's include directory in \s-1INC:\s0
.Sp
.Vb 1
\&  INC => Imager::ExtUtils\->includes
.Ve
.IP "\(bu" 4
use Imager's typemap:
.Sp
.Vb 1
\&  TYPEMAPS => [ Imager::ExtUtils\->typemap ]
.Ve
.IP "\(bu" 4
include Imager 0.48 as a \s-1PREREQ_PM:\s0
.Sp
.Vb 4
\&   PREREQ_PM =>
\&   {
\&    Imager => 0.48,
\&   },
.Ve
.IP "\(bu" 4
Since you use Imager::ExtUtils in \f(CW\*(C`Makefile.PL\*(C'\fR (or \f(CW\*(C`Build.PL\*(C'\fR) you
should include Imager in your configure_requires:
.Sp
.Vb 4
\&   META_MERGE =>
\&   {
\&     configure_requires => { Imager => "0.48" }
\&   },
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Tony Cook <tonyc@cpan.org>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Imager, Imager::ExtUtils, Imager::APIRef, Imager::Inline