fill out documentation
authorTony Cook <tony@develop-help.com>
Mon, 13 Aug 2012 12:17:22 +0000 (22:17 +1000)
committerTony Cook <tony@develop-help.com>
Sat, 24 Nov 2012 03:59:25 +0000 (14:59 +1100)
16 files changed:
Changes
apidocs.perl
context.c
error.c
image.c
imext.c
img16.c
img8.c
imgdouble.c
iolayer.c
lib/Imager/API.pod
lib/Imager/APIRef.pod
limits.c
log.h
palimg.c
t/x20spell.t

diff --git a/Changes b/Changes
index 070a568..7b29d8c 100644 (file)
--- a/Changes
+++ b/Changes
@@ -1,5 +1,9 @@
 Imager release history.  Older releases can be found in Changes.old
 
+Threads work
+TODO: fill objects should refer to the contexts
+TODO: finish up doc changes
+
  - clarify the return value of getpixel();
    https://rt.cpan.org/Ticket/Display.html?id=81198
 
index 02cb99c..b96c727 100644 (file)
@@ -187,7 +187,7 @@ close OUT;
 
 
 sub make_func_list {
-  my @funcs = qw(i_img i_color i_fcolor i_fill_t mm_log i_img_color_channels i_img_has_alpha i_img_dim i_DF i_DFc i_DFp i_DFcp i_psamp_bits i_gsamp_bits i_psamp i_psampf);
+  my @funcs = qw(i_img i_color i_fcolor i_fill_t mm_log mm_log i_img_color_channels i_img_has_alpha i_img_dim i_DF i_DFc i_DFp i_DFcp i_psamp_bits i_gsamp_bits i_psamp i_psampf);
   open FUNCS, "< imexttypes.h"
     or die "Cannot open imexttypes.h: $!\n";
   my $in_struct;
index 4852bf8..08e9a4d 100644 (file)
--- a/context.c
+++ b/context.c
@@ -42,6 +42,9 @@ im_context_new(void) {
 
 /*
 =item im_context_refinc(ctx, where)
+X<im_context_refinc API>
+=section Context objects
+=synopsis im_context_refinc(aIMCTX, "a description");
 
 Add a new reference to the context.
 
@@ -59,9 +62,13 @@ im_context_refinc(im_context_t ctx, const char *where) {
 }
 
 /*
-=item im_context_refdec(ctx)
+=item im_context_refdec(ctx, where)
+X<im_context_refdec API>
+=section Context objects
+=synopsis im_context_refdec(aIMCTX, "a description");
 
-Release memory used by an Imager context object.
+Remove a reference to the context, releasing it if all references have
+been removed.
 
 =cut
 */
diff --git a/error.c b/error.c
index 1f89bb4..a782e3a 100644 (file)
--- a/error.c
+++ b/error.c
@@ -94,7 +94,9 @@ the mark.
 
 =over
 
-=item i_clear_error()
+=item im_clear_error(ctx)
+X<im_clear_error API>X<i_clear_error API>
+=synopsis im_clear_error(aIMCTX);
 =synopsis i_clear_error();
 =category Error handling
 
@@ -102,6 +104,8 @@ Clears the error stack.
 
 Called by any Imager function before doing any other processing.
 
+Also callable as C<i_clear_error()>.
+
 =cut
 */
 
@@ -122,9 +126,11 @@ im_clear_error(im_context_t ctx) {
 }
 
 /*
-=item i_push_error(int code, char const *msg)
+=item im_push_error(ctx, code, message)
+X<im_push_error API>X<i_push_error API>
 =synopsis i_push_error(0, "Yep, it's broken");
 =synopsis i_push_error(errno, "Error writing");
+=synopsis im_push_error(aIMCTX, 0, "Something is wrong");
 =category Error handling
 
 Called by an Imager function to push an error message onto the stack.
@@ -159,8 +165,11 @@ im_push_error(im_context_t ctx, int code, char const *msg) {
 }
 
 /*
-=item i_push_errorvf(int C<code>, char const *C<fmt>, va_list C<ap>)
-
+=item im_push_errorvf(ctx, code, format, args)
+X<im_push_error_vf API>X<i_push_errorvf API>
+=synopsis va_args args;
+=synopsis va_start(args, lastarg);
+=synopsis im_push_errorvf(ctx, code, format, args);
 =category Error handling
 
 Intended for use by higher level functions, takes a varargs pointer
@@ -168,6 +177,8 @@ and a format to produce the finally pushed error message.
 
 Does not support perl specific format codes.
 
+Also callable as C<i_push_errorvf(code, format, args)>
+
 =cut
 */
 void 
@@ -187,11 +198,6 @@ im_push_errorvf(im_context_t ctx, int code, char const *fmt, va_list ap) {
   im_push_error(ctx, code, buf);
 }
 
-void
-(i_push_errorvf)(int code, char const *fmt, va_list ap) {
-  im_push_errorvf(im_get_context(), code, fmt, ap);
-}
-
 /*
 =item i_push_errorf(int code, char const *fmt, ...)
 =synopsis i_push_errorf(errno, "Cannot open file %s: %d", filename, errno);
@@ -211,6 +217,17 @@ i_push_errorf(int code, char const *fmt, ...) {
   va_end(ap);
 }
 
+/*
+=item im_push_errorf(ctx, code, char const *fmt, ...)
+=synopsis im_push_errorf(aIMCTX, errno, "Cannot open file %s: %d", filename, errno);
+=category Error handling
+
+A version of im_push_error() that does printf() like formatting.
+
+Does not support perl specific format codes.
+
+=cut
+*/
 void
 im_push_errorf(im_context_t ctx, int code, char const *fmt, ...) {
   va_list ap;
diff --git a/image.c b/image.c
index 56057e8..10228d1 100644 (file)
--- a/image.c
+++ b/image.c
@@ -44,8 +44,11 @@ im_context_t (*im_get_context)(void) = NULL;
 void i_linker_bug_fake(void) { ceil(1); }
 
 /*
-=item i_img_alloc()
+=item im_img_alloc(aIMCTX)
+X<im_img_alloc API>X<i_img_alloc API>
 =category Image Implementation
+=synopsis i_img *im = im_img_alloc(aIMCTX);
+=synopsis i_img *im = i_img_alloc();
 
 Allocates a new i_img structure.
 
@@ -79,13 +82,15 @@ im_img_alloc(pIMCTX) {
 }
 
 /*
-=item i_img_init(C<img>)
+=item im_img_init(aIMCTX, image)
+X<im_img_init API>X<i_img_init API>
 =category Image Implementation
+=synopsis im_img_init(aIMCTX, im);
+=synopsis i_img_init(im);
 
 Imager internal initialization of images.
 
-Currently this does very little, in the future it may be used to
-support threads, or color profiles.
+See L</im_img_alloc(aIMCTX)> for more information.
 
 =cut
 */
diff --git a/imext.c b/imext.c
index 3f19123..24aad64 100644 (file)
--- a/imext.c
+++ b/imext.c
@@ -567,7 +567,7 @@ int
 Retrieve the context object for the current thread.
 
 Inside Imager itself this is just a function pointer, which the
-Imager.xs BOOT handler initializes for use within perl.  If you're
+F<Imager.xs> BOOT handler initializes for use within perl.  If you're
 taking the Imager code and embedding it elsewhere you need to
 initialize the C<im_get_context> pointer at some point.
 
diff --git a/img16.c b/img16.c
index dfe1613..1b3e452 100644 (file)
--- a/img16.c
+++ b/img16.c
@@ -150,15 +150,18 @@ typedef unsigned short i_sample16_t;
      ((((i_sample16_t *)(bytes))[offset]+127) / 257)
 
 /*
-=item i_img_16_new(x, y, ch)
-
+=item im_img_16_new(ctx, x, y, ch)
+X<im_img_16_new API>X<i_img_16_new API>
 =category Image creation/destruction
+=synopsis i_img *img = im_img_16_new(aIMCTX, width, height, channels);
 =synopsis i_img *img = i_img_16_new(width, height, channels);
 
 Create a new 16-bit/sample image.
 
 Returns the image on success, or NULL on failure.
 
+Also callable as C<i_img_16_new(x, y, ch)>
+
 =cut
 */
 
diff --git a/img8.c b/img8.c
index 373d5a1..c780473 100644 (file)
--- a/img8.c
+++ b/img8.c
@@ -82,10 +82,10 @@ static i_img IIM_base_8bit_direct =
   }*/
 
 /*
-=item i_img_8_new(x, y, ch)
-
+=item im_img_8_new(ctx, x, y, ch)
+X<im_img_8_new API>X<i_img_8_new API>
 =category Image creation/destruction
-
+=synopsis i_img *img = im_img_8_new(aIMCTX, width, height, channels);
 =synopsis i_img *img = i_img_8_new(width, height, channels);
 
 Creates a new image object I<x> pixels wide, and I<y> pixels high with
@@ -94,7 +94,6 @@ I<ch> channels.
 =cut
 */
 
-
 i_img *
 im_img_8_new(pIMCTX, i_img_dim x,i_img_dim y,int ch) {
   i_img *im;
index 1830c94..fdd3302 100644 (file)
@@ -92,12 +92,16 @@ static i_img IIM_base_double_direct =
 };
 
 /*
-=item i_img_double_new(i_img_dim x, i_img_dim y, int ch)
+=item im_img_double_new(ctx, x, y, ch)
+X<im_img_double_new API>X<i_img_double_new API>
 =category Image creation/destruction
+=synopsis i_img *img = im_img_double_new(aIMCTX, width, height, channels);
 =synopsis i_img *img = i_img_double_new(width, height, channels);
 
 Creates a new double per sample image.
 
+Also callable as C<i_img_double_new(width, height, channels)>.
+
 =cut
 */
 i_img *
index 18a7805..d92748a 100644 (file)
--- a/iolayer.c
+++ b/iolayer.c
@@ -154,13 +154,16 @@ static void bufchain_destroy(io_glue *ig);
  */
 
 /*
-=item io_new_bufchain(ctx)
+=item im_io_new_bufchain(ctx)
+X<im_io_new_bufchain API>X<i_io_new_bufchain API>
 =order 10
 =category I/O Layers
 
-returns a new io_glue object that has the 'empty' source and but can
+Returns a new io_glue object that has the 'empty' source and but can
 be written to and read from later (like a pseudo file).
 
+Also callable as C<io_new_bufchain()>.
+
 =cut
 */
 
@@ -195,16 +198,20 @@ im_io_new_bufchain(pIMCTX) {
 }
 
 /*
-=item io_new_buffer(data, length)
+=item im_io_new_buffer(ctx, data, length)
+X<im_io_new_buffer API>X<io_new_buffer API>
 =order 10
 =category I/O Layers
 
 Returns a new io_glue object that has the source defined as reading
 from specified buffer.  Note that the buffer is not copied.
 
+   ctx - an Imager context object
    data - buffer to read from
    length - length of buffer
 
+Also callable as C<io_new_buffer(data, length>.
+
 =cut
 */
 
@@ -234,15 +241,19 @@ im_io_new_buffer(pIMCTX, const char *data, size_t len, i_io_closebufp_t closecb,
 
 
 /*
-=item io_new_fd(fd)
+=item im_io_new_fd(ctx, file)
+X<io_new_fd API>X<im_io_new_fd API>
 =order 10
 =category I/O Layers
 
-returns a new io_glue object that has the source defined as reading
+Returns a new io_glue object that has the source defined as reading
 from specified file descriptor.  Note that the the interface to receiving
 data from the io_glue callbacks hasn't been done yet.
 
-   fd - file descriptor to read/write from
+  ctx - and Imager context object
+  file - file descriptor to read/write from
+
+Also callable as C<io_new_fd(file)>.
 
 =cut
 */
@@ -268,7 +279,8 @@ im_io_new_fd(pIMCTX, int fd) {
 }
 
 /*
-=item io_new_cb(p, read_cb, write_cb, seek_cb, close_cb, destroy_cb)
+=item im_io_new_cb(ctx, p, read_cb, write_cb, seek_cb, close_cb, destroy_cb)
+X<im_io_new_cb API>X<io_new_cb API>
 =category I/O Layers
 =order 10
 
@@ -306,6 +318,9 @@ handlers.
 
 =back
 
+Also callable as C<io_new_cb(p, readcb, writecb, seekcb, closecb,
+destroycb)>.
+
 =cut
 */
 
@@ -339,6 +354,7 @@ im_io_new_cb(pIMCTX, void *p, i_io_readl_t readcb, i_io_writel_t writecb,
 
 /*
 =item io_slurp(ig, c)
+X<io_slurp API>
 =category I/O Layers
 
 Takes the source that the io_glue is bound to and allocates space for
@@ -392,6 +408,7 @@ io_slurp(io_glue *ig, unsigned char **c) {
 
 /*
 =item io_glue_destroy(ig)
+X<io_glue_destroy API>
 =category I/O Layers
 =order 90
 =synopsis io_glue_destroy(ig);
index dbe6414..703eb12 100644 (file)
@@ -25,7 +25,7 @@ Imager::API - Imager's C API - introduction.
 =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:
 
@@ -34,7 +34,7 @@ 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 *
 
@@ -70,31 +70,37 @@ The API makes the following types visible:
 
 =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
@@ -110,7 +116,7 @@ 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.
 
-=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:
@@ -135,16 +141,16 @@ C<channels> - array of channels.
 
 =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.
@@ -156,6 +162,25 @@ Use Imager::FillHandle for parameter and return value types.  At the
 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
@@ -259,6 +284,134 @@ should include Imager in your configure_requires:
 
 =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 AUTHOR
 
 Tony Cook <tonyc@cpan.org>
index 18d65b0..8949d46 100644 (file)
@@ -40,9 +40,24 @@ Imager::APIRef - Imager's C API - reference.
   i_flood_cfill_border(im, 50, 50, fill, border);
 
   # Error handling
+  im_clear_error(aIMCTX);
+  i_clear_error();
+  i_push_error(0, "Yep, it's broken");
+  i_push_error(errno, "Error writing");
+  im_push_error(aIMCTX, 0, "Something is wrong");
+  va_args args;
+  va_start(args, lastarg);
+  im_push_errorvf(ctx, code, format, args);
   i_push_errorf(errno, "Cannot open file %s: %d", filename, errno);
+  im_push_errorf(aIMCTX, errno, "Cannot open file %s: %d", filename, errno);
 
   # Files
+  im_set_image_file_limits(aIMCTX, 500, 500, 1000000);
+  i_set_image_file_limits(500, 500, 1000000);
+  im_get_image_file_limits(aIMCTX, &width, &height, &bytes)
+  i_get_image_file_limits(&width, &height, &bytes)
+  im_int_check_image_file_limits(aIMCTX, width, height, channels, sizeof(i_sample_t))
+  i_int_check_image_file_limits(width, height, channels, sizeof(i_sample_t))
 
   # Fills
   i_fill_t *fill = i_new_fill_solidf(&fcolor, combine);
@@ -66,8 +81,22 @@ Imager::APIRef - Imager's C API - reference.
   # Image creation/destruction
   i_img *img = i_sametype(src, width, height);
   i_img *img = i_sametype_chans(src, width, height, channels);
+  i_img *img = im_img_16_new(aIMCTX, width, height, channels);
+  i_img *img = i_img_16_new(width, height, channels);
+  i_img *img = im_img_8_new(aIMCTX, width, height, channels);
+  i_img *img = i_img_8_new(width, height, channels);
+  i_img *img = im_img_double_new(aIMCTX, width, height, channels);
+  i_img *img = i_img_double_new(width, height, channels);
+  i_img *img = im_img_pal_new(aIMCTX, width, height, channels, max_palette_size)
+  i_img *img = i_img_pal_new(width, height, channels, max_palette_size)
   i_img_destroy(img)
 
+  # Image Implementation
+  i_img *im = im_img_alloc(aIMCTX);
+  i_img *im = i_img_alloc();
+  im_img_init(aIMCTX, im);
+  i_img_init(im);
+
   # Image Information
   // only channel 0 writable 
   i_img_setmask(img, 0x01);
@@ -847,6 +876,69 @@ A version of i_push_error() that does printf() like formatting.
 Does not support perl specific format codes.
 
 
+=for comment
+From: File error.c
+
+=item im_clear_error(ctx)
+X<im_clear_error API>X<i_clear_error API>
+
+  im_clear_error(aIMCTX);
+  i_clear_error();
+
+Clears the error stack.
+
+Called by any Imager function before doing any other processing.
+
+Also callable as C<i_clear_error()>.
+
+
+=for comment
+From: File error.c
+
+=item im_push_error(ctx, code, message)
+X<im_push_error API>X<i_push_error API>
+
+  i_push_error(0, "Yep, it's broken");
+  i_push_error(errno, "Error writing");
+  im_push_error(aIMCTX, 0, "Something is wrong");
+
+Called by an Imager function to push an error message onto the stack.
+
+No message is pushed if the stack is full (since this means someone
+forgot to call i_clear_error(), or that a function that doesn't do
+error handling is calling function that does.).
+
+
+=for comment
+From: File error.c
+
+=item im_push_errorf(ctx, code, char const *fmt, ...)
+
+  im_push_errorf(aIMCTX, errno, "Cannot open file %s: %d", filename, errno);
+
+A version of im_push_error() that does printf() like formatting.
+
+Does not support perl specific format codes.
+
+
+=for comment
+From: File error.c
+
+=item im_push_errorvf(ctx, code, format, args)
+X<im_push_error_vf API>X<i_push_errorvf API>
+
+  va_args args;
+  va_start(args, lastarg);
+  im_push_errorvf(ctx, code, format, args);
+
+Intended for use by higher level functions, takes a varargs pointer
+and a format to produce the finally pushed error message.
+
+Does not support perl specific format codes.
+
+Also callable as C<i_push_errorvf(code, format, args)>
+
+
 =for comment
 From: File error.c
 
@@ -886,6 +978,89 @@ Returns 1 if the C<i_background> tag was found and valid.
 =for comment
 From: File image.c
 
+=item im_get_image_file_limits(ctx, &width, &height, &bytes)
+X<im_get_image_file_limits API>X<i_get_image_file_limits>
+
+  im_get_image_file_limits(aIMCTX, &width, &height, &bytes)
+  i_get_image_file_limits(&width, &height, &bytes)
+
+Retrieves the file limits set by i_set_image_file_limits().
+
+=over
+
+=item *
+
+i_img_dim *width, *height - the maximum width and height of the image.
+
+=item *
+
+size_t *bytes - size in memory of the image in bytes.
+
+=back
+
+Also callable as C<i_get_image_file_limits(&width, &height, &bytes)>.
+
+
+=for comment
+From: File limits.c
+
+=item im_int_check_image_file_limits(width, height, channels, sample_size)
+X<im_int_check_image_file_limits API>X<i_int_check_image_file_limits>
+
+  im_int_check_image_file_limits(aIMCTX, width, height, channels, sizeof(i_sample_t))
+  i_int_check_image_file_limits(width, height, channels, sizeof(i_sample_t))
+
+Checks the size of a file in memory against the configured image file
+limits.
+
+This also range checks the values to those permitted by Imager and
+checks for overflows in calculating the size.
+
+Returns non-zero if the file is within limits.
+
+This function is intended to be called by image file read functions.
+
+Also callable as C<i_int_check_image_file_limits(width, height, channels, sizeof(i_sample_t)>.
+
+
+=for comment
+From: File limits.c
+
+=item im_set_image_file_limits(ctx, width, height, bytes)
+X<im_set_image_file_limits API>X<i_set_image_file_limits API>
+
+  im_set_image_file_limits(aIMCTX, 500, 500, 1000000);
+  i_set_image_file_limits(500, 500, 1000000);
+
+Set limits on the sizes of images read by Imager.
+
+Setting a limit to 0 means that limit is ignored.
+
+Negative limits result in failure.
+
+Parameters:
+
+=over
+
+=item *
+
+i_img_dim width, height - maximum width and height.
+
+=item *
+
+size_t bytes - maximum size in memory in bytes.  A value of zero sets
+this limit to one gigabyte.
+
+=back
+
+Returns non-zero on success.
+
+Also callable as C<i_set_image_file_limits(width, height, bytes)>.
+
+
+=for comment
+From: File limits.c
+
 
 =back
 
@@ -1008,6 +1183,94 @@ From: File fills.c
 
 =over
 
+=item im_io_new_bufchain(ctx)
+X<im_io_new_bufchain API>X<i_io_new_bufchain API>
+
+Returns a new io_glue object that has the 'empty' source and but can
+be written to and read from later (like a pseudo file).
+
+Also callable as C<io_new_bufchain()>.
+
+
+=for comment
+From: File iolayer.c
+
+=item im_io_new_buffer(ctx, data, length)
+X<im_io_new_buffer API>X<io_new_buffer API>
+
+Returns a new io_glue object that has the source defined as reading
+from specified buffer.  Note that the buffer is not copied.
+
+   ctx - an Imager context object
+   data - buffer to read from
+   length - length of buffer
+
+Also callable as C<io_new_buffer(data, length>.
+
+
+=for comment
+From: File iolayer.c
+
+=item im_io_new_cb(ctx, p, read_cb, write_cb, seek_cb, close_cb, destroy_cb)
+X<im_io_new_cb API>X<io_new_cb API>
+
+Create a new I/O layer object that calls your supplied callbacks.
+
+In general the callbacks should behave like the corresponding POSIX
+primitives.
+
+=over
+
+=item *
+
+C<read_cb>(p, buffer, length) should read up to C<length> bytes into
+C<buffer> and return the number of bytes read.  At end of file, return
+0.  On error, return -1.
+
+=item *
+
+C<write_cb>(p, buffer, length) should write up to C<length> bytes from
+C<buffer> and return the number of bytes written.  A return value <= 0
+will be treated as an error.
+
+=item *
+
+C<seekcb>(p, offset, whence) should seek and return the new offset.
+
+=item *
+
+C<close_cb>(p) should return 0 on success, -1 on failure.
+
+=item *
+
+C<destroy_cb>(p) should release any memory specific to your callback
+handlers.
+
+=back
+
+Also callable as C<io_new_cb(p, readcb, writecb, seekcb, closecb,
+destroycb)>.
+
+
+=for comment
+From: File iolayer.c
+
+=item im_io_new_fd(ctx, file)
+X<io_new_fd API>X<im_io_new_fd API>
+
+Returns a new io_glue object that has the source defined as reading
+from specified file descriptor.  Note that the the interface to receiving
+data from the io_glue callbacks hasn't been done yet.
+
+  ctx - and Imager context object
+  file - file descriptor to read/write from
+
+Also callable as C<io_new_fd(file)>.
+
+
+=for comment
+From: File iolayer.c
+
 =item i_io_close(io)
 
 Flush any pending output and perform the close action for the stream.
@@ -1159,6 +1422,7 @@ Returns the number of bytes written.
 From: File iolayer.c
 
 =item io_slurp(ig, c)
+X<io_slurp API>
 
 Takes the source that the io_glue is bound to and allocates space for
 a return buffer and returns the entire content in a single buffer.
@@ -1181,6 +1445,7 @@ from io_new_bufchain().
 From: File iolayer.c
 
 =item io_glue_destroy(ig)
+X<io_glue_destroy API>
 
   io_glue_destroy(ig);
 
@@ -1304,6 +1569,67 @@ For paletted images the equivalent direct type is returned.
 =for comment
 From: File image.c
 
+=item im_img_16_new(ctx, x, y, ch)
+X<im_img_16_new API>X<i_img_16_new API>
+
+  i_img *img = im_img_16_new(aIMCTX, width, height, channels);
+  i_img *img = i_img_16_new(width, height, channels);
+
+Create a new 16-bit/sample image.
+
+Returns the image on success, or NULL on failure.
+
+Also callable as C<i_img_16_new(x, y, ch)>
+
+
+=for comment
+From: File img16.c
+
+=item im_img_8_new(ctx, x, y, ch)
+X<im_img_8_new API>X<i_img_8_new API>
+
+  i_img *img = im_img_8_new(aIMCTX, width, height, channels);
+  i_img *img = i_img_8_new(width, height, channels);
+
+Creates a new image object I<x> pixels wide, and I<y> pixels high with
+I<ch> channels.
+
+
+=for comment
+From: File img8.c
+
+=item im_img_double_new(ctx, x, y, ch)
+X<im_img_double_new API>X<i_img_double_new API>
+
+  i_img *img = im_img_double_new(aIMCTX, width, height, channels);
+  i_img *img = i_img_double_new(width, height, channels);
+
+Creates a new double per sample image.
+
+Also callable as C<i_img_double_new(width, height, channels)>.
+
+
+=for comment
+From: File imgdouble.c
+
+=item im_img_pal_new(ctx, C<x>, C<y>, C<channels>, C<maxpal>)
+X<im_img_pal_new API>X<i_img_pal_new API>
+
+  i_img *img = im_img_pal_new(aIMCTX, width, height, channels, max_palette_size)
+  i_img *img = i_img_pal_new(width, height, channels, max_palette_size)
+
+Creates a new paletted image of the supplied dimensions.
+
+C<maxpal> is the maximum palette size and should normally be 256.
+
+Returns a new image or NULL on failure.
+
+Also callable as C<i_img_pal_new(width, height, channels, max_palette_size)>.
+
+
+=for comment
+From: File palimg.c
+
 =item i_img_destroy(C<img>)
 
   i_img_destroy(img)
@@ -1315,6 +1641,60 @@ Destroy an image object
 From: File image.c
 
 
+=back
+
+=head2 Image Implementation
+
+=over
+
+=item im_img_alloc(aIMCTX)
+X<im_img_alloc API>X<i_img_alloc API>
+
+  i_img *im = im_img_alloc(aIMCTX);
+  i_img *im = i_img_alloc();
+
+Allocates a new i_img structure.
+
+When implementing a new image type perform the following steps in your
+image object creation function:
+
+=over
+
+=item 1.
+
+allocate the image with i_img_alloc().
+
+=item 2.
+
+initialize any function pointers or other data as needed, you can
+overwrite the whole block if you need to.
+
+=item 3.
+
+initialize Imager's internal data by calling i_img_init() on the image
+object.
+
+=back
+
+
+=for comment
+From: File image.c
+
+=item im_img_init(aIMCTX, image)
+X<im_img_init API>X<i_img_init API>
+
+  im_img_init(aIMCTX, im);
+  i_img_init(im);
+
+Imager internal initialization of images.
+
+See L</im_img_alloc(aIMCTX)> for more information.
+
+
+=for comment
+From: File image.c
+
+
 =back
 
 =head2 Image Information
@@ -1495,18 +1875,6 @@ This is an internal function called by the mm_log() macro.
 =for comment
 From: File log.c
 
-=item mm_log((level, format, ...))
-
-This is the main entry point to logging. Note that the extra set of
-parentheses are required due to limitations in C89 macros.
-
-This will format a string with the current file and line number to the
-log file if logging is enabled.
-
-
-=for comment
-From: File log.h
-
 
 =back
 
@@ -1842,6 +2210,65 @@ Returns ~0UL on failure.
 =for comment
 From: File io.c
 
+=item im_errors(ctx)
+
+  i_errmsg *errors = im_errors(aIMCTX);
+  i_errmsg *errors = i_errors();
+
+Returns a pointer to the first element of an array of error messages,
+terminated by a NULL pointer.  The highest level message is first.
+
+Also callable as C<i_errors()>.
+
+
+=for comment
+From: File error.c
+
+=item im_get_context()
+
+Retrieve the context object for the current thread.
+
+Inside Imager itself this is just a function pointer, which the
+F<Imager.xs> BOOT handler initializes for use within perl.  If you're
+taking the Imager code and embedding it elsewhere you need to
+initialize the C<im_get_context> pointer at some point.
+
+
+=for comment
+From: File imext.c
+
+
+
+=back
+
+
+=head1 UNDOCUMENTED
+
+The following API functions are undocumented so far, hopefully this
+will change:
+
+=over
+
+=item *
+
+B<im_context_refdec>
+
+=item *
+
+B<im_context_refinc>
+
+=item *
+
+B<im_lhead>
+
+=item *
+
+B<im_loog>
+
+=item *
+
+B<mm_log>
+
 
 
 =back
@@ -1853,6 +2280,6 @@ Tony Cook <tonyc@cpan.org>
 
 =head1 SEE ALSO
 
-Imager, Imager::ExtUtils, Imager::Inline
+Imager, Imager::API, Imager::ExtUtils, Imager::Inline
 
 =cut
index a245a6b..16deaa7 100644 (file)
--- a/limits.c
+++ b/limits.c
@@ -28,9 +28,10 @@ Setting a value of zero means that limit will be ignored.
 #include "imageri.h"
 
 /*
-=item i_set_image_file_limits(width, height, bytes)
-
+=item im_set_image_file_limits(ctx, width, height, bytes)
+X<im_set_image_file_limits API>X<i_set_image_file_limits API>
 =category Files
+=synopsis im_set_image_file_limits(aIMCTX, 500, 500, 1000000);
 =synopsis i_set_image_file_limits(500, 500, 1000000);
 
 Set limits on the sizes of images read by Imager.
@@ -56,6 +57,8 @@ this limit to one gigabyte.
 
 Returns non-zero on success.
 
+Also callable as C<i_set_image_file_limits(width, height, bytes)>.
+
 =cut
 */
 
@@ -84,9 +87,10 @@ im_set_image_file_limits(pIMCTX, i_img_dim width, i_img_dim height, size_t bytes
 }
 
 /*
-=item i_get_image_file_limits(&width, &height, &bytes)
-
+=item im_get_image_file_limits(ctx, &width, &height, &bytes)
+X<im_get_image_file_limits API>X<i_get_image_file_limits>
 =category Files
+=synopsis im_get_image_file_limits(aIMCTX, &width, &height, &bytes)
 =synopsis i_get_image_file_limits(&width, &height, &bytes)
 
 Retrieves the file limits set by i_set_image_file_limits().
@@ -103,6 +107,8 @@ size_t *bytes - size in memory of the image in bytes.
 
 =back
 
+Also callable as C<i_get_image_file_limits(&width, &height, &bytes)>.
+
 =cut
 */
 
@@ -118,10 +124,11 @@ im_get_image_file_limits(pIMCTX, i_img_dim *width, i_img_dim *height, size_t *by
 }
 
 /*
-=item i_int_check_image_file_limits(width, height, channels, sample_size)
-
+=item im_int_check_image_file_limits(width, height, channels, sample_size)
+X<im_int_check_image_file_limits API>X<i_int_check_image_file_limits>
 =category Files
-=synopsis i_i_int_check_image_file_limits(width, height, channels, sizeof(i_sample_t))
+=synopsis im_int_check_image_file_limits(aIMCTX, width, height, channels, sizeof(i_sample_t))
+=synopsis i_int_check_image_file_limits(width, height, channels, sizeof(i_sample_t))
 
 Checks the size of a file in memory against the configured image file
 limits.
@@ -133,6 +140,8 @@ Returns non-zero if the file is within limits.
 
 This function is intended to be called by image file read functions.
 
+Also callable as C<i_int_check_image_file_limits(width, height, channels, sizeof(i_sample_t)>.
+
 =cut
 */
 
diff --git a/log.h b/log.h
index c54b58a..0dcb74b 100644 (file)
--- a/log.h
+++ b/log.h
@@ -23,7 +23,7 @@ void i_loog(int level,const char *msg, ... ) I_FORMAT_ATTR(2,3);
 void im_loog(pIMCTX, int level,const char *msg, ... ) I_FORMAT_ATTR(3,4);
 
 /*
-=item mm_log((level, format, ...))
+=item im_log((aIMCTX, level, format, ...))
 =category Logging
 
 This is the main entry point to logging. Note that the extra set of
@@ -32,6 +32,13 @@ parentheses are required due to limitations in C89 macros.
 This will format a string with the current file and line number to the
 log file if logging is enabled.
 
+This must be called with a context object defined by one of the
+C<dIMCTX> macros in scope.
+
+This can also be called as C<mm_log((level, format, args))> in which
+case the currently active context is used and any in scope context is
+ignored.
+
 =cut
 */
 
index 9b68b59..b32c0d4 100644 (file)
--- a/palimg.c
+++ b/palimg.c
@@ -86,9 +86,10 @@ static i_img IIM_base_8bit_pal =
 };
 
 /*
-=item i_img_pal_new(C<x>, C<y>, C<channels>, C<maxpal>)
-
+=item im_img_pal_new(ctx, C<x>, C<y>, C<channels>, C<maxpal>)
+X<im_img_pal_new API>X<i_img_pal_new API>
 =category Image creation/destruction
+=synopsis i_img *img = im_img_pal_new(aIMCTX, width, height, channels, max_palette_size)
 =synopsis i_img *img = i_img_pal_new(width, height, channels, max_palette_size)
 
 Creates a new paletted image of the supplied dimensions.
@@ -97,6 +98,8 @@ C<maxpal> is the maximum palette size and should normally be 256.
 
 Returns a new image or NULL on failure.
 
+Also callable as C<i_img_pal_new(width, height, channels, max_palette_size)>.
+
 =cut
 */
 i_img *
index 450fdaa..9c9928a 100644 (file)
@@ -46,6 +46,7 @@ ie
 infix
 invocant
 metadata
+multi-threaded
 paletted
 postfix
 preload