Documentation
=============
Below is a brief blurb about each of the functions in the php_imlib
extension. For examples of how these are used, see the examples page.
There are also some PHP classes included with php_imlib (Which also
have examples posted on the examples page). These classfiles have been
documented using the PHPDoc documentation system. That documentation
can be found here.
Predefined Constants
--------------------
IMLIB_TEXT_TO_RIGHT
IMLIB_TEXT_TO_LEFT
IMLIB_TEXT_TO_DOWN
IMLIB_TEXT_TO_UP
IMLIB_TEXT_TO_ANGLE
IMLIB_TTF_ENCODING_ISO_8859_1
IMLIB_TTF_ENCODING_ISO_8859_2
IMLIB_TTF_ENCODING_ISO_8859_3
IMLIB_TTF_ENCODING_ISO_8859_4
IMLIB_TTF_ENCODING_ISO_8859_5
IMLIB_CHANNEL_RED
IMLIB_CHANNEL_GREEN
IMLIB_CHANNEL_BLUE
IMLIB_CHANNEL_ALPHA
IMLIB_LOAD_ERROR_NONE
IMLIB_LOAD_ERROR_FILE_DOES_NOT_EXIST
IMLIB_LOAD_ERROR_FILE_IS_DIRECTORY
IMLIB_LOAD_ERROR_PERMISSION_DENIED_TO_READ
IMLIB_LOAD_ERROR_NO_LOADER_FOR_FILE_FORMAT
IMLIB_LOAD_ERROR_PATH_TOO_LONG
IMLIB_LOAD_ERROR_PATH_COMPONENT_NON_EXISTANT
IMLIB_LOAD_ERROR_PATH_COMPONENT_NOT_DIRECTORY
IMLIB_LOAD_ERROR_PATH_POINTS_OUTSIDE_ADDRESS_SPACE
IMLIB_LOAD_ERROR_TOO_MANY_SYMBOLIC_LINKS
IMLIB_LOAD_ERROR_OUT_OF_MEMORY
IMLIB_LOAD_ERROR_OUT_OF_FILE_DESCRIPTORS
IMLIB_LOAD_ERROR_PERMISSION_DENIED_TO_WRITE
IMLIB_LOAD_ERROR_OUT_OF_DISK_SPACE
IMLIB_LOAD_ERROR_UNKNOWN
Function List
-------------
imlib_add_color_to_color_range
imlib_blend_image_onto_image
imlib_clone_image
imlib_create_color_range
imlib_create_cropped_image
imlib_create_cropped_scaled_image
imlib_create_image
imlib_create_rotated_image
imlib_image_orientate
imlib_create_scaled_image
imlib_dump_image
imlib_free_color_range
imlib_free_font
imlib_free_image
imlib_get_text_size
imlib_image_blur
imlib_image_draw_ellipse
imlib_image_draw_line
imlib_image_draw_polygon
imlib_image_draw_rectangle
imlib_image_fill_color_range_rectangle
imlib_image_fill_ellipse
imlib_image_fill_polygon
imlib_image_fill_rectangle
imlib_image_flip_horizontal
imlib_image_flip_vertical
imlib_image_flip_diagonal
imlib_image_format
imlib_image_get_filename
imlib_image_get_height
imlib_image_get_width
imlib_image_has_alpha
imlib_image_modify_alpha
imlib_image_set_format
imlib_image_sharpen
imlib_image_tile_horizontal
imlib_image_tile_vertical
imlib_image_tile
imlib_list_fonts
imlib_load_font
imlib_load_image
imlib_polygon_add_point
imlib_polygon_contains_point
imlib_polygon_free
imlib_polygon_get_bounds
imlib_polygon_new
imlib_save_image
imlib_text_draw
imlib_psloadfont
imlib_psfreefont
imlib_psencodefont
imlib_psextendfont
imlib_psslantfont
imlib_pstext
imlib_psbbox
imlib_get_cache_size
imlib_set_cache_size
imlib_create_filter
imlib_free_filter
imlib_image_filter
imlib_filter_set
imlib_filter_set_alpha
imlib_filter_set_red
imlib_filter_set_green
imlib_filter_set_blue
imlib_filter_constants
imlib_filter_divisors
imlib_apply_filter
imlib_modify_color_modifier_gamma
imlib_modify_color_modifier_brightness
imlib_modify_color_modifier_contrast
imlib_reset_color_modifier
imlib_apply_color_modifier
imlib_set_color_modifier
imlib_get_color_modifier
Getting and Setting Image Parameters
------------------------------------
string imlib_image_format(int img)
Returns the image format of an image
string imlib_image_get_filename(int img)
Returns the filename of an image
int imlib_image_get_height(int img)
Returns the height of an image
int imlib_image_get_width(int img)
Returns the width of an image
bool imlib_image_has_alpha(int img)
Return a boolean for whether or not an image has an alpha
channel
void imlib_image_modify_alpha(int img, int alpha)
Set the alpha channel of an image, or modify it if one was
already present
void imlib_image_set_format(int img, string format)
Sets the image format of an image.
Loading/Saving Functions
------------------------
void imlib_free_image(int img)
Free an image
int imlib_load_image(string img[, int &err])
Load a file into an image, optionally fetch an error parameter
bool imlib_save_image(int img, string name[, int &err[, int quality]])
Save an image to a file, at an optional quality level (1-100)
for jpegs. For pngs, the value will be converted to a
compression level (0-9)
Creation Functions
------------------
int imlib_clone_image(int img)
Duplicate an image
int imlib_create_color_range()
Create a new color range
int imlib_create_cropped_image(int img, int srcx, int srcy, int srcw,
int srch)
Create an image from a cropped region of another image
int imlib_create_cropped_scaled_image(int img, int srcx, int srcy, int
srcw, int srch, int dstw, int dsth)
Create a scaled image from a cropped region of another image
int imlib_create_image(int w, int h)
Create a new image with the specified dimensions
int imlib_create_rotated_image(int srcimg, int degrees[, int radians])
Create a rotated copy of an image. If radians is specified,
degrees will be ignored.
int imlib_create_scaled_image(int img, int dstw, int dsth)
Create a scaled copy of an image. If dstw or dsth is left
blank, the aspect ratio of the source image will be preserved.
bool imlib_dump_image(int img[, int &err[, int quality]])
Output an image at an optional quality setting
Rendering Functions
-------------------
void imlib_blend_image_onto_image(int dstimg, int srcimg, int malpha,
int srcx, int srcy, int srcw, int srch, int dstx, int dsty, int
dstw, int dsth, char dither, char blend, char alias)
Blend a rectangular area from an image onto an area of another
image, scaling as necessary
Image Modification Functions
----------------------------
void imlib_image_blur(int img, int radius)
Blur an image with a given blur radius
void imlib_image_flip_horizontal(int img)
Flip an image horizontally
void imlib_image_flip_vertical(int img)
Flip an Imlib_Image vertically
void imlib_image_flip_diagonal(int img)
Flip an image diagonally
void imlib_image_orientate(int img, int stepping)
Orientate an image 90 x steps
void imlib_image_tile_horizontal(int img)
Tile an image horizontally
void imlib_image_tile_vertical(int img)
Tile an image vertically
void imlib_image_tile(int img)
Tile an image horizontally and diagonally
void imlib_image_sharpen(int img, int radius)
Sharpen an image with a given sharpen radius
Drawing on Images
-----------------
bool imlib_image_draw_ellipse(int img, int xc, int yc, int w, int h,
int r, int g, int b, int a[, array cliprect])
Draw an ellipse of the specified size and color on an image
bool imlib_image_draw_line(int img, int x1, int y1, int x2, int y2,
int r, int g, int b, int a[, array cliprect])
Draw a line of the specified size and color on an image
bool imlib_image_draw_polygon(int img, int polygon, bool closed, int
r, int g, int b, int a[, array cliprect])
Draw the defined polygon on an image
bool imlib_image_draw_rectangle(int img, int x, int y, int w, int h,
int r, int g, int b, int a[, array cliprect])
Draw a rectangle of the specified size and color on an image
bool imlib_image_fill_color_range_rectangle(int im, int cr, int x, int
y, int width, int height, int angle)
Fill a rectangle with a color range at a given angle on an
image
void imlib_image_fill_ellipse(int img, int xc, int yc, int w, int h,
int r, int g, int b, int a[, array cliprect])
Fill an ellipse of the specified size and color on an image
bool imlib_image_fill_polygon(int img, int polygon, int r, int g, int
b, int a[, array cliprect])
Draw and fill the defined polygon on an image
void imlib_image_fill_rectange(int img, int x, int y, int w, int h,
int r, int g, int b, int a[, array cliprect])
Fill a rectangle of the specified size and color on an image
Fonts and Text Functions
------------------------
void imlib_free_font(int font)
Free a font
void imlib_get_text_size(int font, string str, int &w, int &h, int
direction)
Determines the width and height of a string if drawn with a
given font in the specified direction
array imlib_list_fonts()
Return an array of all the fonts available in the font path
int imlib_load_font(string fontname[, string encoding])
Load a font
void imlib_text_draw(int img, int font, int x, int y, string str, int
direction, int r, int g, int b, int a)
Draw a text string using a font onto an image
T1 Functions
------------
These functions are almost identical to T1 functions in GD, please
consult GD documentation for more information on specific parameters.
Please note that font resources are NOT interchangeable between GD and
imlib.
int imlib_psloadfont(string pathname)
Load a new font from specified file
bool imlib_psfreefont(int font_index)
Free memory used by a font
bool imlib_psencodefont(int font_index, string filename)
To change a fonts character encoding vector
bool imlib_psextendfont(int font_index, double extend)
Extend or or condense (if extend < 1) a font
bool imlib_psslantfont(int font_index, double slant)
Slant a font
array imlib_pstext(int img, string text, int font, int size, int x, int
y, int r, int g, int b, int a [, int space[, int tightness[, double
angle[, int antialias]]]])
Rasterize a string over an image.
array imlib_psbbox(string text, int font, int size [, int space, int
tightness, int angle])
Return the bounding box needed by a string if rasterized
Color Ranges
------------
void imlib_add_color_to_color_range(int cr, int x, int r, int g, int
b, int a)
Add a color to a color range at a specified distance from the
previous color in the range. A distance of 0 centers it
void imlib_free_color_range(int cr)
Free a color range
Polygons
--------
void imlib_polygon_add_point(int polygon, int x, int y)
Add a point to a given polygon
bool imlib_polygon_contains_point(int polygon, int x, int y)
Check if a give point is inside a polygon
void imlib_polygon_free(int polygon)
Free a polygon
void imlib_polygon_get_bounds(int polygon, int &x1, int &y1, int &x2,
int &y2)
Get the bounding coords of a polygon
int imlib_polygon_new()
Create a new polygon
Image Cache
-----------
void imlib_set_cache_size(int bytes)
Set the size of image cache
int imlib_get_cache_size()
Get the size of image cache
Filters
-------
int imlib_create_filter(void)
Create a new filter
void imlib_free_filter(int filter)
Free a filter
void imlib_image_filter(int img, int filter)
Apply filter to an image
void imlib_filter_set(int filter, int xoff, int yoff, int a, int r, int
g, int b)
Set weights for source pixel at (xoff,yoff). All components of
the destination pixel will be affected.
void imlib_filter_set_alpha(int filter, int xoff, int yoff, int a, int r,
int g, int b)
Set weights for source pixel at (xoff,yoff). Only alpha component
of the destination pixel will be affected.
void imlib_filter_set_red(int filter, int xoff, int yoff, int a, int r,
int g, int b)
Set weights for source pixel at (xoff,yoff). Only red component of
the destination pixel will be affected.
void imlib_filter_set_green(int filter, int xoff, int yoff, int a, int r,
int g, int b)
Set weights for source pixel at (xoff,yoff). Only green component
of the destination pixel will be affected.
void imlib_filter_set_blue(int filter, int xoff, int yoff, int a, int r,
int g, int b)
Set weights for source pixel at (xoff,yoff). Only blue component
of the destination pixel will be affected.
void imlib_filter_constants(int filter, int a, int r, int g, int b)
Set filter constants
void imlib_filter_divisors(int filter, int a, int r, int g, int b)
Set filter divisors
External Filters
----------------
void imlib_apply_filter(int img, string filter, array params)
Apply external filter to an image
Color Modifiers
---------------
int imlib_create_color_modifier(void)
Create a new color modifier
void imlib_free_color_modifier(int cm)
Free a color modifier
void imlib_modify_color_modifier_gamma(int cm, double gamma_value)
Adjust color modifier gamma
void imlib_modify_color_modifier_brightness(int cm, double brightness_value)
Adjust color modifier brightness
void imlib_modify_color_modifier_contrast(int cm, double contrast_value)
Adjust color modifier contrast
void imlib_reset_color_modifier(int cm)
Reset color modifier to default (one-to-one) mapping
void imlib_apply_color_modifier(int img, int cm[, int x, int y, int width,
int height])
Apply color modifier to an image or its part
void imlib_set_color_modifier(int cm, int index, int value[, int channels])
Set color modifier value at given index for given channels (or all if
not specified)
void imlib_get_color_modifier(int cm, int index, int &red, int &green, int
&blue, int &alpha
Get color modifier values at given index