new docs for evas....

SVN revision: 4827
This commit is contained in:
Carsten Haitzler 2001-06-18 02:47:02 +00:00
parent 9528534f0b
commit 05acf22076
14 changed files with 1 additions and 612 deletions

View File

@ -1,4 +1,2 @@
EXTRA_DIST = \
index.html \
logo.gif \
eg1.gif eg2.gif eg3.gif eg4.gif eg5.gif eg6.gif eg7.gif eg8.gif eg9.gif
evas.sdw evas.pdf

Binary file not shown.

Before

Width:  |  Height:  |  Size: 32 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 30 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 34 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 30 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 26 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 26 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 32 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 36 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 32 KiB

BIN
legacy/evas/doc/evas.pdf Normal file

Binary file not shown.

BIN
legacy/evas/doc/evas.sdw Normal file

Binary file not shown.

View File

@ -1,609 +0,0 @@
<html>
<head>
<title>Evas - Documentation</title>
</head>
<body
bgcolor=#ffffff
text=#000000
link=#9933aa
vlink=#aa66bb
alink=#ccaacc>
<center>
<font face=lucida,helvetica,arial size=4>
<img src=logo.gif width=512 height=160 alt=Evas><br>
<b>Documentation for programming using Evas</b><br>
By Carsten Haitzler<br>
Copyright (C) 2000<br>
<br>
From VA Linux Systems<br>
<br>
</center>
</font>
<hr>
<font face=lucida,helvetica,arial size=4>
<p>
<b>Introduction</b>
<p>
<blockquote>
<p>
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.
<p>
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.
<p>
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.
<p>
The best way to use Evas is as follows (simplistic pseudo-code):
<p>
<blockquote><font face=fixed color=#442244><pre>
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
</pre></font></blockquote>
<p>
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.
<p>
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.
<p>
</blockquote>
<p>
<b>Evas Principles</b>
<p>
<blockquote>
<p>
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.
<p>
<img src=eg1.gif width=512 height=384>
<p>
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.
<p>
<img src=eg2.gif width=512 height=384>
<p>
Notice that all the occupation rectangles are bounding the objects
themselves - even if those objects contain blank, unused space.
<p>
<img src=eg3.gif width=512 height=384>
<p>
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 <b>evas_move()</b> 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 <b>evas_render()</b>. 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
<p>
<img src=eg4.gif width=512 height=384>
<p>
When we call <b>evas_render()</b> 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.
<p>
<img src=eg8.gif width=512 height=384>
<p>
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.
<p>
<img src=eg9.gif width=512 height=384>
<p>
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.
<p>
<img src=eg5.gif width=512 height=384>
<p>
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.
<p>
<img src=eg6.gif width=512 height=384>
<p>
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).
<p>
<img src=eg7.gif width=512 height=384>
<p>
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.
<p>
</blockquote>
<p>
<b>API Reference</b>
<p>
<blockquote>
<p>
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.
<p>
<b>Basic Types</b>
<p>
<blockquote>
<p>
Here is a list of the basic types of objects Evas deals with and can
generate. It is small to keep things simple.
<p>
<blockquote><font face=fixed color=#442244><pre>
Evas
Evas_Gradient
Evas_Object
Evas_List
Evas_Callback_Type
Evas_Image_Format
Evas_Render_Method
</pre></font></blockquote>
<p>
<font color=#442244>Evas</font>:
<p>
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.
<p>
<font color=#442244>Evas_Gradient</font>:
<p>
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.
<p>
<font color=#442244>Evas_Object</font>:
<p>
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.
<p>
<font color=#442244>Evas_List</font>:
<p>
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.
<p>
<font color=#442244>Evas_Callback_Type</font>:
<p>
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 <b>CALLBACK_MOUSE_IN</b> (when the mouse enters the bounds of
this object), <b>CALLBACK_MOUSE_OUT</b> (when the mouse leaves the bounadry
of this object), <b>CALLBACK_MOUSE_DOWN</b> (when a mouse button is pressed
in this object), <b>CALLBACK_MOUSE_UP</b> (when a mouse button is raised in
this object), <b>CALLBACK_MOUSE_MOVE</b> (when the mouse mpoves around in
this object) and <b>CALLBACK_FREE</b> (when this object is actually freed so
the application can find free and data attached to the object if it needs to).
<p>
<font color=#442244>Evas_Image_Format</font>:
<p>
Currently this is not useful as you cannot create an image from application
provided data yet.
<p>
<font color=#442244>Evas_Render_Method</font>:
<p>
This is an enumerated type specifying the rendering subsystem to be used for
rendering.
<p>
<blockquote>
<p>
<b>RENDER_METHOD_ALPHA_SOFTWARE</b> 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).
<p>
<b>RENDER_METHOD_BASIC_HARDWARE</b> 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.
<p>
<b>RENDER_METHOD_3D_HARDWARE</b> 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.
<p>
<b>RENDER_METHOD_ALPHA_HARDWARE</b> 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).
<p>
<b>RENDER_METHOD_IMAGE</b> 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).
<p>
</blockquote>
<p>
</blockquote>
<p>
<b>Function Calls</b>
<p>
<blockquote>
<p>
<pre><font face=fixed color=#442244><pre>
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);
</font></pre>
<p>
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 <em>parent_window</em>, and be of size <em>w</em> x <em>h</em>
with a top-left corner at <em>x</em>, <em>y</em>. 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 <em>image_cache</em> is the size
of the image cache in bytes. The <em>font_cache</em> 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 <em>font_dir</em> is a directory on
the host system where truetype font files can be found for Evas to use for text
rendering. The <em>display</em> is the X display on which the Evas will
reside.
<p>
<pre><font face=fixed color=#442244><pre>
Window evas_get_window(Evas e);
</font></pre>
<p>
This is a simple function. It returns the X Window ID of the window the Evas
<em>e</em> 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.
<p>
<pre><font face=fixed color=#442244><pre>
Display *evas_get_display(Evas e);
</font></pre>
<p>
This function uses the current display pointer being used by the Evas
<em>e</em>. If no display is being used NULL is returned.
<p>
<pre><font face=fixed color=#442244><pre>
Visual *evas_get_visual(Evas e);
</font></pre>
<p>
This function returns the currently used X Visual for the Evas <em>e</em> -
if this is not used or set NULL is returned.
<p>
<pre><font face=fixed color=#442244><pre>
Colormap evas_get_colormap(Evas e);
</font></pre>
<p>
This returns the X Colormap being used for the Evas <em>e</em>, if there is a
Colormap being used.
<p>
<pre><font face=fixed color=#442244><pre>
int evas_get_colors(Evas e);
</font></pre>
<p>
This returns the maximum number of color entries the Evas <em>e</em> 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.
<p>
<pre><font face=fixed color=#442244><pre>
Imlib_Image evas_get_image(Evas e);
</font></pre>
<p>
Calling this function will return the Imlib_Image the Evas <em>e</em> is
rendering onto (if there is one), otherwise it returns NULL.
<p>
<pre><font face=fixed color=#442244><pre>
Evas_Render_Method evas_get_render_method(Evas e);
</font></pre>
<p>
This returns the current Rendering Method the Evas <em>e</em> is using. You may
not change this any time after Evas first renders this Evas.
<p>
<pre><font face=fixed color=#442244><pre>
Evas evas_new(void);
</font></pre>
<p>
This function creates a new Evas which is completely uninitialized. It
returns a handle to the Evas when complete.
<p>
<pre><font face=fixed color=#442244><pre>
void evas_free(Evas e);
</font></pre>
<p>
Calling this function frees the Evas <em>e</em>. After freeing it the Evas
handle <em>e</em> 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.
<p>
<pre><font face=fixed color=#442244><pre>
void evas_update_rect(Evas e, int x, int y, int w, int h);
</font></pre>
<p>
Call this function for the Evas <em>e</em> when the rectangle <em>x</em>
<p>
<pre><font face=fixed color=#442244><pre>
void evas_render(Evas e);
</font></pre>
<p>
<p>
<pre><font face=fixed color=#442244><pre>
</font></pre>
<p>
<p>
<pre><font face=fixed color=#442244><pre>
</font></pre>
<p>
<p>
<pre><font face=fixed color=#442244><pre>
</font></pre>
<p>
<p>
<pre><font face=fixed color=#442244><pre>
</font></pre>
<p>
<p>
<pre><font face=fixed color=#442244><pre>
</font></pre>
<p>
<p>
<pre><font face=fixed color=#442244><pre>
</font></pre>
<p>
<p>
<pre><font face=fixed color=#442244><pre>
</font></pre>
<p>
<p>
<pre><font face=fixed color=#442244><pre>
</font></pre>
<p>
<p>
<pre><font face=fixed color=#442244><pre>
</font></pre>
<p>
<p>
<pre><font face=fixed color=#442244><pre>
</font></pre>
<p>
<p>
<pre><font face=fixed color=#442244><pre>
</font></pre>
<p>
<p>
<pre><font face=fixed color=#442244><pre>
</font></pre>
<p>
<p>
<pre><font face=fixed color=#442244><pre>
</font></pre>
<p>
<p>
<pre><font face=fixed color=#442244><pre>
</font></pre>
<p>
<p>
<pre><font face=fixed color=#442244><pre>
</font></pre>
<p>
<p>
<pre><font face=fixed color=#442244><pre>
</font></pre>
<p>
<p>
<pre><font face=fixed color=#442244><pre>
</font></pre>
<p>
<p>
<pre><font face=fixed color=#442244><pre>
</font></pre>
<p>
<p>
<pre><font face=fixed color=#442244><pre>
</font></pre>
<p>
<p>
<pre><font face=fixed color=#442244><pre>
</font></pre>
<p>
<p>
<pre><font face=fixed color=#442244><pre>
</font></pre>
<p>
<p>
<pre><font face=fixed color=#442244><pre>
</font></pre>
<p>
<p>
<pre><font face=fixed color=#442244><pre>
</font></pre>
<p>
<p>
<pre><font face=fixed color=#442244><pre>
</font></pre>
<p>
<p>
<pre><font face=fixed color=#442244><pre>
</font></pre>
<p>
<p>
<pre><font face=fixed color=#442244><pre>
</font></pre>
<p>
<p>
<pre><font face=fixed color=#442244><pre>
</font></pre>
<p>
<p>
<pre><font face=fixed color=#442244><pre>
</font></pre>
<p>
<p>
<pre><font face=fixed color=#442244><pre>
</font></pre>
<p>
<p>
<pre><font face=fixed color=#442244><pre>
</font></pre>
<p>
<p>
<pre><font face=fixed color=#442244><pre>
</font></pre>
<p>
<p>
<pre><font face=fixed color=#442244><pre>
</font></pre>
<p>
<p>
<pre><font face=fixed color=#442244><pre>
</font></pre>
<p>
<p>
<pre><font face=fixed color=#442244><pre>
</font></pre>
<p>
<p>
</blockquote>
<p>
</blockquote>
</font>
</body>
</html>

Binary file not shown.

Before

Width:  |  Height:  |  Size: 17 KiB