`lqr_carver_set_energy_function`
Prev | Energy | Next

## Name

lqr_carver_bias_set_energy_function — set a custom energy function for a `LqrCarver` object

## Synopsis

    #include <lqr.h>

`LqrRetVal lqr_carver_set_energy_function(` | LqrCarver* carver,
| LqrEnergyFunc en_func,
| gint radius,
| LqrEnergyReaderType reader_type,
| gpointer extra_data`)`;

## Description

The function `lqr_carver_set_energy_function` assigns the energy function `en_func` to the `LqrCarver` object pointed to by `carver` (see below for more details on custom functions definitions).

The parameter `radius` determines the size of the square region which affects the computation around each pixel (the side of the square will be `2 * `radius` + 1` pixels long).

The parameter `reader_type` sets the reader type used when reading the image, and therefore it determines what quantity will be passed on to the function `en_func` (see below for more details on reader types).

The parameter `extra_data` is a (void) pointer which can be used to pass on additional values to the function `ef_func`.

## Custom functions definition

The function `en_func` must be of type `LqrEnergyFunc`, whose prototype is defined by:

    typedef gfloat (*LqrEnergyFunc) (gint x, gint y, gint img_width, gint img_height, LqrReadingWindow * rwindow, gpointer extra_data);

Such a function is expected to compute the energy at pixel `x`, `y` based on the knowledge of the current image size (obtained from `width` and `height`) and the content of the image in a square around that pixel, which is passed through the `rwindow` reading window.

In most cases, the parameters `x`, `y`, `width` and `height` would only be used to determine whether the region under consideration is at the image boundary or not.

The `rwindow` content must be read using the function `lqr_rwindow_read`(3).

## Reader types

The `LqrEnergyReaderType` is an enum which can take these values (also noted is the number of channels of the corresponging reading window):

`LQR_ER_BRIGHTNESS`

  brightness (1 channel)

`LQR_ER_BRIGHTNESS`

  luma (1 channel)

`LQR_ER_RGBA`

  RGBA (4 channels)

`LQR_ER_CUSTOM`

  read the normalised image channels as they are (as many channels as the image has)

These readouts always return values beetween `0` and `1`.

Note that these readouts may have special meanings depending on the image type:

- for `LQR_GREY_IMAGE`, `LQR_GREYA_IMAGE` and `LQR_CUSTOM_IMAGE` images, the `LQR_ER_LUMA` readout will yield the same result as `LQR_ER_BRIGHTNESS`

- for `LQR_CUSTOM_IMAGE` images, the `LQR_ER_BRIGHTNESS` readout will return the average pixel value (additive, i.e. if a black channel is present the channel values will be inverted and multiplied by the black channel inverse), multiplied by the alpha channel value.

- for `LQR_CUSTOM_IMAGE` images, the `LQR_ER_RGBA` readout cannot be used: it will always return `0`

## Return value

The return value follows the Liquid Rescale library signalling system.

## See also

`lqr_carver_set_energy_function_builtin`(3), `lqr_carver_get_energy`(3), `lqr_rwindow_read`(3), `lqr_rwindow_get_read_t`(3), `lqr_rwindow_get_radius`(3), `lqr_rwindow_get_channels`(3)

Prev | Up | Next
`lqr_carver_set_energy_function_builtin` | Home | `lqr_carver_get_energy`