# The public pixel image API.

An concrete pixel image. More...

## Data Structures
struct | hpgs_image_vtable_st
| A table of virtual function implementing `hpgs_image`. More...
struct | hpgs_image_st
| An abstract pixel image. More...
struct | hpgs_png_image_st
## Functions
HPGS_API int | hpgs_image_define_color_func (hpgs_image *image, hpgs_paint_color *c)
static int | hpgs_image_define_color (hpgs_image *image, hpgs_paint_color *c)
HPGS_API int | hpgs_image_set_palette (hpgs_image *image, hpgs_palette_color *p, int np)
HPGS_API hpgs_png_image * | hpgs_new_png_image (int width, int height, int depth, hpgs_bool palette, hpgs_bool do_rop3)
HPGS_API int | hpgs_png_image_set_compression (hpgs_png_image *pim, int compression)
HPGS_API int | hpgs_image_set_resolution (hpgs_image *pim, double x_dpi, double y_dpi)
HPGS_API int | hpgs_image_get_data (hpgs_image *_this, unsigned char **data, int *stride, int *depth)
static int | hpgs_image_get_pixel (const hpgs_image *_this, int x, int y, hpgs_paint_color *c, double *alpha)
static int | hpgs_image_put_pixel (hpgs_image *_this, int x, int y, const hpgs_paint_color *c, double alpha)
static int | hpgs_image_put_chunk (hpgs_image *_this, int x1, int x2, int y, const hpgs_paint_color *c)
static int | hpgs_image_rop3_pixel (hpgs_image *_this, int x, int y, const hpgs_paint_color *c, double alpha)
static int | hpgs_image_rop3_chunk (hpgs_image *_this, int x1, int x2, int y, const hpgs_paint_color *c)
HPGS_API int | hpgs_image_resize (hpgs_image *_this, int w, int h)
HPGS_API int | hpgs_image_clear (hpgs_image *_this)
HPGS_API int | hpgs_image_write (hpgs_image *_this, const char *filename)
HPGS_API int | hpgs_image_setrop3 (hpgs_image *_this, hpgs_rop3_func_t rop3)
HPGS_API int | hpgs_image_setpatcol (hpgs_image *_this, const hpgs_palette_color *p)
HPGS_API void | hpgs_image_destroy (hpgs_image *_this)
HPGS_API int | hpgs_image_rop3_clip (hpgs_device *device, hpgs_palette_color *data, const hpgs_image *img, const hpgs_point *ll, const hpgs_point *lr, const hpgs_point *ur, const hpgs_palette_color *p, hpgs_xrop3_func_t xrop3)

## Detailed Description

An concrete pixel image.

The structures and functions in this group handle the creation and manipulation of rectangular pixel containers.

This structure has a public alias `hpgs_png_image` and implements `hpgs_image`. The storage format is similar to the format used by `libpng`, so the image may be written to png file using `hpgs_png_image_write`.

## Function Documentation

HPGS_API int hpgs_image_clear | ( | hpgs_image * | _this | ) |

Clears the given image `_this`.

References hpgs_image_vtable_st::clear, hpgs_set_error(), and hpgs_image_st::vtable.

__inline__ int hpgs_image_define_color | ( | hpgs_image * | image,
|  | hpgs_paint_color * | c |
| ) |  |  | `[static]`

Enter the supplied rgb value to the palette of an indexed image. Set the index member of `c` to the palette index of the RGB triplet.

If the palette is exhausted, -1 is returned.

References hpgs_image_define_color_func(), and hpgs_image_st::palette.

Referenced by hpgs_new_png_image().

HPGS_API int hpgs_image_define_color_func | ( | hpgs_image * | image,
|  | hpgs_paint_color * | c |
| ) |  |  |

The helper function for the inline function `hpgs_image_define_color`, which is actually called for indexed images.

References hpgs_palette_color_st::b, hpgs_paint_color_st::b, hpgs_palette_color_st::g, hpgs_paint_color_st::g, hpgs_set_error(), hpgs_paint_color_st::index, hpgs_image_st::palette, hpgs_image_st::palette_idx, hpgs_image_st::palette_ncolors, hpgs_palette_color_st::r, and hpgs_paint_color_st::r.

Referenced by hpgs_image_define_color().

