Liquid rescaling
Prev | Chapter 2. LqR library API user manual | Next

## Liquid rescaling

### The resizing method

Once initialised, or if a visibility map has been loaded, the image can be resized through this function:

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

This function decides automatically whether it can use the already computed visibility map, it has to update it or waste it completely and start afresh. This last event occurs when the map was computed for horizontal resizing and a vertical resize has been requested, or vice versa, and also when the required enlargment is bigger than the enlargement step value (see Setting the enlargement step). Note that only initialised carvers can update or change the visibility map; if this is not the case, an error is returned.

The function also takes advantage of the fact that the enlargment process mirrors the shrink process. For example, if the original size of the image is `(w0, h0)` and `lqr_carver_resize` is invoked with `(w0 - 100, h0)` as an argument, then subsequent calls to the function will allow on-the-fly resizing in the whole range from `(w0 - 100, h0)` to `(w0 + 100, h0)`. (But note that this may be overcome if `w0 + 100` is bigger than the enlargement step.)

### Flattening

In order to resize in more than one step, the image can be flattened in its current state, thrugh this function:

`gboolean lqr_carver_flatten(` | LqrCarver * carver`)`;

The return value is `FALSE` in case of insufficient memory, `TRUE` otherwise.

This function destroys the current visibility map and reinitialises the multi-size image from its current state.

### Note

Every time that the image is flattened (including when changing the resize direction) the original image and all information about it is lost.

### Cancelling an action

The resizing and flattening operations can be aborted using this function:

`LqrRetVal lqr_carver_cancel(` | LqrCarver * carver`)`;

This function can be invoked asynchronously, from a different thread with respect to the one in which the resizing or flattening methods were called. If successful, this function will return `LQR_OK`, and any ongoing resizing or flattening functions will immidiately abort and return the special value `LQR_USRCANCEL`; however, this function will have no effect if no operation was in progress when calling it.

This function can be called multiple times.

### Important

Whenever a function returns `LQR_USRCANCEL`, it means that the `LqrCarver` object is in an inconsistent state, and there is currently no way to recover from this situation. Therefore, any further operation on it must be avoided, and it must be destroyed.

### Important

The functions `lqr_carver_resize` and `lqr_carver_flatten` are not the only ones which can return `LQR_USRCANCEL`; instead, any function in the library whose return type is `LqrRetVal` and which operates on `LqrCarver` objects can return such value: for example, any function will do so if called over a `LqrCarver` object for which an operation was actually cancelled (but this is not the only possibility).

Prev | Up | Next
Generating the multi-size image | Home | Reading the multi-size image