Image toolkits

	image_gd_info ()
	image_gd_settings ()
	image_gd_settings_validate ($form, &$form_state)
	image_gd_check_settings ()
	image_gd_resize ($source, $destination, $width, $height)
	image_gd_rotate ($source, $destination, $degrees, $background=0x000000)
	image_gd_crop ($source, $destination, $x, $y, $width, $height)
	image_gd_open ($file, $extension)
	image_gd_close ($res, $destination, $extension)
Functions
	image_get_available_toolkits ()
	image_get_toolkit ()
	image_toolkit_invoke ($method, $params=array())
	image_get_info ($file)
	image_scale_and_crop ($source, $destination, $width, $height)
	image_scale ($source, $destination, $width, $height)
	image_resize ($source, $destination, $width, $height)
	image_rotate ($source, $destination, $degrees, $background=0x000000)
	image_crop ($source, $destination, $x, $y, $width, $height)

---

Detailed Description

Drupal's image toolkits provide an abstraction layer for common image file manipulations like scaling, cropping, and rotating. The abstraction frees module authors from the need to support multiple image libraries, and it allows site administrators to choose the library that's best for them.

PHP includes the GD library by default so a GD toolkit is installed with Drupal. Other toolkits like ImageMagic are available from contrib modules. GD works well for small images, but using it with larger files may cause PHP to run out of memory. In contrast the ImageMagick library does not suffer from this problem, but it requires the ISP to have installed additional software.

Image toolkits are installed by copying the image.ToolkitName.inc file into Drupal's includes directory. The toolkit must then be enabled using the admin/settings/image-toolkit form.

Only one toolkit maybe selected at a time. If a module author wishes to call a specific toolkit they can check that it is installed by calling image_get_available_toolkits(), and then calling its functions directly.

---

Function Documentation

image_crop	(	$	source,
		$	destination,
		$	x,
		$	y,
		$	width,
		$	height
	)

Crop an image to the rectangle specified by the given rectangle.

Parameters:

	$source	The file path of the source image.
	$destination	The file path of the destination image.
	$x	The top left co-ordinate, in pixels, of the crop area (x axis value).
	$y	The top left co-ordinate, in pixels, of the crop area (y axis value).
	$width	The target width, in pixels.
	$height	The target height, in pixels.

Returns:

TRUE or FALSE, based on success.

Definition at line 264 of file image.inc.

References image_toolkit_invoke().

Here is the call graph for this function:

image_gd_check_settings

(

)

Verify GD2 settings (that the right version is actually installed).

Returns:

A boolean indicating if the GD toolkit is avaiable on this machine.

Definition at line 67 of file image.gd.inc.

Referenced by image_gd_settings(), and image_get_toolkit().

image_gd_close	(	$	res,
		$	destination,
		$	extension
	)

GD helper to write an image resource to a destination file.

Parameters:

	$res	An image resource created with image_gd_open().
	$destination	A string file path where the iamge should be saved.
	$extension	A string containing one of the following extensions: gif, jpg, jpeg, png.

Returns:

Boolean indicating success.

Definition at line 205 of file image.gd.inc.

References variable_get().

Referenced by image_gd_crop(), image_gd_resize(), and image_gd_rotate().

Here is the call graph for this function:

image_gd_crop	(	$	source,
		$	destination,
		$	x,
		$	y,
		$	width,
		$	height
	)

Crop an image using the GD toolkit.

Definition at line 157 of file image.gd.inc.

References $result, image_gd_close(), image_gd_open(), and image_get_info().

Here is the call graph for this function:

image_gd_info

(

)

Retrieve information about the toolkit.

Definition at line 17 of file image.gd.inc.

References t().

Here is the call graph for this function:

image_gd_open	(	$	file,
		$	extension
	)

GD helper function to create an image resource from a file.

Parameters:

	$file	A string file path where the iamge should be saved.
	$extension	A string containing one of the following extensions: gif, jpg, jpeg, png.

Returns:

An image resource, or FALSE on error.

Definition at line 184 of file image.gd.inc.

Referenced by image_gd_crop(), image_gd_resize(), and image_gd_rotate().

image_gd_resize	(	$	source,
		$	destination,
		$	width,
		$	height
	)

Scale an image to the specified size using GD.

Definition at line 80 of file image.gd.inc.

References $result, image_gd_close(), image_gd_open(), and image_get_info().

Here is the call graph for this function:

image_gd_rotate	(	$	source,
		$	destination,
		$	degrees,
		$	background = 0x000000
	)

Rotate an image the given number of degrees.

Definition at line 133 of file image.gd.inc.

References $result, image_gd_close(), image_gd_open(), and image_get_info().

