Mercurial > MadButterfly
annotate dox/define_backend.h @ 1233:7f17a7e70d82
Integrate MBScene.entrGroup()
author | Thinker K.F. Li <thinker@codemud.net> |
---|---|
date | Mon, 10 Jan 2011 11:45:12 +0800 |
parents | 5dedeedf0408 |
children |
rev | line source |
---|---|
443
1f900a67bd38
Doc How to Define a Backend
Thinker K.F. Li <thinker@branda.to>
parents:
diff
changeset
|
1 /*! \page backend How to Define a Backend |
1f900a67bd38
Doc How to Define a Backend
Thinker K.F. Li <thinker@branda.to>
parents:
diff
changeset
|
2 * |
1f900a67bd38
Doc How to Define a Backend
Thinker K.F. Li <thinker@branda.to>
parents:
diff
changeset
|
3 * A backend is factory to initialize environment to make |
1f900a67bd38
Doc How to Define a Backend
Thinker K.F. Li <thinker@branda.to>
parents:
diff
changeset
|
4 * MadBufferfly available. A backend should provide resources |
1f900a67bd38
Doc How to Define a Backend
Thinker K.F. Li <thinker@branda.to>
parents:
diff
changeset
|
5 * needed by MadButterfly, for example, to provide a surface |
1f900a67bd38
Doc How to Define a Backend
Thinker K.F. Li <thinker@branda.to>
parents:
diff
changeset
|
6 * that will show everything drawing on it. It also translate and |
1f900a67bd38
Doc How to Define a Backend
Thinker K.F. Li <thinker@branda.to>
parents:
diff
changeset
|
7 * relay input events, mouse or keyboard, to MadButterfly. |
1f900a67bd38
Doc How to Define a Backend
Thinker K.F. Li <thinker@branda.to>
parents:
diff
changeset
|
8 * The tasks that a backend should do are listed following, |
934
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
9 * - tranlsate and relay mouse events to MadButterfly. |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
10 * - to provide |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
11 * - *_MB_new()/*_MB_free function to create and free a runtime. |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
12 * - prepare a backend surface, |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
13 * - prepare a front surface, |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
14 * - *_MB_kbevents() to return a subject, for keyboard |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
15 * events, associated with a runtime. |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
16 * - translate and relay keyboard events to MadButterfly, |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
17 * - *_MB_tman() to return a timer manager associated with |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
18 * a runtime. |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
19 * - to handle a timer, and relay timeout events to MadButterfly. |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
20 * - *_MB_ob_factory() to return an observer factory. |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
21 * - *_MB_img_ldr() to return an image loader. |
443
1f900a67bd38
Doc How to Define a Backend
Thinker K.F. Li <thinker@branda.to>
parents:
diff
changeset
|
22 * |
934
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
23 * \section backend_mb_new_n_free *_MB_new()/*_MB_free() |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
24 * |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
25 * MadButterfly supposes that application programmers may create more |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
26 * than one instance of MadButterfly to draw mutliple windows for an |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
27 * application. So, we need you, backend developer, to provide a |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
28 * *_MB_new()/*_MB_free() to create/free an instance respective. |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
29 * |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
30 * *_MB_new() should return an *_MB_runtime_t object to keep states of |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
31 * an instance. The definition of *_MB_runtime_t is up to backend |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
32 * developers. |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
33 * |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
34 * For each *_MB_runtime_t, backend should create a redraw manager, |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
35 * a.k.a rdman, by calling malloc() and redraw_man_init(). For each |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
36 * rdman, you should give it one or two surfaces. Rdman draws shapes |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
37 * on first one, called 'cr' (should be changed), as an off-screen |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
38 * buffer and copy it to 2nd one, called 'backend' surface, as an |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
39 * on-screen buffer. For X, the 'backend' should be a window surface. |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
40 * The reason of two surfaces are to prevent user from seeing |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
41 * intermediate result of drawing procedure. You can also pass a NULL |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
42 * pointer for 2nd surface if you dont care intermediate result, HW |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
43 * accelerator is fast enough, or with HW dobule buffering. |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
44 * |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
45 * \section backend_kbevents Keyboard Events |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
46 * |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
47 * *_MB_kbevents() returns a subject (\see |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
48 * http://en.wikipedia.org/wiki/Observer_pattern). Applications want |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
49 * to receive keyboard events would register an observer on this |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
50 * subject. A backend should translate keyboard events for |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
51 * MadButterfly, and notify observers of this subject. |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
52 * Subject-observer had implemented by MadBuffery. |
443
1f900a67bd38
Doc How to Define a Backend
Thinker K.F. Li <thinker@branda.to>
parents:
diff
changeset
|
53 * |
934
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
54 * \section backend_timer Timer |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
55 * |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
56 * *_MB_tman() should return a timer manager, with type of mb_tman_t. |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
57 * When an application want to get notified at some time later, it |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
58 * would register a callback with the mb_tman_t. A backend should |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
59 * call mb_tman_handle_timeout() at proper time. You can call |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
60 * mb_tman_next_timeout() to get the time to call |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
61 * mb_tman_handle_timeout() for next timeout. For nodejs or other |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
62 * binding that has their-owned timer, you can skip *_MB_tman(). But, |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
63 * C code need this one. |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
64 * |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
65 * \section backend_obfactory Observer Factory |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
66 * |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
67 * *_MB_ob_factory() returns an observer factory, ob_factory_t. It is |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
68 * reponsible for creation of observers. Applications call observer |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
69 * to allocate and free observers and subjects. ob_factory_t is |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
70 * defined in mb_observer.h, there are 5 function pointers in it. You |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
71 * can use functions of default implementation instead of new ones. |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
72 * |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
73 * \section backend_img_ldr Image Loader |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
74 * |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
75 * *_MB_img_ldr() returns an image loader, mb_img_ldr_t. A backend |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
76 * developer can use the default implementation. He can also |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
77 * implement a new one, but it should implement the interface defined |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
78 * by mb_img_ldr_t and mb_img_data_t. |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
79 * |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
80 * \section backend_mouse_events Mouse Events |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
81 * |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
82 * A backend should also translate and relay mouse events to |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
83 * MadButterfly. The mouse events should be dispatched by notifing |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
84 * observers of the subject of a coord or shape of an rdman. The |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
85 * backend developers can check handle_single_x_event() in X_supp.c |
5dedeedf0408
Change page of "How to Defaine a Backend"
Thinker K.F. Li <thinker@codemud.net>
parents:
443
diff
changeset
|
86 * for how to dispatch mouse events. |
443
1f900a67bd38
Doc How to Define a Backend
Thinker K.F. Li <thinker@branda.to>
parents:
diff
changeset
|
87 * |
1f900a67bd38
Doc How to Define a Backend
Thinker K.F. Li <thinker@branda.to>
parents:
diff
changeset
|
88 * \see X_supp.c |
1f900a67bd38
Doc How to Define a Backend
Thinker K.F. Li <thinker@branda.to>
parents:
diff
changeset
|
89 */ |