summaryrefslogtreecommitdiff
path: root/legacy/evas/evas.c.in
blob: 65d7d96106e3dd682a37e6d42707ef009d869b2d (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
/** 
@file
@brief Evas Client-side Library Public API Calls
 
These routines are used for Evas Library interaction
*/

/**

@mainpage Evas
@image latex evas_big.eps width=5cm
@image html  evas.png
@version 1.0.0
@author Carsten Haitzler <raster@rasterman.com>
@author Till Adam <till@adam-lilienthal.de>
@author Steve Ireland <sireland@pobox.com>
@date 2000-2002













@section intro What is Evas?

Evas is a clean display canvas API for several target display systems that
can draw anti-aliased text, smooth super and sub-sampled scaled images,
alpha-blend objects much and more.

It abstracts any need to know much about what the characteristics of your
display system are or what graphics calls are used to draw them and how. It
deals on an object level where all you do is create and manipulate objects
in a canvas, set their properties, and the rest is done for you.

Evas optimises the rendering pipeline to minimise effort in redrawing changes
made to the canvas and so takes this work out of the programmers hand,
saving a lot of time and energy.

It's small and lean, designed to work on embedded systems all the way to
large and powerful multi-cpu workstations. It can be compiled to only have
the features you need for your target platform if you so wish, thus keeping
it small and lean. It has several display back-ends, letting it display on
several display systems, making it portable for cross-device and
cross-platform development.


















@section work How does Evas work?

Evas is a canvas display library. This is markedly different from most
display and windowing systemas as a Canvas is structural and is also a state
engine, wheras most display and windowing systems are immediate mode display
targets. Evas handles the logic between a structural display via its' state
engine, and controls the target windowing system in order to produce
rendered results of the current canvases state on the display.

Immediate mode display systems retain very little, or no state. A program
will execute a series of commands:

@verbatim
bitmap_handle = create_new_bitmap();
draw_line(0, 0, 100, 200);
draw_rectangle(10, 30, 50, 500);
draw_bitmap(10, 30, bitmap_handle);
etc.
@endverbatim

The series of commands is executed by the windowing system and the results
are displayed on the screen (normally). Once the commands are executed the
display system has little or no idea of how to reproduce this image again,
and so has to be instructed by the application how to redraw sections of the
screen whenever needed. Each sucessive command will be executed as
instructed by the application and either emulated by software or sent to the
graphics hardware on the device to be performed.

The advantage of such a system is that it is simple, and gives a program
tight control over how something looks and is drawn. Given the increasing
comlpexity of displays and demands by users to have better looking
interfaces, more and more work is needing to be done at this level by the
internals of widget sets, custom display widgets and other programs. This
means more and more logic and display rendering code needs to be written
time and time again, each time the application needs to figure out how to
minimise redraws so that display is fast and interactive, and keep track of
redraw logic. The power comes at a high-price, lots of extra code and work.
Programmers not very familiar with graphics programming will often make
mistakes at this level and produce code that is sub optimal. Those familiar
with this kind of programming will simply get bored by writign the same code
again and again.

Evas is a structural system in which the programmer creates and manages
display objects and their properties, and as a result of this higher level
state management, the canvas is able to redraw the set of objects when
needed to represent the current state of the canvas.

For example:

@verbatim
bitmap_handle = create_bitmap();
move(bitmap_handle, 10, 30);
show(bitmap_handle);
rectangle_handle = create_rectangle();
move(rectangle_handle, 10, 30);
resize(rectangle_handle, 50, 500);
show(rectangle_handle);
line_handle = create_line();
set_line_coords(line_handle, 0, 0, 100, 200);
show(line_handle);
etc.
@endverbatim

This may look longer, but when the display needs to be refreshed or updated,
the programmer only moves, resizes, shows, hides etc. the objects that they
need to change. The programmer simply thinks at the object logic level, and
the canvas software does the rest of the work for them, figuring out what
actually changed in the canvas since it was lastdrawn, how to most
efficiently redraw he canvas and its contents to reflect the current state,
and then it can go off and do the actual drawing of the canvas.

This lets the programmer think in a more natural way when dealing with a
display, and saves time and effort of woring out how to load and display
images, render given the current display system etc. Since Evas also is
portable across different display systems, this also gives the programmer
the ability to have their code ported and display on different dislpay
systems with very little work.

Evas can be seen as a display system that stands somewhere between a widget
set and an immediate mode display system. It retains basic dislpay logic,
but does very little high-level logic such as scrollbars, sliders, push
buttons etc.
















@section compiling How to compile using Evas?

Evas is a library your application links to. The proceedure for this is very
simple. You simply have to compile your application with the appropriate
compiler flags that the @p evas-config script outputs. For example:

Compiling C or C++ files into object files:

@verbatim
gcc -c main.c -o main.o `evas-config --cflags`
@endverbatim

Linking object files into a binary executable:

@verbatim
gcc main.o -o my_application `evas-config --libs`
@endverbatim

You simply have to make sure that evas-config is in your shell's PATH (see
the manual page for your appropriate shell), or simply use the full path to
where @p evas-config was installed. It's that simple to link and use Evas
once you have written your code to use it.

Since the program is linked to Evas, it is now able to use any advertised
API calls to display graphics in a canvas managed by Evas, as well as use
the API calls provided to manage data as well.

You should make sure you add any extra compile and link flags to your
compile commands that your application may need as well. The above example
is only guaranteed to make Evas add it's own requirements.
















@section install How is it installed?

To be documented...

Suggested configure options for evas for a P2/AMD/P3/P4 desktop X display:

@verbatim
./configure \
--enable-software-x11 \
--enable-image-loader-png \
--enable-image-loader-jpeg \
--enable-cpu-p2-only \
--enable-cpu-mmx \
--enable-cpu-sse \
--enable-cpu-c \
--enable-scale-smooth \
--enable-scale-sample \
--enable-convert-8-rgb-332 \
--enable-convert-8-rgb-666 \
--enable-convert-8-rgb-232 \
--enable-convert-8-rgb-222 \
--enable-convert-8-rgb-221 \
--enable-convert-8-rgb-121 \
--enable-convert-8-rgb-111 \
--enable-convert-16-rgb-565 \
--enable-convert-16-rgb-555 \
--enable-convert-16-rgb-rot-0 \
--enable-convert-32-rgb-8888 \
--enable-convert-32-rgbx-8888 \
--enable-convert-32-bgr-8888 \
--enable-convert-32-bgrx-8888 \
--enable-convert-32-rgb-rot-0

make CFLAGS="-O9 -mpentiumpro -march=pentiumpro -mcpu=pentiumpro"
@endverbatim

For those that want eet and edb image loading ability:

@verbatim
./configure \
--enable-software-x11 \
--enable-image-loader-png \
--enable-image-loader-jpeg \
--enable-image-loader-eet \
--enable-image-loader-edb \
--enable-cpu-p2-only \
--enable-cpu-mmx \
--enable-cpu-sse \
--enable-cpu-c \
--enable-scale-smooth \
--enable-scale-sample \
--enable-convert-8-rgb-332 \
--enable-convert-8-rgb-666 \
--enable-convert-8-rgb-232 \
--enable-convert-8-rgb-222 \
--enable-convert-8-rgb-221 \
--enable-convert-8-rgb-121 \
--enable-convert-8-rgb-111 \
--enable-convert-16-rgb-565 \
--enable-convert-16-rgb-555 \
--enable-convert-16-rgb-rot-0 \
--enable-convert-32-rgb-8888 \
--enable-convert-32-rgbx-8888 \
--enable-convert-32-bgr-8888 \
--enable-convert-32-bgrx-8888 \
--enable-convert-32-rgb-rot-0

make CFLAGS="-O9 -mpentiumpro -march=pentiumpro -mcpu=pentiumpro"
@endverbatim

Or to use the fast sampling scaler only:

@verbatim
./configure \
--enable-software-x11 \
--enable-image-loader-png \
--enable-image-loader-jpeg \
--enable-cpu-p2-only \
--enable-cpu-mmx \
--enable-cpu-sse \
--enable-cpu-c \
--enable-scale-sample \
--enable-convert-8-rgb-332 \
--enable-convert-8-rgb-666 \
--enable-convert-8-rgb-232 \
--enable-convert-8-rgb-222 \
--enable-convert-8-rgb-221 \
--enable-convert-8-rgb-121 \
--enable-convert-8-rgb-111 \
--enable-convert-16-rgb-565 \
--enable-convert-16-rgb-555 \
--enable-convert-16-rgb-rot-0 \
--enable-convert-32-rgb-8888 \
--enable-convert-32-rgbx-8888 \
--enable-convert-32-bgr-8888 \
--enable-convert-32-bgrx-8888 \
--enable-convert-32-rgb-rot-0

make CFLAGS="-O9 -mpentiumpro -march=pentiumpro -mcpu=pentiumpro"
@endverbatim

OpenGL (being worked on. does nothing much at the moment).

@verbatim
./configure \
--enable-gl-x11 \
--enable-image-loader-png \
--enable-image-loader-jpeg \
--enable-cpu-p2-only \
--enable-cpu-mmx \
--enable-cpu-sse \
--enable-cpu-c \
--enable-scale-smooth \
--enable-scale-sample \

make CFLAGS="-g"
@endverbatim

Suggested configure options for an ipaq 36xx:

@verbatim
./configure \
--enable-fb \
--enable-image-loader-png \
--enable-image-loader-jpeg \
--enable-small-dither-mask \
--enable-cpu-c \
--enable-scale-smooth \
--enable-scale-sample \
--enable-convert-16-rgb-ipq \
--enable-convert-16-rgb-rot-270

make CFLAGS="-O9"
@endverbatim

Suggested configure options for an ipaq 38xx:

@verbatim
./configure \
--enable-fb \
--enable-image-loader-png \
--enable-image-loader-jpeg \
--enable-small-dither-mask \
--enable-cpu-c \
--enable-scale-smooth \
--enable-scale-sample \
--enable-convert-16-rgb-565 \
--enable-convert-16-rgb-rot-90

make CFLAGS="-O9"
@endverbatim

Suggested configure options for an cross-compiling ipaq using skiff:

This assumes you have a proper install of freetype2 on your skiff install that
contains a freetype-config script, and a proper install of libpng on your
skiff cross-compile environment.

@verbatim
export CC=/skiff/local/bin/arm-linux-gcc
export CFLAGS="-O9"
./configure \
--enable-fb \
--enable-image-loader-png \
--enable-image-loader-jpeg \
--enable-small-dither-mask \
--enable-cpu-c \
--enable-scale-smooth \
--enable-scale-sample \
--enable-convert-16-rgb-ipq \
--enable-convert-16-rgb-rot-0 \
--enable-convert-16-rgb-rot-270 \
--with-freetype-config=/skiff/local/arm-linux/bin/freetype-config

make CFLAGS="-O9 -I/skiff/local/include -I/skiff/local/arm-linux/include"
@endverbatim

@verbatim
suggested configure options for an DirectFB on x86 target:

./configure \
--enable-directfb \
--enable-cpu-p2-only \
--enable-cpu-mmx \
--enable-cpu-sse \
--enable-cpu-c \
--enable-image-loader-png \
--enable-image-loader-jpeg \
--enable-scale-smooth

make CFLAGS="-O9 -mpentiumpro -march=pentiumpro -mcpu=pentiumpro"
@endverbatim

Suggested configure options for a qtopia target (desktop, qvfb):

@verbatim
./configure \
--enable-software-qtopia \
--enable-image-loader-png \
--enable-image-loader-jpeg \
--enable-cpu-p2-only \
--enable-cpu-mmx \
--enable-cpu-sse \
--enable-cpu-c \
--enable-scale-smooth \
--enable-scale-sample \
--enable-convert-16-rgb-565 \
--enable-convert-16-rgb-555 \
--enable-convert-16-rgb-ipq \
--enable-convert-16-rgb-rot-0 \
--enable-convert-32-rgb-8888 \
--enable-convert-32-bgr-8888 \
--enable-convert-32-rgb-rot-0 \
--with-qtdir=/opt/Qtopia

make CFLAGS="-O9 -mpentiumpro -march=pentiumpro -mcpu=pentiumpro"
@endverbatim

Suggested configure options for a zaurus qtopia cross-compile target:

@verbatim
export CC=/opt/Embedix/tools/arm-linux/bin/gcc
export CXX=/opt/Embedix/tools/arm-linux/bin/g++
export CFLAGS="-O9"
./configure \
--enable-software-qtopia \
--enable-image-loader-png \
--enable-image-loader-jpeg \
--enable-small-dither-mask \
--enable-cpu-c \
--enable-scale-smooth \
--enable-scale-sample \
--enable-convert-16-rgb-565 \
--enable-convert-16-rgb-rot-270 \
--with-qtdir=/opt/Qtopia/sharp \
--with-freetype-config=/opt/Embedix/tools/arm-linux/bin/freetype-config

make CFLAGS="-O9 -I/opt/Embedix/tools/arm-linux/include"
@endverbatim















@todo (1.0) Document API
@todo (1.0) Move callback processing to a queue and do it asynchronously
@todo (1.0) Add button grabbing
@todo (1.0) Add generic object method call system
@todo (1.0) Add callbacks set for smart object parents to be set on all child smart objects too.
@todo (1.0) Define image load errors (and maybe have an error to string func)
@todo (1.0) Add text styles (outline etc.)
@todo (1.0) Add font load query calls (so we know if a font load failed)
@todo (1.0) Add font listing calls
@todo (1.0) Add ability to check image comments & disk format
@todo (1.0) Add group objects
@todo (1.0) Add auto-detection of what engines to build based on system/libs etc. for configure script
@todo (1.0) Add overall engine configure parameters (so you can configure an engine with defaults with 1 configure option) to configure script
@todo (1.1) Make freetype optional and put in optional graymap font engine
@todo (1.1) Free images if object invisible (and put back in chache)
@todo (1.1) Check robustness of malloc/calloc/realloc failures.
@todo (1.1) Add memory use reduction code if any allocations fail
@todo (1.1) If image loads fails due to memory allocatue failure, load reduced res version
@todo (1.1) If image load fails due to memory allocation failure, try split it up into tiles and demand-load them
@todo (1.2) Add external image loaders (application provided callbacks to load)
@todo (1.2) Add loadable image loader module support (evas loads file.so)
@todo (1.2) Add external image lodaer modules (application proivdes path to file.so)
@todo (1.3) Add OpenGL GLX Engine
@todo (1.3) Add X11 primtive engine
@todo (1.3) Add immediate mode drawing commands to image objects
@todo (1.3) Fix FB engine to allocate vt and release properly
@todo (1.4) Add SDL Engine
@todo (1.4) Add ellipse objects (circle, arc, ellipse etc.)
@todo (1.4) Add video/movie/animation objects
@todo (1.5) Make software engine draw lines & polys with aa
@todo (1.5) Add radial gradients to gradient objects
@todo (1.5) Add Symbian Engine
@todo (1.6) Add PalmOS Engine
@todo (1.6) Add Win32 OpenGL Engine
@todo (1.6) Add Apple OpenGL Engine
@todo (1.7) Document Engine API
@todo (1.7) Allow any object to clip any other object, and not just rectangles
@todo (1.8) Add more evas demos

*/