color.rgba.r = 255; color.rgba.g = 0; color.rgba.b = 255;
+ # Blit tools
+
# Data Types
i_img *img;
i_color black;
black.rgba.r = black.rgba.g = black.rgba.b = black.rgba.a = 0;
i_fill_t *fill;
- i_img_dim x;
+ i_img_dim x, y;
+ printf("left %" i_DF "\n", i_DFc(x));
+ printf("point (" i_DFp ")\n", i_DFcp(x, y));
# Drawing
i_arc(im, 50, 50, 20, 45, 135, &color);
i_flood_cfill_border(im, 50, 50, fill, border);
# Error handling
- i_clear_error();
- i_push_error(0, "Yep, it's broken");
- i_push_error(errno, "Error writing");
i_push_errorf(errno, "Cannot open file %s: %d", filename, errno);
# Files
- i_set_image_file_limits(500, 500, 1000000);
- i_get_image_file_limits(&width, &height, &bytes)
- i_i_int_check_image_file_limits(width, height, channels, sizeof(i_sample_t))
# Fills
i_fill_t *fill = i_new_fill_solidf(&fcolor, combine);
i_fr_triangle, 0, i_fts_grid, 9, 1, segs);
i_fill_destroy(fill);
+ # I/O Layers
+ ssize_t count = i_io_peekn(ig, buffer, sizeof(buffer));
+ ssize_t result = i_io_write(io, buffer, size)
+ char buffer[BUFSIZ]
+ ssize_t len = i_io_gets(buffer, sizeof(buffer), '\n');
+ io_glue_destroy(ig);
+
# Image
# Image creation/destruction
- i_img *img = i_img_8_new(width, height, channels);
i_img *img = i_sametype(src, width, height);
i_img *img = i_sametype_chans(src, width, height, channels);
- i_img *img = i_img_pal_new(width, height, channels, max_palette_size)
- i_img *img = i_img_double_new(width, height, channels);
- i_img *img = i_img_16_new(width, height, channels);
i_img_destroy(img)
- # Image Implementation
-
# Image Information
- // only channel 0 writeable
+ // only channel 0 writable
i_img_setmask(img, 0x01);
int mask = i_img_getmask(img);
int channels = i_img_getchannels(img);
=head1 DESCRIPTION
+=head2 Blit tools
+
+=over
+
+=item i_render_color(r, x, y, width, source, color)
+
+Render the given color with the coverage specified by C<source[0]> to
+C<source[width-1]>.
+
+Renders in normal combine mode.
+
+
+=for comment
+From: File render.im
+
+=item i_render_delete(r)
+
+Release an C<i_render> object.
+
+
+=for comment
+From: File render.im
+
+=item i_render_fill(r, x, y, width, source, fill)
+
+Render the given fill with the coverage in C<source[0]> through
+C<source[width-1]>.
+
+
+=for comment
+From: File render.im
+
+=item i_render_line(r, x, y, width, source, fill)
+
+Render the given fill with the coverage in C<source[0]> through
+C<source[width-1]>.
+
+
+=for comment
+From: File render.im
+
+=item i_render_linef(r, x, y, width, source, fill)
+
+Render the given fill with the coverage in C<source[0]> through
+C<source[width-1]>.
+
+
+=for comment
+From: File render.im
+
+=item i_render_new(im, width)
+
+Allocate a new C<i_render> object and initialize it.
+
+
+=for comment
+From: File render.im
+
+
+=back
+
=head2 Data Types
=over
=item i_img
+ i_img *img;
+
This is Imager's image type.
It contains the following members:
i_f_psamp_bits - implements i_psamp_bits() for this image.
+=item *
+
+i_f_psamp - implements psamp() for this image.
+
+=item *
+
+i_f_psampf - implements psamp() for this image.
+
+=item *
+
+C<im_data> - image specific data internal to Imager.
+
+=item *
+
+C<context> - the Imager API context this image belongs to.
+
=back
=item i_color
+ i_color black;
+ black.rgba.r = black.rgba.g = black.rgba.b = black.rgba.a = 0;
+
Type for 8-bit/sample color.
Samples as per;
=item i_fill_t
+ i_fill_t *fill;
+
This is the "abstract" base type for Imager's fill types.
Unless you're implementing a new fill type you'll typically treat this
=item i_img_dim
+ i_img_dim x, y;
+
A signed integer type that represents an image dimension or ordinate.
May be larger than int on some platforms.
+=for comment
+From: File imdatatypes.h
+
+=item i_DF
+
+ printf("left %" i_DF "\n", i_DFc(x));
+
+This is a constant string that can be used with functions like
+printf() to format i_img_dim values after they're been cast with i_DFc().
+
+Does not include the leading C<%>.
+
+
+=for comment
+From: File imdatatypes.h
+
+=item i_DFc
+
+Cast an C<i_img_dim> value to a type for use with the i_DF format
+string.
+
+
+=for comment
+From: File imdatatypes.h
+
+=item i_DFcp
+
+Casts two C<i_img_dim> values for use with the i_DF (or i_DFp) format.
+
+
+=for comment
+From: File imdatatypes.h
+
+=item i_DFp
+
+ printf("point (" i_DFp ")\n", i_DFcp(x, y));
+
+Format a pair of C<i_img_dim> values. This format string I<does>
+include the leading C<%>.
+
+
=for comment
From: File imdatatypes.h
=item i_arc(im, x, y, rad, d1, d2, color)
+ i_arc(im, 50, 50, 20, 45, 135, &color);
+
Fills an arc centered at (x,y) with radius I<rad> covering the range
of angles in degrees from d1 to d2, with the color.
=item i_arc_aa(im, x, y, rad, d1, d2, color)
+ i_arc_aa(im, 50, 50, 35, 90, 135, &color);
+
Anti-alias fills an arc centered at (x,y) with radius I<rad> covering
the range of angles in degrees from d1 to d2, with the color.
=item i_arc_aa_cfill(im, x, y, rad, d1, d2, fill)
+ i_arc_aa_cfill(im, 50, 50, 35, 90, 135, fill);
+
Anti-alias fills an arc centered at (x,y) with radius I<rad> covering
the range of angles in degrees from d1 to d2, with the fill object.
=item i_arc_cfill(im, x, y, rad, d1, d2, fill)
+ i_arc_cfill(im, 50, 50, 35, 90, 135, fill);
+
Fills an arc centered at (x,y) with radius I<rad> covering the range
of angles in degrees from d1 to d2, with the fill object.
=item i_box(im, x1, y1, x2, y2, color)
+ i_box(im, 0, 0, im->xsize-1, im->ysize-1, &color).
+
Outlines the box from (x1,y1) to (x2,y2) inclusive with I<color>.
=item i_box_cfill(im, x1, y1, x2, y2, fill)
+ i_box_cfill(im, 0, 0, im->xsize-1, im->ysize-1, fill);
+
Fills the box from (x1,y1) to (x2,y2) inclusive with fill.
=item i_box_filled(im, x1, y1, x2, y2, color)
+ i_box_filled(im, 0, 0, im->xsize-1, im->ysize-1, &color);
+
Fills the box from (x1,y1) to (x2,y2) inclusive with color.
=item i_circle_aa(im, x, y, rad, color)
+ i_circle_aa(im, 50, 50, 45, &color);
+
Anti-alias fills a circle centered at (x,y) for radius I<rad> with
color.
=item i_flood_cfill(C<im>, C<seedx>, C<seedy>, C<fill>)
+ i_flood_cfill(im, 50, 50, fill);
+
Flood fills the 4-connected region starting from the point (C<seedx>,
C<seedy>) with C<fill>.
=item i_flood_cfill_border(C<im>, C<seedx>, C<seedy>, C<fill>, C<border>)
+ i_flood_cfill_border(im, 50, 50, fill, border);
+
Flood fills the 4-connected region starting from the point (C<seedx>,
C<seedy>) with C<fill>, the fill stops when it reaches pixels of color
C<border>.
=item i_flood_fill(C<im>, C<seedx>, C<seedy>, C<color>)
+ i_flood_fill(im, 50, 50, &color);
+
Flood fills the 4-connected region starting from the point (C<seedx>,
C<seedy>) with I<color>.
=item i_flood_fill_border(C<im>, C<seedx>, C<seedy>, C<color>, C<border>)
+ i_flood_fill_border(im, 50, 50, &color, &border);
+
Flood fills the 4-connected region starting from the point (C<seedx>,
C<seedy>) with C<color>, fill stops when the fill reaches a pixels
with color C<border>.
channel_count)
+=for comment
+From: File imext.c
+
+=item i_gsamp_bg(im, l, r, y, samples, out_channels, background)
+
+
+Like C<i_gsampf()> but applies the source image color over a supplied
+background color.
+
+This is intended for output to image formats that don't support alpha
+channels.
+
+
+=for comment
+From: File paste.im
+
+=item i_gsamp_bits(im, left, right, y, samples, channels, channel_count, bits)
+
+Reads integer samples scaled to C<bits> bits of precision into the
+C<unsigned int> array C<samples>.
+
+Expect this to be slow unless C<< bits == im->bits >>.
+
+Returns the number of samples copied, or -1 on error.
+
+Not all image types implement this method.
+
+Pushes errors, but does not call C<i_clear_error()>.
+
+
=for comment
From: File imext.c
=for comment
From: File imext.c
+=item i_gsampf_bg(im, l, r, y, samples, out_channels, background)
+
+
+Like C<i_gsampf()> but applies the source image color over a supplied
+background color.
+
+This is intended for output to image formats that don't support alpha
+channels.
+
+
+=for comment
+From: File paste.im
+
=item i_line(C<im>, C<x1>, C<y1>, C<x2>, C<y2>, C<color>, C<endp>)
=for comment
From: File imext.c
+=item i_psamp(im, left, right, y, samples, channels, channel_count)
-=back
+Writes sample values from C<samples> to C<im> for the horizontal line
+(left, y) to (right-1, y) inclusive for the channels specified by
+C<channels>, an array of C<int> with C<channel_count> elements.
-=head2 Error handling
+If C<channels> is C<NULL> then the first C<channels_count> channels
+are written to for each pixel.
-=over
+Returns the number of samples written, which should be (right - left)
+* channel_count. If a channel not in the image is in channels, left
+is negative, left is outside the image or y is outside the image,
+returns -1 and pushes an error.
-=item i_clear_error()
-Clears the error stack.
+=for comment
+From: File immacros.h
-Called by any Imager function before doing any other processing.
+=item i_psamp_bits(im, left, right, y, samples, channels, channel_count, bits)
+Writes integer samples scaled to C<bits> bits of precision from the
+C<unsigned int> array C<samples>.
-=for comment
-From: File error.c
+Expect this to be slow unless C<< bits == im->bits >>.
-=item i_push_error(int code, char const *msg)
+Returns the number of samples copied, or -1 on error.
-Called by an Imager function to push an error message onto the stack.
+Not all image types implement this method.
-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.).
+Pushes errors, but does not call C<i_clear_error()>.
=for comment
-From: File error.c
+From: File imext.c
-=item i_push_errorf(int code, char const *fmt, ...)
+=item i_psampf(im, left, right, y, samples, channels, channel_count)
-A version of i_push_error() that does printf() like formatting.
+Writes floating point sample values from C<samples> to C<im> for the
+horizontal line (left, y) to (right-1, y) inclusive for the channels
+specified by C<channels>, an array of C<int> with C<channel_count>
+elements.
-Does not support perl specific format codes.
+If C<channels> is C<NULL> then the first C<channels_count> channels
+are written to for each pixel.
+
+Returns the number of samples written, which should be (right - left)
+* channel_count. If a channel not in the image is in channels, left
+is negative, left is outside the image or y is outside the image,
+returns -1 and pushes an error.
=for comment
-From: File error.c
+From: File immacros.h
+
-=item i_push_errorvf(int C<code>, char const *C<fmt>, va_list C<ap>)
+=back
+=head2 Error handling
-Intended for use by higher level functions, takes a varargs pointer
-and a format to produce the finally pushed error message.
+=over
+
+=item i_push_errorf(int code, char const *fmt, ...)
+
+ i_push_errorf(errno, "Cannot open file %s: %d", filename, errno);
+
+A version of i_push_error() that does printf() like formatting.
Does not support perl specific format codes.
=over
-=item i_get_image_file_limits(&width, &height, &bytes)
-
-
-Retrieves the file limits set by i_set_image_file_limits().
-
-
-=for comment
-From: File limits.c
-
-=item i_int_check_image_file_limits(width, height, channels, sample_size)
-
+=item i_get_file_background(im, &bg)
-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.
+Retrieve the file write background color tag from the image.
-Returns non-zero if the file is within limits.
+If not present, C<bg> is set to black.
-This function is intended to be called by image file read functions.
+Returns 1 if the C<i_background> tag was found and valid.
=for comment
-From: File limits.c
+From: File image.c
-=item i_set_image_file_limits(width, height, bytes)
+=item i_get_file_backgroundf(im, &bg)
-Set limits on the sizes of images read by Imager.
+Retrieve the file write background color tag from the image as a
+floating point color.
-Setting a limit to 0 means that limit is ignored.
+Implemented in terms of i_get_file_background().
-Negative limits result in failure.
+If not present, C<bg> is set to black.
-Returns non-zero on success.
+Returns 1 if the C<i_background> tag was found and valid.
=for comment
-From: File limits.c
+From: File image.c
=back
=item i_new_fill_fount(C<xa>, C<ya>, C<xb>, C<yb>, C<type>, C<repeat>, C<combine>, C<super_sample>, C<ssample_param>, C<count>, C<segs>)
+ fill = i_new_fill_fount(0, 0, 100, 100, i_ft_linear, i_ft_linear,
+ i_fr_triangle, 0, i_fts_grid, 9, 1, segs);
+
Creates a new general fill which fills with a fountain fill.
=item i_new_fill_hatch(C<fg>, C<bg>, C<combine>, C<hatch>, C<cust_hatch>, C<dx>, C<dy>)
+ i_fill_t *fill = i_new_fill_hatch(&fg_color, &bg_color, combine, hatch, custom_hatch, dx, dy);
+
Creates a new hatched fill with the C<fg> color used for the 1 bits in
the hatch and C<bg> for the 0 bits. If C<combine> is non-zero alpha
values will be combined.
=item i_new_fill_hatchf(C<fg>, C<bg>, C<combine>, C<hatch>, C<cust_hatch>, C<dx>, C<dy>)
+ i_fill_t *fill = i_new_fill_hatchf(&fg_fcolor, &bg_fcolor, combine, hatch, custom_hatch, dx, dy);
+
Creates a new hatched fill with the C<fg> color used for the 1 bits in
the hatch and C<bg> for the 0 bits. If C<combine> is non-zero alpha
values will be combined.
=item i_new_fill_image(C<im>, C<matrix>, C<xoff>, C<yoff>, C<combine>)
+ i_fill_t *fill = i_new_fill_image(src_img, matrix, x_offset, y_offset, combine);
+
Create an image based fill.
matrix is an array of 9 doubles representing a transformation matrix.
=item i_new_fill_solid(color, combine)
+ i_fill_t *fill = i_new_fill_solid(&color, combine);
+
Create a solid fill based on an 8-bit color.
If combine is non-zero then alpha values will be combined.
=item i_new_fill_solidf(color, combine)
+ i_fill_t *fill = i_new_fill_solidf(&fcolor, combine);
+
Create a solid fill based on a float color.
If combine is non-zero then alpha values will be combined.
=item i_fill_destroy(fill)
+ i_fill_destroy(fill);
+
Call to destroy any fill object.
=back
-=head2 Image
+=head2 I/O Layers
=over
-=item i_copy(source)
+=item io_new_bufchain()
+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).
-Creates a new image that is a copy of the image C<source>.
-Tags are not copied, only the image data.
+=for comment
+From: File iolayer.c
-Returns: i_img *
+=item io_new_buffer(data, length)
+
+Returns a new io_glue object that has the source defined as reading
+from specified buffer. Note that the buffer is not copied.
+
+ data - buffer to read from
+ length - length of buffer
=for comment
-From: File image.c
+From: File iolayer.c
-=item i_copyto(C<dest>, C<src>, C<x1>, C<y1>, C<x2>, C<y2>, C<tx>, C<ty>)
+=item io_new_cb(p, read_cb, write_cb, seek_cb, close_cb, destroy_cb)
+Create a new I/O layer object that calls your supplied callbacks.
-Copies image data from the area (C<x1>,C<y1>)-[C<x2>,C<y2>] in the
-source image to a rectangle the same size with it's top-left corner at
-(C<tx>,C<ty>) in the destination image.
+In general the callbacks should behave like the corresponding POSIX
+primitives.
-If C<x1> > C<x2> or C<y1> > C<y2> then the corresponding co-ordinates
-are swapped.
+=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
=for comment
-From: File paste.im
+From: File iolayer.c
-=item i_copyto_trans(C<im>, C<src>, C<x1>, C<y1>, C<x2>, C<y2>, C<tx>, C<ty>, C<trans>)
+=item io_new_fd(fd)
+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.
-(C<x1>,C<y1>) (C<x2>,C<y2>) specifies the region to copy (in the
-source coordinates) (C<tx>,C<ty>) specifies the upper left corner for
-the target image. pass NULL in C<trans> for non transparent i_colors.
+ fd - file descriptor to read/write from
=for comment
-From: File image.c
+From: File iolayer.c
-=item i_img_info(im, info)
+=item i_io_close(io)
+Flush any pending output and perform the close action for the stream.
-Return image information
+Returns 0 on success.
- im - Image pointer
- info - pointer to array to return data
-info is an array of 4 integers with the following values:
+=for comment
+From: File iolayer.c
- info[0] - width
- info[1] - height
- info[2] - channels
- info[3] - channel mask
+=item i_io_flush(io)
+
+Flush any buffered output.
+
+Returns true on success,
=for comment
-From: File image.c
+From: File iolayer.c
-=item i_rubthru(C<im>, C<src>, C<tx>, C<ty>, C<src_minx>, C<src_miny>, C<src_maxx>, C<src_maxy>)
+=item i_io_getc(ig)
+A macro to read a single byte from a buffered I/O glue object.
-Takes the sub image C<src>[C<src_minx>, C<src_maxx>)[C<src_miny>, C<src_maxy>)> and
-overlays it at (C<tx>,C<ty>) on the image object.
+Returns EOF on failure, or a byte.
-The alpha channel of each pixel in C<src> is used to control how much
-the existing color in C<im> is replaced, if it is 255 then the color
-is completely replaced, if it is 0 then the original color is left
-unmodified.
+
+=for comment
+From: File iolayer.c
+
+=item i_io_gets(ig, buffer, size, end_of_line)
+
+ char buffer[BUFSIZ]
+ ssize_t len = i_io_gets(buffer, sizeof(buffer), '\n');
+
+Read up to C<size>-1 bytes from the stream C<ig> into C<buffer>.
+
+If the byte C<end_of_line> is seen then no further bytes will be read.
+
+Returns the number of bytes read.
+
+Always C<NUL> terminates the buffer.
=for comment
-From: File rubthru.im
+From: File iolayer.c
+=item i_io_peekc(ig)
-=back
+Read the next character from the stream without advancing the stream.
-=head2 Image creation/destruction
+On error or end of file, return EOF.
+
+For unbuffered streams a single character buffer will be setup.
-=over
-=item i_img_16_new(x, y, ch)
+=for comment
+From: File iolayer.c
+=item i_io_peekn(ig, buffer, size)
-Create a new 16-bit/sample image.
+ ssize_t count = i_io_peekn(ig, buffer, sizeof(buffer));
-Returns the image on success, or NULL on failure.
+Buffer at least C<size> (at most C<< ig->buf_size >> bytes of data
+from the stream and return C<size> bytes of it to the caller in
+C<buffer>.
+
+This ignores the buffered state of the stream, and will always setup
+buffering if needed.
+
+If no C<type> parameter is provided to Imager::read() or
+Imager::read_multi(), Imager will call C<i_io_peekn()> when probing
+for the file format.
+
+Returns -1 on error, 0 if there is no data before EOF, or the number
+of bytes read into C<buffer>.
=for comment
-From: File img16.c
+From: File iolayer.c
+
+=item i_io_putc(ig, c)
-=item i_img_8_new(x, y, ch)
+Write a single character to the stream.
+On success return c, on error returns EOF
+
+
+=for comment
+From: File iolayer.c
+=item i_io_read(io, buffer, size)
-Creates a new image object I<x> pixels wide, and I<y> pixels high with
-I<ch> channels.
+Read up to C<size> bytes from the stream C<io> into C<buffer>.
+
+Returns the number of bytes read. Returns 0 on end of file. Returns
+-1 on error.
=for comment
-From: File image.c
+From: File iolayer.c
+
+=item i_io_seek(io, offset, whence)
-=item i_img_double_new(int x, int y, int ch)
+Seek within the stream.
-Creates a new double per sample image.
+Acts like perl's seek.
=for comment
-From: File imgdouble.c
+From: File iolayer.c
+
+=item i_io_set_buffered(io, buffered)
+
+Set the buffering mode of the stream.
+
+If you switch buffering off on a stream with buffering on:
-=item i_img_pal_new(C<x>, C<y>, C<channels>, C<maxpal>)
+=over
+=item *
-Creates a new paletted image of the supplied dimensions.
+any buffered output will be flushed.
-C<maxpal> is the maximum palette size and should normally be 256.
+=item *
-Returns a new image or NULL on failure.
+any existing buffered input will be consumed before reads become
+unbuffered.
+
+=back
+
+Returns true on success. This may fail if any buffered output cannot
+be flushed.
=for comment
-From: File palimg.c
+From: File iolayer.c
-=item i_sametype(C<im>, C<xsize>, C<ysize>)
+=item i_io_write(io, buffer, size)
+ ssize_t result = i_io_write(io, buffer, size)
-Returns an image of the same type (sample size, channels, paletted/direct).
+Write to the given I/O stream.
-For paletted images the palette is copied from the source.
+Returns the number of bytes written.
+
+
+=for comment
+From: File iolayer.c
+
+=item io_slurp(ig, c)
+
+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.
+Note: This only works for io_glue objects created by
+io_new_bufchain(). It is useful for saving to scalars and such.
+
+ ig - io_glue object
+ c - pointer to a pointer to where data should be copied to
+
+ char *data;
+ size_t size = io_slurp(ig, &data);
+ ... do something with the data ...
+ myfree(data);
+
+io_slurp() will abort the program if the supplied I/O layer is not
+from io_new_bufchain().
+
+
+=for comment
+From: File iolayer.c
+
+=item io_glue_destroy(ig)
+
+ io_glue_destroy(ig);
+
+Destroy an io_glue objects. Should clean up all related buffers.
+
+ ig - io_glue object to destroy.
+
+
+=for comment
+From: File iolayer.c
+
+
+=back
+
+=head2 Image
+
+=over
+
+=item i_copy(source)
+
+
+Creates a new image that is a copy of the image C<source>.
+
+Tags are not copied, only the image data.
+
+Returns: i_img *
=for comment
From: File image.c
-=item i_sametype_chans(C<im>, C<xsize>, C<ysize>, C<channels>)
+=item i_copyto(C<dest>, C<src>, C<x1>, C<y1>, C<x2>, C<y2>, C<tx>, C<ty>)
-Returns an image of the same type (sample size).
+Copies image data from the area (C<x1>,C<y1>)-[C<x2>,C<y2>] in the
+source image to a rectangle the same size with it's top-left corner at
+(C<tx>,C<ty>) in the destination image.
-For paletted images the equivalent direct type is returned.
+If C<x1> > C<x2> or C<y1> > C<y2> then the corresponding co-ordinates
+are swapped.
+
+
+=for comment
+From: File paste.im
+
+=item i_copyto_trans(C<im>, C<src>, C<x1>, C<y1>, C<x2>, C<y2>, C<tx>, C<ty>, C<trans>)
+
+
+(C<x1>,C<y1>) (C<x2>,C<y2>) specifies the region to copy (in the
+source coordinates) (C<tx>,C<ty>) specifies the upper left corner for
+the target image. pass NULL in C<trans> for non transparent i_colors.
=for comment
From: File image.c
-=item i_img_destroy(C<img>)
+=item i_img_info(im, info)
-Destroy an image object
+
+Return image information
+
+ im - Image pointer
+ info - pointer to array to return data
+
+info is an array of 4 integers with the following values:
+
+ info[0] - width
+ info[1] - height
+ info[2] - channels
+ info[3] - channel mask
=for comment
From: File image.c
+=item i_rubthru(C<im>, C<src>, C<tx>, C<ty>, C<src_minx>, C<src_miny>, C<src_maxx>, C<src_maxy>)
+
+
+Takes the sub image C<src>[C<src_minx>, C<src_maxx>)[C<src_miny>, C<src_maxy>)> and
+overlays it at (C<tx>,C<ty>) on the image object.
+
+The alpha channel of each pixel in C<src> is used to control how much
+the existing color in C<im> is replaced, if it is 255 then the color
+is completely replaced, if it is 0 then the original color is left
+unmodified.
+
+
+=for comment
+From: File rubthru.im
+
=back
-=head2 Image Implementation
+=head2 Image creation/destruction
=over
-=item i_img_alloc()
+=item i_sametype(C<im>, C<xsize>, C<ysize>)
-Allocates a new i_img structure.
-When implementing a new image type perform the following steps in your
-image object creation function:
+ i_img *img = i_sametype(src, width, height);
-=over
+Returns an image of the same type (sample size, channels, paletted/direct).
+
+For paletted images the palette is copied from the source.
-=item 1.
-allocate the image with i_img_alloc().
+=for comment
+From: File image.c
-=item 2.
+=item i_sametype_chans(C<im>, C<xsize>, C<ysize>, C<channels>)
-initialize any function pointers or other data as needed, you can
-overwrite the whole block if you need to.
-=item 3.
+ i_img *img = i_sametype_chans(src, width, height, channels);
-initialize Imager's internal data by calling i_img_init() on the image
-object.
+Returns an image of the same type (sample size).
-=back
+For paletted images the equivalent direct type is returned.
=for comment
From: File image.c
-=item i_img_
init(C<img>)
+=item i_img_
destroy(C<img>)
-Imager internal initialization of images.
+ i_img_destroy(img)
-Currently this does very little, in the future it may be used to
-support threads, or color profiles.
+Destroy an image object
=for comment
=item i_img_get_height(C<im>)
+ i_img_dim height = i_img_get_height(im);
+
Returns the height in pixels of the image.
=item i_img_get_width(C<im>)
+ i_img_dim width = i_img_get_width(im);
+
Returns the width in pixels of the image.
=item i_img_getchannels(C<im>)
+ int channels = i_img_getchannels(img);
+
Get the number of channels in C<im>.
=item i_img_getmask(C<im>)
+ int mask = i_img_getmask(img);
+
Get the image channel mask for C<im>.
=item i_img_setmask(C<im>, C<ch_mask>)
+ // only channel 0 writable
+ i_img_setmask(img, 0x01);
+
Set the image channel mask for C<im> to C<ch_mask>.
The image channel mask gives some control over which channels can be
=item i_tags_set(tags, name, data, size)
+ i_tags_set(&img->tags, "i_comment", -1);
+
Sets the given tag to the string I<data>
If size is -1 then the strlen(I<data>) bytes are stored.
=item i_tags_setn(C<tags>, C<name>, C<idata>)
+ i_tags_setn(&img->tags, "i_xres", 204);
+ i_tags_setn(&img->tags, "i_yres", 196);
+
Sets the given tag to the integer C<idata>
Even on failure, if an existing tag C<name> exists, it will be
From: File tags.c
+=back
+
+=head2 Uncategorized functions
+
+=over
+
+=item i_utf8_advance(char **p, size_t *len)
+
+Retrieve a C<UTF-8> character from the stream.
+
+Modifies *p and *len to indicate the consumed characters.
+
+This doesn't support the extended C<UTF-8> encoding used by later
+versions of Perl. Since this is typically used to implement text
+output by font drivers, the strings supplied shouldn't have such out
+of range characters.
+
+This doesn't check that the C<UTF-8> character is using the shortest
+possible representation.
+
+Returns ~0UL on failure.
+
+
+=for comment
+From: File io.c
+
+
+
=back
=head1 AUTHOR
-Tony Cook <tony@imager.perl.org>
+Tony Cook <tonyc@cpan.org>
=head1 SEE ALSO
projects / imager.git / blobdiff