Here is the call graph for this function:

image_gd_settings

(

)

Retrieve settings for the GD2 toolkit.

Definition at line 24 of file image.gd.inc.

References form_set_error(), image_gd_check_settings(), t(), and variable_get().

Here is the call graph for this function:

image_gd_settings_validate	(	$	form,
		&$	form_state
	)

Validate the submitted GD settings.

Definition at line 53 of file image.gd.inc.

References $value, form_set_error(), and t().

Here is the call graph for this function:

image_get_available_toolkits

(

)

Return a list of available toolkits.

Returns:

An array of toolkit name => descriptive title.

Definition at line 39 of file image.inc.

References $output, file_scan_directory(), and name.

Referenced by system_image_toolkit_settings().

Here is the call graph for this function:

image_get_info

(

$

file

)

Get details about an image.

Drupal only supports GIF, JPG and PNG file formats.

Returns:

FALSE, if the file could not be found or is not an image. Otherwise, a keyed array containing information about the image: 'width' - Width in pixels. 'height' - Height in pixels. 'extension' - Commonly used file extension for the image. 'mime_type' - MIME type ('image/jpeg', 'image/gif', 'image/png'). 'file_size' - File size in bytes.

Definition at line 116 of file image.inc.

Referenced by file_validate_image_resolution(), file_validate_is_image(), image_gd_crop(), image_gd_resize(), image_gd_rotate(), image_scale(), and image_scale_and_crop().

image_get_toolkit

(

)

Retrieve the name of the currently used toolkit.

Returns:

String containing the name of the selected toolkit, or FALSE on error.

Definition at line 61 of file image.inc.

References image_gd_check_settings(), and variable_get().

Referenced by file_validate_image_resolution(), image_toolkit_invoke(), and system_image_toolkit_settings().

Here is the call graph for this function:

image_resize	(	$	source,
		$	destination,
		$	width,
		$	height
	)

Resize an image to the given dimensions (ignoring aspect ratio).

Parameters:

	$source	The file path of the source image.
	$destination	The file path of the destination image.
	$width	The target width, in pixels.
	$height	The target height, in pixels.

Returns:

TRUE or FALSE, based on success.

Definition at line 222 of file image.inc.

References image_toolkit_invoke().

Here is the call graph for this function:

image_rotate	(	$	source,
		$	destination,
		$	degrees,
		$	background = 0x000000
	)

Rotate an image by the given number of degrees.

Parameters:

	$source	The file path of the source image.
	$destination	The file path of the destination image.
	$degrees	The number of (clockwise) degrees to rotate the image.
	$background	An hexidecimal integer specifying the background color to use for the uncovered area of the image after the rotation. E.g. 0x000000 for black, 0xff00ff for magenta, and 0xffffff for white.

Returns:

TRUE or FALSE, based on success.

Definition at line 242 of file image.inc.

References image_toolkit_invoke().

Here is the call graph for this function:

image_scale	(	$	source,
		$	destination,
		$	width,
		$	height
	)

Scales an image to the given width and height while maintaining aspect ratio.

The resulting image can be smaller for one or both target dimensions.

Parameters:

	$source	The file path of the source image.
	$destination	The file path of the destination image.
	$width	The target width, in pixels.
	$height	The target height, in pixels.

Returns:

TRUE or FALSE, based on success.

Definition at line 187 of file image.inc.

References image_get_info(), and image_toolkit_invoke().

Referenced by file_validate_image_resolution().

Here is the call graph for this function:

image_scale_and_crop	(	$	source,
		$	destination,
		$	width,
		$	height
	)

Scales an image to the exact width and height given. Achieves the target aspect ratio by cropping the original image equally on both sides, or equally on the top and bottom. This function is, for example, useful to create uniform sized avatars from larger images.

The resulting image always has the exact target dimensions.

Parameters:

	$source	The file path of the source image.
	$destination	The file path of the destination image.
	$width	The target width, in pixels.
	$height	The target height, in pixels.

Returns:

TRUE or FALSE, based on success.

Definition at line 157 of file image.inc.

References image_get_info(), and image_toolkit_invoke().

Here is the call graph for this function:

image_toolkit_invoke	(	$	method,
		$	params = array()
	)

Invokes the given method using the currently selected toolkit.

Parameters:

	$method	A string containing the method to invoke.
	$params	An optional array of parameters to pass to the toolkit method.

Returns:

Mixed values (typically Boolean indicating successful operation).

Definition at line 88 of file image.inc.

References image_get_toolkit(), and watchdog().

Referenced by image_crop(), image_resize(), image_rotate(), image_scale(), image_scale_and_crop(), and system_image_toolkit_settings().

Here is the call graph for this function: