NAME

image.c - implements most of the basic functions of Imager and much of the rest

SYNOPSIS

i_img *i;
i_color *c;
c = i_color_new(red, green, blue, alpha);
ICL_DESTROY(c);
i = i_img_8_new();
i_img_destroy(i);
// and much more

DESCRIPTION

image.c implements the basic functions to create and destroy image and color objects for Imager.

FUNCTION REFERENCE

Some of these functions are internal.

im_img_alloc(aIMCTX) =category Image Implementation =synopsis i_img *im = im_img_alloc(aIMCTX); =synopsis 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:

1. allocate the image with i_img_alloc().

2. initialize any function pointers or other data as needed, you can overwrite the whole block if you need to.

3. initialize Imager's internal data by calling i_img_init() on the image object.

im_img_init(aIMCTX, image) =category Image Implementation =synopsis im_img_init(aIMCTX, im); =synopsis i_img_init(im);

Imager internal initialization of images.

See "im_img_alloc(aIMCTX)" for more information.

ICL_new_internal(r, g, b, a)

Return a new color object with values passed to it.

r - red   component (range: 0 - 255)
g - green component (range: 0 - 255)
b - blue  component (range: 0 - 255)
a - alpha component (range: 0 - 255)

ICL_set_internal(cl, r, g, b, a)

Overwrite a color with new values.

  cl - pointer to color object
  r - red   component (range: 0 - 255)
  g - green component (range: 0 - 255)
  b - blue  component (range: 0 - 255)
  a - alpha component (range: 0 - 255)

ICL_add(dst, src, ch)

Add src to dst inplace - dst is modified.

dst - pointer to destination color object
src - pointer to color object that is added
ch - number of channels

ICL_info(cl)

Dump color information to log - strictly for debugging.

cl - pointer to color object

ICL_DESTROY

Destroy ancillary data for Color object.

cl - pointer to color object

i_fcolor_new(double r, double g, double b, double a)

i_fcolor_destroy(i_fcolor *cl)

i_img_exorcise(im)

Free image data.

im - Image pointer

i_img_destroy(img) =order 90 =category Image creation/destruction =synopsis i_img_destroy(img)

Destroy an image object

i_img_info(im, info)

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

i_img_setmask(im, ch_mask) =category Image Information =synopsis // only channel 0 writable =synopsis i_img_setmask(img, 0x01);

Set the image channel mask for im to ch_mask.

The image channel mask gives some control over which channels can be written to in the image.

i_img_getmask(im) =category Image Information =synopsis int mask = i_img_getmask(img);

Get the image channel mask for im.

i_img_getchannels(im) =category Image Information =synopsis int channels = i_img_getchannels(img);

Get the number of channels in im.

i_img_get_width(im) =category Image Information =synopsis i_img_dim width = i_img_get_width(im);

Returns the width in pixels of the image.

i_img_get_height(im) =category Image Information =synopsis i_img_dim height = i_img_get_height(im);

Returns the height in pixels of the image.

i_img_color_model(im) =category Image Information =synopsis i_color_model_t cm = i_img_color_model(im);

Returns the color model for the image.

A future version of Imager will allow for images with extra channels beyond gray/rgb and alpha.

i_img_alpha_channel(im, &channel) =category Image Information =synopsis int alpha_channel; =synopsis int has_alpha = i_img_alpha_channel(im, &alpha_channel);

Work out the alpha channel for an image.

If the image has an alpha channel, sets *channel to the alpha channel index and returns non-zero.

If the image has no alpha channel, returns zero and *channel is not modified.

channel may be NULL.

i_img_color_channels(im) =category Image Information =synopsis int color_channels = i_img_color_channels(im);

Returns the number of color channels in the image. For now this is always 1 (for grayscale) or 3 (for RGB) but may be 0 in some special cases in a future release of Imager.

i_copyto_trans(im, src, x1, y1, x2, y2, tx, ty, trans)

(x1,y1) (x2,y2) specifies the region to copy (in the source coordinates) (tx,ty) specifies the upper left corner for the target image. pass NULL in trans for non transparent i_colors.

