Evas 1.7.99 ****************************************************************************** FOR ANY ISSUES PLEASE EMAIL: enlightenment-devel@lists.sourceforge.net ****************************************************************************** Requirements: ------------- Must: libc eina (1.6.0 or better) eobj freetype (2.1.9 or better) Recommended: libX11 + libXext + libXrender OpenGL2.0 or OpenGL-ES 2.0 fontconfig libpng libjpeg (6.0 or better) eet (1.5.0 or better) fribidi harfbuzz liblinebreak Optional: XCB SDL esvg libtiff libwebp libgif edb DirectFB evas_generic_loaders Evas is a clean display canvas API for several target display systems that can draw anti-aliased text, smooth super and sub-sampled scaled images, alpha-blend objects much and more. Evas is designed to be portable to different display systems. 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 optimizations 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 internationalized 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 characters do. ------------------------------------------------------------------------------ COMPILING AND INSTALLING: ./configure make (as root unless you are installing in your users directories): make install if you want to know what options to enable ./configure --help Evas's rendering code assumes a decently optimizing compiler. For example gcc with -O2 -march=nocona for example (compile for core2 duo x86 or better). You may choose not to compile for a very modern architecture, and Evas still has MMX/SSE, NEON and other hand-crafted assembly, but not for everything, so make use of your compiler optimizing as much as possible. At least use -O2 or equivalents. 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 really need the speed for low depth 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. notes on features (--enable-FEATURE enables it and --disable-FEATURE disables it, some being enabled or disabled by default or if dependencies are found): Also the wayland support (EGL and SHM engines) is considered experimental as wayland itself is still unstable and liable to change core protocol. If you use this api, it is possible it will break in future, until this notice is removed. ------------------------------------------------------------------------------ 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. ------------------------------------------------------------------------------ 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 noticeable, 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 forgo the speed. --enable-line-dither-mask this is a faster alternative to the small or large dither masks above. this dithers only on an alternating-line basis. this only provides 1 intermediate "dither" level whose odd and even pixels alternate between the 2 closest colors available, but it is very fast. almost as fast as no dithering. quality though will not be as good as small or default "large" dither masks. --enable-no-dither-mask this disables dithering entirely. this is the fastest option, but the lowest quality. not suggested in general unless you are really in need of an extra few percent speed and are willing to have fairly awful quality. but in general this is the standard rendering for most "realtime graphics" if it has to drop to lower bit-depths, so it's not anything unusual. just in the evas world the quality is considered poor enough to be discouraged as evas's internal rendering is so much higher quality. ------------------------------------------------------------------------------ ENGINES: All engines can be compiled statically inside libevas.so in order to reduce runtime time at dynamically loaded modules. All you have to do is to enable your chosen modules with "=static" suffix. If they depend on software_generic (most do), you need that as well. Examples: ./configure --enable-static-software-generic --enable-software-xlib=static --enable-software-xlib[=static] this enables the software x11 rendering engine that renders to X drawable targets using highly optimized software routines. there is no hardware assist here. this engine requires X11 to be installed to build (and run). This is a good generic engine that is fast and can run in X for good development and debugging purposes. --enable-software-xcb[=static] this enable the software xcb rendering engine. It allows the same features than the software xlib engine. It require the XCB and XCBImage libraries. For the test programs, XCBICCCM is also needed. It is not recommended to use this as it's experimental and will create problems with both ecore_evas and enlightenment itself. --enable-fb[=static] this is the software framebuffer driving engine. this uses the linux 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. this engine is specifically geared towards people writing minimalist display systems for embedded devices such as the ipaq, zaurus, etc. it also scales up to high-res desktop systems as well. --enable-directfb[=static] 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). as such this engine is in relative disrepair and is not maintained. use with great care. --enable-buffer[=static] this enables the memory buffer rendering engine. this engine renders to a region of memory that is considered to be a 32bit ARGB buffer of pixels, allowing the results of rendering to be directly read out or used again for other purposes. --enable-gl-x11[=static] this is the opengl engine. it is intended for an x11 target (via xlib) rather than framebuffer (even if you use EGL, the EGL flavor is expected to be an x11 one). it is a full opengl based rendering engine with all rendering implemented as a texture + triangle pipeline and more. it also supports opengl-es2.0 and is reliant on modern opengl2.0+ shader support. this engine also supports the native surface api for adopting pixmaps directly to textures for compositing. some environment variables that control the opengl engine are as follows: export EVAS_GL_INFO=1 set this environment variable to enable output of opengl information such as vendor, version, extensions, maximum texture size etc. unset the environment variable to make the output quiet again. export EVAS_GL_MEMINFO=1 set this environment variable to enable dumping of debug output whenever textures are allocated or freed, giving the number of textures of each time and how many kb worth of pixel data are allocated for the textures. unset it again to stop this dumping of information. export EVAS_GL_WIN_RESURF=1 set this environment variable to enable the gl engine to try and ddelete the window surface, if it can, when told to "dump resources" to save memory, and re-allocate it when needed (when rendering occurs). unset it to not have this behavior. export EVAS_GL_CUTOUT_MAX=N set this environment variable to the maximum number of rectangles applied to a rendering of a primitive that "cut away" parts of that primitive to render to avoid overdraw. default is 512. unset it to use defaults, otherwise set N to the max value desired or to -1 for "unlimited rectangles". export EVAS_GL_PIPES_MAX=N set the maximum number of parallel pending pipelines to N. the default number is 32 (except on tegra2 where is it 1). evas keeps 1 (or more) pipelines of gl draw commands in parallel at any time, to allow for merging of non-overlapping draw commands to avoid texture binding and context changes which allows for more streamlining of the draw arrays that are filled and passed to gl per frame. the more pipelines exist, the more chance evas has of merging draw commands that have the same modes, texture source etc., but the more overhead there is in finding a pipeline slot for the draw command to merge into, so there is a compromise here between spare cpu resources and gpu pipelining. unset this environment variable to let evas use it's default value. export EVAS_GL_ATLAS_ALLOC_SIZE=N set the size (width in pixels) of the evas texture atlas strips that are allocated. the default is 1024. unset this to let evas use its default. if this value is larger than the maximum texture size, then it is limited to that maximum size internally anyway. evas tries to store images together in "atlases". these are large single textures that contain multiple images within the same texture. to do this evas allocates a "wide strip" of pixels (that is a certain height) and then tries to fit all images loaded that need textures into an existing atlas texture before allocating a new one. evas tries a best fit policy to avoid too much wasting of texture memory. texture atlas textures are always allocated to be EVAS_GL_ATLAS_ALLOC_SIZE width, and a multiple of EVAS_GL_ATLAS_SLOT_SIZE pixels high (if possible - power of 2 limits are enforced if required). export EVAS_GL_ATLAS_ALLOC_ALPHA_SIZE=N this is exactly the same as EVAS_GL_ATLAS_ALLOC_SIZE, but for "alpha" textures (texture used for font glyph data). it works exactly the same way as for images, but per font glyph being put in an atlas slot. the default value for this is 4096. export EVAS_GL_ATLAS_MAX_W=N set this to limit the maximum image size (width) that will be allowed to go into a texture atlas. if an image exceeds this size, it gets allocated its own separate individual texture (this is to help minimize fragmentation). the default value for this is 512. if you set this environment variable it will be overridden by the value it is set to. the maximum value possible here is 512. you may set it to a smaller value. export EVAS_GL_ATLAS_MAX_H=N this is the same as EVAS_GL_ATLAS_MAX_W, but sets the maximum height of an image that is allowed into an atlas texture. export EVAS_GL_ATLAS_SLOT_SIZE=N this sets the height granularity for atlas strips. the default (and minimum) value is 16. this means texture atlas strips are always a multiple of 16 pixels high (16, 32, 48, 64, etc...). this allows you to change the granularity to another value to avoid having more textures allocated or try and consolidate allocations into fewer atlas strips etc. export EVAS_GL_NO_MAP_IMAGE_SEC=1 if this environment variable is set, it disabled support for the SEC map image extension (a zero copy direct-texture access extension that removes texture upload overhead). if you have problems with dynamic evas images, and this is detected by evas (see EVAS_GL_INFO above to find out if its detected), then setting this will allow it to be forcibly disabled. unset it to allow auto-detection to keep working. --enable-gl-flavor-gles this enables the opengl-es 2.0 flavor of opengl (as opposed to desktop opengl) when building evas's gl-x11 engine above. this will be needed if you are building evas for opengl-es 2.0 enabled embedded devices. evas works on several opengl-es 2.0 compliant gpu's and gains more testing and optimization regularly. it is also capable of texture-from-pixmap support in opengl-es like it is in desktop opengl. --enable-gles-variety-sgx this tells evas that you are building the gl-es engine for a shader-compiler "sgx style" opengl-es 2.0 implementation. this is where the shader compiler is provided at runtime and can accept the shader glsl source and work --enable-gles-variety-s3c6410 this tells evas that you have an s3c6410 style opengl-es implementation that has an offline shader compiler and that needs pre-compiled shader binaries (provided with evas). this has not been tested in quite a while as the drivers and environment for this system have gone missing --enable-software-gdi[=static] windows gdi based engine for evas --enable-software-ddraw[=static] windows direct-draw engine for evas --enable-direct3d[=static] evas direct3d engine (experimental) --enable-software-sdl[=static] this is the sdl engine that uses sdl library (http://www.libsdl.org). This library should work on many operating system. the buffer is software-rendered with evas's default software rendering core. --enable-gl-sdl[=static] opengl (and opengl-es2.0) rendering engine that uses sdl as the front end interface. see --enable-gl-x11 etc. for information. ------------------------------------------------------------------------------ CPU: --enable-cpu-c this enabled the c code. you can actually build the code without the c fallback code and only have the mmx routines for example. it is suggested to always use this regardless unless you have some definite size issues with the code. --enable-cpu-mmx this enables the mmx optimized routines. this works for pentium, 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 with all optimizations) in speed. --enable-cpu-sse this enables sse optimizations available 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 with all optimizations) in speed. --enable-cpu-sse3 this enables sse3 optimizations available in the Intel Pentium4, Core, Xeon, and Atom processors, as well as the AMD Athlon64, Phenom, Opteron, and Turion processors. --enable-cpu-neon This enables support for the Arm Cortex-A8 and later Neon register set. In particular it will use neon optimized code for rotations and drawing with the software engines. Open GL based renderers will gain nothing from the use of neon. To use neon with gcc-4.4 you need a post-2009 gcc and options something like: -mcpu=cortex-a8 -mfloat-abi=softfp -mfpu=neon Note that this slightly slows down non-optimized parts of evas but the gains in drawing are more then worth it overall. This is enabled by default, and turns off if a small test program is unable to compile. Performance is at least 50%, and in some real world tests approaches 100%. If you have any issues with neon, please report them to either the edevel mailing list or Brett Nash ------------------------------------------------------------------------------ IMAGE LOADERS: --enable-image-loader-png[=static] 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 uses less 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[=static] this enables the loader code that loads jpeg files using libjpeg. this loader also supports load options to pre-scale jpeg images down to provide much faster load times while also getting downscaling by 1/2, 1/4 or 1/8th the size in each dimension for "free". with an added patch to libjpeg7, it can also fast-decode a specific region of a jpeg file (without the patch it take a slow-path to do this). --enable-image-loader-edb[=static] edb image loader- can load images inside edb database files. not very useful as edb itself is no longer used by enlightenment. may be removed at some point, so unless you have a burning need for this, don't use edb files to store image data and rely on this loader --enable-image-loader-eet[=static] loads image data from eet files. eet files are the backing for edje storage, so this is needed for edje to work. it is very useful as it can load an image from anywhere in the eet archive by key value so eet files are like "zip" files where you can pack a whole lot of image and other data together and just pick out the pieces you need at runtime. requires the eet library. --enable-image-loader-gif[=static] gif image loader. gif is an obsolete format, but due to its longevity, sitll has lots of existing data around. NOTE: evas has no notion of time, thus animated gif file are not supported! --enable-image-loader-pmaps[=static] ppm/pnm/pgm image loader that can load the "pnm" style image format. not very common, but the files are simple raw RGB, greyscale image or bitmap data in binary or ascii format --enable-image-loader-svg[=static] this loader can load svg files via esvg (thus it is a dependency). This loader supports load options to set the dpi to decode the svg at etc. which can then be used to create scalable images that scale to any size without becoming blocky or blurry, if the source is an svg file. Esvg can be found here: http://code.google.com/p/enesim/ Install (in that order): enesim ender etch egueb --enable-image-loader-tiff[=static] this loader uses libtiff to load tiff image files --enable-image-loader-webp[=static] this loader uses libwebp to load webp image files --enable-image-loader-xpm[=static] this is an xpm format image loader. xpm format images are ascii files that look like c/c++ source code that contain images. these files are old-fashioned unix+x11 images you may encounter, but are inefficient for storage and decoding and have been superseded by png files in almost every way --enable-image-loader-bmp[=static] this enables the bmp image format loader. note that there seems to be a disagreement on 32bit bmp format images where alpha channels are concerned and you may run into issues with bmps generated by the gimp that have alpha channels. there is a problem where they don't seem to be spec-conformant. --enable-image-loader-tga[=static] this loader load tga format files. these files are very old-fashioned but found often in the 3d graphics world. --enable-image-loader-generic[=static] this loader will execute a given binary to decode an image and read the resulting image data via a shared memory segment, a mmaped file or stdout. it uses the command-line to pass the filename and any load parameters, and reads stdout from the loader binary to get metadata like width, height, alpha channel flag and location of pixel data. this loader has no dependencies as the binaries run are to be found in PREIFX/lib/evas/utils and are named evas_image_loader.EXTENSION where .EXTENSION is replaced by the filename extension to be decoded. if this binary does not exist then evas_image_loader (with no extension) is tried as a last fallback allowing it to handle "all cases". since this loader doesn't use any libraires, it relies on runtime dependencies and executables existing in the utils directory. note that images loaded via this mechanism will have slower load times due to the overhead of execution of another binary, but any instability in the loaders themselves will not affect the application using evas. this also means that licenses such as GPL for the binaries in this utils directory do not affect evas and the applications or libraries using evas. there is a separately released evas_generic_loaders package which builds stand-alone binaries that can do this style of decoding for for evas. this package currently handles XCF, PDF, PS, RAW, SVG (via librsvg) and video formats (via gstreamer). ------------------------------------------------------------------------------ FONT LOADERS: --enable-font-loader-eet[=static] this loader can load font (ttf) files directly from eet archives like the eet image loader. requires the eet library ------------------------------------------------------------------------------ CONVERTERS: --enable-convert-yuv this enables an optimized yuv (yv12 601 colorspace) to ARGB32 converter in evas --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 assumes the upper 4 bits fo each color primitive 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 displays 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 display and you should 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) converters for 16bpp. this is the standard display mode for things like pocketpc on the ipaq and the zaurus etc. this is an optimized part of the rendering pipeline to allow portrait display with a much lower overhead than doing it through X. --enable-convert-16-rgb-rot-180 same as --enable-convert-16-rgb-rot-270 but for 180 degrees --enable-convert-16-rgb-rot-90 same as --enable-convert-16-rgb-rot-270 but for 90 degrees --enable-convert-24-rgb-888 this converts evas's 32bit ARGB to 24bit RGB packed format for output if needed --enable-convert-24-bgr-888 this converts evas's 32bit ARGB to 24bit packed BGR format for output if needed --enable-convert-32-rgb-8888 32bit RGB output conversion support. byteswapping compared to evas's native colorspace --enable-convert-32-bgr-8888 conversion (reduces to a memory copy) from evas's native colorspace to the same color format. --enable-convert-32-rgb-rot-0 copies without rotation evas's native image format --enable-convert-32-rgb-rot-270 copies evas's native ARGB32 pixels but at a rotation of 270 degrees. --enable-convert-32-rgb-rot-180 same as --enable-convert-32-rgb-rot-270 but for 180 degrees --enable-convert-32-rgb-rot-90 same as --enable-convert-32-rgb-rot-270 but for 90 degrees --enable-convert-24-rgb-ezx a special colorspace handler for 18bit color packed into 24bit output (where only 6 bits per r, g and b byte are used). the only known platform that did this was the motorola esx based phones that used qtopia originally and have open ezx ports for them. --enable-convert-8-gry-1 enable 8bit gray to 1 bit black & white converter --enable-convert-8-gry-16 8bit grey to 16 level grayscale converter --enable-convert-8-grayscale-64 8bit grey to 64 level grayscale converter --enable-convert-8-rgb-332 enable converter from 32bit ARGB to 8bit color "332" colorspace (3bits red, 3 bits green, 2 bits blue) --enable-convert-8-rgb-666 enable converter from 32bit ARGB to 8bit color "216" "websafe" colorspace (6 values for red, 6 for green and 6 for blue - 6x6x6 being 216 colors). --enable-convert-8-rgb-232 same as convert-8-rgb-332 but 2 bits red, 3 green, 2 blue --enable-convert-8-rgb-222 same as convert-8-rgb-332 but 2 bits red, 2 green, 2 blue --enable-convert-8-rgb-221 same as convert-8-rgb-332 but 2 bits red, 2 green, 1 blue --enable-convert-8-rgb-121 same as convert-8-rgb-332 but 1 bit red, 2 green, 1 blue --enable-convert-8-rgb-111 same as convert-8-rgb-332 but 1 bit red, 1 green, 1 blue. this is the lowest sized colorspace supported for rgb (3bits, 8 color). ------------------------------------------------------------------------------ MISC: --enable-pthreads this enables pthread support in evas so multiple threads may run internally for parallel rendering, loading etc. --enable-async-events this provides the ability for evas to have an asynchronous event notification pipe to provide events when background threads are done with tasks, like pre-loading image files --enable-async-preload evas can load images (preload) in the background using a thread if you ask it to, and provide events when done. this goes hand-in-hand with --enable-pthreads and --enable-async-events. you really want all of these available. --enable-pipe-render **NOT ON BY DEFAULT DUE TO DUBIOUS IMPROVEMENTS** this enables a multiple-thread renderer that divides the rendering into N regions (1 per core) to speed up rendering in software when you have multiple cpu cores. --enable-fontconfig this enables fontconfig support for loading font files by using generic fontconfig font names and styles. you really should use this by default on any linux/unix platform for universal font support. --enable-fribidi this enables support for the fribidi library to have right to left and left to right font rendering so languges such as arabic, hebrew and other "RTL" langauges display properly. --enable-harfbuzz this enables support for the harfbuzz shaping library for complex shaping support in arabic, hindi and other similar languages. --enable-liblinebreak this enables support of complex line breaking rules using liblinebreak. --enable-evas-magic-debug this allows you to enable and disable evas's extra magic number checks. these allow better stability with runtime object magic "number" checks to make sure you are accessing a real object in memory of the right type, and will avoid doing "bad things" if they detect the wrong object type being passed in. if you are absolutely sure your system has no bugs in accessing objects of the wrong type with the wrong calls, you can gain some small performance by disabling this. ------------------------------------------------------------------------------ NOTES: For the arm optimizations you want to try: export CFLAGS="-O2 -march=armv5te -mcpu=arm1136jf-s -fomit-frame-pointer" To enable the async renderer compile with: --enable-async-render and also runtime set this environment variable: export EVAS_RENDER_MODE=non-blocking For compilation with MinGW, fnmatch.h is probably missing. That file can be found here: http://www.koders.com/c/fid2B518462CB1EED3D4E31E271DB83CD1582F6EEBE.aspx It should be installed in the mingw include directory.