forked from enlightenment/efl
[evas] Just explaining more the main top function blocks the
main doc. page points to. The rest is just a proof read check on the main section. SVN revision: 61098
This commit is contained in:
parent
32d38b1a61
commit
153c7394df
|
@ -45,25 +45,26 @@
|
||||||
|
|
||||||
@section intro What is Evas?
|
@section intro What is Evas?
|
||||||
|
|
||||||
Evas is a clean display canvas API for several target display systems that
|
Evas is a clean display canvas API for several target display systems
|
||||||
can draw anti-aliased text, smooth super and sub-sampled scaled images,
|
that can draw anti-aliased text, smooth super and sub-sampled scaled
|
||||||
alpha-blend objects much and more.
|
images, alpha-blend objects and much more.
|
||||||
|
|
||||||
It abstracts any need to know much about what the characteristics of your
|
It abstracts any need to know much about what the characteristics of
|
||||||
display system are or what graphics calls are used to draw them and how. It
|
your display system are or what graphics calls are used to draw them
|
||||||
deals on an object level where all you do is create and manipulate objects
|
and how. It deals on an object level where all you do is create and
|
||||||
in a canvas, set their properties, and the rest is done for you.
|
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
|
Evas optimises the rendering pipeline to minimise effort in redrawing
|
||||||
made to the canvas and so takes this work out of the programmers hand,
|
changes made to the canvas and so takes this work out of the
|
||||||
saving a lot of time and energy.
|
programmers hand, saving a lot of time and energy.
|
||||||
|
|
||||||
It's small and lean, designed to work on embedded systems all the way to
|
It's small and lean, designed to work on embedded systems all the way
|
||||||
large and powerful multi-cpu workstations. It can be compiled to only have
|
to large and powerful multi-cpu workstations. It can be compiled to
|
||||||
the features you need for your target platform if you so wish, thus keeping
|
only have the features you need for your target platform if you so
|
||||||
it small and lean. It has several display back-ends, letting it display on
|
wish, thus keeping it small and lean. It has several display
|
||||||
several display systems, making it portable for cross-device and
|
back-ends, letting it display on several display systems, making it
|
||||||
cross-platform development.
|
portable for cross-device and cross-platform development.
|
||||||
|
|
||||||
@subsection intro_not_evas What Evas is not?
|
@subsection intro_not_evas What Evas is not?
|
||||||
|
|
||||||
|
@ -73,7 +74,7 @@ for a toolkit based on Evas, Edje, Ecore and other Enlightenment
|
||||||
technologies.
|
technologies.
|
||||||
|
|
||||||
It is not dependent or aware of main loops, input or output
|
It is not dependent or aware of main loops, input or output
|
||||||
systems. Input should be polled from various sources and feed them to
|
systems. Input should be polled from various sources and fed to
|
||||||
Evas. Similarly, it will not create windows or report windows updates
|
Evas. Similarly, it will not create windows or report windows updates
|
||||||
to your system, rather just drawing the pixels and reporting to the
|
to your system, rather just drawing the pixels and reporting to the
|
||||||
user the areas that were changed. Of course these operations are quite
|
user the areas that were changed. Of course these operations are quite
|
||||||
|
@ -84,14 +85,15 @@ Ecore_Evas (http://docs.enlightenment.org/auto/ecore/).
|
||||||
@section work How does Evas work?
|
@section work How does Evas work?
|
||||||
|
|
||||||
Evas is a canvas display library. This is markedly different from most
|
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
|
display and windowing systems as a canvas is structural and is also a
|
||||||
engine, whereas most display and windowing systems are immediate mode display
|
state engine, whereas most display and windowing systems are immediate
|
||||||
targets. Evas handles the logic between a structural display via its' state
|
mode display targets. Evas handles the logic between a structural
|
||||||
engine, and controls the target windowing system in order to produce
|
display via its state engine, and controls the target windowing system
|
||||||
rendered results of the current canvases state on the display.
|
in order to produce rendered results of the current canvas' state on
|
||||||
|
the display.
|
||||||
|
|
||||||
Immediate mode display systems retain very little, or no state. A program
|
Immediate mode display systems retain very little, or no state. A
|
||||||
will execute a series of commands, as in the pseudo code:
|
program will execute a series of commands, as in the pseudo code:
|
||||||
|
|
||||||
@verbatim
|
@verbatim
|
||||||
draw line from position (0, 0) to position (100, 200);
|
draw line from position (0, 0) to position (100, 200);
|
||||||
|
@ -103,27 +105,29 @@ scale bitmap_handle to size 100 x 100;
|
||||||
draw image bitmap_handle at position (10, 30);
|
draw image bitmap_handle at position (10, 30);
|
||||||
@endverbatim
|
@endverbatim
|
||||||
|
|
||||||
The series of commands is executed by the windowing system and the results
|
The series of commands is executed by the windowing system and the
|
||||||
are displayed on the screen (normally). Once the commands are executed the
|
results are displayed on the screen (normally). Once the commands are
|
||||||
display system has little or no idea of how to reproduce this image again,
|
executed the display system has little or no idea of how to reproduce
|
||||||
and so has to be instructed by the application how to redraw sections of the
|
this image again, and so has to be instructed by the application how
|
||||||
screen whenever needed. Each successive command will be executed as
|
to redraw sections of the screen whenever needed. Each successive
|
||||||
instructed by the application and either emulated by software or sent to the
|
command will be executed as instructed by the application and either
|
||||||
graphics hardware on the device to be performed.
|
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
|
The advantage of such a system is that it is simple, and gives a
|
||||||
tight control over how something looks and is drawn. Given the increasing
|
program tight control over how something looks and is drawn. Given the
|
||||||
complexity of displays and demands by users to have better looking
|
increasing complexity of displays and demands by users to have better
|
||||||
interfaces, more and more work is needing to be done at this level by the
|
looking interfaces, more and more work is needing to be done at this
|
||||||
internals of widget sets, custom display widgets and other programs. This
|
level by the internals of widget sets, custom display widgets and
|
||||||
means more and more logic and display rendering code needs to be written
|
other programs. This means more and more logic and display rendering
|
||||||
time and time again, each time the application needs to figure out how to
|
code needs to be written time and time again, each time the
|
||||||
minimise redraws so that display is fast and interactive, and keep track of
|
application needs to figure out how to minimise redraws so that
|
||||||
redraw logic. The power comes at a high-price, lots of extra code and work.
|
display is fast and interactive, and keep track of redraw logic. The
|
||||||
Programmers not very familiar with graphics programming will often make
|
power comes at a high-price, lots of extra code and work. Programmers
|
||||||
mistakes at this level and produce code that is sub optimal. Those familiar
|
not very familiar with graphics programming will often make mistakes
|
||||||
with this kind of programming will simply get bored by writing the same code
|
at this level and produce code that is sub optimal. Those familiar
|
||||||
again and again.
|
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
|
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
|
application to redraw the area from 0, 0 to 50, 50 (also referred as
|
||||||
|
@ -149,7 +153,7 @@ Redraw from position (0, 0) to position (50, 50):
|
||||||
The clever reader might have noticed that, if all elements in the
|
The clever reader might have noticed that, if all elements in the
|
||||||
above scene are opaque, then the system is doing useless paints: part
|
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
|
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
|
behind the image. These useless paints tend to be very costly, as
|
||||||
pixels tend to be 4 bytes in size, thus an overlapping region of 100 x
|
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
|
100 pixels is around 40000 useless writes! The developer could write
|
||||||
code to calculate the overlapping areas and avoid painting then, but
|
code to calculate the overlapping areas and avoid painting then, but
|
||||||
|
@ -157,10 +161,10 @@ then it should be mixed with the "expose event" handling mentioned
|
||||||
above and quickly one realizes the initially simpler method became
|
above and quickly one realizes the initially simpler method became
|
||||||
really complex.
|
really complex.
|
||||||
|
|
||||||
Evas is a structural system in which the programmer creates and manages
|
Evas is a structural system in which the programmer creates and
|
||||||
display objects and their properties, and as a result of this higher level
|
manages display objects and their properties, and as a result of this
|
||||||
state management, the canvas is able to redraw the set of objects when
|
higher level state management, the canvas is able to redraw the set of
|
||||||
needed to represent the current state of the canvas.
|
objects when needed to represent the current state of the canvas.
|
||||||
|
|
||||||
For example, the pseudo code:
|
For example, the pseudo code:
|
||||||
|
|
||||||
|
@ -182,32 +186,34 @@ show bitmap_handle;
|
||||||
render scene;
|
render scene;
|
||||||
@endverbatim
|
@endverbatim
|
||||||
|
|
||||||
This may look longer, but when the display needs to be refreshed or updated,
|
This may look longer, but when the display needs to be refreshed or
|
||||||
the programmer only moves, resizes, shows, hides etc. the objects that they
|
updated, the programmer only moves, resizes, shows, hides etc. the
|
||||||
need to change. The programmer simply thinks at the object logic level, and
|
objects that need to change. The programmer simply thinks at the
|
||||||
the canvas software does the rest of the work for them, figuring out what
|
object logic level, and the canvas software does the rest of the work
|
||||||
actually changed in the canvas since it was last drawn, how to most
|
for them, figuring out what actually changed in the canvas since it
|
||||||
efficiently redraw he canvas and its contents to reflect the current state,
|
was last drawn, how to most efficiently redraw the canvas and its
|
||||||
and then it can go off and do the actual drawing of the canvas.
|
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
|
This lets the programmer think in a more natural way when dealing with
|
||||||
display, and saves time and effort of working out how to load and display
|
a display, and saves time and effort of working out how to load and
|
||||||
images, render given the current display system etc. Since Evas also is
|
display images, render given the current display system etc. Since
|
||||||
portable across different display systems, this also gives the programmer
|
Evas also is portable across different display systems, this also
|
||||||
the ability to have their code ported and display on different display
|
gives the programmer the ability to have their code ported and
|
||||||
systems with very little work.
|
displayed on different display systems with very little work.
|
||||||
|
|
||||||
Evas can be seen as a display system that stands somewhere between a widget
|
Evas can be seen as a display system that stands somewhere between a
|
||||||
set and an immediate mode display system. It retains basic display logic,
|
widget set and an immediate mode display system. It retains basic
|
||||||
but does very little high-level logic such as scrollbars, sliders, push
|
display logic, but does very little high-level logic such as
|
||||||
buttons etc.
|
scrollbars, sliders, push buttons etc.
|
||||||
|
|
||||||
|
|
||||||
@section compiling How to compile using Evas ?
|
@section compiling How to compile using Evas ?
|
||||||
|
|
||||||
Evas is a library your application links to. The procedure for this is very
|
Evas is a library your application links to. The procedure for this is
|
||||||
simple. You simply have to compile your application with the appropriate
|
very simple. You simply have to compile your application with the
|
||||||
compiler flags that the @p pkg-config script outputs. For example:
|
appropriate compiler flags that the @c pkg-config script outputs. For
|
||||||
|
example:
|
||||||
|
|
||||||
Compiling C or C++ files into object files:
|
Compiling C or C++ files into object files:
|
||||||
|
|
||||||
|
@ -221,18 +227,19 @@ Linking object files into a binary executable:
|
||||||
gcc -o my_application main.o `pkg-config --libs evas`
|
gcc -o my_application main.o `pkg-config --libs evas`
|
||||||
@endverbatim
|
@endverbatim
|
||||||
|
|
||||||
You simply have to make sure that pkg-config is in your shell's PATH (see
|
You simply have to make sure that @c pkg-config is in your shell's @c
|
||||||
the manual page for your appropriate shell) and evas.pc in /usr/lib/pkgconfig
|
PATH (see the manual page for your appropriate shell) and @c evas.pc
|
||||||
or its path is in the PKG_CONFIG_PATH environment variable. It's that simple
|
in @c /usr/lib/pkgconfig or its path in the @c PKG_CONFIG_PATH
|
||||||
to link and use Evas once you have written your code to use it.
|
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
|
Since the program is linked to Evas, it is now able to use any
|
||||||
API calls to display graphics in a canvas managed by Evas, as well as use
|
advertised API calls to display graphics in a canvas managed by it, as
|
||||||
the API calls provided to manage data as well.
|
well as use the API calls provided to manage data.
|
||||||
|
|
||||||
You should make sure you add any extra compile and link flags to your
|
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
|
compile commands that your application may need as well. The above
|
||||||
is only guaranteed to make Evas add it's own requirements.
|
example is only guaranteed to make Evas add it's own requirements.
|
||||||
|
|
||||||
|
|
||||||
@section install How is it installed?
|
@section install How is it installed?
|
||||||
|
@ -259,17 +266,22 @@ you tons of work compared to using just Evas directly.
|
||||||
|
|
||||||
Recommended reading:
|
Recommended reading:
|
||||||
|
|
||||||
@li @ref Evas_Object_Group
|
@li @ref Evas_Object_Group, where you'll get how to basically
|
||||||
@li @ref Evas_Object_Rectangle
|
manipulate generic objects lying on an Evas canvas, handle canvas
|
||||||
@li @ref Evas_Object_Image
|
and object events, etc.
|
||||||
@li @ref Evas_Object_Text
|
@li @ref Evas_Object_Rectangle, to learn about the most basic object
|
||||||
@li @ref Evas_Smart_Object_Group and @ref Evas_Smart_Group to define
|
type on Evas -- the rectangle.
|
||||||
an object that provides custom functions to handle clipping,
|
@li @ref Evas_Object_Image, to learn about image objects, over which
|
||||||
hiding, moving, resizing, setting the color and more. These could
|
Evas can do a plethora of operations.
|
||||||
|
@li @ref Evas_Object_Text, to learn how to create textual elements on
|
||||||
|
the canvas.
|
||||||
|
@li @ref Evas_Smart_Object_Group and @ref Evas_Smart_Group, to define
|
||||||
|
new objects that provide @b custom functions to handle clipping,
|
||||||
|
hiding, moving, resizing, color setting and more. These could
|
||||||
be as simple as a group of objects that move together (see @ref
|
be as simple as a group of objects that move together (see @ref
|
||||||
Evas_Smart_Object_Clipped). These smart objects can implement what
|
Evas_Smart_Object_Clipped) up to implementations of what
|
||||||
ends to be a widget, providing some intelligence (thus the name),
|
ends to be a widget, providing some intelligence (thus the name)
|
||||||
like a button or check box.
|
to Evas objects -- like a button or check box, for example.
|
||||||
|
|
||||||
@section intro_example Introductory Example
|
@section intro_example Introductory Example
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue