Mercurial > MadButterfly

annotate dox/define_backend.h @ 1020:f25b8ad338b4 refine_backend_if

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Fix error on error checking for mb_timer_man_new()
author Thinker K.F. Li <thinker@codemud.net>
date Mon, 22 Nov 2010 13:57:59 +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 */