Mercurial > MadButterfly

comparison dox/define_backend.h @ 1067:7b4e80ab671a openvg

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
merge from default branch
author Thinker K.F. Li <thinker@codemud.net>
date Wed, 01 Dec 2010 12:25:56 +0800
parents 5dedeedf0408
children
comparison
equal deleted inserted replaced
630:bd18951b51d5 1067:7b4e80ab671a
4 * MadBufferfly available. A backend should provide resources 4 * MadBufferfly available. A backend should provide resources
5 * needed by MadButterfly, for example, to provide a surface 5 * needed by MadButterfly, for example, to provide a surface
6 * that will show everything drawing on it. It also translate and 6 * that will show everything drawing on it. It also translate and
7 * relay input events, mouse or keyboard, to MadButterfly. 7 * relay input events, mouse or keyboard, to MadButterfly.
8 * The tasks that a backend should do are listed following, 8 * The tasks that a backend should do are listed following,
9 * - to prepare a backend surface, 9 * - tranlsate and relay mouse events to MadButterfly.
10 * - to prepare a front surface, 10 * - to provide
11 * - to translate and relay input events to MadButterfly, 11 * - *_MB_new()/*_MB_free function to create and free a runtime.
12 * - to handle a timer, and relay timeout events to MadButterfly. 12 * - prepare a backend surface,
13 * - prepare a front surface,
14 * - *_MB_kbevents() to return a subject, for keyboard
15 * events, associated with a runtime.
16 * - translate and relay keyboard events to MadButterfly,
17 * - *_MB_tman() to return a timer manager associated with
18 * a runtime.
19 * - to handle a timer, and relay timeout events to MadButterfly.
20 * - *_MB_ob_factory() to return an observer factory.
21 * - *_MB_img_ldr() to return an image loader.
13 * 22 *
14 * The output device surface for X Window is a surface return by 23 * \section backend_mb_new_n_free *_MB_new()/*_MB_free()
15 * cairo_xlib_surface_create(). MadButterfly will copy everything
16 * from front surface to backend surface to show graphy to user.
17 * The copying is to avoid user find slowly redrawing. The latency
18 * between X client and server can be large. For this situation,
19 * we need a font surface as a buffer drawing, and copy image from
20 * front surface to backend surface after completion of a series
21 * of drawing. A front surface can be an image surface for this
22 * situation.
23 * 24 *
24 * The input events of X Window should be translated to raw events of 25 * MadButterfly supposes that application programmers may create more
25 * MadButterfly and sent them to rdman through notify_coord_or_shape() 26 * than one instance of MadButterfly to draw mutliple windows for an
26 * function. 27 * application. So, we need you, backend developer, to provide a
28 * *_MB_new()/*_MB_free() to create/free an instance respective.
29 *
30 * *_MB_new() should return an *_MB_runtime_t object to keep states of
31 * an instance. The definition of *_MB_runtime_t is up to backend
32 * developers.
33 *
34 * For each *_MB_runtime_t, backend should create a redraw manager,
35 * a.k.a rdman, by calling malloc() and redraw_man_init(). For each
36 * rdman, you should give it one or two surfaces. Rdman draws shapes
37 * on first one, called 'cr' (should be changed), as an off-screen
38 * buffer and copy it to 2nd one, called 'backend' surface, as an
39 * on-screen buffer. For X, the 'backend' should be a window surface.
40 * The reason of two surfaces are to prevent user from seeing
41 * intermediate result of drawing procedure. You can also pass a NULL
42 * pointer for 2nd surface if you dont care intermediate result, HW
43 * accelerator is fast enough, or with HW dobule buffering.
44 *
45 * \section backend_kbevents Keyboard Events
46 *
47 * *_MB_kbevents() returns a subject (\see
48 * http://en.wikipedia.org/wiki/Observer_pattern). Applications want
49 * to receive keyboard events would register an observer on this
50 * subject. A backend should translate keyboard events for
51 * MadButterfly, and notify observers of this subject.
52 * Subject-observer had implemented by MadBuffery.
53 *
54 * \section backend_timer Timer
55 *
56 * *_MB_tman() should return a timer manager, with type of mb_tman_t.
57 * When an application want to get notified at some time later, it
58 * would register a callback with the mb_tman_t. A backend should
59 * call mb_tman_handle_timeout() at proper time. You can call
60 * mb_tman_next_timeout() to get the time to call
61 * mb_tman_handle_timeout() for next timeout. For nodejs or other
62 * binding that has their-owned timer, you can skip *_MB_tman(). But,
63 * C code need this one.
64 *
65 * \section backend_obfactory Observer Factory
66 *
67 * *_MB_ob_factory() returns an observer factory, ob_factory_t. It is
68 * reponsible for creation of observers. Applications call observer
69 * to allocate and free observers and subjects. ob_factory_t is
70 * defined in mb_observer.h, there are 5 function pointers in it. You
71 * can use functions of default implementation instead of new ones.
72 *
73 * \section backend_img_ldr Image Loader
74 *
75 * *_MB_img_ldr() returns an image loader, mb_img_ldr_t. A backend
76 * developer can use the default implementation. He can also
77 * implement a new one, but it should implement the interface defined
78 * by mb_img_ldr_t and mb_img_data_t.
79 *
80 * \section backend_mouse_events Mouse Events
81 *
82 * A backend should also translate and relay mouse events to
83 * MadButterfly. The mouse events should be dispatched by notifing
84 * observers of the subject of a coord or shape of an rdman. The
85 * backend developers can check handle_single_x_event() in X_supp.c
86 * for how to dispatch mouse events.
27 * 87 *
28 * \see X_supp.c 88 * \see X_supp.c
29 */ 89 */