efl/legacy/evas

#####################
# Evas 1.0.0 pre-13 #
#####################

This is a !!!!!!!!***** PRE RELEASE *****!!!!!!!!.

This does NOT mean this is a 1.0.0. It is not complete. It has a 1.0.0
version to make sure it does not conflict with previous evas versions
(0.6.0). 1.0.0 is there because this codebase is PLANNED for 1.0.0. The API
is now stable and I'm happy with it. Until a final 1.0.0, all releases will
have a pre-<number> release. Don't be fooled though. This code should be
stable and fast, but it just may be missing features (like a fully working
OpenGL engine, or documentation).

When this no longer has a pre-<something> as its version THEN it is ready.

--------------------------------------------------------------------------
Requires:

  freetype 2.x.x (I want to make this optional)

Optional:

  X11R6
  DirectFB
  OpenGL (underway at the moment)
  Linux
  Qtopia
  libpng
  libjpeg
  libeet
  libedb

--------------------------------------------------------------------------
Evas as of 1.0.0 has a new (and incompatible) API. Why? It's much cleaner
and more compact. Designed for portable access to different display systems.
It is also much more optimised internally, uses much less ram than previous
Evas libraries, and is tiny. Evas when compiled for the Ipaq is a grand
total of 191Kb (thats all of Evas minus libjpeg, libpng, libz (required for 
libpng), and minus freetype (required for font rendering)). I have plans that 
may involve having an alternative font engine other than freetype to minimise
requirements, and having a native (optional) image loader for an image
format that may end up being custom to evas, but will minimise code &
requirements especially for embedded use.

Evas uses very little RAM too (try profiling it in memprof if you want to 
know) most of the ram allocated, if you look, is for freetype itself,
image pixel data, and font glyph data. You can't really avoid this, though
evas tries to share this data as much as possible and not duplicate where it
can. Feel free to point me at sensible memory optimisations etc. though :) I 
want this baby to be lean, mean tiny, fast and do everything from your 
massive multi-cpu desktop with gobs of ram and disk to a tiny watch.

Evas also supports full UTF-8 for text object strings, thus allowing for
full internationalised text strings (if your font gives you all the
characters). I've tested with quite a few fonts and it works quite well.
Though this requires a unicode compatible font with unicode charmap support
(cyberbit is quite good actually as a font). For now Evas draws the fonts
only from left to right, so arabic, hebrew etc. won't display quite right,
direction-wise, but the charcters do.

--------------------------------------------------------------------------
if you want to know what options to enable
./confiugre --help

Notes:
  the small dither mask is faster on the ipaq, but is not as good looking. on
    desktop machines it makes no speed difference so only use
    --enable-small-dither-mask if you are compiling for the ipaq
  you need at least 1 image loader if you want to load images.
  gcc 3.0.x on solaris screws up the jpeg code so erroring out doesn't work.
    use gcc 3.2 on solaris.
  freetype 2.1.2 is BAD. RedHat 8.0 uses this as do some debain distributions.
    either downgrade to 2.1.1. freetype 2.1.3 is ALSO BAD, as is 2.0.9. It has
    glyph metric rendering bugs and glyph geomery query bugs. do not use it.
    try using 2.0.3. It is known to be stable and work perfectly with Evas.

--------------------------------------------------------------------------
notes on features:

SCALING:
--enable-scale-sample

this enables the sampling scaler code. this is the fastest image scaling
code, but also the lowest quality. when scaling up pixels will become blocky
and when scaling down you will see shimmering/aliasing artifacts. this is a
speed vs. quality tradeoff

--enable-scale-smooth

this is the nicest looking scaler that is not that much slower than
tri-linear, but it looks really good. it also uses mipmaps and is optimised
heavily. it is recommended to always use this unless you are really
struggling for speed and are qilling to forego the quality

DITHERING:
--enable-small-dither-mask

this uses a 4x4 dither mask instead of 128x128. on desktop boxes these days
(pentium, pentium2, amd etc.) the speed difference is not really measurable,
but the quality of the 128x128 dither mask is quite a lot better. patterns
of dithering are much less noticable, so it is recommended to not enable
this unless you are struggling for speed. the compaq ipaq for example shows
a slowdown with this large a dither mask so enabling a small dither mask is
recommended unless you really want to forego the speed.

ENGINES:
--enable-software-x11

this enables the software x11 rendering engine that renders to X drawable
targets using highly optimised software routines. there is no hardware
assist here. this engine requires X11 to be installed to build (and run).
This si a godo generic engine that is fast and can run in X for good
development and debugging purposes.

--enable-fb

this is the software framebuffer drivign engine. this uses the linxu
framebuffer device (/dev/fb<x>) and will currently just inherit the current
framebuffer settings on the fb device and use them to run in. this engine is
almost fully functional except for the fb management itself. i'd be quite
happy for people to help out with fixing up the fb init & management code to
properly set up a vt and release it etc. this engine is specifically geared
towards peoel writing minimalist display systems for embedded devices such
as the ipaq, zaurus, etc. it also scales up to high-res desktop systems as
well and performs outstandingly. i have measured up to 67% speedup over X11
using the fb driver insetad of X11.

--enable-direcfb

this is the direct fb engine that uses direcftb (http://www.directfb.org) on
linux to access the framebuffer with (or maybe without) acceleration. for
people making set-top boxes or just wanting an alternative to X this is
really good. it may also be useful for embedded devices supported by
directfb that offer acceleration (otherwise the fb driver will likely be
faster).

CPU:
--enable-cpu-c

this enabled the c code. you can actually build the code withotu the c
fallback code and only have the mmx routines for example. it is suggested to
always use this regardless uness you have some definite size issues with the
code.

--enable-cpu-mmx

this enables the mmx optimised routines. this works for penitum, pentium2,
pentium3, pentium4, athlon and duron processors. it can get quite
considerable speedups, souse it if you can. ppc owners just have to live with
the c fallback functions unfortunately as no one has provided any ALTIVEC asm 
routines yet. :) arm owners will also have to rely on the c fallback
routines as i haven't managed to come up with any arm assembly that actually
can beat the c code (when compiled whht all optimisations) in speed.

--enable-cpu-sse

this enables sse optimisations availbale in he pentium3 and 4 cpus (not
athlon and duron or pentium 2 or pentium cpu's). ppc owners just have to
live with the c fallback functions unfortunately as no one has provided any
ALTIVEC asm routines yet. :) arm owners will also have to rely on the c
fallback routines as i haven't managed to come up with any arm assembly that 
actually can beat the c code (when compiled whht all optimisations) in speed.

IMAGE LOADERS:
--enable-image-loader-png

this enables the loader code that loads png files using libpng. there may be
call for embedded devices later that have custom written small image
loaders that use sless disk space than libpng to load custom format images.
for now this is the only loader so you may as well include it.

--enable-image-loader-jpeg

this enables the loader code that loads jpeg files using libjpeg.

CONVERTERS:
--enable-convert-16-rgb-565

the most common converter you'll want for 16bpp. this means 5 bits for red,
6 bits for green and 5 bits for blue are used.

--enable-convert-16-rgb-555

this is a converter for what many people know as "15 bit" color. you might
want to enable this for X output as it used to be common to find many cards
that do this.

--enable-convert-16-rgb-444

this converter outputs to 12bit packed (int 16 bit WORDS).

--enable-convert-16-rgb-ipq

this converter was written specifically for the ipaq (and may apply to
similarly configured devices) because it lies about its screen depth. it
says it is 16bit 565 (that means 5 upper bits of the WORD are red, the next 6
bits are for green abd the next 5 for blue) but in fact only the upper 4
bits of each color component (red green and blue) are significant and work,
so effectively the display is 12 bits of color, not 16, but padded out to
fill 16bits, with unused bits in the color masks. X on the ipaq advertises
it as a full 16bpp 565 display (i can't remember what the linux framebuffer
advertised it as) and so many lumps of code can be fooled into rendering
data badly because they think the output will look as the expect. This
renderer assuems the upper 4 bits fo each color primitie only are
significant and renders accordingly. this produces nice quality images on
the ipaq and even still works in 16bpp 565 on your pc. it is highly
recommended to use this renderer if your target is an ipaq or your device
dislpays similar qualities of the ipaq for display purposes.

--enable-convert-16-rgb-rot-0

this enables the 16bpp converters to run with 0 degrees rotation - this is 
normal disp;ay and you shoudl really include this (though it is optional if you
only ever want to do portrait mode - perhaps like on an ipaq embedded device)

--enable-convert-16-rgb-rot-270

this enables the portrait mode (270 degree rotation) converteres for 16bpp.
this is the standard display mode for things like pocketpc on the ipaq and
the zaurus etc. thsi si a optimised part of the rendering pipeline to allow
portrait display with a much lower overhead than doing it through X.

--enable-convert-24-rgb-888

To be documented...

--enable-convert-24-bgr-888

To be documented...

--enable-convert-32-rgb-8888

To be documented...

--enable-convert-32-bgr-8888

To be documented...

--enable-convert-32-rgb-rot-0

To be documented...

--enable-convert-32-rgb-rot-270

To be documented...

...