273 lines
8.2 KiB
C
273 lines
8.2 KiB
C
/**
|
|
@file
|
|
@brief Evas Client-side Library Public API Calls
|
|
|
|
These routines are used for Evas Library interaction
|
|
*/
|
|
|
|
/**
|
|
|
|
@mainpage Evas Library Documentation
|
|
@image latex evas_big.eps width=5cm
|
|
@image html evas.png
|
|
@version 1.0.0
|
|
@author Carsten Haitzler <raster@rasterman.com>
|
|
@date 2001-2002
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@section intro What is Evas?
|
|
|
|
Evas is a clean display canvas API for several 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 displays 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...
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@todo Document API
|
|
@todo Document Engine API
|
|
@todo Add keyboard callbacks/event feeds and focus
|
|
@todo Make freetype optional and put in optional graymap font engine
|
|
@todo Add external image loaders (application provided callbacks to load)
|
|
@todo Add loadable image loader module support (evas loads file.so)
|
|
@todo Add external image lodaer modules (application proivdes path to file.so)
|
|
@todo Define image load errors (and maybe have an error to string func)
|
|
@todo Add ability to check image comments & disk format
|
|
@todo Add text styles (outline etc.)
|
|
@todo Add font load query calls (so we know if a font load failed)
|
|
@todo Add font listing calls
|
|
@todo Add OpenGL GLX Engine
|
|
@todo Add Win32 OpenGL Engine
|
|
@todo Add Apple OpenGL Engine
|
|
@todo Add X11 primtive engine
|
|
@todo Add SDL Engine
|
|
@todo Add Symbian Engine
|
|
@todo Add PalmOS Engine
|
|
@todo Fix FB engine to allocat vt and release properly
|
|
@todo Add ellipse objects (circle, arc, ellipse etc.)
|
|
@todo Add video/movie/animation objects
|
|
@todo Make software engine draw lines & polys with aa
|
|
@todo Add radial gradients to gradient objects
|
|
@todo Allow any object to clip any other object, and not just rectangles
|
|
@todo Free images if object invisible (and put back in chache)
|
|
@todo Check robustness of malloc/calloc/realloc failures.
|
|
@todo Add memory use reduction code if any allocations fail
|
|
@todo If image loads fails due to memory allocatue failure, load reduced res version
|
|
@todo If image load fails due to memory allocation failure, try split it up into tiles and demand-load them
|
|
@todo Add auto-detection of what engines to build based on system/libs etc.
|
|
@todo Add overall engine configure parameters (so you can configure an engine with defaults with 1 configure option)
|
|
@todo Add more evas demos
|
|
|
|
*/
|