Tony Cook > Imager-0.93 > Imager::API


Annotate this POD



New  44
Open  17
View/Report Bugs
Source   Latest Release: Imager-0.99_01


Imager::API - Imager's C API - introduction.


  #include "imext.h"
  #include "imperl.h"


  MODULE = Your::Module  PACKAGE = Your::Module


    /* any release with the API */
    /* preferred from Imager 0.91 */


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:

See Imager::Inline for information on using Imager's Inline::C support.

Beware ^

Types ^

The API makes the following types visible:

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:

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 ^

Load Imager:

  use Imager 0.48;

and bootstrap your XS code - see XSLoader or DynaLoader.


You'll need the following in your XS source:


In any other source files where you want to access the Imager API, you'll need to:


If you're creating an XS module that depends on Imager's API your Makefile.PL will need to do the following:


Tony Cook <>


Imager, Imager::ExtUtils, Imager::APIRef, Imager::Inline

syntax highlighting: