README.in

   1 Evas @VERSION@
   2
   3 Evas is a clean display canvas API for several target display systems
   4 that can draw anti-aliased text, smooth super and sub-sampled scaled
   5 images, alpha-blend objects much and more.
   6
   7 Requirements:
   8 -------------
   9
  10 Must:
  11   libc libm freetype2.1.9+
  12
  13 Recommended:
  14   libX11 libXext libXrender fontconfig libpng libjpeg eet libpthread
  15
  16 Optional:
  17   XCB SDL OpenGL Qtopia librsvg libtiff libgif edb DirectFB
  18
  19 --------------------------------------------------------------------------
  20 Evas as of 0.9.9 has a new (and incompatible) API. Why? It's much cleaner
  21 and more compact. Designed for portable access to different display systems.
  22 It is also much more optimised internally, uses much less ram than previous
  23 Evas libraries, and is tiny. Evas when compiled for the Ipaq is a grand
  24 total of 191Kb (thats all of Evas minus libjpeg, libpng, libz (required for
  25 libpng), and minus freetype (required for font rendering)). I have plans that
  26 may involve having an alternative font engine other than freetype to minimise
  27 requirements, and having a native (optional) image loader for an image
  28 format that may end up being custom to evas, but will minimise code &
  29 requirements especially for embedded use.
  30
  31 Evas uses very little RAM too (try profiling it in memprof if you want to
  32 know) most of the ram allocated, if you look, is for freetype itself,
  33 image pixel data, and font glyph data. You can't really avoid this, though
  34 evas tries to share this data as much as possible and not duplicate where it
  35 can. Feel free to point me at sensible memory optimisations etc. though :) I
  36 want this baby to be lean, mean tiny, fast and do everything from your
  37 massive multi-cpu desktop with gobs of ram and disk to a tiny watch.
  38
  39 Evas also supports full UTF-8 for text object strings, thus allowing for
  40 full internationalised text strings (if your font gives you all the
  41 characters). I've tested with quite a few fonts and it works quite well.
  42 Though this requires a unicode compatible font with unicode charmap support
  43 (cyberbit is quite good actually as a font). For now Evas draws the fonts
  44 only from left to right, so arabic, hebrew etc. won't display quite right,
  45 direction-wise, but the characters do.
  46
  47 --------------------------------------------------------------------------
  48 if you want to know what options to enable
  49 ./configure --help
  50
  51 Notes:
  52   the small dither mask is faster on the ipaq, but is not as good looking. on
  53     desktop machines it makes no speed difference so only use
  54     --enable-small-dither-mask if you are compiling for the ipaq
  55   you need at least 1 image loader if you want to load images.
  56   gcc 3.0.x on solaris screws up the jpeg code so erroring out doesn't work.
  57     use gcc 3.2 on solaris.
  58
  59 --------------------------------------------------------------------------
  60 notes on features:
  61
  62 SCALING:
  63 --enable-scale-sample
  64
  65 this enables the sampling scaler code. this is the fastest image scaling
  66 code, but also the lowest quality. when scaling up pixels will become blocky
  67 and when scaling down you will see shimmering/aliasing artifacts. this is a
  68 speed vs. quality tradeoff
  69
  70 --enable-scale-smooth
  71
  72 this is the nicest looking scaler that is not that much slower than
  73 tri-linear, but it looks really good. it also uses mipmaps and is optimised
  74 heavily. it is recommended to always use this unless you are really
  75 struggling for speed and are qilling to forego the quality
  76
  77 DITHERING:
  78 --enable-small-dither-mask
  79
  80 this uses a 4x4 dither mask instead of 128x128. on desktop boxes these days
  81 (pentium, pentium2, amd etc.) the speed difference is not really measurable,
  82 but the quality of the 128x128 dither mask is quite a lot better. patterns
  83 of dithering are much less noticable, so it is recommended to not enable
  84 this unless you are struggling for speed. the compaq ipaq for example shows
  85 a slowdown with this large a dither mask so enabling a small dither mask is
  86 recommended unless you really want to forego the speed.
  87
  88 ENGINES:
  89 --enable-software-x11
  90
  91 this enables the software x11 rendering engine that renders to X drawable
  92 targets using highly optimised software routines. there is no hardware
  93 assist here. this engine requires X11 to be installed to build (and run).
  94 This is a godo generic engine that is fast and can run in X for good
  95 development and debugging purposes.
  96
  97 --enable-software-xcb
  98 this enable the software xcb rendering engine. It allows the same
  99 features than the software x11 engine. It require the XCB and XCBImage
 100 libraries. For the test programs, XCBICCCM is also needed.
 101
 102 --enable-fb
 103
 104 this is the software framebuffer driving engine. this uses the linux
 105 framebuffer device (/dev/fb<x>) and will currently just inherit the current
 106 framebuffer settings on the fb device and use them to run in. this engine is
 107 almost fully functional except for the fb management itself. i'd be quite
 108 happy for people to help out with fixing up the fb init & management code to
 109 properly set up a vt and release it etc. this engine is specifically geared
 110 towards peoel writing minimalist display systems for embedded devices such
 111 as the ipaq, zaurus, etc. it also scales up to high-res desktop systems as
 112 well and performs outstandingly. i have measured up to 67% speedup over X11
 113 using the fb driver insetad of X11.
 114
 115 --enable-direcfb
 116
 117 this is the direct fb engine that uses direcftb (http://www.directfb.org) on
 118 linux to access the framebuffer with (or maybe without) acceleration. for
 119 people making set-top boxes or just wanting an alternative to X this is
 120 really good. it may also be useful for embedded devices supported by
 121 directfb that offer acceleration (otherwise the fb driver will likely be
 122 faster).
 123
 124 --enable-sdl
 125
 126 this is the sdl engine that uses sdl library (http://www.libsdl.org). This
 127 library should work on many operating system.
 128
 129
 130 CPU:
 131 --enable-cpu-c
 132
 133 this enabled the c code. you can actually build the code withotu the c
 134 fallback code and only have the mmx routines for example. it is suggested to
 135 always use this regardless uness you have some definite size issues with the
 136 code.
 137
 138 --enable-cpu-mmx
 139
 140 this enables the mmx optimised routines. this works for pentium, pentium2,
 141 pentium3, pentium4, athlon and duron processors. it can get quite
 142 considerable speedups, souse it if you can. ppc owners just have to live with
 143 the c fallback functions unfortunately as no one has provided any ALTIVEC asm
 144 routines yet. :) arm owners will also have to rely on the c fallback
 145 routines as i haven't managed to come up with any arm assembly that actually
 146 can beat the c code (when compiled with all optimisations) in speed.
 147
 148 --enable-cpu-sse
 149
 150 this enables sse optimizations availbale in he pentium3 and 4 cpus (not
 151 athlon and duron or pentium 2 or pentium cpu's). ppc owners just have to
 152 live with the c fallback functions unfortunately as no one has provided any
 153 ALTIVEC asm routines yet. :) arm owners will also have to rely on the c
 154 fallback routines as i haven't managed to come up with any arm assembly that
 155 actually can beat the c code (when compiled with all optimizations) in speed.
 156
 157 IMAGE LOADERS:
 158 --enable-image-loader-png
 159
 160 this enables the loader code that loads png files using libpng. there may be
 161 call for embedded devices later that have custom written small image
 162 loaders that uses less disk space than libpng to load custom format images.
 163 for now this is the only loader so you may as well include it.
 164
 165 --enable-image-loader-jpeg
 166
 167 this enables the loader code that loads jpeg files using libjpeg.
 168
 169 CONVERTERS:
 170 --enable-convert-16-rgb-565
 171
 172 the most common converter you'll want for 16bpp. this means 5 bits for red,
 173 6 bits for green and 5 bits for blue are used.
 174
 175 --enable-convert-16-rgb-555
 176
 177 this is a converter for what many people know as "15 bit" color. you might
 178 want to enable this for X output as it used to be common to find many cards
 179 that do this.
 180
 181 --enable-convert-16-rgb-444
 182
 183 this converter outputs to 12bit packed (int 16 bit WORDS).
 184
 185 --enable-convert-16-rgb-ipq
 186
 187 this converter was written specifically for the ipaq (and may apply to
 188 similarly configured devices) because it lies about its screen depth. it
 189 says it is 16bit 565 (that means 5 upper bits of the WORD are red, the next 6
 190 bits are for green abd the next 5 for blue) but in fact only the upper 4
 191 bits of each color component (red green and blue) are significant and work,
 192 so effectively the display is 12 bits of color, not 16, but padded out to
 193 fill 16bits, with unused bits in the color masks. X on the ipaq advertises
 194 it as a full 16bpp 565 display (i can't remember what the linux framebuffer
 195 advertised it as) and so many lumps of code can be fooled into rendering
 196 data badly because they think the output will look as the expect. This
 197 renderer assuems the upper 4 bits fo each color primitie only are
 198 significant and renders accordingly. this produces nice quality images on
 199 the ipaq and even still works in 16bpp 565 on your pc. it is highly
 200 recommended to use this renderer if your target is an ipaq or your device
 201 dislpays similar qualities of the ipaq for display purposes.
 202
 203 --enable-convert-16-rgb-rot-0
 204
 205 this enables the 16bpp converters to run with 0 degrees rotation - this is
 206 normal display and you should really include this (though it is optional if you
 207 only ever want to do portrait mode - perhaps like on an ipaq embedded device)
 208
 209 --enable-convert-16-rgb-rot-270
 210
 211 this enables the portrait mode (270 degree rotation) converteres for 16bpp.
 212 this is the standard display mode for things like pocketpc on the ipaq and
 213 the zaurus etc. thsi si a optimized part of the rendering pipeline to allow
 214 portrait display with a much lower overhead than doing it through X.
 215
 216 --enable-convert-24-rgb-888
 217
 218 To be documented...
 219
 220 --enable-convert-24-bgr-888
 221
 222 To be documented...
 223
 224 --enable-convert-32-rgb-8888
 225
 226 To be documented...
 227
 228 --enable-convert-32-bgr-8888
 229
 230 To be documented...
 231
 232 --enable-convert-32-rgb-rot-0
 233
 234 To be documented...
 235
 236 --enable-convert-32-rgb-rot-270
 237
 238 To be documented...
 239
 240 ...
 241
 242
 243 ------------------------------------------------------------------------------
 244 COMPILING AND INSTALLING:
 245
 246   ./configure
 247   make
 248 (as root unless youa re installing in your users directories):
 249   make install
 250
 251 ------------------------------------------------------------------------------
 252 BUILDING PACKAGES:
 253
 254 RPM: To build rpm packages:
 255
 256   sudo rpm -ta @PACKAGE@-@VERSION@.tar.gz
 257
 258 You will find rpm packages in your system /usr/src/redhat/* dirs (note you may
 259 not need to use sudo or root if you have your own ~/.rpmrc. see rpm documents
 260 for more details)
 261
 262 DEB: To build deb packages:
 263
 264   tar zvf @PACKAGE@-@VERSION@.tar.gz
 265   cd @PACKAGE@-@VERSION@
 266   dpkg-buildpackage -us -uc -rfakeroot
 267   cd ..
 268   rm -rf @PACKAGE@-@VERSION@
 269
 270 You will find all the debian source, binary etc. packages put in the directory
 271 where you first untarred the source tarball.
 272
 273
 274 NOTES:
 275
 276 For the arm optimizations you want to try:
 277   export CFLAGS="-O2 -march=armv5te -mcpu=arm1136jf-s -fomit-frame-pointer"