HPGS_API void hpgs_image_destroy | ( | hpgs_image * | _this | ) |

Destroys the given image and frees all allocated resources by this image.

References hpgs_image_vtable_st::destroy, hpgs_image_st::palette, hpgs_image_st::palette_idx, and hpgs_image_st::vtable.

Referenced by hpgs_destroy_reader(), and hpgs_new_paint_device().

HPGS_API int hpgs_image_get_data | ( | hpgs_image * | _this,
|  | unsigned char ** | data,
|  | int * | stride,
|  | int * | depth |
| ) |  |  |

Gets the pixel buffer of the png image, which is needed by some backends. If the image is not a png image -1 is retuned.

If 0 is returned, *data point to the image data and *stride is the number of bytes between two consecutive scanlines of the image.

References hpgs_image_vtable_st::get_data, hpgs_set_error(), and hpgs_image_st::vtable.

__inline__ int hpgs_image_get_pixel | ( | const hpgs_image * | _this,
|  | int | x,
|  | int | y,
|  | hpgs_paint_color * | c,
|  | double * | alpha |
| ) |  |  | `[static]`

Retrieves the color and alpha value of the pixel in column `x` and row `y`.

References hpgs_image_vtable_st::get_pixel, and hpgs_image_st::vtable.

Referenced by hpgs_image_rop3_clip().

__inline__ int hpgs_image_put_chunk | ( | hpgs_image * | _this,
|  | int | x1,
|  | int | x2,
|  | int | y,
|  | const hpgs_paint_color * | c |
| ) |  |  | `[static]`

Sets the color of all pixels in the columns `x1` up to `x2` in row `y`. The alpha value is set to 1.

References hpgs_image_vtable_st::put_chunk, and hpgs_image_st::vtable.

__inline__ int hpgs_image_put_pixel | ( | hpgs_image * | _this,
|  | int | x,
|  | int | y,
|  | const hpgs_paint_color * | c,
|  | double | alpha |
| ) |  |  | `[static]`

Sets the color and alpha value of the pixel in column `x` and row `y`.

References hpgs_image_vtable_st::put_pixel, and hpgs_image_st::vtable.

HPGS_API int hpgs_image_resize | ( | hpgs_image * | _this,
|  | int | w,
|  | int | h |
| ) |  |  |

Resizes the given image `_this` to a new width `w` and new height `h`. The pixel data preserved or initialized, if the image grows.

References hpgs_set_error(), hpgs_image_vtable_st::resize, and hpgs_image_st::vtable.

__inline__ int hpgs_image_rop3_chunk | ( | hpgs_image * | _this,
|  | int | x1,
|  | int | x2,
|  | int | y,
|  | const hpgs_paint_color * | c |
| ) |  |  | `[static]`

Sets the color of all pixels in the columns `x1` up to `x2` in row `y`. The alpha value is set to 1. This function applies a ROP3 operation, if supported by the image.

References hpgs_image_vtable_st::rop3_chunk, and hpgs_image_st::vtable.

HPGS_API int hpgs_image_rop3_clip | ( | hpgs_device * | device,
|  | hpgs_palette_color * | data,
|  | const hpgs_image * | img,
|  | const hpgs_point * | ll,
|  | const hpgs_point * | lr,
|  | const hpgs_point * | ur,
|  | const hpgs_palette_color * | p,
|  | hpgs_xrop3_func_t | xrop3 |
| ) |  |  |

Sets a clip frame to the given device, which encloses all regions of the device, which are cover by the image taking into account the given ROP3 transfer function.

The argument `data` must contain a pointer to a two-dimensional array of raw pixels of the size of the image. This array is filled with pixel values as if the image has been painted to a white destination area using the given ROP3 function.

Return values:

- 0 The clip frame is empty, no operation has been performed on the output device.

- 1 The clip frame is not empty, the clip path has been set to the output device using clipsave/moveto/lineto/clip operations.

- 2 The clip frame covers the whole image, no operation has been performed on the output device.

- 3 The clip frame is not empty, the visible pixels have all the same color and clip path has been set to the output device using moveto/lineto/setrgbcolor/fill operations. The image does not have to be transferred by subsequent functions, the rgb color of the device has been altered.

- -1 An error occured on the output device.

