1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
|
# The OSMORA Display Architecture (ODA)
Written by Ian M. Moffett
## Introduction
The OSMORA Display Architecture (ODA) is a protocol describing how
a compositor should create and manage graphical windows. A graphical
session in Hyra consists of a compositor, window management system and
management of user input.
There are many existing display architectures out there. Take for instace, the X11
protocol. X11 for example, has the concept of an "X server" in which window managers
or certain graphical programs would connect to as a means of performing interprocess
communication (IPC). The idea is that X will service graphics related requests from
the window manager or compositor.
While this works just fine, the highly centralized nature of X11 or similar protocols
may complicate the flexibility of the graphics stack. On the other hand with ODA, a
compositor links with the ODA library and becomes the server for window managers running
on the system. The idea of ODA is to minimize complexity while preserving flexibility.
Additionally, the compositor should provide its own API for use by window management
software.
## Scope
This document serves to describe common OSMORA Display Architecture (ODA) concepts
as well as providing basic example C sources showcasing how compositors and window
managers may interface with the described APIs for various needs.
## Terminology
### OSMORA Display Architecture (ODA):
OSMORA protocol defining common interfaces for C2W and
W2C interactions.
### Compositor to window (C2W):
Describes the direction of communication originating from
a compositor and directed towards a specific window:
``COMPOSITOR -> WINDOW``
### Window to compositor (W2C):
Describes the direction of communication originating from
a specific window to a compositor running on the system:
``WINDOW -> COMPOSITOR``
## Architecture
```
+-------------+
| LIBGFX |
+-------------+
^
| linked with libgfx
V
+-------------+
| COMPOSITOR |
+-------------+ <---+ signal
| | | |
| | | | c2w: <winop: e.g., close>
| | | | w2c: <winop to accept: e.g., close>
WIN WIN WIN <---+
```
### C2W signal flow:
```
-- CLOSE SIGNAL EXAMPLE --
WINDOW RECEIVES CLOSE SIGNAL
|
ECHO BACK TO COMPOSITOR
|
YES ---+--- NO
| |
| V
| nothing happens
|
V
window is destroyed by compositor
```
## Libgfx
The Hyra userspace includes ``libgfx`` which is a low-level graphics library aimed
to facilitate drawing on the screen and performing various graphical operations while
decoupling from the concept of compositors, windows and the ODA as a whole. In other words,
libgfx has no knowledge of anything outside of the framebuffer and itself.
The following is an example of how one may draw a yellow square at
x/y (30,0):
```c
#include <libgfx/gfx.h> /* Common routines/defs */
#include <libgfx/draw.h> /* Drawing related routines/defs */
int
main(void)
{
struct gfx_ctx ctx;
struct gfx_shape sh = GFX_SHAPE_DEFAULT;
int error;
/* Set the x/y and color */
sh.x = 30;
sh.y = 0;
sh.color = GFX_YELLOW
error = gfx_init(&ctx);
if (error < 0) {
printf("gfx_init returned %d\n", error);
return error;
}
/* Draw the square and cleanup */
gfx_draw_shape(&ctx, &sh);
gfx_cleanup(&ctx);
return 0;
}
```
## Liboda
The Hyra userspace includes the ``liboda`` library which includes various
interfaces conforming to the OSMORA Display Architecture (ODA).
### Linking a compositor with liboda
In order for an ODA compliant compositor to reference library
symbols for ``liboda``, it should use the following linker flags:
``... -loda -logfx``
### ODA Session
For the ODA library to keep track of state, it relies on an ``oda_state``
structure defined in ``liboda/oda.h``. Additionally, in order for any ODA
library calls to be made, the compositor must initialize the library with
``oda_init()`` like in the following example:
```
#include <liboda/oda.h>
struct oda_state state;
int error;
/* Returns 0 on success */
error = oda_init(&state);
...
```
Upon failure of ``oda_init()`` a negative POSIX errno value
is returned (see ``sys/errno.h``).
### Using liboda to request windows
A compositor may request windows from the ODA by using
``oda_reqwin()`` like in the following example:
```
#include <liboda/oda.h>
...
struct oda_wattr wattr;
struct oda_state state;
...
wattr.session = &state;
wattr.parent = NULL;
wattr.bg = GFX_YELLOW;
wattr.x = 200;
wattr.y = 150;
wattr.w = 120;
wattr.h = 300;
/* Returns 0 on success */
error = oda_reqwin(&wattr, &win);
```
Arguments passed to ``oda_reqwin()`` are first stored in a ``struct oda_wattr``
structure to minimize the number of parameters used in the function signature.
Upon failure of ``oda_reqwin()`` a negative POSIX errno value
is returned (see ``sys/errno.h``).
|
