From: Tony Cook Date: Mon, 13 Aug 2012 12:17:22 +0000 (+1000) Subject: fill out documentation X-Git-Tag: v0.93_02~41 X-Git-Url: http://git.imager.perl.org/imager.git/commitdiff_plain/abffffed92e054cd7db5f69280201dec71fbf310 fill out documentation --- diff --git a/Changes b/Changes index 070a5680..7b29d8ce 100644 --- 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 diff --git a/apidocs.perl b/apidocs.perl index 02cb99ce..b96c7277 100644 --- a/apidocs.perl +++ b/apidocs.perl @@ -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; diff --git a/context.c b/context.c index 4852bf81..08e9a4d7 100644 --- a/context.c +++ b/context.c @@ -42,6 +42,9 @@ im_context_new(void) { /* =item im_context_refinc(ctx, where) +X +=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 +=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 1f89bb42..a782e3a0 100644 --- a/error.c +++ b/error.c @@ -94,7 +94,9 @@ the mark. =over -=item i_clear_error() +=item im_clear_error(ctx) +XX +=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. + =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) +XX =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, char const *C, va_list C) - +=item im_push_errorvf(ctx, code, format, args) +XX +=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 + =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 56057e87..10228d11 100644 --- 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) +XX =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) +=item im_img_init(aIMCTX, image) +XX =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 for more information. =cut */ diff --git a/imext.c b/imext.c index 3f191231..24aad642 100644 --- 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 BOOT handler initializes for use within perl. If you're taking the Imager code and embedding it elsewhere you need to initialize the C pointer at some point. diff --git a/img16.c b/img16.c index dfe16138..1b3e4521 100644 --- 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) +XX =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 + =cut */ diff --git a/img8.c b/img8.c index 373d5a18..c7804733 100644 --- 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) +XX =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 pixels wide, and I pixels high with @@ -94,7 +94,6 @@ I channels. =cut */ - i_img * im_img_8_new(pIMCTX, i_img_dim x,i_img_dim y,int ch) { i_img *im; diff --git a/imgdouble.c b/imgdouble.c index 1830c94e..fdd33020 100644 --- a/imgdouble.c +++ b/imgdouble.c @@ -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) +XX =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. + =cut */ i_img * diff --git a/iolayer.c b/iolayer.c index 18a78058..d92748a0 100644 --- 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) +XX =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. + =cut */ @@ -195,16 +198,20 @@ im_io_new_bufchain(pIMCTX) { } /* -=item io_new_buffer(data, length) +=item im_io_new_buffer(ctx, data, length) +XX =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. + =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) +XX =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. =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) +XX =category I/O Layers =order 10 @@ -306,6 +318,9 @@ handlers. =back +Also callable as C. + =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 =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 =category I/O Layers =order 90 =synopsis io_glue_destroy(ig); diff --git a/lib/Imager/API.pod b/lib/Imager/API.pod index dbe6414b..703eb121 100644 --- a/lib/Imager/API.pod +++ b/lib/Imager/API.pod @@ -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. 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 example. =item * @@ -70,31 +70,37 @@ The API makes the following types visible: =item * -i_img - used to represent an image +L - used to represent an image =item * -i_color - used to represent a color with up to 8 bits per sample. +L - 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 - used to represent +a color with a double per sample. =item * -i_fill_t - an abstract fill +L - fill objects>> - an abstract fill + +=item * + +L - 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, C, C), image metadata (C, C, C, -C), potentially image data (C) and the a function -table, with pointers to functions to perform various low level image +C), potentially image data (C) 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 - 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 - array of channels. =back -Use Imager::Color for parameter and return value types. +Use C for parameter and return value types. -=head2 C - floating point color +=head2 i_fcolor Similar to C except that each component is a double instead of an unsigned char. Use Imager::Color::Float for parameter and return value types. -=head2 C - 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 member of the Perl level Imager::Fill object. +=head2 i_io_glue_t + +C is Imager's I/O abstraction. + +Historically named C, 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 mapping and a +DESTROY method for this type you B never return objects of this +type back to perl. + +See L 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 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 + +With C defined, C refers to the locally +defined context object, either via one the of the C macros or +as a parameter with the C macro. + +Without C, C is a call to +C which retrieves the context object for the current +thread. + +There is no C macro, any Imager function that can accept a +context parameter always accepts it. + +=head2 C + +This macro declares a variable of type L that's +accessible via the C macro. This is intended for use as a +parameter declaration for functions: + + void f(pIMCTX) { + ... use aIMCTX here + } + + void g(...) { + ... + f(aIMCTX); + } + +=head2 C + +Defines a local context variable and initializes it via +L. + +=head2 C + +Defines a local context variable and initializes it from the context +stored in an L, eg: + + void f(i_img *im) { + dIMCTXim(im); + ... + } + +=head2 C + +Defines a local context variable and initializes it from the context +stored in an L object. + + void f(i_io_glue_t *io) { + dIMCTXio(io); + ... + } + +=head2 C + +Defines a local context variable accessible via C 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 diff --git a/lib/Imager/APIRef.pod b/lib/Imager/APIRef.pod index 18d65b06..8949d460 100644 --- a/lib/Imager/APIRef.pod +++ b/lib/Imager/APIRef.pod @@ -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) +XX + + 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. + + +=for comment +From: File error.c + +=item im_push_error(ctx, code, message) +XX + + 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) +XX + + 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 + + =for comment From: File error.c @@ -886,6 +978,89 @@ Returns 1 if the C tag was found and valid. =for comment From: File image.c +=item im_get_image_file_limits(ctx, &width, &height, &bytes) +XX + + 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. + + +=for comment +From: File limits.c + +=item im_int_check_image_file_limits(width, height, channels, sample_size) +XX + + 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. + + +=for comment +From: File limits.c + +=item im_set_image_file_limits(ctx, width, height, bytes) +XX + + 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. + + +=for comment +From: File limits.c + =back @@ -1008,6 +1183,94 @@ From: File fills.c =over +=item im_io_new_bufchain(ctx) +XX + +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. + + +=for comment +From: File iolayer.c + +=item im_io_new_buffer(ctx, data, length) +XX + +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. + + +=for comment +From: File iolayer.c + +=item im_io_new_cb(ctx, p, read_cb, write_cb, seek_cb, close_cb, destroy_cb) +XX + +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(p, buffer, length) should read up to C bytes into +C and return the number of bytes read. At end of file, return +0. On error, return -1. + +=item * + +C(p, buffer, length) should write up to C bytes from +C and return the number of bytes written. A return value <= 0 +will be treated as an error. + +=item * + +C(p, offset, whence) should seek and return the new offset. + +=item * + +C(p) should return 0 on success, -1 on failure. + +=item * + +C(p) should release any memory specific to your callback +handlers. + +=back + +Also callable as C. + + +=for comment +From: File iolayer.c + +=item im_io_new_fd(ctx, file) +XX + +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. + + +=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 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(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) +XX + + 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 + + +=for comment +From: File img16.c + +=item im_img_8_new(ctx, x, y, ch) +XX + + 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 pixels wide, and I pixels high with +I channels. + + +=for comment +From: File img8.c + +=item im_img_double_new(ctx, x, y, ch) +XX + + 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. + + +=for comment +From: File imgdouble.c + +=item im_img_pal_new(ctx, C, C, C, C) +XX + + 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 is the maximum palette size and should normally be 256. + +Returns a new image or NULL on failure. + +Also callable as C. + + +=for comment +From: File palimg.c + =item i_img_destroy(C) 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) +XX + + 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) +XX + + im_img_init(aIMCTX, im); + i_img_init(im); + +Imager internal initialization of images. + +See L 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. + + +=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 BOOT handler initializes for use within perl. If you're +taking the Imager code and embedding it elsewhere you need to +initialize the C 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 + +=item * + +B + +=item * + +B + +=item * + +B + +=item * + +B + =back @@ -1853,6 +2280,6 @@ Tony Cook =head1 SEE ALSO -Imager, Imager::ExtUtils, Imager::Inline +Imager, Imager::API, Imager::ExtUtils, Imager::Inline =cut diff --git a/limits.c b/limits.c index a245a6b2..16deaa73 100644 --- 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) +XX =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. + =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) +XX =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. + =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) +XX =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. + =cut */ diff --git a/log.h b/log.h index c54b58ae..0dcb74be 100644 --- 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 macros in scope. + +This can also be called as C in which +case the currently active context is used and any in scope context is +ignored. + =cut */ diff --git a/palimg.c b/palimg.c index 9b68b59d..b32c0d49 100644 --- a/palimg.c +++ b/palimg.c @@ -86,9 +86,10 @@ static i_img IIM_base_8bit_pal = }; /* -=item i_img_pal_new(C, C, C, C) - +=item im_img_pal_new(ctx, C, C, C, C) +XX =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 is the maximum palette size and should normally be 256. Returns a new image or NULL on failure. +Also callable as C. + =cut */ i_img * diff --git a/t/x20spell.t b/t/x20spell.t index 450fdaae..9c9928aa 100644 --- a/t/x20spell.t +++ b/t/x20spell.t @@ -46,6 +46,7 @@ ie infix invocant metadata +multi-threaded paletted postfix preload