References hpgs_color_st::b, hpgs_palette_color_st::b, hpgs_paint_color_st::b, hpgs_color_st::g, hpgs_palette_color_st::g, hpgs_paint_color_st::g, hpgs_image_st::height, hpgs_clip(), hpgs_clipsave(), hpgs_closepath(), hpgs_fill(), hpgs_image_get_pixel(), hpgs_lineto(), hpgs_log(), hpgs_moveto(), hpgs_newpath(), hpgs_set_error(), hpgs_setrgbcolor(), hpgs_color_st::r, hpgs_palette_color_st::r, hpgs_paint_color_st::r, hpgs_image_st::width, hpgs_point_st::x, and hpgs_point_st::y.

__inline__ int hpgs_image_rop3_pixel | ( | hpgs_image * | _this,
|  | int | x,
|  | int | y,
|  | const hpgs_paint_color * | c,
|  | double | alpha |
| ) |  |  | `[static]`

Sets the color and alpha value of the pixel in column `x` and row `y`. This function applies a ROP3 operation, if supported by the image.

References hpgs_image_vtable_st::rop3_pixel, and hpgs_image_st::vtable.

HPGS_API int hpgs_image_set_palette | ( | hpgs_image * | image,
|  | hpgs_palette_color * | p,
|  | int | np |
| ) |  |  |

Sets the palette to an indexed image.

References hpgs_set_error(), hpgs_image_st::palette, hpgs_image_st::palette_idx, hpgs_image_st::palette_ncolors, and hpgs_palette_color_st::r.

HPGS_API int hpgs_image_set_resolution | ( | hpgs_image * | _this,
|  | double | x_dpi,
|  | double | y_dpi |
| ) |  |  |

Sets the resolution of this image in dpi. Note that for PNG images the information in the pHYs chunk is given as an integral number of pixels per meter.

References hpgs_image_vtable_st::set_resolution, and hpgs_image_st::vtable.

Referenced by hpgs_new_paint_device().

HPGS_API int hpgs_image_setpatcol | ( | hpgs_image * | _this,
|  | const hpgs_palette_color * | p |
| ) |  |  |

Sets the color of the pattern applied by the ROP3 operation.

References hpgs_image_vtable_st::setpatcol, and hpgs_image_st::vtable.

HPGS_API int hpgs_image_setrop3 | ( | hpgs_image * | _this,
|  | hpgs_rop3_func_t | rop3 |
| ) |  |  |

Sets the ROP3 raster operation applied by `hpgs_image_put_pixel` and `hpgs_image_put_chunk`.

References hpgs_image_vtable_st::setrop3, and hpgs_image_st::vtable.

HPGS_API int hpgs_image_write | ( | hpgs_image * | _this,
|  | const char * | filename |
| ) |  |  |

Writes the given image `_this` to a file with the given name `filename`.

References hpgs_set_error(), hpgs_image_st::vtable, and hpgs_image_vtable_st::write.

HPGS_API hpgs_png_image* hpgs_new_png_image | ( | int | width,
|  | int | height,
|  | int | depth,
|  | hpgs_bool | palette,
|  | hpgs_bool | do_rop3 |
| ) |  |  |

Creates a new `hpgs_png_image` on the heap using the given `width` and `height`. The bit depth `depth` of the image is limited to 8,16, 24 or 32.

If `palette` is `HPGS_TRUE` the image uses and indexed palette and the bit depth is limited to 8.

If `palette` is `HPGS_FALSE` the folowing depth are supported:

- 8 contructs a greyscale image.
- 16 contructs a greyscale image with alpha (transparency) plane.
- 24 contructs an RGB image.
- 16 contructs an RGB image with alpha (transparency) plane.

If `do_rop3` is `HPGS_TRUE` the image uses ROP3 raster operations. `do_rop3` is ignored for indexed images. Indexed images do never support raster operations.

References hpgs_paint_color_st::b, hpgs_paint_color_st::g, hpgs_image_define_color(), and hpgs_paint_color_st::r.

HPGS_API int hpgs_png_image_set_compression | ( | hpgs_png_image * | pim,
|  | int | compression |
| ) |  |  |

Sets the compression ratio used for a png image. Returns 0, if the compression is in the interval from 1 to 9 inclusive.

If the compression is invalid, -1 is returned.

References hpgs_set_error().