Tiler
Eina » Data Types

## Data Structures

struct | Eina_Tile_Grid_Info
| Grid type of a tiler. More...

## Typedefs

typedef struct _Eina_Tiler | Eina_Tiler
| Tiler type.
typedef struct Eina_Tile_Grid_Info | Eina_Tile_Grid_Info
| Grid type of a tiler.
typedef struct _Eina_Tile_Grid_Slicer | Eina_Tile_Grid_Slicer

## Functions

EINA_API Eina_Tiler * | eina_tiler_new (int w, int h)
| Creates a new tiler with `w` width and `h` height.
EINA_API void | eina_tiler_free (Eina_Tiler *t)
| Frees a tiler.
EINA_API void | eina_tiler_tile_size_set (Eina_Tiler *t, int w, int h)
| Sets the size of tiles for a tiler.
EINA_API void | eina_tiler_area_size_set (Eina_Tiler *t, int w, int h)
| Changes the size of the area covered by the tiler.
EINA_API void | eina_tiler_area_size_get (const Eina_Tiler *t, int *w, int *h)
| Gets the size of the area covered by the tiler.
EINA_API void | eina_tiler_strict_set (Eina_Tiler *t, Eina_Bool strict)
| Defines if we need to follow a strict grid of tile or a loose one.
EINA_API Eina_Bool | eina_tiler_empty (const Eina_Tiler *t)
| Tells if a tiler is empty or not.
EINA_API Eina_Bool | eina_tiler_rect_add (Eina_Tiler *t, const Eina_Rectangle *r)
| Adds a rectangle to a tiler.
EINA_API void | eina_tiler_rect_del (Eina_Tiler *t, const Eina_Rectangle *r)
| Removes a rectangle from a tiler.
EINA_API void | eina_tiler_clear (Eina_Tiler *t)
| Removes all rectangles from tiles.
EINA_API Eina_Iterator * | eina_tiler_iterator_new (const Eina_Tiler *t)
| Creates a iterator to access the tilers calculated rectangles.
EINA_API Eina_Iterator * | eina_tile_grid_slicer_iterator_new (int x, int y, int w, int h, int tile_w, int tile_h)
| Creates a new Eina_Iterator that iterates over a list of tiles.
EINA_API Eina_Bool | eina_tiler_union (Eina_Tiler *dst, Eina_Tiler *src)
| Gets the union of two tilers.
EINA_API Eina_Bool | eina_tiler_subtract (Eina_Tiler *dst, Eina_Tiler *src)
| Subtracts two tilers.
EINA_API Eina_Tiler * | eina_tiler_intersection (Eina_Tiler *t1, Eina_Tiler *t2)
| Gets the intersection of two tilers.
EINA_API Eina_Bool | eina_tiler_equal (const Eina_Tiler *t1, const Eina_Tiler *t2)
| Gets whether two tilers are equal in rects or not.
static Eina_Bool | eina_tile_grid_slicer_next (Eina_Tile_Grid_Slicer *slc, const Eina_Tile_Grid_Info **rect)
| Iterates over the tiles set by eina_tile_grid_slicer_setup().
static Eina_Bool | eina_tile_grid_slicer_setup (Eina_Tile_Grid_Slicer *slc, int x, int y, int w, int h, int tile_w, int tile_h)
| Sets up an Eina_Tile_Grid_Slicer struct.

## Detailed Description

