Mercurial > MadButterfly

annotate dox/define_backend.h @ 1515:e963793c9793

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Show component name at status bar of FSM editor window
author Thinker K.F. Li <thinker@codemud.net>
date Wed, 11 May 2011 00:11:24 +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 */