forked from enlightenment/efl
321 lines
13 KiB
Plaintext
321 lines
13 KiB
Plaintext
/**
|
|
|
|
@mainpage Evas
|
|
|
|
@image html e_big.png
|
|
|
|
@version @PACKAGE_VERSION@
|
|
@author Carsten Haitzler <raster@@rasterman.com>
|
|
@author Till Adam <till@@adam-lilienthal.de>
|
|
@author Steve Ireland <sireland@@pobox.com>
|
|
@author Brett Nash <nash@@nash.id.au>
|
|
@author Tilman Sauerbeck <tilman@@code-monkey.de>
|
|
@author Corey Donohoe <atmos@@atmos.org>
|
|
@author Yuri Hudobin <glassy_ape@@users.sourceforge.net>
|
|
@author Nathan Ingersoll <ningerso@@d.umn.edu>
|
|
@author Willem Monsuwe <willem@@stack.nl>
|
|
@author Jose O Gonzalez <jose_ogp@@juno.com>
|
|
@author Bernhard Nemec <Bernhard.Nemec@@viasyshc.com>
|
|
@author Jorge Luis Zapata Muga <jorgeluis.zapata@@gmail.com>
|
|
@author Cedric Bail <cedric.bail@@free.fr>
|
|
@author Gustavo Sverzut Barbieri <barbieri@@profusion.mobi>
|
|
@author Vincent Torri <vtorri@@univ-evry.fr>
|
|
@author Tim Horton <hortont424@@gmail.com>
|
|
@author Tom Hacohen <tom@@stosb.com>
|
|
@author Mathieu Taillefumier <mathieu.taillefumier@@free.fr>
|
|
@author Iván Briano <ivan@@profusion.mobi>
|
|
@author Gustavo Lima Chaves <glima@@profusion.mobi>
|
|
|
|
@date 2000-2010
|
|
|
|
@section toc Table of Contents
|
|
|
|
@li @ref intro
|
|
@li @ref work
|
|
@li @ref compiling
|
|
@li @ref install
|
|
@li @ref next_steps
|
|
@li @ref intro_example
|
|
|
|
|
|
@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.
|
|
|
|
@subsection intro_not_evas What Evas is not?
|
|
|
|
Evas is not a widget set or widget toolkit, however it is their
|
|
base. See Elementary (http://docs.enlightenment.org/auto/elementary/)
|
|
for a toolkit based on Evas, Edje, Ecore and other Enlightenment
|
|
technologies.
|
|
|
|
It is not dependent or aware of main loops, input or output
|
|
systems. Input should be polled from various sources and feed them to
|
|
Evas. Similarly, it will not create windows or report windows updates
|
|
to your system, rather just drawing the pixels and reporting to the
|
|
user the areas that were changed. Of course these operations are quite
|
|
common and thus they are ready to use in Ecore, particularly in
|
|
Ecore_Evas (http://docs.enlightenment.org/auto/ecore/).
|
|
|
|
|
|
@section work How does Evas work?
|
|
|
|
Evas is a canvas display library. This is markedly different from most
|
|
display and windowing systems 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, as in the pseudo code:
|
|
|
|
@verbatim
|
|
draw line from position (0, 0) to position (100, 200);
|
|
|
|
draw rectangle from position (10, 30) to position (50, 500);
|
|
|
|
bitmap_handle = create_bitmap();
|
|
scale bitmap_handle to size 100 x 100;
|
|
draw image bitmap_handle at position (10, 30);
|
|
@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
|
|
complexity 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 writing the same code
|
|
again and again.
|
|
|
|
For example, if in the above scene, the windowing system requires the
|
|
application to redraw the area from 0, 0 to 50, 50 (also referred as
|
|
"expose event"), then the programmer must calculate manually the
|
|
updates and repaint it again:
|
|
|
|
@verbatim
|
|
Redraw from position (0, 0) to position (50, 50):
|
|
|
|
// what was in area (0, 0, 50, 50)?
|
|
|
|
// 1. intersection part of line (0, 0) to (100, 200)?
|
|
draw line from position (0, 0) to position (25, 50);
|
|
|
|
// 2. intersection part of rectangle (10, 30) to (50, 500)?
|
|
draw rectangle from position (10, 30) to position (50, 50)
|
|
|
|
// 3. intersection part of image at (10, 30), size 100 x 100?
|
|
bitmap_subimage = subregion from position (0, 0) to position (40, 20)
|
|
draw image bitmap_subimage at position (10, 30);
|
|
@endverbatim
|
|
|
|
The clever reader might have noticed that, if all elements in the
|
|
above scene are opaque, then the system is doing useless paints: part
|
|
of the line is behind the rectangle, and part of the rectangle is
|
|
behind the image. These useless paints tends to be very costly, as
|
|
pixels tend to be 4 bytes in size, thus an overlapping region of 100 x
|
|
100 pixels is around 40000 useless writes! The developer could write
|
|
code to calculate the overlapping areas and avoid painting then, but
|
|
then it should be mixed with the "expose event" handling mentioned
|
|
above and quickly one realizes the initially simpler method became
|
|
really complex.
|
|
|
|
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, the pseudo code:
|
|
|
|
@verbatim
|
|
line_handle = create_line();
|
|
set line_handle from position (0, 0) to position (100, 200);
|
|
show line_handle;
|
|
|
|
rectangle_handle = create_rectangle();
|
|
move rectangle_handle to position (10, 30);
|
|
resize rectangle_handle to size 40 x 470;
|
|
show rectangle_handle;
|
|
|
|
bitmap_handle = create_bitmap();
|
|
scale bitmap_handle to size 100 x 100;
|
|
move bitmap_handle to position (10, 30);
|
|
show bitmap_handle;
|
|
|
|
render scene;
|
|
@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 last drawn, 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 working 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 display
|
|
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 display 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 procedure for this is very
|
|
simple. You simply have to compile your application with the appropriate
|
|
compiler flags that the @p pkg-config script outputs. For example:
|
|
|
|
Compiling C or C++ files into object files:
|
|
|
|
@verbatim
|
|
gcc -c -o main.o main.c `pkg-config --cflags evas`
|
|
@endverbatim
|
|
|
|
Linking object files into a binary executable:
|
|
|
|
@verbatim
|
|
gcc -o my_application main.o `pkg-config --libs evas`
|
|
@endverbatim
|
|
|
|
You simply have to make sure that pkg-config is in your shell's PATH (see
|
|
the manual page for your appropriate shell) and evas.pc in /usr/lib/pkgconfig
|
|
or its path is in the PKG_CONFIG_PATH environment variable. 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?
|
|
|
|
Simple:
|
|
|
|
@verbatim
|
|
./configure
|
|
make
|
|
su -
|
|
...
|
|
make install
|
|
@endverbatim
|
|
|
|
@section next_steps Next Steps
|
|
|
|
After you understood what Evas is and installed it in your system you
|
|
should proceed understanding the programming interface for all
|
|
objects, then see the specific for the most used elements. We'd
|
|
recommend you to take a while to learn Ecore
|
|
(http://docs.enlightenment.org/auto/ecore/) and Edje
|
|
(http://docs.enlightenment.org/auto/edje/) as they will likely save
|
|
you tons of work compared to using just Evas directly.
|
|
|
|
Recommended reading:
|
|
|
|
@li @ref Evas_Object_Group
|
|
@li @ref Evas_Object_Rectangle
|
|
@li @ref Evas_Object_Image
|
|
@li @ref Evas_Object_Text
|
|
@li @ref Evas_Smart_Object_Group and @ref Evas_Smart_Group to define
|
|
an object that provides custom functions to handle clipping,
|
|
hiding, moving, resizing, setting the color and more. These could
|
|
be as simple as a group of objects that move together (see @ref
|
|
Evas_Smart_Object_Clipped). These smart objects can implement what
|
|
ends to be a widget, providing some intelligence (thus the name),
|
|
like a button or check box.
|
|
|
|
@section intro_example Introductory Example
|
|
|
|
@include evas-buffer-simple.c
|
|
|
|
|
|
|
|
@todo (1.0) Need a way ot scaling an image and just PRODUCING the output (scaling direct to target buffe r- no blend/copy etc.)
|
|
@todo (1.0) Could improve evas's scaling down code to limit multiple samples per output pixel to maybe 2x2?
|
|
@todo (1.0) Document API
|
|
@todo (1.0) Evas needs to check delete_me member for all object functions
|
|
@todo (1.0) Evas engine that renders to Evas_Objects
|
|
@todo (1.0) OpenGL engine needs to use texture meshes
|
|
@todo (1.0) OpenGL engine needs texture cache and size setting
|
|
@todo (1.0) OpenGL Engine needs YUV import API to YUV texture
|
|
@todo (1.0) All engines need pixel import API
|
|
@todo (1.0) Add parital render through composite layer api to engines
|
|
@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) 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 fontset support
|
|
@todo (1.0) Export engine rendering API cleanly to Evas API
|
|
@todo (1.0) Add smart object ability to provide rendering callback
|
|
@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 loader modules (application provides path to file.so)
|
|
@todo (1.3) Add X11 primtive engine (ie pixmap)
|
|
@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 ellipse objects (circle, arc, ellipse etc.)
|
|
@todo (1.5) Make software engine draw lines & polys etc. 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 Apple OpenGL Engine
|
|
@todo (1.7) Document engine API and other internals
|
|
@todo (1.7) Allow any object to clip any other object, and not just rectangles
|
|
@todo (1.8) Add more evas demos
|
|
@todo (1.9) Write the error mechanism in evas_xcb_buffer.c
|
|
@todo (1.9) Rewrite the render xcb engine
|
|
@todo (1.10) Improve Win32 Direct3D Engine
|
|
|
|
*/
|