WebRadioApp  0.1
ewgfxtasks.h
Go to the documentation of this file.
1 /*******************************************************************************
2  *
3  * E M B E D D E D W I Z A R D P R O J E C T
4  *
5  * Copyright (c) TARA Systems
6  *GmbH written by Paul Banach and Manfred Schweyer
7  *
8  ********************************************************************************
9  *
10  * This software and related documentation ("Software") are intellectual
11  * property owned by TARA Systems and are copyright of TARA Systems.
12  * Any modification, copying, reproduction or redistribution of the Software in
13  * whole or in part by any means not in accordance with the End-User License
14  * Agreement for Embedded Wizard is expressly prohibited. The removal of this
15  * preamble is expressly prohibited.
16  *
17  ********************************************************************************
18  *
19  * DESCRIPTION:
20  * This is an internal header of the Embedded Wizard Graphics Engine EWGFX.
21  *
22  * This header file provides declarations of data structures of drawing tasks
23  * and few functions needed to perform the optimization and elimination steps
24  * of these tasks and to dispatch the tasks to underlying graphics subsystem
25  * or to the emulated software pixel driver.
26  *
27  *******************************************************************************/
28 
29 #ifndef EWGFXTASKS_H
30 #define EWGFXTASKS_H
31 
32 #ifdef __cplusplus
33 extern "C" {
34 #endif
35 
36 /*******************************************************************************
37  * TYPE:
38  * XFillRectangle
39  *
40  * DESCRIPTION:
41  * The XFillRectangle structure defines the parameters set for a
42  *FILL_RECTANGLE task.
43  *
44  * When executed, the task should fill the destination area with a solid
45  *color. If the color values differ, the area should be filled with a color
46  *gradient by interpolation of the colors for all drawn pixel.
47  *
48  * ELEMENTS:
49  * DstX1, DstY1,
50  * DstX2, DstY2 - Destination area to fill within the surface.
51  * Colors - Colors to fill the area in the RGBA8888 format. The four
52  * values correspond to the four corners of the destination area (top-left,
53  * top-right, bottom-right, botom-left).
54  *
55  *******************************************************************************/
56 typedef struct {
57  short DstX1;
58  short DstY1;
59  short DstX2;
60  short DstY2;
61  unsigned int Colors[4];
62 } XFillRectangle;
63 
64 /*******************************************************************************
65  * TYPE:
66  * XCopySurface
67  *
68  * DESCRIPTION:
69  * The XCopySurface structure defines the parameters set for a COPY_SURFACE
70  * task.
71  *
72  * When executed, the task should copy the given source area from the source
73  * surface and place it within the destination area of the destination
74  *surface.
75  *
76  * The additional four color values control the fading effects while drawing
77  * the pixel. If these values differ, the pixel are faded with a gradient by
78  * interpolation of the four values for all copied pixel.
79  *
80  * ELEMENTS:
81  * DstX1, DstY1,
82  * DstX2, DstY2 - Destination area to fill within the destination surface.
83  * SrcX, SrcY - Origin position for the source area to copy.
84  * Surface - Source surface.
85  * Colors - Color values to use while copying the source surface. The
86  * four values correspond to the four corners of the destination area.
87  * (top-left, top-right, bottom-right, botom-left)
88  *
89  *******************************************************************************/
90 typedef struct {
91  short DstX1;
92  short DstY1;
93  short DstX2;
94  short DstY2;
95  short SrcX;
96  short SrcY;
97  XSurface *Surface;
98  unsigned int Colors[4];
99 } XCopySurface;
100 
101 /*******************************************************************************
102  * TYPE:
103  * XTileSurface
104  *
105  * DESCRIPTION:
106  * The XTileSurface structure defines the parameters set for a TILE_SURFACE
107  * task.
108  *
109  * When executed, the task should copy the given source area from the source
110  * surface and place it within the destination area of the destination
111  *surface. If the both areas differ in the size, the source area is repeated in
112  *the x and y direction until the entire destination area was completely filled.
113  *
114  * The additional four color values control the fading effects while drawing
115  * the pixel. If these values differ, the pixel are faded with a gradient by
116  * interpolation of the four values for all copied pixel.
117  *
118  * ELEMENTS:
119  * DstX1, DstY1,
120  * DstX2, DstY2 - Destination area to fill within the destination surface.
121  * SrcX1, SrcY1,
122  * SrcX2, SrcY2 - Source area to copy from the source surface.
123  * OfsX, OfsY - Position within the source area to start the operation. This
124  * is an offset, which allows the scrolling of the drawn content within the
125  * destination area. The source position has to lie within the source area.
126  * Surface - Source surface.
127  * Colors - Color values to use while copying the source surface. The
128  * four values correspond to the four corners of the destination area.
129  * (top-left, top-right, bottom-right, bottom-left)
130  *
131  *******************************************************************************/
132 typedef struct {
133  short DstX1;
134  short DstY1;
135  short DstX2;
136  short DstY2;
137  short SrcX1;
138  short SrcY1;
139  short SrcX2;
140  short SrcY2;
141  short OfsX;
142  short OfsY;
143  XSurface *Surface;
144  unsigned int Colors[4];
145 } XTileSurface;
146 
147 /*******************************************************************************
148  * TYPE:
149  * XWarpSurface
150  *
151  * DESCRIPTION:
152  * The XWarpSurface structure defines the parameters set for a WARP_SURFACE
153  * task.
154  *
155  * When executed, the task should copy the given source area from the source
156  * surface and place it within the destination area of the destination
157  *surface. Unlike the COPY_SURFACE task, WARP_SURFACE supports non rectangular
158  *areas. Depending on the shape of the area and the W coordinates, different
159  *kinds of transformations are possible, even the 3D perspective projection.
160  *
161  * The additional four opacity values control the fading effects while drawing
162  * the pixel. If these values differ, the pixel are faded with a gradient by
163  * interpolation of the four values for all copied pixel.
164  *
165  * ELEMENTS:
166  * DstX1, DstY1, DstW1,
167  * ...
168  * DstX4, DstY4, DstW4 - Destination polygon to fill within the destination
169  * surface.
170  * SrcX1, SrcY1,
171  * SrcX2, SrcY2 - Source area to copy from the source surface.
172  * Surface - Source surface.
173  * Colors - Color values to modulate the copied pixel. The four
174  * values correspond to the four corners of the destination polygon.
175  *
176  *******************************************************************************/
177 typedef struct {
178  float DstX1;
179  float DstY1;
180  float DstW1;
181  float DstX2;
182  float DstY2;
183  float DstW2;
184  float DstX3;
185  float DstY3;
186  float DstW3;
187  float DstX4;
188  float DstY4;
189  float DstW4;
190  short SrcX1;
191  short SrcY1;
192  short SrcX2;
193  short SrcY2;
194  XSurface *Surface;
195  unsigned int Colors[4];
196 } XWarpSurface;
197 
198 /*******************************************************************************
199  * TYPE:
200  * XDrawLine
201  *
202  * DESCRIPTION:
203  * The XDrawLine structure defines the parameters set for a DRAW_LINE task.
204  *
205  * When executed, the task should draw a line with the given colors. If both
206  * color values differ, the line should be drawn with a color gradient.
207  *
208  * ELEMENTS:
209  * DstX1, DstY1,
210  * DstX2, DstY2 - The start and the end point of the line. The end point does
211  * not belong to the line - it is invisible. In this manner polylines can
212  * be drawn.
213  * Colors - Colors to fill the area in the RGBA8888 format. The both
214  * values correspond to the start and the end point of the drawn line.
215  *
216  *******************************************************************************/
217 typedef struct {
218  short DstX1;
219  short DstY1;
220  short DstX2;
221  short DstY2;
222  unsigned int Colors[2];
223 } XDrawLine;
224 
225 /*******************************************************************************
226  * TYPE:
227  * XDrawText
228  *
229  * DESCRIPTION:
230  * The XDrawText structure defines the parameters set for a DRAW_TEXT task.
231  *
232  * When executed, the task should draw text into the destination surface by
233  * composing it from an array of glyphs. The references to these glyphs and
234  * the associated kerning values are stored in the memory area at the end of
235  * this parameters structure. Kerning values are represented by 32-bit signed
236  * integers. Glyphs are refereces to the corresponding XGlyph struct as shown
237  * below:
238  *
239  * +-----------+------+-------+------+-------+ +------+-------+
240  * | XDrawText | Kern | Glyph | Kern | Glyph | ... | Kern | Glyph |
241  * +-----------+------+-------+------+-------+ +------+-------+
242  *
243  * The text composition should start at the location OfsX, OfsY relative to
244  * the origin of the destination area. This represents the drawing position.
245  * For each glyph the position should move accordingly to the glyph's advance
246  * metrics.
247  *
248  * The additional four color values determine the color of the drawn glyphs.
249  * If these values differ, the glyphs should be drawn with a color gradient
250  * by interpolation of the four values for all copied pixel.
251  *
252  * ELEMENTS:
253  * DstX1, DstY1,
254  * DstX2, DstY2 - Destination area to fill within the surface.
255  * OfsX, OfsY - Position to start the text drawing. Relative to the corner
256  * of the destination area, which by taking in account the specified text
257  * orientation serves as the origin for the drawing operation.
258  * StretchFac,
259  * StretchAcc - White space stretch factor in 16.16 fixed point format.
260  * Glyphs - Number of glyph/kerning entries within the following array
261  * as described above. This is the number of glyphs to output.
262  * Orientation - Rotation of the text as value 0, 90, 180 or 270.
263  * Colors - Colors to fill the area in the RGBA8888 format. The four
264  * values correspond to the four corners of the destination area (top-left,
265  * top-right, bottom-right, bottom-left).
266  *
267  *******************************************************************************/
268 typedef struct {
269  short DstX1;
270  short DstY1;
271  short DstX2;
272  short DstY2;
273  short OfsX;
274  short OfsY;
275  int StretchFac;
276  int StretchAcc;
277  short Glyphs;
278  short Orientation;
279  unsigned int Colors[4];
280 } XDrawText;
281 
282 /*******************************************************************************
283  * TYPE:
284  * XFillPolygon
285  *
286  * DESCRIPTION:
287  * The XFillPolygon structure defines the parameters set for a FILL_POLYGON
288  * task.
289  *
290  * When executed, the task should fill the raster a polygon resulting from the
291  * given path information and store it within the destination area of the
292  * destination surface. The path information is stored in the memory at the
293  * end of this parameters structure. It is an array of int values starting
294  * with the number of edges a path is composed of. Then follow the coordinates
295  * of all path corners as X,Y pairs. After the last coordinate pair next path
296  * can follow starting again with the number of edges. The end of the path
297  * data is signed with 0. The X,Y coordinates are stored as signed integer
298  * with 4-bit fixpoint precision:
299  *
300  * +-------+------+------+------+------+------+------+-------+ +-----+
301  * | edges | X0 | Y0 | X1 | Y1 | X2 | Y2 | edges | ... | 0 |
302  * +-------+------+------+------+------+------+------+-------+ +-----+
303  *
304  * The additional four color values control the fading effects while drawing
305  * the pixel. If these values differ, the pixel are faded with a gradient by
306  * interpolation of the four values for all copied pixel.
307  *
308  * ELEMENTS:
309  * DstX1, DstY1,
310  * DstX2, DstY2 - Destination area to fill within the destination surface.
311  * NonZeroWinding - Controls the fill rule to be used by the algorithm. If
312  * this parameter is == 0, the even-odd fill rule is used. If this parameter
313  * is != 0, the non-zero winding rule is used.
314  * Orientation - Stores the orientation of the paths data relative to the
315  * physical origin of destination surface. This can be 0, 90, 180 or 270. If
316  * the specified orientation doesn't correspond to the of the destination
317  * surface, all path coordinates need to be converted just before performing
318  * the operation.
319  * Colors - Color values to use while rasterizing the polygon. The
320  * four values correspond to the four corners of the destination area.
321  * (top-left, top-right, bottom-right, botom-left)
322  *
323  *******************************************************************************/
324 typedef struct {
325  short DstX1;
326  short DstY1;
327  short DstX2;
328  short DstY2;
329  short NonZeroWinding;
330  short Orientation;
331  unsigned int Colors[4];
332 } XFillPolygon;
333 
334 /*******************************************************************************
335  * FUNCTION:
336  * EwEliminateTasks
337  *
338  * DESCRIPTION:
339  * The function EwEliminateTasks() has the job to find and eliminate
340  *superfluous drawing operations in the given issue.
341  *
342  * ARGUMENTS:
343  * aIssue - Issue containing the tasks to eliminate.
344  *
345  * RETURN VALUE:
346  * None
347  *
348  *******************************************************************************/
349 void EwEliminateTasks(XIssue *aIssue);
350 
351 /*******************************************************************************
352  * FUNCTION:
353  * EwReorderTasks
354  *
355  * DESCRIPTION:
356  * The function EwReorderTasks() has the job to change the order of the drawing
357  * tasks with the objective to put together all the software emulated tasks.
358  *
359  * ARGUMENTS:
360  * aIssue - Issue containing the tasks to change the order.
361  *
362  * RETURN VALUE:
363  * None
364  *
365  *******************************************************************************/
366 void EwReorderTasks(XIssue *aIssue);
367 
368 /*******************************************************************************
369  * FUNCTION:
370  * EwReverseTasks
371  *
372  * DESCRIPTION:
373  * The function EwReverseTasks() has the job to reverse the order of all tasks
374  * within the issue.
375  *
376  * ARGUMENTS:
377  * aIssue - Issue containing the tasks to change the order.
378  *
379  * RETURN VALUE:
380  * None
381  *
382  *******************************************************************************/
383 void EwReverseTasks(XIssue *aIssue);
384 
385 /*******************************************************************************
386  * FUNCTION:
387  * EwExecuteTasks
388  *
389  * DESCRIPTION:
390  * The function EwExecuteTasks() has the job to traverse the list of drawing
391  * task and to invoke the appropriate driver functions for their execution.
392  *
393  * ARGUMENTS:
394  * aIssue - Issue containing the tasks to execute.
395  *
396  * RETURN VALUE:
397  * None
398  *
399  *******************************************************************************/
400 void EwExecuteTasks(XIssue *aIssue);
401 
402 /*******************************************************************************
403  * FUNCTION:
404  * EwCompleteTasks
405  *
406  * DESCRIPTION:
407  * The function EwCompleteTasks() has the job to release resources used by the
408  * tasks contained within the given issue.
409  *
410  * ARGUMENTS:
411  * aIssue - Issue containing the tasks to complete.
412  *
413  * RETURN VALUE:
414  * None
415  *
416  *******************************************************************************/
417 void EwCompleteTasks(XIssue *aIssue);
418 
419 /*******************************************************************************
420  * FUNCTION:
421  * EwCountTasks
422  *
423  * DESCRIPTION:
424  * The function EwCountTasks() exists for statistic purpose only. The function
425  * evaluates the tasks, counts them and calculates the amount of pixel to copy
426  * and to blend.
427  *
428  * ARGUMENTS:
429  * aIssue - Issue containing the tasks to cout.
430  * aNoOfTasks - Pointer to variable, where the resulting number of tasks is
431  * returned.
432  * aCopyArea - Pointer to variable, where the resulting pixel copy area is
433  * returned.
434  * aBlendArea - Pointer to variable, where the resulting pixel blend area is
435  * returned.
436  *
437  * RETURN VALUE:
438  * None
439  *
440  *******************************************************************************/
441 void EwCountTasks(XIssue *aIssue, int *aNoOfTasks, int *aCopyArea,
442  int *aBlendArea);
443 
444 /*******************************************************************************
445  * TYPE:
446  * XTraceTasksProc
447  *
448  * DESCRIPTION:
449  * The following type declares a prototype of a user defined function, which
450  * can be registered in order to monitor task execution. To register the user
451  * function EwTraceTasks() is intended.
452  *
453  * The user defined callback function is allways called after the given task
454  * has been executed.
455  *
456  * Note the special behaviour of hardware accelerated target systems where all
457  * drawing operations may remain still pending until the entire drawing cycle
458  * has been finished. For this reason, it is not guaranteed that the operation
459  * results are stored in the destination surface memory when the user callback
460  * function is called.
461  *
462  * ARGUMENTS:
463  * aDst - Destination surface affected by the operation.
464  * aTask - Task beeing executed. Note, the corresponding drawing operation
465  * may still remain pending in the graphics hardware.
466  * aUserArg1 - User argument passed in the EwTraceTasks() function.
467  * aUserArg2 - User argument passed in the EwTraceTasks() function.
468  *
469  * RETURN VALUE:
470  * None
471  *
472  *******************************************************************************/
473 typedef void (*XTraceTasksProc)(XSurface *aDst, XTask *aTask, void *aUserArg1,
474  void *aUserArg2);
475 
476 /*******************************************************************************
477  * FUNCTION:
478  * EwTraceTasks
479  *
480  * DESCRIPTION:
481  * The function EwTraceTasks() provides a mechanism to monitor task execution.
482  * EwTraceTasks() registers a user defined callback function aProc to call when
483  * a task is executed.
484  *
485  * The registered function is called for each executed task until
486  *EwTraceTasks() is called again with 0 (zero) as aProc paramater.
487  *
488  * ARGUMENTS:
489  * aProc - User defined callback function to call for each executed task.
490  * aUserArg1 - User argument to pass additionally to the called user function.
491  * aUserArg2 - User argument to pass additionally to the called user function.
492  *
493  * RETURN VALUE:
494  * None
495  *
496  *******************************************************************************/
497 void EwTraceTasks(XTraceTasksProc aProc, void *aUserArg1, void *aUserArg2);
498 
499 #ifdef __cplusplus
500 }
501 #endif
502 
503 #endif /* EWGFXTASKS_H */
504 
505 /* pba */
EwTraceTasks
void EwTraceTasks(XTraceTasksProc aProc, void *aUserArg1, void *aUserArg2)
XDrawLine
Definition: ewgfxtasks.h:217
EwCompleteTasks
void EwCompleteTasks(XIssue *aIssue)
XTask
Definition: ewgfxcore.h:432
XIssue
Definition: ewgfxcore.h:374
XTraceTasksProc
void(* XTraceTasksProc)(XSurface *aDst, XTask *aTask, void *aUserArg1, void *aUserArg2)
Definition: ewgfxtasks.h:473
void
XRect CoreOutline aOutline void(CoreRoot _this, GraphicsCanvas aCanvas, XRect aClip, XPoint aOffset, XInt32 aOpacity, XBool aBlend) EW_METHOD(HandleEvent
EwEliminateTasks
void EwEliminateTasks(XIssue *aIssue)
XDrawText
Definition: ewgfxtasks.h:268
EwReverseTasks
void EwReverseTasks(XIssue *aIssue)
XCopySurface
Definition: ewgfxtasks.h:90
XFillPolygon
Definition: ewgfxtasks.h:324
EwReorderTasks
void EwReorderTasks(XIssue *aIssue)
EwCountTasks
void EwCountTasks(XIssue *aIssue, int *aNoOfTasks, int *aCopyArea, int *aBlendArea)
XTileSurface
Definition: ewgfxtasks.h:132
XFillRectangle
Definition: ewgfxtasks.h:56
XWarpSurface
Definition: ewgfxtasks.h:177
XSurface
Definition: ewgfxcore.h:221
EwExecuteTasks
void EwExecuteTasks(XIssue *aIssue)