Imager::API - Imager's C API - introduction. |
Imager::API - Imager's C API - introduction.
#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");
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 the Imager::Inline manpage for information on using Imager's Inline::C support.
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.
This contains the dimensions of the image (xsize
, ysize
,
channels
), image metadata (ch_mask
, bits
, type
,
virtual
), potentially image data (idata
) and 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.
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
.
rgb
- r
, g
, b
members.
rgba
- r
, g
, b
, a
members.
channels
- array of channels.
Use Imager::Color
for parameter and return value types.
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.
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.
i_io_glue_t
is Imager's I/O abstraction.
Historically named io_glue
, and this name is available for backward
compatibility.
This new type is an opaque type that stores Imager's per-thread state, including the error message stack, the current log file state and image size file limits.
While Imager's internal typemap provides a T_PTROBJ
mapping and a
DESTROY method for this type you must never return objects of this
type back to perl.
See Context objects for more information.
Represents a single polygon supplied to i_poly_poly_aa()
and
i_poly_poly_aa_cfill().
This is a structure with 3 members:
x
, y
- pointers to the first elements of arrays of doubles that define
the vertices of the polygon.
count
- the number of values in each of the x
and y
arrays.
An enumerated type of the possible fill modes for polygons:
i_pfm_evenodd
- if areas overlap an odd number of times, they
are filled, and are otherwise unfilled.
i_pfm_nonzero
- areas that have an unbalanced clockwise and
anti-clockwise boundary are filled. This is the same as
WindingRule
for X and WINDING
for Win32 GDI.
Load Imager:
use Imager 0.48;
and bootstrap your XS code - see XSLoader or the DynaLoader manpage.
Foo.xs
You'll need the following in your XS source:
#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: PERL_INITIALIZE_IMAGER_CALLBACKS;
From Imager 0.91 you can supply your module name to improve error reporting:
BOOT: PERL_INITIALIZE_IMAGER_CALLBACKS_NAME("My::Module");
In any other source files where you want to access the Imager API, you'll need to:
#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->includesuse 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:
META_MERGE => { configure_requires => { Imager => "0.48" } },
Starting with Imager 0.93, Imager keeps some state per-thread rather than storing it in global (or static) variables. The intent is to improve support for multi-threaded perl programs.
For the typical XS or Inline::C module using Imager's API this won't matter - the changes are hidden behind macros and rebuilding your module should require no source code changes.
Some operations will be slightly slower, these include:
You can avoid this fairly minor overhead by adding a #define
:
#define IMAGER_NO_CONTEXT
before including any Imager header files, but you will need to manage context objects yourself.
Some functions and macros that are available without
IMAGER_NO_CONTEXT
are not available with it defined, these are:
mm_log()
- to avoid using a different context object for the line
header and the line text you need to use im_log()
instead, with a
context object visible in scope.
aIMCTX
With IMAGER_NO_CONTEXT
defined, aIMCTX
refers to the locally
defined context object, either via one the of the dIMCTX
macros or
as a parameter with the pIMCTX
macro.
Without IMAGER_NO_CONTEXT
, aIMCTX
is a call to
im_get_context()
which retrieves the context object for the current
thread.
There is no aIMCTX_
macro, any Imager function that can accept a
context parameter always accepts it.
pIMCTX
This macro declares a variable of type im_context_t that's
accessible via the aIMCTX
macro. This is intended for use as a
parameter declaration for functions:
void f(pIMCTX) { ... use aIMCTX here }
void g(...) { ... f(aIMCTX); }
dIMCTX
Defines a local context variable and initializes it via im_get_context().
dIMCTXim
Defines a local context variable and initializes it from the context stored in an image object, eg:
void f(i_img *im) { dIMCTXim(im); ... }
dIMCTXio
Defines a local context variable and initializes it from the context stored in an I/O object object.
void f(i_io_glue_t *io) { dIMCTXio(io); ... }
dIMCTXctx
Defines a local context variable accessible via aIMCTX
in terms of
an expression you supply:
void f(my_object *p) { dIMCTXctx(p->context); ... }
This can be used to define your own local context macro:
#define dIMCTXmine(mine) ((mine)->context)
void f(my_object *p) { dIMCTXmine(p); ... }
Since some libraries are not thread safe, Imager's API includes some simple mutex functions.
To create a mutex:
i_mutex_t m = i_mutex_new();
To control or lock the mutex:
i_mutex_lock(m);
To release or unlock the mutex:
i_mutex_unlock(m);
To free any resources used by the mutex:
i_mutex_destroy(m);
I most cases where you'd use these functions, your code would create the mutex in your BOOT section, then lock and unlock the mutex as needed to control access to the library.
To avoid abstracting the platform TLS and thread clean up handling, Imager provides simple APIs for storing per-context information.
To allocate a slot:
im_slot_t slot = im_context_slot_new(callback)
where callback is a (possibly NULL) function pointer called when the context object is destroyed.
By default, the stored value for a slot is NULL, whether for a new context or for a cloned context.
To store a value:
im_context_slot_set(aIMCTX, slot, somevalue);
where somevalue
can be represented as a void *
.
To retrieve the value:
value = im_context_slot_get(aIMCTX, slot);
Tony Cook <tonyc@cpan.org>
Imager, Imager::ExtUtils, Imager::APIRef, Imager::Inline
Imager::API - Imager's C API - introduction. |