diff --git a/legacy/eina/src/include/eina_inline_tiler.x b/legacy/eina/src/include/eina_inline_tiler.x index ffc34c1cf6..2a8b205dc2 100644 --- a/legacy/eina/src/include/eina_inline_tiler.x +++ b/legacy/eina/src/include/eina_inline_tiler.x @@ -42,19 +42,6 @@ struct _Eina_Tile_Grid_Slicer * @endcond */ -/** - * @brief Iterates over the tiles set by eina_tile_grid_slicer_setup(). - * - * @param slc Pointer to an Eina_Tile_Grid_Slicer struct. - * @param rect Pointer to a struct Eina_Tile_Grid_Info *. - * @return @c EINA_TRUE if the current rect is valid. - * @c EINA_FALSE if there is 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. - */ static inline Eina_Bool eina_tile_grid_slicer_next(Eina_Tile_Grid_Slicer *slc, const Eina_Tile_Grid_Info **rect) { @@ -102,24 +89,6 @@ eina_tile_grid_slicer_next(Eina_Tile_Grid_Slicer *slc, const Eina_Tile_Grid_Info return EINA_TRUE; } -/** - * @brief Setup an Eina_Tile_Grid_Slicer struct. - * - * @param slc Pointer to an Eina_Tile_Grid_Slicer struct. - * @param x X axis coordinate. - * @param y Y axis coordinate. - * @param w width. - * @param h height. - * @param tile_w tile width. - * @param tile_h tile height. - * @return A pointer to the Eina_Iterator. - * @c NULL on failure. - * - * This function splits the rectangle given as argument into tiles of size - * tile_w X tile_h, and returns an iterator to them. The geometry of each - * tile can be accessed with eina_tile_grid_slicer_next, where rect - * will be a pointer to a struct Eina_Tile_Grid_Info. - */ static inline 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) { diff --git a/legacy/eina/src/include/eina_tiler.h b/legacy/eina/src/include/eina_tiler.h index e1cbe0d9d7..cc6af75236 100644 --- a/legacy/eina/src/include/eina_tiler.h +++ b/legacy/eina/src/include/eina_tiler.h @@ -32,6 +32,49 @@ /** * @defgroup Eina_Tiler_Group Tiler * + * @warning This is a very low level tool, in most situations(for example if + * you're using evas) you won't need this. + * + * @section basic 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 a pseudo-code showing some simple use of Eina_Tiler: + * @code + * 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); + * @endcode + * + * @see eina_tiler_new() + * @see eina_tiler_rect_add() + * @see eina_tiler_iterator_new() + * + * @warning There are no guarantees that this will be the most efficient way to + * re-render for any particular case. + * + * @section grid_slicer Grid Slicer + * + * Grid slicer and Eina_Tiler are usually used together, that is however @b not + * nescessary, they can be used independently. Grid slicer provides an easy API + * to divide an area in tiles which is usefull 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. + * + * @see eina_tiler_new() + * @see eina_tiler_rect_add() + * @see eina_tile_grid_slicer_setup() + * @see eina_tile_grid_slicer_next() + * @see eina_tile_grid_slicer_iterator_new() + * * @{ */ @@ -53,24 +96,83 @@ typedef struct Eina_Tile_Grid_Info Eina_Tile_Grid_Info; */ struct Eina_Tile_Grid_Info { - unsigned long col; /**< column of the tiler grid */ - unsigned long row; /**< row of the tiler grid*/ - Eina_Rectangle rect; /**< rectangle of the tiler grid*/ + unsigned long col; /**< column of the tile grid */ + unsigned long row; /**< row of the tile grid*/ + Eina_Rectangle rect; /**< rectangle of the tile grid, coordinates are + relative to tile*/ Eina_Bool full; /**< whether the grid is full or not */ }; typedef struct _Eina_Tile_Grid_Slicer Eina_Tile_Grid_Slicer; +/** + * @brief Creates a new tiler with @p w width and @p h height. + * + * @param w Width of the tiler + * @param h Height of the tiler + * @return The newly created tiler + * + * @see eina_tiler_free() + */ EAPI Eina_Tiler *eina_tiler_new(int w, int h); +/** + * @brief Frees a tiler. + * + * @param t The tiler to free. + * + * This function frees @p t. It does not free the memory allocated for the + * elements of @p t. + */ EAPI void eina_tiler_free(Eina_Tiler *t); +/** + * @brief Sets the size of tiles for a tiler. + * + * @param t The tiler whose tile size will be set. + * @param w Width of the tiles. + * @param h Height of the tiles. + * + * @warning @p w and @p h @b must be greater than zero, otherwise tile size + * won't be changed. + * @warning Tile size is not used! + */ EAPI void eina_tiler_tile_size_set(Eina_Tiler *t, int w, int h); +/** + * @brief Adds a rectangle to a tiler. + * + * @param t The tiler in which to add a container. + * @param r The rectangle to be added. + * + * @see eina_tiler_rect_del() + */ EAPI Eina_Bool eina_tiler_rect_add(Eina_Tiler *t, const Eina_Rectangle *r); +/** + * @brief Removes a rectangle from a tiler. + * + * @param t The tiler in which to add a container. + * @param r The rectangle to be removed. + * + * @see eina_tiler_rect_add() + * @see eina_tiler_clear() + */ EAPI void eina_tiler_rect_del(Eina_Tiler *t, const Eina_Rectangle *r); +/** + * @brief Removes all rectangles from tiles. + * + * @param t The tiler to clear. + * + * @see eina_tiler_rect_del() + */ EAPI void eina_tiler_clear(Eina_Tiler *t); +/** + * @brief Create a iterator to access the tilers calculated rectangles. + * + * @param t The tiler to iterate over. + * @return A iterator containing Eina_Rectangle. + */ EAPI Eina_Iterator *eina_tiler_iterator_new(const Eina_Tiler *t); /** - * @brief Creates a new Eina_Iterator that slices over a list of tiles. + * @brief Creates a new Eina_Iterator that iterates over a list of tiles. * * @param x X axis coordinate. * @param y Y axis coordinate. @@ -78,19 +180,52 @@ EAPI Eina_Iterator *eina_tiler_iterator_new(const Eina_Tiler *t); * @param h height. * @param tile_w tile width. * @param tile_h tile height. - * @return A pointer to the Eina_Iterator. - * @c NULL on failure. + * @return A pointer to the Eina_Iterator. @c NULL on failure. * - * The tile grid is defined by @a tile_w and @a tile_h while the region is - * defined by @a x, @a y, @a w, @a h. The output is given as - * @c Eina_Tile_Grid_Info where tile index is given in @c col col and - * @c row row with tile-relative - * coordinates in @c x, @c y, @c w, @c h. If tile was fully filled by - * region, then @c full flag - * is set. + * The region defined by @a x, @a y, @a w, @a h will be divided in to a grid of + * tiles of width @a tile_w and height @p 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 convinience function, iterating over the returned iterator is + * equivalent to calling eina_tile_grid_slicer_setup() and calling + * eina_tile_grid_slicer_next() untill it returns EINA_FALSE. */ EAPI Eina_Iterator *eina_tile_grid_slicer_iterator_new(int x, int y, int w, int h, int tile_w, int tile_h); +/** + * @brief Iterates over the tiles set by eina_tile_grid_slicer_setup(). + * + * @param slc Pointer to an Eina_Tile_Grid_Slicer struct. + * @param rect Pointer to a struct Eina_Tile_Grid_Info *. + * @return @c EINA_TRUE if the current rect is valid. + * @c EINA_FALSE if there is 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. + */ static inline Eina_Bool eina_tile_grid_slicer_next(Eina_Tile_Grid_Slicer *slc, const Eina_Tile_Grid_Info **rect); +/** + * @brief Setup an Eina_Tile_Grid_Slicer struct. + * + * @param slc Pointer to an Eina_Tile_Grid_Slicer struct. + * @param x X axis coordinate. + * @param y Y axis coordinate. + * @param w width. + * @param h height. + * @param tile_w tile width. + * @param tile_h tile height. + * @return A pointer to the Eina_Iterator. @c NULL on failure. + * + * The region defined by @a x, @a y, @a w, @a h will be divided in to a grid of + * tiles of width @a tile_w and height @p tile_h, @p 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. + */ static inline 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); #include "eina_inline_tiler.x"