summaryrefslogtreecommitdiff
path: root/src/lib/evas/Evas.h
diff options
context:
space:
mode:
authorBryce Harrington <bryce@osg.samsung.com>2017-08-29 16:23:30 -0700
committerCedric BAIL <cedric@osg.samsung.com>2017-08-29 16:23:34 -0700
commitdcc2654673f7bdf83d9dba4ad94ff085a23bc89a (patch)
tree652220939952e86e2da92b252e914de7146b51c1 /src/lib/evas/Evas.h
parent84cfde45f66383661cab0805bdcbab13c589a449 (diff)
evas: make the high level documentation more concise
Summary: This is a very informative document but is much longer than it needs to be. Tighten it up by condensing redundant information and expressing the ideas more efficiently. Focus more on Evas and what it is than what it isn't. Avoid explaining general graphics concepts like immediate vs. retained, replacing with synopses. Switch from 2nd person to 3rd person (i.e. don't say You/Your) to be less awkward, since we don't really know why the reader is reading it. Simplify the compilation directions; these are pretty standard, and most people won't be manually linking to Evas anyway. While this shortens the document considerably, it retains the important key points, and makes it far more readable. Reviewers: cedric Reviewed By: cedric Subscribers: jpeg Differential Revision: https://phab.enlightenment.org/D5130 Signed-off-by: Cedric BAIL <cedric@osg.samsung.com>
Diffstat (limited to 'src/lib/evas/Evas.h')
-rw-r--r--src/lib/evas/Evas.h248
1 files changed, 84 insertions, 164 deletions
diff --git a/src/lib/evas/Evas.h b/src/lib/evas/Evas.h
index d25847c7bf..81df72cba2 100644
--- a/src/lib/evas/Evas.h
+++ b/src/lib/evas/Evas.h
@@ -15,126 +15,70 @@
15 @section evas_main_intro Introduction 15 @section evas_main_intro Introduction
16 16
17 Evas is a clean display canvas API for several target display systems 17 Evas is a clean display canvas API for several target display systems
18 that can draw anti-aliased text, smooth super and sub-sampled scaled 18 that can draw anti-aliased text, smooth super- and sub-sampled scaled
19 images, alpha-blend objects and much more. 19 images, alpha-blend objects and more.
20 20
21 It abstracts any need to know much about what the characteristics of 21 It abstracts the graphics drawing characteristics of the display
22 your display system are or what graphics calls are used to draw them 22 system by implementing a canvas where graphical objects can be
23 and how. It deals on an object level where all you do is create and 23 created, manipulated, and modified. It then handles the rendering
24 manipulate objects in a canvas, set their properties, and the rest is 24 pipeline in an optimal way for the underlying device in order to
25 done for you. 25 minimize redraws, via a programmatically efficient API.
26 26
27 Evas optimises the rendering pipeline to minimise effort in redrawing 27 A design goal for the system is to run well at both small and large
28 changes made to the canvas and so takes this work out of the 28 scale, and be portable from embedded systems to multi-CPU
29 programmers hand, saving a lot of time and energy. 29 workstations. Architecturally, this is achieved via 'backends' that
30 30 provide the specialized display logic for specific devices. As well,
31 It is small and lean, and is designed to work on embedded systems all the way 31 there are various compile options to exclude feature support not
32 to large and powerful multi-CPU workstations. It can be compiled to 32 required for a target platform to help minimize disk and memory
33 only have the features you need for your target platform if you so 33 requirements.
34 wish, thus keeping it small and lean. It has several display 34
35 back-ends, letting it display on several display systems, making it 35 Evas can serve as a base for widget sets or toolkits
36 portable for cross-device and cross-platform development. 36 (e.g. Elementary, http://docs.enlightenment.org/auto/elementary/) by
37 37 handling pixel drawing and regional change reporting, but does not
38 @subsection evas_main_intro_not_evas What Evas is not? 38 manage windows itself, nor deal with input or window update event
39 39 propagation. In other words, it is intended for use in drawing
40 Evas is not a widget set or widget toolkit, however it is their 40 scrollbars, sliders, and push buttons but not for high-level logic of
41 base. See Elementary (http://docs.enlightenment.org/auto/elementary/) 41 how the widget operates and behaves. Under Enlightenment, window and
42 for a toolkit based on @ref Evas, @ref Edje, @ref Ecore and other 42 widget management is handled by other software components, including
43 Enlightenment technologies. 43 @ref Ecore (see @ref Ecore_Evas_Group in particular); however Evas is
44 44 designed to not be dependent on any particular main loop
45 It is not dependent or aware of main loops, input or output 45 architecture, and also strives to be input and output system
46 systems. Input should be polled from various sources and fed to 46 agnostic.
47 Evas. Similarly, it does not create windows or report windows updates
48 to your system, but just draws the pixels and report to the
49 user the areas that were changed. Of course these operations are quite
50 common and thus they are ready to use in @ref Ecore, particularly in
51 @ref Ecore_Evas_Group.
52 47
48 Evas can be seen as a display system that stands somewhere between a
49 widget set and an immediate mode display system. It retains basic
50 display logic, but does very little high-level logic such as
51 scrollbars, sliders, and push buttons.
53 52
54 @section evas_main_work How does Evas work?
55
56 Evas is a canvas display library. This is markedly different from most
57 display and windowing systems as a canvas is structural and is also a
58 state engine, whereas most display and windowing systems are immediate
59 mode display targets. Evas handles the logic between a structural
60 display via its state engine, and controls the target windowing system
61 in order to produce rendered results of the current canvas' state on
62 the display.
63
64 Immediate mode display systems retain very little, or no state. A
65 program executes a series of commands, as in the pseudo code:
66
67 @verbatim
68 draw line from position (0, 0) to position (100, 200);
69
70 draw rectangle from position (10, 30) to position (50, 500);
71
72 bitmap_handle = create_bitmap();
73 scale bitmap_handle to size 100 x 100;
74 draw image bitmap_handle at position (10, 30);
75 @endverbatim
76
77 The series of commands is executed by the windowing system and the
78 results are displayed on the screen (normally). Once the commands are
79 executed the display system has little or no idea of how to reproduce
80 this image again, and so has to be instructed by the application on how
81 to redraw sections of the screen whenever needed. Each successive
82 command is executed as instructed by the application and either
83 emulated by software or sent to the graphics hardware on the device to
84 be performed.
85
86 The advantage of such a system is that it is simple, and gives a
87 program tight control over how something looks and is drawn. Given the
88 increasing complexity of displays and demands by users to have better
89 looking interfaces, more and more work is needing to be done at this
90 level by the internals of widget sets, custom display widgets and
91 other programs. This means that more and more logic and display rendering
92 code needs to be written each time the application needs to figure out
93 how to minimise redraws so that display is fast and interactive, and
94 keeps track of redraw logic. The power comes at a high-price with lots
95 of extra code and work. Programmers not very familiar with graphics
96 programming often make mistakes at this level and produce code that
97 is sub optimal. Those familiar with this kind of programming simply
98 get bored by writing the same code again and again.
99
100 For example, if in the above scene, the windowing system requires the
101 application to redraw the area from 0, 0 to 50, 50 (also referred as
102 "expose event"), then the programmer must manually calculate the
103 updates and repaint it again:
104
105 @verbatim
106 Redraw from position (0, 0) to position (50, 50):
107
108 // what is in area (0, 0, 50, 50)?
109
110 // 1. intersection part of line (0, 0) to (100, 200)?
111 draw line from position (0, 0) to position (25, 50);
112
113 // 2. intersection part of rectangle (10, 30) to (50, 500)?
114 draw rectangle from position (10, 30) to position (50, 50)
115 53
116 // 3. intersection part of image at (10, 30), size 100 x 100? 54 @section evas_main_work How does Evas work?
117 bitmap_subimage = subregion from position (0, 0) to position (40, 20)
118 draw image bitmap_subimage at position (10, 30);
119 @endverbatim
120 55
121 You might have noticed that, if all elements in the 56 The Evas canvas is a 'retained mode' renderer, which differs from the
122 above scene are opaque, then the system is doing useless paints: part 57 more traditional 'immediate mode' display and windowing systems by
123 of the line is behind the rectangle, and part of the rectangle is 58 tracking drawing state information of its contained objects.
124 behind the image. These useless paints tend to be very costly, as 59
125 pixels tend to be 4 bytes in size; thus an overlapping region of 100 x 60 In an immediate mode rendering system, each frame is drawn from
126 100 pixels is around 40000 useless writes! You could write 61 scratch by having each drawing element redraw itself. Once the
127 code to calculate the overlapping areas and avoid painting then, but 62 commands are executed, the display system blits the frame to the
128 then it should be mixed with the "expose event" handling mentioned 63 screen but has no idea how to reproduce the image again, so the
129 above and you quickly realize that the initially simpler method becomes 64 application has to run through the same sequence of drawing commands
130 very complex. 65 again. Very little or no state is kept from one frame draw to the
66 next; while this is simple it forces each application to manually
67 optimize their graphics code.
68
69 With retained mode systems like Evas, the application does not need
70 to implement the display rendering code and associated logic, but
71 merely updates the list of objects maintained in the canvas. Evas is
72 then able to optimize the processing and rendering of the visible
73 elements, and is better able to avoid redraws due to occlusion or
74 opacity.
131 75
132 Evas is a structural system in which the programmer creates and 76 Evas is a structural system in which the programmer creates and
133 manages display objects and their properties, and as a result of this 77 manages display objects and their properties, and as a result of this
134 higher level state management, the canvas is able to redraw the set of 78 higher level state management, the canvas is able to redraw the set of
135 objects when needed to represent the current state of the canvas. 79 objects when needed to represent the current state of the canvas.
136 80
137 For example, the pseudo code: 81 For example, consider the pseudo code:
138 82
139 @verbatim 83 @verbatim
140 line_handle = create_line(); 84 line_handle = create_line();
@@ -154,63 +98,39 @@
154 render scene; 98 render scene;
155 @endverbatim 99 @endverbatim
156 100
157 This may look longer, but when the display needs to be refreshed or 101 By expressing the drawing as a set of drawable objects, Evas is able
158 updated, you move, resize, show, or hide the objects that need to change. 102 to internally handle refreshing, updating, moving, resizing, showing,
159 You can simply think at the object logic level, and the canvas software 103 and hiding the objects, and to determine to most efficiently redraw
160 does the rest of the work for you, figuring out what actually changed in the 104 the canvas and its contents to reflect the current state. This
161 canvas since it had been last drawn, how to most efficiently redraw the canvas and 105 permits the application to focus on the higher level logic, which
162 its contents to reflect the current state, and then it can go off and do 106 both reduces the amount of coding and allows a more natural way of
163 the actual drawing of the canvas. 107 dealing with the display. Importantly, abstracting the display logic
164 108 like this also simplifies porting the application to different
165 This lets you think in a more natural way when dealing with 109 display systems, since its own code is less tied into how that system
166 a display, and saves time and effort of working out how to load and 110 works.
167 display images, render given the current display system, and so on. Since 111
168 Evas is also portable across different display systems, this also 112 @section evas_main_compiling How to compile the library
169 gives you the ability to have their code ported and 113
170 displayed on different display systems with very little work. 114 Evas compiles automatically within EFL's build system, and is
171 115 automatically linked with @ref Ecore and other components that need
172 Evas can be seen as a display system that stands somewhere between a 116 it. But it can also be built and used standalone, by compiling and
173 widget set and an immediate mode display system. It retains basic 117 linking your application with the compiler flags indicated by @c
174 display logic, but does very little high-level logic such as 118 pkg-config. For example:
175 scrollbars, sliders, and push buttons.
176
177
178 @section evas_main_compiling How to compile
179
180 Evas is a library your application links to. The procedure for this is
181 very simple. You simply have to compile your application with the
182 appropriate compiler flags that the @c pkg-config script outputs. For
183 example:
184
185 Compiling C or C++ files into object files:
186 119
187 @verbatim 120 @verbatim
188 gcc -c -o main.o main.c `pkg-config --cflags evas` 121 gcc -c -o my_main.o my_main.c `pkg-config --cflags evas`
189 @endverbatim
190
191 Linking object files into a binary executable:
192 122
193 @verbatim 123 gcc -o my_application my_main.o `pkg-config --libs evas`
194 gcc -o my_application main.o `pkg-config --libs evas`
195 @endverbatim 124 @endverbatim
196 125
197 See @ref pkgconfig 126 See @ref pkgconfig
198 127
199 @section evas_main_next_steps Next Steps 128 @section evas_main_next_steps Recommended reading
200
201 After you understood what Evas is and installed it in your system
202 you should proceed understanding the programming interface for all
203 objects, then see the specific for the most used elements. We'd
204 recommend you to take a while to learn @ref Ecore, @ref Edje and
205 Elementary (http://docs.enlightenment.org/auto/elementary/) as they
206 will likely save you tons of work compared to using just Evas
207 directly.
208 129
209 Recommended reading: 130 @li @ref Ecore, @ref Edje, and @ref Elementary that provide higher
210 131 level infrastructure and components for real world usage.
211 @li @ref Evas_Object_Group, where you'll get how to basically 132 @li @ref Evas_Object_Group for how to manipulate generic objects on
212 manipulate generic objects lying on an Evas canvas, handle canvas 133 an Evas canvas and handle the associated events.
213 and object events, etc.
214 @li @ref Evas_Object_Rectangle, to learn about the most basic object 134 @li @ref Evas_Object_Rectangle, to learn about the most basic object
215 type on Evas -- the rectangle. 135 type on Evas -- the rectangle.
216 @li @ref Evas_Object_Polygon, to learn how to create polygon elements 136 @li @ref Evas_Object_Polygon, to learn how to create polygon elements
@@ -223,13 +143,13 @@
223 the canvas. 143 the canvas.
224 @li @ref Evas_Object_Textblock, to learn how to create multiline 144 @li @ref Evas_Object_Textblock, to learn how to create multiline
225 textual elements on the canvas. 145 textual elements on the canvas.
146
226 @li @ref Evas_Smart_Object_Group and @ref Evas_Smart_Group, to define 147 @li @ref Evas_Smart_Object_Group and @ref Evas_Smart_Group, to define
227 new objects that provide @b custom functions to handle clipping, 148 new objects that provide @b custom functions to handle clipping,
228 hiding, moving, resizing, color setting and more. These could 149 hiding, moving, resizing, color setting and more. This includes
229 be as simple as a group of objects that move together (see @ref 150 simple grouping of objects that move together (see @ref
230 Evas_Smart_Object_Clipped) up to implementations of what 151 Evas_Smart_Object_Clipped) and more complex widget-like intelligent
231 ends to be a widget, providing some intelligence (thus the name) 152 behaviors such as buttons and check boxes.
232 to Evas objects -- like a button or check box, for example.
233 153
234 @section evas_main_intro_example Introductory Example 154 @section evas_main_intro_example Introductory Example
235 155