efl/legacy/evas

####################
# Evas 1.0.0 pre-4 #
####################

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.0.x (I want to make this optional)

Optional:

  X11R6
  DirectFB
  OpenGL (underway at the moment)
  Linux
  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 strins (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.

--------------------------------------------------------------------------
##########################################################################
##########################################################################
##########################################################################
--------------------------------------------------------------------------
suggested configure options for evas for a P2/AMD/P3/P4 desktop X display:

./configure \
--enable-software-x11 \
--enable-image-loader-png \
--enable-image-loader-jpeg \
--enable-cpu-p2-only \
--enable-cpu-mmx \
--enable-cpu-sse \
--enable-cpu-c \
--enable-scale-smooth \
--enable-scale-sample \
--enable-convert-8-rgb-332 \
--enable-convert-8-rgb-666 \
--enable-convert-8-rgb-232 \
--enable-convert-8-rgb-222 \
--enable-convert-8-rgb-221 \
--enable-convert-8-rgb-121 \
--enable-convert-8-rgb-111 \
--enable-convert-16-rgb-565 \
--enable-convert-16-rgb-555 \
--enable-convert-16-rgb-rot-0 \
--enable-convert-32-rgb-8888 \
--enable-convert-32-rgbx-8888 \
--enable-convert-32-bgr-8888 \
--enable-convert-32-bgrx-8888 \
--enable-convert-32-rgb-rot-0

make CFLAGS="-O9 -mpentiumpro -march=pentiumpro -mcpu=pentiumpro"

for those that want eet and edb image loading ability:

./configure \
--enable-software-x11 \
--enable-image-loader-png \
--enable-image-loader-jpeg \
--enable-image-loader-eet \
--enable-image-loader-edb \
--enable-fmemopen \
--enable-cpu-p2-only \
--enable-cpu-mmx \
--enable-cpu-sse \
--enable-cpu-c \
--enable-scale-smooth \
--enable-scale-sample \
--enable-convert-8-rgb-332 \
--enable-convert-8-rgb-666 \
--enable-convert-8-rgb-232 \
--enable-convert-8-rgb-222 \
--enable-convert-8-rgb-221 \
--enable-convert-8-rgb-121 \
--enable-convert-8-rgb-111 \
--enable-convert-16-rgb-565 \
--enable-convert-16-rgb-555 \
--enable-convert-16-rgb-rot-0 \
--enable-convert-32-rgb-8888 \
--enable-convert-32-rgbx-8888 \
--enable-convert-32-bgr-8888 \
--enable-convert-32-bgrx-8888 \
--enable-convert-32-rgb-rot-0

make CFLAGS="-O9 -mpentiumpro -march=pentiumpro -mcpu=pentiumpro"

or to use the fast sampling scaler:

./configure \
--enable-software-x11 \
--enable-image-loader-png \
--enable-image-loader-jpeg \
--enable-cpu-p2-only \
--enable-cpu-mmx \
--enable-cpu-sse \
--enable-cpu-c \
--enable-scale-sample \
--enable-convert-8-rgb-332 \
--enable-convert-8-rgb-666 \
--enable-convert-8-rgb-232 \
--enable-convert-8-rgb-222 \
--enable-convert-8-rgb-221 \
--enable-convert-8-rgb-121 \
--enable-convert-8-rgb-111 \
--enable-convert-16-rgb-565 \
--enable-convert-16-rgb-555 \
--enable-convert-16-rgb-rot-0 \
--enable-convert-32-rgb-8888 \
--enable-convert-32-rgbx-8888 \
--enable-convert-32-bgr-8888 \
--enable-convert-32-bgrx-8888 \
--enable-convert-32-rgb-rot-0

make CFLAGS="-O9 -mpentiumpro -march=pentiumpro -mcpu=pentiumpro"










###### OpenGL (being worked on. does nothing much at the moment) #######

./configure \
--enable-gl-x11 \
--enable-image-loader-png \
--enable-image-loader-jpeg \
--enable-cpu-p2-only \
--enable-cpu-mmx \
--enable-cpu-sse \
--enable-cpu-c \
--enable-scale-smooth \
--enable-scale-sample \

make CFLAGS="-g"






--------------------------------------------------------------------------
suggested configure options for an ipaq 36xx:

./configure \
--enable-fb \
--enable-image-loader-png \
--enable-image-loader-jpeg \
--enable-small-dither-mask \
--enable-cpu-c \
--enable-scale-smooth \
--enable-scale-sample \
--enable-convert-16-rgb-ipq \
--enable-convert-16-rgb-rot-270

make CFLAGS="-O9"

suggested configure options for an ipaq 38xx:

./configure \
--enable-fb \
--enable-image-loader-png \
--enable-image-loader-jpeg \
--enable-small-dither-mask \
--enable-cpu-c \
--enable-scale-smooth \
--enable-scale-sample \
--enable-convert-16-rgb-ipq \
--enable-convert-16-rgb-rot-90

make CFLAGS="-O9"

--------------------------------------------------------------------------
suggested configure options for an cross-compiling ipaq using skiff:

export CC=/skiff/local/bin/arm-linux-gcc
export CFLAGS="-O9"
./configure \
--enable-fb \
--enable-image-loader-png \
--enable-image-loader-jpeg \
--enable-small-dither-mask \
--enable-cpu-c \
--enable-scale-smooth \
--enable-scale-sample \
--enable-convert-16-rgb-ipq \
--enable-convert-16-rgb-rot-0 \
--enable-convert-16-rgb-rot-270 \
--with-freetype-config=/skiff/local/arm-linux/bin/freetype-config

make CFLAGS="-O9 -I/skiff/local/include -I/skiff/local/arm-linux/include"

this assumes you have a proper install of freetype2 on your skiff install that
contains a freetype-config script, and a proper install of libpng on your
skiff cross-compile environment.

--------------------------------------------------------------------------
suggested configure options for an DirectFB on x86 target:

./configure \
--enable-directfb \
--enable-cpu-p2-only \
--enable-cpu-mmx \
--enable-cpu-sse \
--enable-cpu-c \
--enable-image-loader-png \
--enable-image-loader-jpeg \
--enable-scale-smooth

make CFLAGS="-O9 -mpentiumpro -march=pentiumpro -mcpu=pentiumpro"


--------------------------------------------------------------------------
suggested configure options for a qtopia target (desktop, qvfb):

./configure \
--enable-software-qtopia \
--enable-image-loader-png \
--enable-image-loader-jpeg \
--enable-cpu-p2-only \
--enable-cpu-mmx \
--enable-cpu-sse \
--enable-cpu-c \
--enable-scale-smooth \
--enable-scale-sample \
--enable-convert-16-rgb-565 \
--enable-convert-16-rgb-555 \
--enable-convert-16-rgb-ipq \
--enable-convert-16-rgb-rot-0 \
--enable-convert-32-rgb-8888 \
--enable-convert-32-bgr-8888 \
--enable-convert-32-rgb-rot-0 \
--with-qtdir=/opt/Qtopia

make CFLAGS="-O9 -mpentiumpro -march=pentiumpro -mcpu=pentiumpro"

--------------------------------------------------------------------------
suggested configure options for a zaurus qtopia cross-compile target:

export CC=/opt/Embedix/tools/arm-linux/bin/gcc
export CXX=/opt/Embedix/tools/arm-linux/bin/g++
export CFLAGS="-O9"
./configure \
--enable-software-qtopia \
--enable-image-loader-png \
--enable-image-loader-jpeg \
--enable-small-dither-mask \
--enable-cpu-c \
--enable-scale-smooth \
--enable-scale-sample \
--enable-convert-16-rgb-565 \
--enable-convert-16-rgb-rot-270 \
--with-qtdir=/opt/Qtopia/sharp \
--with-freetype-config=/opt/Embedix/tools/arm-linux/bin/freetype-config

make CFLAGS="-O9 -I/opt/Embedix/tools/arm-linux/include"

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

Notes:
  you must enable one and ONLY one scaler. ie: --enable-scale-smooth
  you only need scalers and converters and have to provide cpu info if using
  the fb or software x11 engines right now.
  you must enable some level of cpu optimisations (at least C, if not mmx and 
    sse) ie: --enable-cpu-c --enable-cpu-mmx --enable-cpu-sse
  you will find much improved performance on pentium and pentium2, and amd
    cpu's if you use --enable-cpu-p2-only
  if you have a pentium3 or 4 you may see more speed with 
    --enable-cpu-p3-only (do not use in combination with --enable-cpu-p2-only)
  if you use the fb or software_x11 engines if you don't build in a converter
    for at least the depth you run, then display won't work. they are all
    optional for the purpose of leaning evas down for embedded devices to only
    inlcude the code you need. if you have the disk and ram space then enable
    all the converters
  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.

--------------------------------------------------------------------------
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-trilinear

this enables tilinear scaling. it uses a similar algorithm to what 3d cards
do - the quality is good and speed is slower than sampled scaling, but looks
a bit better. uses extra ram (up to 33% more) for image data for mipmaps
(they are built on-demand), but is a nice compromise

--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-p2-only

this tricks the cpu detecting code to avoid detection routines and assume a
pentium, pentium2, amd etc. cpu and use mmx routines (it's a bit misnamed -
but hey). this is suggested if your target is a pentium and up system.

--enable-cpu-p3-only

this tricks the cpu detection code into thinking you have a pentium3 or up
cpu (not - this is NOt for amd processors). it is suggested for p3 or 4
targets for more speedups again. if you use this option do NOt use the
--enable-cpu-p2-only option.

--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 peoel knwo 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
days its 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 linxu framebuffer
advertised it as) and so many lumsp fo code can be fooled into rendering
data badly because they think the output will look as the expect. thsi
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 thsi 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...