diff options
Diffstat (limited to '')
-rw-r--r-- | libraries/eina/src/include/eina_tiler.h | 310 |
1 files changed, 310 insertions, 0 deletions
diff --git a/libraries/eina/src/include/eina_tiler.h b/libraries/eina/src/include/eina_tiler.h new file mode 100644 index 0000000..5272099 --- /dev/null +++ b/libraries/eina/src/include/eina_tiler.h | |||
@@ -0,0 +1,310 @@ | |||
1 | /* EINA - EFL data type library | ||
2 | * Copyright (C) 2007-2008 Jorge Luis Zapata Muga | ||
3 | * | ||
4 | * This library is free software; you can redistribute it and/or | ||
5 | * modify it under the terms of the GNU Lesser General Public | ||
6 | * License as published by the Free Software Foundation; either | ||
7 | * version 2.1 of the License, or (at your option) any later version. | ||
8 | * | ||
9 | * This library is distributed in the hope that it will be useful, | ||
10 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
11 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
12 | * Lesser General Public License for more details. | ||
13 | * | ||
14 | * You should have received a copy of the GNU Lesser General Public | ||
15 | * License along with this library; | ||
16 | * if not, see <http://www.gnu.org/licenses/>. | ||
17 | */ | ||
18 | |||
19 | #ifndef EINA_TILER_H_ | ||
20 | #define EINA_TILER_H_ | ||
21 | |||
22 | #include "eina_types.h" | ||
23 | #include "eina_iterator.h" | ||
24 | #include "eina_rectangle.h" | ||
25 | |||
26 | /** | ||
27 | * @page eina_tiler_example_01 | ||
28 | * @dontinclude eina_tiler_01.c | ||
29 | * | ||
30 | * This is an example that illustrates how Eina_Tiler works for a given set of | ||
31 | * rectangles. The rectangles must be given in the command line in the form: | ||
32 | * <width>x<height>+<x offset>+<y offset> | ||
33 | * The example will show two panels, the first(input) will show the given | ||
34 | * rectangles(in different colors) and in the seconds(output) it will show the | ||
35 | * rectangles given by the tiler. The rectangles will be added one by one every | ||
36 | * two seconds. A lot of the example deals with actually painting the rectangles | ||
37 | * so we'll skip over quite a bit of code, but you can see all of it in @ref | ||
38 | * eina_tiler_01.c "eina_tiler_01.c". | ||
39 | * | ||
40 | * The first thing of note in our example is the creation of the tiler: | ||
41 | * @skipline eina_tiler_new | ||
42 | * @note @p maxw and @p maxh are calculated such that the tiler's size will | ||
43 | * fully encompass all given rectangles. | ||
44 | * | ||
45 | * We'll now look at the function that actually adds rectangles to our tiler. It | ||
46 | * first checks if we added all rectangles already and if so stops right there: | ||
47 | * @dontinclude eina_tiler_01.c | ||
48 | * @skip static Eina_Bool | ||
49 | * @until } | ||
50 | * | ||
51 | * Our function then clears all rectangles given to us by tiler from the last | ||
52 | * execution. It does this because each rectangle we add may change everything | ||
53 | * about the output of eina_tiler: | ||
54 | * @until output_rects_reset | ||
55 | * | ||
56 | * Next we get another rectangle, print it and show it in the input panel: | ||
57 | * @until add_input_rect | ||
58 | * | ||
59 | * We now come to the tiler stuff, we add our new rectangle to it and get a new | ||
60 | * iterator for the tiler: | ||
61 | * @until itr | ||
62 | * | ||
63 | * We now iterate over our tiler printing every rect it gives us and sowing it | ||
64 | * in the output panel: | ||
65 | * @until } | ||
66 | * | ||
67 | * We of course must remember to free our iterator and that's it for this | ||
68 | * function: | ||
69 | * @until } | ||
70 | * | ||
71 | * You should try many different inputs to see how the tiler works, here are a | ||
72 | * few suggestions: | ||
73 | * @li 100x100+0+0 100x100+200+200 | ||
74 | * @li 100x100+0+0 100x100+5+5 100x100+10+10 100x100+15+15 100x100+20+20 | ||
75 | * @li 100x100+0+0 100x100+100+100 100x100+200+0 100x100+0+200 100x100+200+200 | ||
76 | * @li 10x10+0+0 10x10+10+10 10x10+20+0 10x10+0+20 10x10+20+20 | ||
77 | * | ||
78 | * @example eina_tiler_01.c | ||
79 | */ | ||
80 | /** | ||
81 | * @addtogroup Eina_Data_Types_Group Data Types | ||
82 | * | ||
83 | * @{ | ||
84 | */ | ||
85 | |||
86 | /** | ||
87 | * @defgroup Eina_Tiler_Group Tiler | ||
88 | * | ||
89 | * @warning This is a very low level tool, in most situations(for example if | ||
90 | * you're using evas) you won't need this. | ||
91 | * | ||
92 | * @section basic Basic usage | ||
93 | * | ||
94 | * Eina_Tiler is a tool to facilitate calculations of which areas are damaged | ||
95 | * and thus need to be re-rendered. The basic usage of Eina_Tiler is to give it | ||
96 | * the size of your canvas and a set of rectangular areas that need | ||
97 | * re-rendering, from that and using heuristics it'll tell you an efficient way | ||
98 | * to re-render in the form of a set of non-overlapping rectangles that covers | ||
99 | * the whole area that needs re-rendering. | ||
100 | * | ||
101 | * The following is pseudo-code showing some simple use of Eina_Tiler: | ||
102 | * @code | ||
103 | * tiler = eina_tiler_new(MY_CANVAS_WIDTH, MY_CANVAS_HEIGHT); | ||
104 | * EINA_LIST_FOREACH(list_of_areas_that_need_re_rendering, l, rect) | ||
105 | * eina_tiler_add(tiler, rect); | ||
106 | * itr = eina_tiler_iterator_new(tiler); | ||
107 | * EINA_ITERATOR_FOREACH(itr, rect) | ||
108 | * my_function_that_repaints_areas_of_the_canvas(rect); | ||
109 | * @endcode | ||
110 | * | ||
111 | * @see eina_tiler_new() | ||
112 | * @see eina_tiler_rect_add() | ||
113 | * @see eina_tiler_iterator_new() | ||
114 | * | ||
115 | * @warning There are no guarantees that this will be the most efficient way to | ||
116 | * re-render for any particular case. | ||
117 | * | ||
118 | * @section grid_slicer Grid Slicer | ||
119 | * | ||
120 | * Grid slicer and Eina_Tiler are usually used together, that is however @b not | ||
121 | * nescessary, they can be used independently. Grid slicer provides an easy API | ||
122 | * to divide an area in tiles which is usefull in certain applications to divide | ||
123 | * the area that will be rendered into tiles. It's customary to, then create one | ||
124 | * Eina_Tiler for each tile. | ||
125 | * | ||
126 | * The following is pseudo-code showing a very simplified use of grid slicer | ||
127 | * together with Eina_Tiler: | ||
128 | * @code | ||
129 | * itr = eina_tile_grid_slicer_iterator_new(0, 0, MY_CANVAS_WIDTH, MY_CANVAS_HEIGHT, TILE_WIDTH, TILE_HEIGHT); | ||
130 | * EINA_ITERATOR_FOREACH(itr, grid_info) | ||
131 | * { | ||
132 | * tiler = eina_tiler_new(grid_info->rect.w, grid_info->rect.w); | ||
133 | * EINA_LIST_FOREACH(list_of_areas_that_need_re_rendering_in_this_tile, l, rect) | ||
134 | * eina_tiler_add(tiler, rect); | ||
135 | * itr = eina_tiler_iterator_new(tiler); | ||
136 | * EINA_ITERATOR_FOREACH(itr, rect) | ||
137 | * my_function_that_repaints_areas_of_the_canvas(rect); | ||
138 | * } | ||
139 | * @endcode | ||
140 | * | ||
141 | * @see eina_tiler_new() | ||
142 | * @see eina_tiler_rect_add() | ||
143 | * @see eina_tile_grid_slicer_setup() | ||
144 | * @see eina_tile_grid_slicer_next() | ||
145 | * @see eina_tile_grid_slicer_iterator_new() | ||
146 | * | ||
147 | * @{ | ||
148 | */ | ||
149 | |||
150 | /** | ||
151 | * @typedef Eina_Tiler | ||
152 | * Tiler type. | ||
153 | */ | ||
154 | typedef struct _Eina_Tiler Eina_Tiler; | ||
155 | |||
156 | /** | ||
157 | * @typedef Eina_Tile_Grid_Info | ||
158 | * Grid type of a tiler. | ||
159 | */ | ||
160 | typedef struct Eina_Tile_Grid_Info Eina_Tile_Grid_Info; | ||
161 | |||
162 | /** | ||
163 | * @struct Eina_Tile_Grid_Info | ||
164 | * Grid type of a tiler. | ||
165 | */ | ||
166 | struct Eina_Tile_Grid_Info | ||
167 | { | ||
168 | unsigned long col; /**< column of the tile grid */ | ||
169 | unsigned long row; /**< row of the tile grid*/ | ||
170 | Eina_Rectangle rect; /**< rectangle of the tile grid, coordinates are | ||
171 | relative to tile*/ | ||
172 | Eina_Bool full; /**< whether the grid is full or not */ | ||
173 | }; | ||
174 | |||
175 | typedef struct _Eina_Tile_Grid_Slicer Eina_Tile_Grid_Slicer; | ||
176 | |||
177 | /** | ||
178 | * @brief Creates a new tiler with @p w width and @p h height. | ||
179 | * | ||
180 | * @param w Width of the tiler | ||
181 | * @param h Height of the tiler | ||
182 | * @return The newly created tiler | ||
183 | * | ||
184 | * @see eina_tiler_free() | ||
185 | */ | ||
186 | EAPI Eina_Tiler *eina_tiler_new(int w, int h); | ||
187 | /** | ||
188 | * @brief Frees a tiler. | ||
189 | * | ||
190 | * @param t The tiler to free. | ||
191 | * | ||
192 | * This function frees @p t. It does not free the memory allocated for the | ||
193 | * elements of @p t. | ||
194 | */ | ||
195 | EAPI void eina_tiler_free(Eina_Tiler *t); | ||
196 | /** | ||
197 | * @brief Sets the size of tiles for a tiler. | ||
198 | * | ||
199 | * @param t The tiler whose tile size will be set. | ||
200 | * @param w Width of the tiles. | ||
201 | * @param h Height of the tiles. | ||
202 | * | ||
203 | * @warning @p w and @p h @b must be greater than zero, otherwise tile size | ||
204 | * won't be changed. | ||
205 | * @warning Tile size is not used! | ||
206 | */ | ||
207 | EAPI void eina_tiler_tile_size_set(Eina_Tiler *t, int w, int h); | ||
208 | /** | ||
209 | * @brief Adds a rectangle to a tiler. | ||
210 | * | ||
211 | * @param t The tiler in which to add a container. | ||
212 | * @param r The rectangle to be added. | ||
213 | * | ||
214 | * @see eina_tiler_rect_del() | ||
215 | */ | ||
216 | EAPI Eina_Bool eina_tiler_rect_add(Eina_Tiler *t, const Eina_Rectangle *r); | ||
217 | /** | ||
218 | * @brief Removes a rectangle from a tiler. | ||
219 | * | ||
220 | * @param t The tiler in which to add a container. | ||
221 | * @param r The rectangle to be removed. | ||
222 | * | ||
223 | * @see eina_tiler_rect_add() | ||
224 | * @see eina_tiler_clear() | ||
225 | */ | ||
226 | EAPI void eina_tiler_rect_del(Eina_Tiler *t, const Eina_Rectangle *r); | ||
227 | /** | ||
228 | * @brief Removes all rectangles from tiles. | ||
229 | * | ||
230 | * @param t The tiler to clear. | ||
231 | * | ||
232 | * @see eina_tiler_rect_del() | ||
233 | */ | ||
234 | EAPI void eina_tiler_clear(Eina_Tiler *t); | ||
235 | /** | ||
236 | * @brief Create a iterator to access the tilers calculated rectangles. | ||
237 | * | ||
238 | * @param t The tiler to iterate over. | ||
239 | * @return A iterator containing Eina_Rectangle. | ||
240 | */ | ||
241 | EAPI Eina_Iterator *eina_tiler_iterator_new(const Eina_Tiler *t); | ||
242 | |||
243 | /** | ||
244 | * @brief Creates a new Eina_Iterator that iterates over a list of tiles. | ||
245 | * | ||
246 | * @param x X axis coordinate. | ||
247 | * @param y Y axis coordinate. | ||
248 | * @param w width. | ||
249 | * @param h height. | ||
250 | * @param tile_w tile width. | ||
251 | * @param tile_h tile height. | ||
252 | * @return A pointer to the Eina_Iterator. @c NULL on failure. | ||
253 | * | ||
254 | * The region defined by @a x, @a y, @a w, @a h will be divided in to a grid of | ||
255 | * tiles of width @a tile_w and height @p tile_h, the returned iterator will | ||
256 | * iterate over every tile in the grid having as its data a | ||
257 | * #Eina_Tile_Grid_Info. | ||
258 | * | ||
259 | * @note This is a convinience function, iterating over the returned iterator is | ||
260 | * equivalent to calling eina_tile_grid_slicer_setup() and calling | ||
261 | * eina_tile_grid_slicer_next() untill it returns EINA_FALSE. | ||
262 | */ | ||
263 | EAPI Eina_Iterator *eina_tile_grid_slicer_iterator_new(int x, int y, int w, int h, int tile_w, int tile_h); | ||
264 | /** | ||
265 | * @brief Iterates over the tiles set by eina_tile_grid_slicer_setup(). | ||
266 | * | ||
267 | * @param slc Pointer to an Eina_Tile_Grid_Slicer struct. | ||
268 | * @param rect Pointer to a struct Eina_Tile_Grid_Info *. | ||
269 | * @return @c EINA_TRUE if the current rect is valid. | ||
270 | * @c EINA_FALSE if there is no more rects to iterate over (and | ||
271 | * thus the current one isn't valid). | ||
272 | * | ||
273 | * This functions iterates over each Eina_Tile_Grid_Info *rect of the grid. | ||
274 | * eina_tile_grid_slicer_setup() must be called first, and *rect is only valid | ||
275 | * if this function returns EINA_TRUE. Its content shouldn't be modified. | ||
276 | * | ||
277 | * @note Consider using eina_tile_grid_slicer_iterator_new() instead. | ||
278 | */ | ||
279 | static inline Eina_Bool eina_tile_grid_slicer_next(Eina_Tile_Grid_Slicer *slc, const Eina_Tile_Grid_Info **rect); | ||
280 | /** | ||
281 | * @brief Setup an Eina_Tile_Grid_Slicer struct. | ||
282 | * | ||
283 | * @param slc Pointer to an Eina_Tile_Grid_Slicer struct. | ||
284 | * @param x X axis coordinate. | ||
285 | * @param y Y axis coordinate. | ||
286 | * @param w width. | ||
287 | * @param h height. | ||
288 | * @param tile_w tile width. | ||
289 | * @param tile_h tile height. | ||
290 | * @return A pointer to the Eina_Iterator. @c NULL on failure. | ||
291 | * | ||
292 | * The region defined by @a x, @a y, @a w, @a h will be divided in to a grid of | ||
293 | * tiles of width @a tile_w and height @p tile_h, @p slc can then be used with | ||
294 | * eina_tile_grid_slicer_next() to access each tile. | ||
295 | * | ||
296 | * @note Consider using eina_tile_grid_slicer_iterator_new() instead. | ||
297 | */ | ||
298 | 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); | ||
299 | |||
300 | #include "eina_inline_tiler.x" | ||
301 | |||
302 | /** | ||
303 | * @} | ||
304 | */ | ||
305 | |||
306 | /** | ||
307 | * @} | ||
308 | */ | ||
309 | |||
310 | #endif /* EINA_TILER_H_ */ | ||