...
BOOT:
+ /* any release with the API */
PERL_INITIALIZE_IMAGER_CALLBACKS;
+ /* preferred from Imager 0.91 */
+ PERL_INITIALIZE_IMAGER_CALLBACKS_NAME("My::Module");
=head1 DESCRIPTION
=for stopwords XS
The API allows you to access Imager functions at the C level from XS
-and from Inline::C.
+and from C<Inline::C>.
The intent is to allow users to:
=item *
write C code that does Imager operations the user might do from Perl,
-but faster, for example, the Imager::CountColor example.
+but faster, for example, the L<Imager::CountColor> example.
=item *
=item *
-i_img - used to represent an image
+L</i_img> - used to represent an image
=item *
-i_color - used to represent a color with up to 8 bits per sample.
+L</i_color> - used to represent a color with up
+to 8 bits per sample.
=item *
-i_fcolor - used to represent a color with a double per sample.
+L</i_fcolor> - used to represent
+a color with a double per sample.
=item *
-i_fill_t - an abstract fill
+L</i_fill_t> - fill objects>> - an abstract fill
+
+=item *
+
+L</im_context_t> - Imager's per-thread state.
=back
At this point there is no consolidated font object type, and hence the
font functions are not visible through Imager's API.
-=head2 i_img - images
+=head2 i_img
This contains the dimensions of the image (C<xsize>, C<ysize>,
C<channels>), image metadata (C<ch_mask>, C<bits>, C<type>,
-C<virtual>), potentially image data (C<idata>) and the a function
-table, with pointers to functions to perform various low level image
+C<virtual>), potentially image data (C<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
Imager return type and a raw image object for an Imager::ImgRaw return
type.
-=head2 C<i_color> - 8-bit color
+=head2 i_color
Represents an 8-bit per sample color. This is a union containing
several different structs for access to components of a color:
=back
-Use Imager::Color for parameter and return value types.
+Use C<Imager::Color> for parameter and return value types.
-=head2 C<i_fcolor> - floating point color
+=head2 i_fcolor
Similar to C<i_color> except that each component is a double instead of
an unsigned char.
Use Imager::Color::Float for parameter and return value types.
-=head2 C<i_fill_t> - fill objects
+=head2 i_fill_t
Abstract type containing pointers called to perform low level fill
operations.
Perl level this is stored in the C<fill> member of the Perl level
Imager::Fill object.
+=head2 i_io_glue_t
+
+C<i_io_glue_t> is Imager's I/O abstraction.
+
+Historically named C<io_glue>, and this name is available for backward
+compatibility.
+
+=head2 im_context_t
+
+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 C<T_PTROBJ> mapping and a
+DESTROY method for this type you B<must> never return objects of this
+type back to perl.
+
+See L</Context objects> for more information.
+
=head1 Create an XS module using the Imager API
=head2 Foo.pm
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");
+
=back
=head2 foo.c
=back
+=head1 Context objects
+
+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:
+
+=over
+
+=item *
+
+creating an image
+
+=item *
+
+reporting errors
+
+=item *
+
+creating I/O objects
+
+=item *
+
+setting/getting/testing image file limits
+
+=item *
+
+logging
+
+=back
+
+You can avoid this fairly minor overhead by adding a C<#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
+C<IMAGER_NO_CONTEXT> are not available with it defined, these are:
+
+=over
+
+=item *
+
+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.
+
+=back
+
+=head2 C<aIMCTX>
+
+With C<IMAGER_NO_CONTEXT> defined, C<aIMCTX> refers to the locally
+defined context object, either via one the of the C<dIMCTX> macros or
+as a parameter with the C<pIMCTX> macro.
+
+Without C<IMAGER_NO_CONTEXT>, C<aIMCTX> is a call to
+C<im_get_context()> which retrieves the context object for the current
+thread.
+
+There is no C<aIMCTX_> macro, any Imager function that can accept a
+context parameter always accepts it.
+
+=head2 C<pIMCTX>
+
+This macro declares a variable of type L</im_context_t> that's
+accessible via the C<aIMCTX> macro. This is intended for use as a
+parameter declaration for functions:
+
+ void f(pIMCTX) {
+ ... use aIMCTX here
+ }
+
+ void g(...) {
+ ...
+ f(aIMCTX);
+ }
+
+=head2 C<dIMCTX>
+
+Defines a local context variable and initializes it via
+L<im_get_context()|Imager::APIRef/im_get_context()>.
+
+=head2 C<dIMCTXim>
+
+Defines a local context variable and initializes it from the context
+stored in an L<image object|/i_img>, eg:
+
+ void f(i_img *im) {
+ dIMCTXim(im);
+ ...
+ }
+
+=head2 C<dIMCTXio>
+
+Defines a local context variable and initializes it from the context
+stored in an L<I/O object|/i_io_glue_t> object.
+
+ void f(i_io_glue_t *io) {
+ dIMCTXio(io);
+ ...
+ }
+
+=head2 C<dIMCTXctx>
+
+Defines a local context variable accessible via C<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);
+ ...
+ }
+
+=head1 Mutex Functions
+
+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.
+
+=head1 Context slots
+
+=for stopwords
+TLS APIs
+
+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 C<somevalue> can be represented as a C<void *>.
+
+To retrieve the value:
+
+ value = im_context_slot_get(aIMCTX, slot);
+
=head1 AUTHOR
-Tony Cook <tony@imager.perl.org>
+Tony Cook <tonyc@cpan.org>
=head1 SEE ALSO
projects / imager.git / blobdiff