i_copy(source)

Creates a new image that is a copy of the image source.

Tags are not copied, only the image data.

Returns: i_img *

i_scaleaxis(im, value, axis)

Returns a new image object which is im scaled by value along wither the x-axis (axis == 0) or the y-axis (axis == 1).

i_scale_nn(im, scx, scy)

Scale by using nearest neighbor Both axes scaled at the same time since nothing is gained by doing it in two steps

i_sametype(im, xsize, ysize)

Returns an image of the same type (sample size, channels, paletted/direct).

For paletted images the palette is copied from the source.

i_sametype_chans(im, xsize, ysize, channels)

Returns an image of the same type (sample size).

For paletted images the equivalent direct type is returned.

i_transform(im, opx, opxl, opy, opyl, parm, parmlen)

Spatially transforms im returning a new image.

opx for a length of opxl and opy for a length of opy are arrays of operators that modify the x and y positions to retreive the pixel data from.

parm and parmlen define extra parameters that the operators may use.

Note that this function is largely superseded by the more flexible "i_transform2" in transform.c.

Returns the new image.

The operators for this function are defined in stackmach.c.

i_img_diff(im1, im2)

Calculates the sum of the squares of the differences between correspoding channels in two images.

If the images are not the same size then only the common area is compared, hence even if images are different sizes this function can return zero.

i_img_diffd(im1, im2)

Calculates the sum of the squares of the differences between correspoding channels in two images.

If the images are not the same size then only the common area is compared, hence even if images are different sizes this function can return zero.

This is like i_img_diff() but looks at floating point samples instead.

i_count_colors(im, maxc)

returns number of colors or -1 to indicate that it was more than max colors

Image method wrappers

These functions provide i_fsample_t functions in terms of their i_sample_t versions.

i_ppixf_fp(i_img *im, i_img_dim x, i_img_dim y, i_fcolor *pix)

i_gpixf_fp(i_img *im, i_img_dim x, i_img_dim y, i_fcolor *pix)

i_plinf_fp(i_img *im, i_img_dim l, i_img_dim r, i_img_dim y, i_fcolor *pix)

i_glinf_fp(i_img *im, i_img_dim l, i_img_dim r, i_img_dim y, i_fcolor *pix)

i_gsampf_fp(i_img *im, i_img_dim l, i_img_dim r, i_img_dim y, i_fsample_t *samp, int *chans, int chan_count)

Palette wrapper functions

Used for virtual images, these forward palette calls to a wrapped image, assuming the wrapped image is the first pointer in the structure that im->ext_data points at.

i_addcolors_forward(i_img *im, const i_color *colors, int count)

i_getcolors_forward(i_img *im, int i, i_color *color, int count)

i_setcolors_forward(i_img *im, int i, const i_color *color, int count)

i_colorcount_forward(i_img *im)

i_maxcolors_forward(i_img *im)

i_findcolor_forward(i_img *im, const i_color *color, i_palidx *entry)

Fallback handler

i_gsamp_bits_fb

i_test_format_probe(io_glue *data, int length)

Check the beginning of the supplied file for a 'magic number'

i_img_is_monochrome(img, &zero_is_white)

Tests an image to check it meets our monochrome tests.

The idea is that a file writer can use this to test where it should write the image in whatever bi-level format it uses, eg. pbm for pnm.

For performance of encoders we require monochrome images:

• be paletted

• have a palette of two colors, containing only (0,0,0) and (255,255,255) in either order.

zero_is_white is set to non-zero if the first palette entry is white.

i_get_file_background(im, &bg)

Retrieve the file write background color tag from the image.

If not present, bg is set to black.

Returns 1 if the i_background tag was found and valid.

i_get_file_backgroundf(im, &bg)

Retrieve the file write background color tag from the image as a floating point color.

Implemented in terms of i_get_file_background().

If not present, bg is set to black.

Returns 1 if the i_background tag was found and valid.

AUTHOR

Arnar M. Hrafnkelsson <addi@umich.edu>

Tony Cook <tonyc@cpan.org>

SEE ALSO

Imager, gif.c