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
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;
/*
=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.
}
/*
-=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
*/
=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
Called by any Imager function before doing any other processing.
+Also callable as C<i_clear_error()>.
+
=cut
*/
}
/*
-=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.
}
/*
-=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
Does not support perl specific format codes.
+Also callable as C<i_push_errorvf(code, format, args)>
+
=cut
*/
void
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);
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;
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.
}
/*
-=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
*/
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.
((((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
*/
}*/
/*
-=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
=cut
*/
-
i_img *
im_img_8_new(pIMCTX, i_img_dim x,i_img_dim y,int ch) {
i_img *im;
};
/*
-=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 *
*/
/*
-=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
*/
}
/*
-=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
*/
/*
-=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
*/
}
/*
-=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
=back
+Also callable as C<io_new_cb(p, readcb, writecb, seekcb, closecb,
+destroycb)>.
+
=cut
*/
/*
=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
/*
=item io_glue_destroy(ig)
+X<io_glue_destroy API>
=category I/O Layers
=order 90
=synopsis io_glue_destroy(ig);
=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
=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>
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);
# 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);
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
=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
=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.
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.
From: File iolayer.c
=item io_glue_destroy(ig)
+X<io_glue_destroy API>
io_glue_destroy(ig);
=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)
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
=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
=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
=head1 SEE ALSO
-Imager, Imager::ExtUtils, Imager::Inline
+Imager, Imager::API, Imager::ExtUtils, Imager::Inline
=cut
#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.
Returns non-zero on success.
+Also callable as C<i_set_image_file_limits(width, height, bytes)>.
+
=cut
*/
}
/*
-=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().
=back
+Also callable as C<i_get_image_file_limits(&width, &height, &bytes)>.
+
=cut
*/
}
/*
-=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.
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
*/
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
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
*/
};
/*
-=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.
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 *
infix
invocant
metadata
+multi-threaded
paletted
postfix
preload
projects / imager.git / commitdiff