path: root/docs/api.txt

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)
       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