-Documentation for programming using Evas
-By Carsten Haitzler
-Copyright (C) 2000
-
-From VA Linux Systems
-
-
-Introduction -
-
---Evas is a canvas library, designed to work with the X Window System. It is -designed to be able to take advantage of any graphics hardware or CPU -processing power you may have, or to adjust for the lack of it. It has a -simplistic API to access the features of a canvas to aid in making -development using Evas easy. -
-First it is necessary to explain what a canvas is and how in principle it -works. For those used to doing the drawing themselves, it is a new way of -looking at the problem of drawing displays that contain lots of information -an application may have to keep track of. This may be in the form of -primitives (lines, circles, rectangles, polygons and text) or may be a -mixture of these and more complex objects such as gradients, images etc. An -application normally needs to hold all this data and when required, redraw -the data to a window or pixmap if the data changes, or the window contents -become damaged and need a redraw to restore them. To do this optimally the -application would also need to figure out what exactly changed, which parts -of the window or pixmap this data mapped to and then order the drawing so -all objects are drawn in the right order, and only the part of the window -that needs redrawing is drawn to to save excess processing. For a large -range of objects and data this becomes a fairly involved problem all on it's -own. Thus came the evolution of the canvas. -
-Some of the better known canvas systems around are the Tk Canvas and the -GNOME canvas. In principle a canvas works on an object level. Like windows -in X11, you create objects, move them, resize them show them, hide them, -change their properties etc. The canvas figures out what objects changed and -how only when it comes to it's draw cycle - not every time you do something. -This means moving, resizing and changing object properties is a very fast -and inexpensive operation since only attribute values change, rather than -any drawing being done, unlike when you move and resize windows in X11 which -happens instantly, not later. This means higher efficiency for the -application's rendering, as long as evas render calls are only called when -the application has hit an idle state (nothing left in it's queue of things -to do for the moment). This also means object maintinence is now left up to -the canvas - the application only needs to keep a handle to that object -around so it can be uniquely identified. -
-The best way to use Evas is as follows (simplistic pseudo-code): -
-
--Initialise program -... -Create canvas -Add objects to canvas (fill in with some content) -... -Infinite loop ... - while input events are pending ... - if event is for evas window then pass onto evas - ... (no more input events in queue awaiting processing) - modify, add or delete objects in evas to reflect new state - call evas render function -... continue program infinite loop --In a naively written program an event loop may have many re-renderings and -re-drawings going on as things are modified, otherwise the application needs -to retain state like evas does and then handle draws in idle time too, which -means applications need to do the work Evas does themselves, as well as the -optimizations already in place in Evas. -
-The major advantages arise out of the fact that Evas does not only handle -the logic of such object management and rendering for you, and optimize it, -it also provides an abstraction layer that allows evas to render not just -solid objects, but semi-transparent objects and images that can be -alpha-blended, anti-aliased text and much more. It not only does these and -does them fast (using Imlib2 as the core rendering engine to do this), but -is able to instantly take advantage of hardware acceleration (for example -OpenGL) quietly for you to blend and scale images, speeding up rendering -many times over, without you having to know a single line of OpenGL. Evas's -Software routines alone are many many many times faster than Mesa's software -OpenGL rendering, as Imlib2's code is purpose written for 2D operations with -Assembly optimizations for the core routines. -
-
-Evas Principles -
-
---Let's demonstrate how Evas optimizes updates when you manipulate objects. -Let's take an example Evas for demonstration purposes that has several -objects in it. -
-
-
-This simple Evas has 4 image objects. All objects occupy a rectangular area -in the Evas. This is the region events for the object are accepted, and is -also the region that gets updated when that object changes. The occupied -areas of the objects would look something as follows. -
-
-
-Notice that all the occupation rectangles are bounding the objects -themselves - even if those objects contain blank, unused space. -
-
-
-Now let's say we want to move the arrow object a bit down and to the right -as shown here. We would simply call the evas_move() function call with -the new co-ordinates of the top-left origin of the object. Evas will simply -record the new co-ordinates and mark the object as having a possible update. -As long as you are busy modifying the Evas, no rendering is actually done - -moving and resizing objects etc. is almost for free. Rendering only occurs -when you call evas_render(). Let us say for this example that we make -no further changes to the evas and now our program hits an idle state. We -now need to render -
-
-
-When we call evas_render() Evas goes through the object list looking -at objects marked with possible updates. If they do it inspects their state -the last time it rendered them and now - if the states do not match, Evas adds -a rectangle to it's list of rectangles in the Evas to be updated. In the case -of a move or resize, a rectangle for the previous and current locations for -that object are added as above. -
-
-
-Now our 2 rectangles have been inserted Evas will want to keep updates -within a tiled grid of 32x32 pixel blocks. The 32x32 mesh is shown above. -Notice the update rectangles do not align perfectly with the grid. -
-
-
-Now evas will figure out a minimum number of rectangles that would align to -this tile grid and cover the area the update rectangles cover, as shown -above. The Green, Yellow and Red Rectangles cover the update regions and -align to the grid. -
-
-
-Above you can see how the updated rectangles do not overlap each other but are -a superset of the update regions. Evas has already now optimized drawing to -only re-render these rectangles. -
-
-
-Evas will now go and re-render the contents of each of these rectangles one -at a time in the render function (unless the back-end renderer does not -support this as is the case with the Hardware 3D accelerated driver since -OpenGL does not support partial buffer swaps). -
-
-
-And now we have the result. A newly rendered Evas that only rendered what -changed and shows the state of the Evas as it currently stands. As you can -imagine if lots of objects overlap, small and large, and are changing every -now and again, Evas can do a pretty good job of keeping re-draws down to a -minimum sane number. Rendering should only be called once you have made your -changes and want to see them appear in the Evas. This will ensure you do not -render more often than you need to. -
-
-API Reference -
-
-- - - diff --git a/legacy/evas/doc/logo.gif b/legacy/evas/doc/logo.gif deleted file mode 100644 index 2c177424b4..0000000000 Binary files a/legacy/evas/doc/logo.gif and /dev/null differ-Before you embark on any programming using Evas, it is highly recommended -that you read this API reference to become familiar with the interface -provided to Evas before first using it. The documentation for each function -call in Evas not only documents it but also gives insight into subtle side -effects it may have, and other aspects of its use that are not necessarily -completely part of that call's specific use. -
-Basic Types -
-
---Here is a list of the basic types of objects Evas deals with and can -generate. It is small to keep things simple. -
-
--Evas -Evas_Gradient -Evas_Object -Evas_List -Evas_Callback_Type -Evas_Image_Format -Evas_Render_Method --Evas: -
-This is the basic type of an Evas itself. When you create a new evas this -type will be returned (not a pointer to it - the Evas type itself. It is -intended to be completely opaque to the application and may change its nature -over time - it may be a void pointer now and tomorrow a hashed ID or -anything else). All functions dealing with Evases and their contents will -require you use this handle to denote what Evas you are talking about. -
-Evas_Gradient: -
-This is the basic type use to build a gradient object from or modify its -colors. You need to create a new one of these before you can create any -useful gradient object. You add colors to the gradient, each one (after the -first color added) are added a certain ``distance'' from the previous color -which will determine relative distances between colors in the gradient. The -larger the distance number, the more of the total gradient length the -transition between the previous color and the one being added will take. -Once you hve filled the gradient with colors, create a gradient object, or -multiple gradient objects and set the gradient to those gradient objects. -When you are done and don't need that gradient anymore, simply free the -gradient. If you wish to change the colors or distances between them in a -gradient object simply build a new gradient, set it to the object then free -the gradient you created. -
-Evas_Object: -
-This is the fundamental building block that makes the contents of an Evas -have meaning. Without any objects in an Evas it will not draw anything, or -draw usless garbage where no objects exist. Whenever you create an object -you will get this type of handle back. If you wish to modify an object's -geometry, show, hide, change its properties or delete it you will need to -use this as the handle to addess it by. -
-Evas_List: -
-This is the only non-opaque data type. It is for conevenience of Evas, and -for the application to use too. This type is a doubly-linked list of data. -You may traverse the list using loops and using the next and prev members of -this structure. Do not modify these though as this could mean memory leaks -and losing parts of the list. If prev is NULL, you are at the start of the -list and if next is NULL you are at the end. The data member points to -whatever data was inserted at that place in the list. You may read this and -cast it to whatever makes sense in the situation. If Evas returns an -Evas_List of things the data member will be of the type specified by the -function. You may use Evas_List's yourself for anything you find them useful -for. -
-Evas_Callback_Type: -
-This is an enumerated type to specify what kind of event would trigger a -callback to be called when attaching a callback to an object. Legal values -for this are CALLBACK_MOUSE_IN (when the mouse enters the bounds of -this object), CALLBACK_MOUSE_OUT (when the mouse leaves the bounadry -of this object), CALLBACK_MOUSE_DOWN (when a mouse button is pressed -in this object), CALLBACK_MOUSE_UP (when a mouse button is raised in -this object), CALLBACK_MOUSE_MOVE (when the mouse mpoves around in -this object) and CALLBACK_FREE (when this object is actually freed so -the application can find free and data attached to the object if it needs to). -
-Evas_Image_Format: -
-Currently this is not useful as you cannot create an image from application -provided data yet. -
-Evas_Render_Method: -
-This is an enumerated type specifying the rendering subsystem to be used for -rendering. -
-
---RENDER_METHOD_ALPHA_SOFTWARE when specified requests that henceforth -the evas use optimized software rendering for display. This is the default. -It uses Imlib2 to do this rendering. This form of rendering, if on a local X -display is almost compleyely bound by CPU speed, and toa slightly lesser -extent memory bandwidth and graphics bus bandwidth. Not much else really -affects the speed (graphics card included). -
-RENDER_METHOD_BASIC_HARDWARE when used, use basic X primities to do -rendering. This means lines, rectangles, pixmaps etc. It is necessary to -create some of the building blocks of these primitives via Imlib2 when they -are first needed, but thereafter the windowing system, X, is responsible for -pasting pixmaps, drawing rectangles, lines etc. The speed of this may vary -depending how much new data needs to be generated as pixmaps, how much can -be recycled, the speed of your CPU, the amount of hardware acceleration your -X Server is able to use to perform these operations, the speed of the -graphics hardware and so on. This rendering method is probably very good for -situations where the data is readily recyclable (i.e. images don't change size -much and there are not many gradients), and the host machine has a slow cpu, -but a reasonable graphics card and reasonably well accelerated X Server. You -lose alpha blending when using this rendering engine, as if smooth scaling -is turned on it will apporoximate using dithering, so quality will -definitely suffer, but in situations it may bring speed increases. -
-RENDER_METHOD_3D_HARDWARE is a rendering back end that uses OpenGL to -perform the dirty work of blending, scaling, drawing lines, rectangles, text -etc. when used. If you have an X Server that supports OpenGL, accelerates -it well through the graphics hardware, this rendering method could give you -massive speed increases, even over software, as well as retain quality of -display. With good graphics cards and good acceleration this could mean an -easy 10-100 fold speedup of rendering. This will depend on the combination -of X Server and graphics hardware. If you only have software OpenGL -available be prepared for a shock. Unlike what may almost be logical, -software OpenGL is not like Imlib2 software rendering. It is many many many -times slower. Imlib2 software rendering should easily be 50-100 times faster. -If you are experiencing massively slow displays in Evas when using this -rendering mode, it is because your OpenGL support is software only. If when -Evas was compiled, it could not find OpenGL on the system it was building -on, OpenGL support will be disabled and silently fall back to software -Imlib2 rendering. If the X Server Evas is displaying on does not support OpenGL -it will also fall back silently to Imlib2 software rendering. Unlike the -Imlib2 software and X11 primitive engine rendering this subsystem can only -render to a window, and not to a pixmap. -
-RENDER_METHOD_ALPHA_HARDWARE is currently unimplimented - it is -intended for use when an actual alpha blending/rendering extension exists in -X (it is being worked on at the current time). -
-RENDER_METHOD_IMAGE is used for rendering to a virtual Imlib2 image. -This is useful for when your display of an Evas is destined for something -other than a window - for example being able to render a canvas and save it -to disk as a jpeg or png file, or to be able to take this Image and process -it later. This rendering method is about half the speed of Imlib2 software -rendering as some optimizations cannot be performed (due to the nature of it -being able to render a canvas on top of already existing graphic data in the -destination image). -
-
-
-Function Calls -
-
---
--Evas evas_new_all(Display *display, - Window parent_window, - int x, - int y, - int w, - int h, - Evas_Render_Method render_method, - int colors, - int font_cache, - int image_cache, - char *font_dir); --This function creates a new Evas, a window for it, initialises it's -rendering mode, font and image cache sizes, font path, the number of colors -it will use and on success returns a valid Evas handle. The Evas is -completely empty to begin and the window is not mapped. You do not need to -destroy the window yourself when you free this Evas as Evas will destroy it -for you. If it fails it will return NULL. The window it creates will be a -child of the parent_window, and be of size w x h -with a top-left corner at x, y. It will have a border width -of 0. It is suggested you set an event mask on this window after creation and -check for expose events as well as mouse events, handing them back to Evas -with its event and update handling functions to ensure the evas gets redrawn -and handles events properly. If you resize this window you need to tell evas -of the resize too by setting the output size and where needed adjusting the -output viewport. You cannot change the rendering method or number of colors -allocated once the evas has been created. The image_cache is the size -of the image cache in bytes. The font_cache is also in bytes. -Remember that Evas totally relies on the caches for all rendering - all -images and fonts are loaded from cache every time they need rendering and -freed afterwards. If your cache is small, perfromance will be horrid - -regardless of rendering method. If memory is low or you know you do not need -to render again for a while you can flush the caches. You can adjust cache -size any time you like, growing it or shrinking it as available -memory varies for best perfromance. The font_dir is a directory on -the host system where truetype font files can be found for Evas to use for text -rendering. The display is the X display on which the Evas will -reside. -
-
--Window evas_get_window(Evas e); --This is a simple function. It returns the X Window ID of the window the Evas -e is using. If you created the evas with evas_new_all() the Window ID -returned will be the window created by Evas. If Evas created the window you -should not destroy it yourself. It will be destroyed when the Evas is freed. -You may map, unmap set properties on this window, resize, reparent, move -etc. as you please. -
-
--Display *evas_get_display(Evas e); --This function uses the current display pointer being used by the Evas -e. If no display is being used NULL is returned. -
-
--Visual *evas_get_visual(Evas e); --This function returns the currently used X Visual for the Evas e - -if this is not used or set NULL is returned. -
-
--Colormap evas_get_colormap(Evas e); --This returns the X Colormap being used for the Evas e, if there is a -Colormap being used. -
-
--int evas_get_colors(Evas e); --This returns the maximum number of color entries the Evas e can -allocate when on a pseudo-color display (i.e. 8 bit color). Evas may allocate -fewer colors than this if fewer are available on the display. -
-
--Imlib_Image evas_get_image(Evas e); --Calling this function will return the Imlib_Image the Evas e is -rendering onto (if there is one), otherwise it returns NULL. -
-
--Evas_Render_Method evas_get_render_method(Evas e); --This returns the current Rendering Method the Evas e is using. You may -not change this any time after Evas first renders this Evas. -
-
--Evas evas_new(void); --This function creates a new Evas which is completely uninitialized. It -returns a handle to the Evas when complete. -
-
--void evas_free(Evas e); --Calling this function frees the Evas e. After freeing it the Evas -handle e is no longer valid and should not be used. If Evas created -a window for you for this Evas it will be destroyed at this time. -
-
--void evas_update_rect(Evas e, int x, int y, int w, int h); --Call this function for the Evas e when the rectangle x -
-
--void evas_render(Evas e); --
-
---
-
---
-
---
-
---
-
---
-
---
-
---
-
---
-
---
-
---
-
---
-
---
-
---
-
---
-
---
-
---
-
---
-
---
-
---
-
---
-
---
-
---
-
---
-
---
-
---
-
---
-
---
-
---
-
---
-
---
-
---
-
---
-
---
-
---
-
-