Ilib Image Library
The Ilib library is a portable set of routines for manipulating images. It has been successfully compiled and run on various UNIX platforms as well as Windows 95/98/NT (gcc, lcc-win32 and MS Visual C++). The source is 32-bit, so this will never be a 16-bit Windows application. It is intended to be independent of any windowing system or graphics file format.
API Documentation
IColor IAllocColor ( unsigned int red, unsigned int green, unsigned int blue )
Allocates a color to be used for drawing. (See ISetForeground).
Returns: IColor
Input Parameters:
- unsigned int red - red value (0-255)
- unsigned int green - green value (0-255)
- unsigned int blue - blue value (0-255)
IError IAllocNamedColor ( char *colorname, IColor *color_ret )
Allocates a color by name (i.e. "blue") to be used for drawing. (See ISetForeground).
Returns: IError
Input Parameters:
- char *colorname - color name ("red, "orange", etc.)
- IColor *color_ret - resulting color
IError IArcProperties ( IGC gc, int x, int y, int r1, int r2, double a1, double a2, int *a1_x, int *a1_y, int *a2_x, int *a2_y, int *middle_x, int *middle_y )
Determines the x-y coordinates of the starting, stopping and middle point of an arc. Any of the pointers may be NULL if you're not interested in obtaining the value.
Returns: IError
Input Parameters:
- IGC gc - graphics context
- int x - arc center x coordinate
- int y - arc center y coordinate
- int r1 - angle 1 radius
- int r2 - angle 2 radius
- double a1 - first angle (in degrees)
- double a2 - second angle (in degrees)
Output Parameters:
- int *a1_x - x coordinate of edge of angle 1
- int *a1_y - y coordinate of edge of angle 1
- int *a2_x - x coordinate of edge of angle 2
- int *a2_y - y coordinate of edge of angle 2
- int *middle_x - x coordinate of edge center
- int *middle_y - y coordinate of edge center
IError ICopyImage ( IImage source, IImage dest, IGC gc, int src_x, int src_y, unsigned int width, unsigned int height, int dest_x, int dest_y )
Copies all or part of one image onto another image at a specified coordinate.
Returns: IError
Input Parameters:
- IImage source - source image
- IImage dest - destination image
- IGC gc - graphics context
- int src_x - x from source image
- int src_y - y from source image
- unsigned int width - width to copy
- unsigned int height - height to copy
- int dest_x - x coordinate on the destination image
- int dest_y - y coordinate on the destination image
IError ICopyImageScaled ( IImage source, IImage dest, IGC gc, int src_x, int src_y, unsigned int src_width, unsigned int src_height, int dest_x, int dest_y, unsigned int dest_width, unsigned int dest_height )
Copies all of an image to another image by scaling it to fit.
Returns: IError
Input Parameters:
- IImage source - source image
- IImage dest - destination image
- IGC gc - graphics context
- int src_x - x from source image
- int src_y - y from source image
- unsigned int src_width - width of source image to copy
- unsigned int src_height - height of source image to copy
- int dest_x - x coordinate on the destination image
- int dest_y - y coordinate on the destination image
- unsigned int dest_width - width to copy to
- unsigned int dest_height - height to copy to
IGC ICreateGC ( )
Creates a graphic context for drawing on an image.
Returns: IGC
Input Parameters:
IImage ICreateImage ( unsigned int width, unsigned int height, unsigned int options )
Create a blank (white) image of a specified width and height.
Returns: IImage
Input Parameters:
- unsigned int width - image width
- unsigned int height - image height
- unsigned int options - options flags (IOPTION_GREYSCALE, etc.)
IError IDrawArc ( IImage image, IGC gc, int x, int y, int r1, int r2, double a1, double a2 )
Draws an arc onto the image using the graphic context's current line style ( see ISetLineStyle). In order to draw an arc that passes over 0 degrees, the first angle (a1) should be negative and the second angle (a2) should be positive.
Returns: IError
Input Parameters:
- IImage image - image
- IGC gc - graphics context
- int x - arc center x coordinate
- int y - arc center y coordinate
- int r1 - angle 1 radius
- int r2 - angle 2 radius
- double a1 - first angle (in degrees)
- double a2 - second angle (in degrees)
IError IDrawCircle ( IImage image, IGC gc, int x, int y, int r )
Draws a circle onto the image using the graphic context's current line style ( see ISetLineStyle).
Returns: IError
Input Parameters:
- IImage image - image
- IGC gc - graphics context
- int x - circle center x coordinate
- int y - circle center y coordinate
- int r - circle radius
IError IDrawEllipse ( IImage image, IGC gc, int x, int y, int r1, int r2 )
Draws an ellipse onto the image using the graphic context's current line style ( see ISetLineStyle).
Returns: IError
Input Parameters:
- IImage image - image
- IGC gc - graphics context
- int x - ellipse center x coordinate
- int y - ellipse center y coordinate
- int r1 - x radius
- int r2 - y radius
IError IDrawEnclosedArc ( IImage image, IGC gc, int x, int y, int r1, int r2, double a1, double a2 )
Draws an arc and connects the arc to the center point using the graphic context's current line style ( see ISetLineStyle). This function is intended to be used drawing pie charts. In order to draw an arc that passes over 0 degrees, the first angle (a1) should be negative and the second angle (a2) should be positive.
Returns: IError
Input Parameters:
- IImage image - image
- IGC gc - graphics context
- int x - arc center x coordinate
- int y - arc center y coordinate
- int r1 - angle 1 radius
- int r2 - angle 2 radius
- double a1 - first angle (in degrees)
- double a2 - second angle (in degrees)
IError IDrawLine ( IImage image, IGC gc, int x1, int y1, int x2, int y2 )
Draws a line onto the image using the graphics context's current line style ( see ISetLineStyle).
Returns: IError
Input Parameters:
- IImage image - image
- IGC gc - graphics context
- int x1 - 1st coordinate
- int y1 - 1st coordinate
- int x2 - 2nd coordinate
- int y2 - 2nd coordinate
IError IDrawPoint ( IImage image, IGC gc, int x, int y )
Draws a single point on the image.
Returns: IError
Input Parameters:
- IImage image - image
- IGC gc - graphics context
- int x - x coordinate
- int y - y coordinate
IError IDrawPolygon ( IImage image, IGC gc, IPoint *points, int npoints )
Draws a polygon onto the image using the graphics context's current line style ( see ISetLineStyle).
Returns: IError
Input Parameters:
- IImage image - image
- IGC gc - graphics context
- IPoint *points - array of points
- int npoints - size of above array
IError IDrawRectangle ( IImage image, IGC gc, int x, int y, unsigned int width, unsigned int height )
Draws a rectangle onto the image of the specified width and height using the graphic context's current line stlye ( see ISetLineStyle).
Returns: IError
Input Parameters:
- IImage image - image
- IGC gc - graphics context
- int x - x coordinate
- int y - y coordinate
- unsigned int width - width
- unsigned int height - height
IError IDrawString ( IImage image, IGC gc, int x, int y, char *text, unsigned int len )
Draws text onto the image at the specified coordinate. See the font definition file to determine which characters are supported.
Note: the font is set with ISetFont.
Returns: IError
Input Parameters:
- IImage image - image
- IGC gc - graphics context
- int x - x coordinate (lower left of text)
- int y - y coordinate (lower left of text)
- char *text - pointer to text
- unsigned int len - length of text
IError IDrawStringRotated ( IImage image, IGC gc, int x, int y, char *text, unsigned int len, ITextDirection direction )
Draws text onto the image at the specified coordinate using one of the angles: ITEXT_LEFT_TO_RIGHT, ITEXT_TOP_TO_BOTTOM, or ITEXT_BOTTOM_TO_TOP. See the font definition file to determine which characters are supported.
Note: the font is set with ISetFont. The x-y coordinates always specify the starting point to draw from (the lower left spot of the first character). For example, for ITEXT_TOP_TO_BOTTOM the x-y would represent the upper left area of the box where text will be drawn.
Returns: IError
Input Parameters:
- IImage image - image
- IGC gc - graphics context
- int x - x coordinate
- int y - y coordinate
- char *text - pointer to text
- unsigned int len - length of text
- ITextDirection direction - direction to draw text
IError IDrawStringRotatedAngle ( IImage image, IGC gc, int x, int y, char *text, unsigned int len, double angle )
Draws text onto the image at the specified coordinate using one the specified angle. This is slightly slower than IDrawStringRotated, so only use this function if you're drawing something other than 90, 180, or 270 degrees. See the font definition file to determine which characters are supported.
Note: the font is set with ISetFont. The x-y coordinates always specify the starting point to draw from (the lower left spot of the first character).
Returns: IError
Input Parameters:
- IImage image - image
- IGC gc - graphics context
- int x - x coordinate
- int y - y coordinate
- char *text - pointer to text
- unsigned int len - length of text
- double angle - angle to rotate text
IError IDuplicateImage ( IImage image, IImage *image_return )
Creates a duplicate of the original image.
Returns: IError
Input Parameters:
- IImage image - image to duplicate
Output Parameters:
- IImage *image_return - pointer to new image
char * IErrorString ( IError err )
Convert an IError value into text suitable for printing in an error message.
Returns: char *
Input Parameters:
IError IFileType ( char *file, IFileFormat *format_return )
Determine the type of image by the file extension.
Returns: IError
Input Parameters:
Output Parameters:
- IFileFormat *format_return - format of file
IError IFillArc ( IImage image, IGC gc, int x, int y, int r1, int r2, double a1, double a2 )
Fill an arc. In order to draw an arc that passes over 0 degrees, the first angle (a1) should be negative and the second angle (a2) should be positive.
Returns: IError
Input Parameters:
- IImage image - image
- IGC gc - graphics context
- int x - arc center x coordinate
- int y - arc center y coordinate
- int r1 - angle 1 radius
- int r2 - angle 2 radius
- double a1 - first angle (in degrees)
- double a2 - second angle (in degrees)
IError IFillCircle ( IImage image, IGC gc, int x, int y, int r )
Fill a circle.
Returns: IError
Input Parameters:
- IImage image - image
- IGC gc - graphics context
- int x - arc center x coordinate
- int y - arc center y coordinate
- int r - radius
IError IFillEllipse ( IImage image, IGC gc, int x, int y, int r1, int r2 )
Fill an ellipse.
Returns: IError
Input Parameters:
- IImage image - image
- IGC gc - graphics context
- int x - arc center x coordinate
- int y - arc center y coordinate
- int r1 - angle 1 radius
- int r2 - angle 2 radius
IError IFillPolygon ( IImage image, IGC gc, IPoint *points, int npoints )
Fill a polygon. Only convex, non-intersecting polygons are supported. Invalid polygons will return an error.
Returns: IError
Input Parameters:
- IImage image - image
- IGC gc - graphics context
- IPoint *points - array of points
- int npoints - size of above array
IError IFillRectangle ( IImage image, IGC gc, int x, int y, unsigned int width, unsigned int height )
Fills a rectangle on the image using the graphics context's foreground color (see ISetForeground).
Returns: IError
Input Parameters:
- IImage image - image
- IGC gc - graphics context
- int x - x coordinate
- int y - y coordinate
- unsigned int width - width
- unsigned int height - height
IError IFontSize ( IFont font, unsigned int *height_return )
Gets the pixel height of the font. (See ITextHeight for calculating the height of a multiline text.)
Returns: IError
Input Parameters:
Output Parameters:
- unsigned int *height_return - height in pixels of font
IError IFreeColor ( IColor color )
Frees a color no longer in use.
Returns: IError
Input Parameters:
IError IFreeFont ( IFont font )
Frees a font no longer in use.
Returns: IError
Input Parameters:
- IFont font - font to free
IError IFreeGC ( IGC gc )
Frees a graphic context no longer in use.
Returns: IError
Input Parameters:
- IGC gc - graphics context
IError IFreeImage ( IImage image )
Frees the memory associated with an image that will not be used again.
Returns: IError
Input Parameters:
- IImage image - pointer to image
IError IGetComment ( IImage image, char **comment )
Get the comment (if there is one).
Returns: IError
Input Parameters:
- IImage image - pointer to image
- char **comment - address to comment
IError IGetTransparent ( IImage image, IColor *color )
Get the transparent color of the image. If there is no transparent image set, then INoTransparentColor is returned.
Returns: IError
Input Parameters:
- IImage image - image
- IColor *color - returned color
IError ILoadFontFromData ( char *name, char **lines, IFont *font_return )
Loads a font from data passed in. This is identical to ILoadFontFromFile except the font data is passed in as an argument rather than a file. This allows the font to be embedded in the application rather than distributed as a separate file.
Returns: IError
Input Parameters:
- char *name - name to use for reference (filename)
- char **lines - font data (identical to file contents) as an array of character strings (one text line per array element terminated with a NULL element
Output Parameters:
- IFont *font_return - pointer to returned font
IError ILoadFontFromFile ( char *name, char *path, IFont *font_return )
Load a font from file. Currently, only BDF font files can be used. BDF font files can be found at: ftp://ftp.x.org/pub/R6.1/xc/fonts/bdf/75dpi/. (BDF fonts are part of the X11 Window System developed at MIT and used on almost all UNIX workstations.)
Returns: IError
Input Parameters:
- char *name - name to use for reference (filename)
- char *path - path to font file
Output Parameters:
- IFont *font_return - returned font
IError IReadImageFile ( FILE *fp, IFileFormat format, IOptions options, IImage *image_return )
Creates an image from an image file. Currently can read raw PPM (IFORMAT_PPM), XPM (IFORMAT_XPM), GIF (IFORMAT_GIF), PNG (IFORMAT_PNG), and JPEG (IFORMAT_JPEG) files. The file is left open for the caller to close. (Note: you should set the file to binary mode on Win32 platforms by using something like:
file = fopen ( filename, "rb" );
Returns: IError
Input Parameters:
- FILE *fp - file pointer
- IFileFormat format - output format (e.g. IFORMAT_GIF)
- IOptions options - options
Output Parameters:
- IImage *image_return - returned image on success
IError ISetBackground ( IGC gc, IColor color )
Set the background color of a graphics context. This will affect colors when using text styles.
Returns: IError
Input Parameters:
- IGC gc - graphics context
- IColor color - color
IError ISetComment ( IImage image, char *comment )
Set the comment.
Returns: IError
Input Parameters:
- IImage image - pointer to image
- char *comment - new comment
IError ISetFont ( IGC gc, IFont font )
Sets the current drawing font for a graphics context. Subsequent calls to IDrawString will use the specified font.
Returns: IError
Input Parameters:
- IGC gc - graphics context
- IFont font - font
IError ISetForeground ( IGC gc, IColor color )
Set the foreground color of a graphics context. This will set the drawing color for drawing functions (IDrawLine, IFillRectangle, etc.)
Returns: IError
Input Parameters:
- IGC gc - graphics context
- IColor color - color
IError ISetLineStyle ( IGC gc, ILineStyle line_style )
Sets the current line drawing style for a graphics context. Currently support ILINE_SOLID (default) and ILINE_ON_OFF_DASH. (This applies to IDrawLine and IDrawRectangle.)
Returns: IError
Input Parameters:
- IGC gc - graphics context
- ILineStyle line_style - line style
IError ISetLineWidth ( IGC gc, unsigned int line_width )
Sets the line drawing with for a graphics context. (This applies to IDrawLine and IDrawRectangle.)
Returns: IError
Input Parameters:
- IGC gc - graphics context
- unsigned int line_width - line width
IError ISetTextStyle ( IGC gc, ILineStyle line_style )
Returns: IError
Input Parameters:
- IGC gc - graphics context
- ILineStyle line_style - line style
IError ISetTransparent ( IImage image, IColor color )
Set the transparent color of the image. This is only relevant to images that are written to either GIF or XPM formats.
Returns: IError
Input Parameters:
- IImage image - image
- IColor color - color
IError ITextDimensions ( IGC gc, IFont font, char *text, unsigned int len, unsigned int *width_return, unsigned int *height_return )
Determines the width & height (in pixels) of the given text for the specified font. (useful for multiline text)
Returns: IError
Input Parameters:
- IGC gc - graphics context
- IFont font - font
- char *text - text
- unsigned int len - length of text
Output Parameters:
- unsigned int *width_return - width in pixels of text
- unsigned int *height_return - height in pixels of text
IError ITextHeight ( IGC gc, IFont font, char *text, unsigned int len, unsigned int *height_return )
Determines the height (in pixels) of the given text for the specified font. This is useful for multiline text.
Returns: IError
Input Parameters:
- IGC gc - graphics context
- IFont font - font
- char *text - text
- unsigned int len - length of text
Output Parameters:
- unsigned int *height_return - height in pixels of text
IError ITextWidth ( IGC gc, IFont font, char *text, unsigned int len, unsigned int *width_return )
Determines the length (in pixels) of the given text for the specified font.
Returns: IError
Input Parameters:
- IGC gc - graphics context
- IFont font - font
- char *text - text
- unsigned int len - length of text
Output Parameters:
- unsigned int *width_return - width in pixels of text
IError IWriteImageFile ( FILE *fp, IImage image, IFileFormat format, IOptions options )
Writes an image to a file. Currently supports writing PPM (IFORMAT_PPM), XPM (IFORMAT_XPM), GIF (IFORMAT_GIF), PNG (IFORMAT_PNG) and JPEG (IFORMAT_JPEG) formats. The file is left open for the caller to close. (Note: you should set the file to binary mode on Win32 platforms.)
Returns: IError
Input Parameters:
- FILE *fp - file pointer
- IImage image - image
- IFileFormat format - output format (e.g. IFORMAT_XPM)
- IOptions options - options (e.g. IOPTION_INTERLACED)