Warning
  This is a very low level tool, in most situations (for example if you're using evas) you won't need this.

# Basic usage

Eina_Tiler is a tool to facilitate calculations of which areas are damaged and thus need to be re-rendered. The basic usage of Eina_Tiler is to give it the size of your canvas and a set of rectangular areas that need re-rendering, from that and using heuristics it'll tell you an efficient way to re-render in the form of a set of non-overlapping rectangles that covers the whole area that needs re-rendering.

The following is pseudo-code showing some simple use of Eina_Tiler:

tiler = eina_tiler_new(MY_CANVAS_WIDTH, MY_CANVAS_HEIGHT);
EINA_LIST_FOREACH(list_of_areas_that_need_re_rendering, l, rect)
eina_tiler_add(tiler, rect);
itr = eina_tiler_iterator_new(tiler);
EINA_ITERATOR_FOREACH(itr, rect)
my_function_that_repaints_areas_of_the_canvas(rect);
EINA_ITERATOR_FOREACH
#define EINA_ITERATOR_FOREACH(itr, data)
Definition for the macro to iterate over all elements easily.
Definition eina_iterator.h:448
EINA_LIST_FOREACH
#define EINA_LIST_FOREACH(list, l, _data)
Definition for the macro to iterate over a list.
Definition eina_list.h:1415
eina_tiler_iterator_new
EINA_API Eina_Iterator * eina_tiler_iterator_new(const Eina_Tiler *t)
Creates a iterator to access the tilers calculated rectangles.
Definition eina_tiler.c:1291
eina_tiler_new
EINA_API Eina_Tiler * eina_tiler_new(int w, int h)
Creates a new tiler with w width and h height.
Definition eina_tiler.c:1140

See also
  eina_tiler_new()
  eina_tiler_rect_add()
  eina_tiler_iterator_new()

Warning
  There are no guarantees that this will be the most efficient way to re-render for any particular case.

# Grid Slicer

Grid slicer and Eina_Tiler are usually used together, that is however not necessary, they can be used independently. Grid slicer provides an easy API to divide an area in tiles which is useful in certain applications to divide the area that will be rendered into tiles. It's customary to, then create one Eina_Tiler for each tile.

The following is pseudo-code showing a very simplified use of grid slicer together with Eina_Tiler:

itr = eina_tile_grid_slicer_iterator_new(0, 0, MY_CANVAS_WIDTH, MY_CANVAS_HEIGHT, TILE_WIDTH, TILE_HEIGHT);
EINA_ITERATOR_FOREACH(itr, grid_info)
{
tiler = eina_tiler_new(grid_info->rect.w, grid_info->rect.w);
EINA_LIST_FOREACH(list_of_areas_that_need_re_rendering_in_this_tile, l, rect)
eina_tiler_add(tiler, rect);
itr = eina_tiler_iterator_new(tiler);
EINA_ITERATOR_FOREACH(itr, rect)
my_function_that_repaints_areas_of_the_canvas(rect);
}
eina_tile_grid_slicer_iterator_new
EINA_API Eina_Iterator * eina_tile_grid_slicer_iterator_new(int x, int y, int w, int h, int tile_w, int tile_h)
Creates a new Eina_Iterator that iterates over a list of tiles.
Definition eina_tiler.c:1608

See also
  eina_tiler_new()
  eina_tiler_rect_add()
  eina_tile_grid_slicer_setup()
  eina_tile_grid_slicer_next()
  eina_tile_grid_slicer_iterator_new()

## Function Documentation

## eina_tiler_new()

EINA_API Eina_Tiler * eina_tiler_new | ( | int | w,
|  | int | h )

Creates a new tiler with `w` width and `h` height.

Parameters

  [in] | w | Width of the tiler
  [in] | h | Height of the tiler

Returns
  The newly created tiler

See also
  eina_tiler_free()

References EINA_API, EINA_MAGIC_SET, EINA_SAFETY_ON_TRUE_RETURN_VAL, and EINA_TRUE.

Referenced by eina_tiler_intersection().

## eina_tiler_free()

EINA_API void eina_tiler_free | ( | Eina_Tiler * | t | ) |

Frees a tiler.

Parameters

  [in] | t | The tiler to free.

This function frees `t`. It does not free the memory allocated for the elements of `t`.

References EINA_API.

Referenced by eina_tiler_intersection().

## eina_tiler_tile_size_set()

EINA_API void eina_tiler_tile_size_set | ( | Eina_Tiler * | t,
|  | int | w,
|  | int | h )

Sets the size of tiles for a tiler.

Parameters

  [in,out] | t | The tiler whose tile size will be set.
  [in] | w | Width of the tiles.
  [in] | h | Height of the tiles.

Warning
  `w` and `h` must be greater than zero, otherwise tile size won't be changed.
  Tile size is not used!

References EINA_API, and EINA_FALSE.

## eina_tiler_area_size_set()

EINA_API void eina_tiler_area_size_set | ( | Eina_Tiler * | t,
|  | int | w,
|  | int | h )

Changes the size of the area covered by the tiler.

Parameters

  [in,out] | t | The tiler whose area size will be set.
  [in] | w | Width of the area.
  [in] | h | Height of the area.

Since
  1.8

Warning
  Must clear the tiler before changing its size.

References EINA_API.

## eina_tiler_area_size_get()

EINA_API void eina_tiler_area_size_get | ( | const Eina_Tiler * | t,
|  | int * | w,
|  | int * | h )

Gets the size of the area covered by the tiler.

Parameters

  [in] | t | The tiler whose area size will be fetched.
  [out] | w | Width of the area.
  [out] | h | Height of the area.

Since
  1.8

References EINA_API.

## eina_tiler_strict_set()

EINA_API void eina_tiler_strict_set | ( | Eina_Tiler * | t,
|  | Eina_Bool | strict )

Defines if we need to follow a strict grid of tile or a loose one.

Parameters

  [in,out] | t | The tiler to apply the strict rules to.
  [in] | strict | Define if it will be strict or loose

By default it will be loose.

Since
  1.8

## eina_tiler_empty()

EINA_API Eina_Bool eina_tiler_empty | ( | const Eina_Tiler * | t | ) |

Tells if a tiler is empty or not.

Parameters

  [in] | t | The tiler to apply the strict rules to.

Returns
  EINA_TRUE when empty, EINA_FALSE when not.

Since
  1.8

References EINA_TRUE.

Referenced by eina_tiler_intersection().

## eina_tiler_rect_add()

EINA_API Eina_Bool eina_tiler_rect_add | ( | Eina_Tiler * | t,
|  | const Eina_Rectangle * | r )

Adds a rectangle to a tiler.

Parameters

  [in,out] | t | The tiler in which to add a container.
  [in] | r | The rectangle to be added.

Returns
  EINA_TRUE on success, EINA_FALSE on failure.

See also
  eina_tiler_rect_del()

References EINA_API, EINA_FALSE, EINA_SAFETY_ON_NULL_RETURN_VAL, and EINA_TRUE.

## eina_tiler_rect_del()

EINA_API void eina_tiler_rect_del | ( | Eina_Tiler * | t,
|  | const Eina_Rectangle * | r )

Removes a rectangle from a tiler.

Parameters

  [in,out] | t | The tiler in which to add a container.
  [in] | r | The rectangle to be removed.

See also
  eina_tiler_rect_add()
  eina_tiler_clear()

References EINA_API, EINA_FALSE, and EINA_SAFETY_ON_NULL_RETURN.

## eina_tiler_clear()

EINA_API void eina_tiler_clear | ( | Eina_Tiler * | t | ) |

Removes all rectangles from tiles.

Parameters

  [in,out] | t | The tiler to clear.

See also
  eina_tiler_rect_del()

References EINA_API.

## eina_tiler_iterator_new()

EINA_API Eina_Iterator * eina_tiler_iterator_new | ( | const Eina_Tiler * | t | ) |

Creates a iterator to access the tilers calculated rectangles.

Parameters

  [in] | t | The tiler to iterate over.

Returns
  A iterator containing Eina_Rectangle.

References EINA_API, EINA_MAGIC_SET, EINA_TRUE, _Eina_Iterator::free, FUNC_ITERATOR_FREE, FUNC_ITERATOR_GET_CONTAINER, FUNC_ITERATOR_NEXT, _Eina_Iterator::get_container, _Eina_Iterator::next, and _Eina_Iterator::version.

Referenced by eina_tiler_equal(), eina_tiler_intersection(), eina_tiler_subtract(), and eina_tiler_union().

## eina_tile_grid_slicer_iterator_new()

EINA_API Eina_Iterator * eina_tile_grid_slicer_iterator_new | ( | int | x,
|  | int | y,
|  | int | w,
|  | int | h,
|  | int | tile_w,
|  | int | tile_h )

Creates a new Eina_Iterator that iterates over a list of tiles.

Parameters

  [in] | x | X axis coordinate.
  [in] | y | Y axis coordinate.
  [in] | w | Width.
  [in] | h | Height.
  [in] | tile_w | Tile width.
  [in] | tile_h | Tile height.

Returns
  A pointer to the Eina_Iterator. `NULL` on failure.

The region defined by x, y, w, h will be divided in to a grid of tiles of width tile_w and height `tile_h`, the returned iterator will iterate over every tile in the grid having as its data a Eina_Tile_Grid_Info.

Note
  This is a convenience function, iterating over the returned iterator is equivalent to calling eina_tile_grid_slicer_setup() and calling eina_tile_grid_slicer_next() until it returns EINA_FALSE.

References EINA_MAGIC_SET, _Eina_Iterator::free, FUNC_ITERATOR_FREE, FUNC_ITERATOR_NEXT, _Eina_Iterator::next, and _Eina_Iterator::version.

## eina_tiler_union()

EINA_API Eina_Bool eina_tiler_union | ( | Eina_Tiler * | dst,
|  | Eina_Tiler * | src )

Gets the union of two tilers.

Parameters

  [in,out] | dst | The first tiler, will store the result.
  [in] | src | The second tiler.

Returns
  EINA_TRUE on success, EINA_FALSE otherwise.

This function gets the union of tilers `dst` and `src`. The result is stored in `dst`. It returns EINA_TRUE if it succeeds.

Since
  1.11

References EINA_FALSE, EINA_ITERATOR_FOREACH, eina_iterator_free(), eina_tiler_iterator_new(), EINA_TRUE, _Eina_Rectangle::h, MAX, and _Eina_Rectangle::w.

## eina_tiler_subtract()

EINA_API Eina_Bool eina_tiler_subtract | ( | Eina_Tiler * | dst,
|  | Eina_Tiler * | src )

Subtracts two tilers.

Parameters

  [in,out] | dst | The first tiler, will store the result.
  [in] | src | The second tiler.

Returns
  EINA_TRUE on success, EINA_FALSE otherwise.

This function subtracts two tilers `dst` and `src`. The result is stored in `dst`. It returns EINA_TRUE if it succeeds.

Since
  1.11

References EINA_FALSE, EINA_ITERATOR_FOREACH, eina_iterator_free(), eina_tiler_iterator_new(), EINA_TRUE, _Eina_Rectangle::h, and _Eina_Rectangle::w.

## eina_tiler_intersection()

EINA_API Eina_Tiler * eina_tiler_intersection | ( | Eina_Tiler * | t1,
|  | Eina_Tiler * | t2 )

Gets the intersection of two tilers.

Parameters

  [in] | t1 | The first tile.
  [in] | t2 | The second tiler.

Returns
  A pointer of intersection result. `NULL` if intersection doesn't exist.

This function gets the intersection of two tilers `t1` and `t2`. It returns a pointer of result if intersection of two tilers exists., otherwise returns NULL.

Since
  1.11

References eina_iterator_free(), eina_iterator_next(), eina_tiler_empty(), eina_tiler_free(), eina_tiler_iterator_new(), eina_tiler_new(), _Eina_Rectangle::h, MAX, MIN, _Eina_Rectangle::w, _Eina_Rectangle::x, and _Eina_Rectangle::y.

## eina_tiler_equal()

EINA_API Eina_Bool eina_tiler_equal | ( | const Eina_Tiler * | t1,
|  | const Eina_Tiler * | t2 )

Gets whether two tilers are equal in rects or not.

Parameters

  [in] | t1 | The first tiler.
  [in] | t2 | The second tiler.

Returns
  EINA_TRUE if equal, EINA_FALSE if unequal.

This function gets result of comparison for `t1` and `t2`. It returns EINA_TRUE if tilers are equal.

Since
  1.11

References EINA_FALSE, eina_iterator_free(), eina_iterator_next(), eina_tiler_iterator_new(), EINA_TRUE, _Eina_Rectangle::h, _Eina_Rectangle::w, _Eina_Rectangle::x, and _Eina_Rectangle::y.

## eina_tile_grid_slicer_next()

Eina_Bool eina_tile_grid_slicer_next | ( | Eina_Tile_Grid_Slicer * | slc,
|  | const Eina_Tile_Grid_Info ** | rect )

inline static

Iterates over the tiles set by eina_tile_grid_slicer_setup().

Parameters

  [in,out] | slc | Pointer to an Eina_Tile_Grid_Slicer struct.
  [out] | rect | Pointer to a struct Eina_Tile_Grid_Info *.

Returns
  EINA_TRUE if the current rect is valid. EINA_FALSE if there are no more rects to iterate over (and thus the current one isn't valid).

This functions iterates over each Eina_Tile_Grid_Info *rect of the grid. eina_tile_grid_slicer_setup() must be called first, and *rect is only valid if this function returns EINA_TRUE. Its content shouldn't be modified.

Note
  Consider using eina_tile_grid_slicer_iterator_new() instead.

## eina_tile_grid_slicer_setup()

Eina_Bool eina_tile_grid_slicer_setup | ( | Eina_Tile_Grid_Slicer * | slc,
|  | int | x,
|  | int | y,
|  | int | w,
|  | int | h,
|  | int | tile_w,
|  | int | tile_h )

inline static

Sets up an Eina_Tile_Grid_Slicer struct.

Parameters

  [out] | slc | Pointer to an Eina_Tile_Grid_Slicer struct.
  [in] | x | X axis coordinate.
  [in] | y | Y axis coordinate.
  [in] | w | Width.
  [in] | h | Height.
  [in] | tile_w | Tile width.
  [in] | tile_h | Tile height.

Returns
  A pointer to the Eina_Iterator, `NULL` on failure.

The region defined by x, y, w, h will be divided into a grid of tiles of width tile_w and height `tile_h`, `slc` can then be used with eina_tile_grid_slicer_next() to access each tile.

Note
  Consider using eina_tile_grid_slicer_iterator_new() instead.