`lqr_carver_resize`
Prev | Carver objects | Next

## Name

lqr_carver_resize — liquid rescale a `LqrCarver` object

## Synopsis

    #include <lqr.h>

`LqrRetVal lqr_carver_resize(` | LqrCarver* carver,
| gint new_width,
| gint new_height`)`;

## Description

The function `lqr_carver_resize` performs the liquid rescaling over the `LqrCarver` object pointed to by `carver`. If a visibility map was loaded through the function `lqr_vmap_load`, and the carver was not initialised, the resizing operations must be limited to the direction and the sizes included in the loaded map. If the carver was initialised through the function `lqr_carver_init`, there are no limitations to the final size.

The resizing function can be called multiple times, and it will decide automatically whether the computation of the visibility map is necessary or not. In case it isn't, the function returns almost immediately, otherwise operations will proceed following the order given through the function `lqr_carver_set_resize_order`. Currently, on-the-fly rescaling without computation is only possible for a single direction at a time.

If the new size (in one direction or in both) is greater than or equal to the original size multiplied by the enlargement step of the `carver` object (as obtained through `lqr_carver_get_enl_step`(3)), the rescaling will be performed in multiple steps. At each step, the original size stored internally is reset to the new value; therefore, each step in the process can be bigger then the previous one.

Whenever the resizing dirction changes (this may happen in a single call of the rescaling function or through multiple calls), or if performing a multiple steps enlargement as per the previous paragraph, the visibility map computed during the first direction rescale is dropped to make place for the one for the second (and the original size of the image is reset to the current value). These visibility maps can be saved by using the `lqr_carver_set_vmap_dump` function, for inspection or future use.

## Return value

The return value follows the Liquid Rescale library signalling system. It returns an error if trying to exceed the limitations of a loaded visibility map, or if passed a negative or null size.

## See also

LqrRetVal(3), `lqr_carver_init`(3), `lqr_carver_flatten`(3), `lqr_carver_set_enl_step`(3), `lqr_carver_get_enl_step`(3), `lqr_carver_cancel`(3), `lqr_vmap_load`(3)

Prev | Up | Next
`lqr_carver_set_black_channel` | Home | `lqr_carver_flatten`