evas.c.in

   1 /**
   2
   3 @mainpage Evas
   4 @image latex evas_big.eps width=5cm
   5 @image html  evas.png
   6 @version 1.0.0
   7 @author Carsten Haitzler <raster\@rasterman.com>
   8 @author Till Adam <till\@adam-lilienthal.de>
   9 @author Steve Ireland <sireland\@pobox.com>
  10 @author Brett Nash <nash\@nash.id.au>
  11 @author Tilman Sauerbeck <tilman at code-monkey.de>
  12 @author Corey Donohoe <atmos\@atmos.org>
  13 @author Yuri Hudobin <glassy_ape\@users.sourceforge.net>
  14 @author Nathan Ingersoll <ningerso\@d.umn.edu>
  15 @author Willem Monsuwe <willem\@stack.nl>
  16 @author Vincent Torri <vtorri at univ-evry dot fr>
  17 @author Gustavo Barbieri <barbieri at profusion dot mobi>
  18 @author Cedric Bail <moa dot bluebugs at gmail dot com>
  19 @date 2000-2008
  20
  21
  22 @section intro What is Evas?
  23
  24 Evas is a clean display canvas API for several target display systems that
  25 can draw anti-aliased text, smooth super and sub-sampled scaled images,
  26 alpha-blend objects much and more.
  27
  28 It abstracts any need to know much about what the characteristics of your
  29 display system are or what graphics calls are used to draw them and how. It
  30 deals on an object level where all you do is create and manipulate objects
  31 in a canvas, set their properties, and the rest is done for you.
  32
  33 Evas optimises the rendering pipeline to minimise effort in redrawing changes
  34 made to the canvas and so takes this work out of the programmers hand,
  35 saving a lot of time and energy.
  36
  37 It's small and lean, designed to work on embedded systems all the way to
  38 large and powerful multi-cpu workstations. It can be compiled to only have
  39 the features you need for your target platform if you so wish, thus keeping
  40 it small and lean. It has several display back-ends, letting it display on
  41 several display systems, making it portable for cross-device and
  42 cross-platform development.
  43
  44
  45 @section work How does Evas work?
  46
  47 Evas is a canvas display library. This is markedly different from most
  48 display and windowing systems as a Canvas is structural and is also a state
  49 engine, wheras most display and windowing systems are immediate mode display
  50 targets. Evas handles the logic between a structural display via its' state
  51 engine, and controls the target windowing system in order to produce
  52 rendered results of the current canvases state on the display.
  53
  54 Immediate mode display systems retain very little, or no state. A program
  55 will execute a series of commands:
  56
  57 @verbatim
  58 bitmap_handle = create_new_bitmap();
  59 draw_line(0, 0, 100, 200);
  60 draw_rectangle(10, 30, 50, 500);
  61 draw_bitmap(10, 30, bitmap_handle);
  62 etc.
  63 @endverbatim
  64
  65 The series of commands is executed by the windowing system and the results
  66 are displayed on the screen (normally). Once the commands are executed the
  67 display system has little or no idea of how to reproduce this image again,
  68 and so has to be instructed by the application how to redraw sections of the
  69 screen whenever needed. Each sucessive command will be executed as
  70 instructed by the application and either emulated by software or sent to the
  71 graphics hardware on the device to be performed.
  72
  73 The advantage of such a system is that it is simple, and gives a program
  74 tight control over how something looks and is drawn. Given the increasing
  75 complexity of displays and demands by users to have better looking
  76 interfaces, more and more work is needing to be done at this level by the
  77 internals of widget sets, custom display widgets and other programs. This
  78 means more and more logic and display rendering code needs to be written
  79 time and time again, each time the application needs to figure out how to
  80 minimise redraws so that display is fast and interactive, and keep track of
  81 redraw logic. The power comes at a high-price, lots of extra code and work.
  82 Programmers not very familiar with graphics programming will often make
  83 mistakes at this level and produce code that is sub optimal. Those familiar
  84 with this kind of programming will simply get bored by writing the same code
  85 again and again.
  86
  87 Evas is a structural system in which the programmer creates and manages
  88 display objects and their properties, and as a result of this higher level
  89 state management, the canvas is able to redraw the set of objects when
  90 needed to represent the current state of the canvas.
  91
  92 For example:
  93
  94 @verbatim
  95 bitmap_handle = create_bitmap();
  96 move(bitmap_handle, 10, 30);
  97 show(bitmap_handle);
  98 rectangle_handle = create_rectangle();
  99 move(rectangle_handle, 10, 30);
 100 resize(rectangle_handle, 50, 500);
 101 show(rectangle_handle);
 102 line_handle = create_line();
 103 set_line_coords(line_handle, 0, 0, 100, 200);
 104 show(line_handle);
 105 etc.
 106 @endverbatim
 107
 108 This may look longer, but when the display needs to be refreshed or updated,
 109 the programmer only moves, resizes, shows, hides etc. the objects that they
 110 need to change. The programmer simply thinks at the object logic level, and
 111 the canvas software does the rest of the work for them, figuring out what
 112 actually changed in the canvas since it was last drawn, how to most
 113 efficiently redraw he canvas and its contents to reflect the current state,
 114 and then it can go off and do the actual drawing of the canvas.
 115
 116 This lets the programmer think in a more natural way when dealing with a
 117 display, and saves time and effort of working out how to load and display
 118 images, render given the current display system etc. Since Evas also is
 119 portable across different display systems, this also gives the programmer
 120 the ability to have their code ported and display on different display
 121 systems with very little work.
 122
 123 Evas can be seen as a display system that stands somewhere between a widget
 124 set and an immediate mode display system. It retains basic display logic,
 125 but does very little high-level logic such as scrollbars, sliders, push
 126 buttons etc.
 127
 128
 129 @section compiling How to compile using Evas?
 130
 131 Evas is a library your application links to. The proceedure for this is very
 132 simple. You simply have to compile your application with the appropriate
 133 compiler flags that the @p evas-config script outputs. For example:
 134
 135 Compiling C or C++ files into object files:
 136
 137 @verbatim
 138 gcc -c -o main.o main.c `pkg-config --cflags evas`
 139 @endverbatim
 140
 141 Linking object files into a binary executable:
 142
 143 @verbatim
 144 gcc -o my_application main.o `pkg-config --libs evas`
 145 @endverbatim
 146
 147 You simply have to make sure that pkg-config is in your shell's PATH (see
 148 the manual page for your appropriate shell) and evas.pc in /usr/lib/pkgconfig
 149 or its path is in the PKG_CONFIG_PATH environment variable. It's that simple
 150 to link and use Evas once you have written your code to use it.
 151
 152 Since the program is linked to Evas, it is now able to use any advertised
 153 API calls to display graphics in a canvas managed by Evas, as well as use
 154 the API calls provided to manage data as well.
 155
 156 You should make sure you add any extra compile and link flags to your
 157 compile commands that your application may need as well. The above example
 158 is only guaranteed to make Evas add it's own requirements.
 159
 160
 161 @section install How is it installed?
 162
 163 Simple:
 164
 165 @verbatim
 166 ./configure
 167 make
 168 su -
 169 ...
 170 make install
 171 @endverbatim
 172
 173
 174 @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.)
 175 @todo (1.0) Could improve evas's scaling down code to limit multiple samples per output pixel to maybe 2x2?
 176 @todo (1.0) Document API
 177 @todo (1.0) Evas needs to check delete_me member for all object functions
 178 @todo (1.0) Evas engine that renders to Evas_Objects
 179 @todo (1.0) OpenGL engine needs to use texture meshes
 180 @todo (1.0) OpenGL engine needs texture cache and size setting
 181 @todo (1.0) OpenGL Engine needs YUV import API to YUV texture
 182 @todo (1.0) All engines need pixel import API
 183 @todo (1.0) Add parital render through composite layer api to engines
 184 @todo (1.0) Move callback processing to a queue and do it asynchronously???
 185 @todo (1.0) Add button grabbing
 186 @todo (1.0) Add generic object method call system
 187 @todo (1.0) Add callbacks set for smart object parents to be set on all child smart objects too.
 188 @todo (1.0) Define image load errors (and maybe have an error to string func)
 189 @todo (1.0) Add text styles (outline etc.)
 190 @todo (1.0) Add font load query calls (so we know if a font load failed)
 191 @todo (1.0) Add font listing calls
 192 @todo (1.0) Add ability to check image comments & disk format
 193 @todo (1.0) Add group objects
 194 @todo (1.0) Add fontset support
 195 @todo (1.0) Export engine rendering API cleanly to Evas API
 196 @todo (1.0) Add smart object ability to provide rendering callback
 197 @todo (1.1) Make freetype optional and put in optional graymap font engine
 198 @todo (1.1) Free images if object invisible (and put back in chache)
 199 @todo (1.1) Check robustness of malloc/calloc/realloc failures.
 200 @todo (1.1) Add memory use reduction code if any allocations fail
 201 @todo (1.1) If image loads fails due to memory allocatue failure, load reduced res version
 202 @todo (1.1) If image load fails due to memory allocation failure, try split it up into tiles and demand-load them
 203 @todo (1.2) Add external image loaders (application provided callbacks to load)
 204 @todo (1.2) Add loadable image loader module support (evas loads file.so)
 205 @todo (1.2) Add external image loader modules (application provides path to file.so)
 206 @todo (1.3) Add X11 primtive engine (ie pixmap)
 207 @todo (1.3) Add immediate mode drawing commands to image objects
 208 @todo (1.3) Fix FB engine to allocate vt and release properly
 209 @todo (1.4) Add ellipse objects (circle, arc, ellipse etc.)
 210 @todo (1.5) Make software engine draw lines & polys etc. with aa
 211 @todo (1.5) Add radial gradients to gradient objects
 212 @todo (1.5) Add Symbian Engine
 213 @todo (1.6) Add PalmOS Engine
 214 @todo (1.6) Add Apple OpenGL Engine
 215 @todo (1.7) Document engine API and other internals
 216 @todo (1.7) Allow any object to clip any other object, and not just rectangles
 217 @todo (1.8) Add more evas demos
 218 @todo (1.9) Write the error mechanism in evas_xcb_buffer.c
 219 @todo (1.9) Rewrite the render xcb engine
 220 @todo (1.10) Improve Win32 Direct3D Engine
 221
 222 */