Last updated 13 March 2009. Created on 9 March 2008.
Edited by Scheepers de Bruin. Log in to edit this page.

Painter provides an API to create dynamic graphics by defining sequences of image IO, manipulation and drawing operations.

This documentation is primarily intended for developers and themers. View the painter ui (http://drupal.org/node/400876) and page elements (http://drupal.org/node/400890) module documentation for functions accessible through the user interface.

Painter provides the following methods to render dynamic imagery:

function painter_filename($chain_name, $args = FALSE, $id = FALSE, $meta = FALSE, $extension = '.png')

Returns the filename or metadata on a dynamically rendered image. If a chain is cached, the cached filename or metadata is returned.

$chain_name
The name of the rendering chain to use for image rendering.
$args
Arguments to be passed to a chain. (Text or an image filename, for the most part)
Arguments may be a single argument, or a keyed array of arguments. (A single argument will be converted to a keyed array with 'default' as the array key)
$meta
TRUE if the metadata should be returned in stead of the filename.
$extension
The extension of the output file - (PNG, JPG and GIF supported)

function painter_execute_chain($chain_name, $chain, &$variables = array())

Renders a dynamic image directly, bypassing the cache and returns the resulting $variables array (where all images and intermediate images are stored during chain execution)

$chain_name
The name of the rendering chain to use for image rendering.
$chain
The completely loaded and argument populated chain to be executed.
$variables
The variables array to use to store images during chain execution.

function painter_invoke_op($operation, $arguments, &$variables = NULL, $chain_name = NULL)

Invokes an image operation by finding the module that provides it, and executing the operation method with the provided variables and arguments.

$operation
The name of the operation to invoke.
$arguments
A keyed array of arguments to be passed to the operation.
$variables
The variables array to use to store images during execution.
$chain_name
The name of the chain this operation forms part of (for logging purposes).

Hooks exposed by the painter:

For modules that want to provide rendering chains:

function hook_chain($op, $arg = FALSE, $chain_args = FALSE)

Loads or lists chains provided by the implementing module.

$op ('list' || 'load')
Specifies whether to list chains, or to load a chain.
$arg
For $op == 'list': $arg specifies whether to list chains applicable to 'image' or 'text'. Lists all, if not supplied.
For $op == 'load': $arg specifies the chain name to be loaded
$chain_args
Only applies to loading a chain. The arguments passed to the chain.

For modules that want to provide image operations that may be used within chains:

function hook_provides_operations()

Returns an array of strings listing the image operations an implementing module provides.
These strings will be used as labels to present the operations within the UI, and will cause the painter to look for certain hook implementations within the module.

Eg. Returning array("Save image") will cause the painter to look for:

function mymodulename_op_save_image($args, &$variables = NULL)

This is the method that performs the actual image operation on images within the variables array.

$args
Arguments that is passed to the operation.
$variables
The variable array that is passed from operation to operation within a chain.

function mymodulename_op_form_save_image($chain_name, $args = FALSE)
optional

This hook provides the painter UI with a form to present to the user to provide arguments for the operation. Note that ONLY the fields required for arguments should be added. Buttons are provided.

$chain_name
The name of the chain that the operation is (or will be) part of.
$args
The arguments of an operation when it is being edited.

function mymodulename_op_form_save_image_validate($form, &$form_state)
optional

This hook provides the module the opportunity to validate the operation form values.

function mymodulename_op_form_save_image_adjust($form_id, $form_values)
optional

This hook provides the module the opportunity to adjust form values post validation, before being saved.

function mymodulename_op_summary_save_image($args)
optional

Returns a summary of the operation arguments to present in listings in the UI.

Looking for support? Visit the Drupal.org forums, or join #drupal-support in IRC.