1// This file is part of SmallBASIC
2//
3// SmallBASIC: low-level platform driver
4//
5// This program is distributed under the terms of the GPL v2.0 or later
6// Download the GNU Public License (GPL) from www.gnu.org
7//
8// Copyright(C) 2001 Nicholas Christopoulos
9
10/**
11 * @defgroup lgraf Low-level graphics/sound driver
12 */
13
14#if !defined(_osd_h)
15#define _osd_h
16
17#if defined(__cplusplus)
18extern "C" {
19#endif
20
21/**
22 * @ingroup lgraf
23 *
24 * initialize driver
25 *
26 * @return non-zero on success
27 */
28int osd_devinit(void);
29
30/**
31 * @ingroup lgraf
32 *
33 * close driver
34 *
35 * @return non-zero on success
36 */
37int osd_devrestore(void);
38
39/**
40 * @ingroup lgraf
41 *
42 * the driver must check its events
43 *
44 * the keyboard events must be store in SB's keyboard buffer by using,
45 * the dev_pushkey()
46 *
47 * @return
48 * 0 if there is not new events in the queue.
49 * >0 the number of the new events.
50 * -1 that means BREAK (brun_break() it was called).
51 * -2 that means BREAK (executor displays "BREAK" message).
52 */
53int osd_events(int wait_flag);
54
55/**
56 * @ingroup lgraf
57 *
58 * clear screen
59 */
60void osd_cls(void);
61
62/**
63 * @ingroup lgraf
64 *
65 * set current position
66 *
67 * @param x the x position in pixels
68 * @param y the y position in pixels
69 */
70void osd_setxy(int x, int y);
71
72/**
73 * @ingroup lgraf
74 *
75 * return the current x position
76 *
77 * @return the current x position
78 */
79int osd_getx(void);
80
81/**
82 * @ingroup lgraf
83 *
84 * return the current y position
85 *
86 * @return the current y position
87 */
88int osd_gety(void);
89
90/**
91 * @ingroup lgraf
92 *
93 * returns the width of the text in pixels
94 *
95 * @param str the text
96 * @return the width of the text in pixels
97 */
98int osd_textwidth(const char *str);
99
100/**
101 * @ingroup lgraf
102 *
103 * returns the height of the text in pixels
104 *
105 * @param str the text
106 * @return the height of the text in pixels
107 */
108int osd_textheight(const char *str);
109
110/**
111 * @ingroup lgraf
112 *
113 * enable/disable pen/mouse driver.
114 *
115 * @note PEN ON/OFF command
116 *
117 * @param enable non-zero to enable pen/mouse driver.
118 */
119void osd_setpenmode(int enable);
120
121/**
122 * @ingroup lgraf
123 *
124 * Mouse & lightpen!
125 *
126 * Since 1988 the mouse was an new device for PC's, there is no mouse support on QB.
127 *
128 * <pre>
129 PEN, Lightpen & Mouse API
130 ================================
131 PEN(0) -> true (non zero) if there is a new pen or mouse event
132 PEN(1) -> PEN: last pen-down x; MOUSE: last mouse button down x
133 PEN(2) -> PEN: last pen-down y; MOUSE: last mouse button down y
134 PEN(3) -> QB compatiblity, don't use it
135 PEN(4) -> PEN: last/current x, MOUSE: the current x position only
136 if the left mouse button is pressed (like PEN is down)
137 PEN(5) -> PEN: last/current y, MOUSE: the current y position only
138 if the left mouse button is pressed (like PEN is down)
139 PEN(6) -> QB compatiblity, don't use it
140 PEN(7) -> QB compatiblity, don't use it
141 PEN(8) -> QB compatiblity, don't use it
142 PEN(9) -> QB compatiblity, don't use it
143
144 Mouse buttons:
145 PEN(10) -> current mouse x position
146 PEN(11) -> current mouse y position
147 PEN(12) -> true if the left mouse button is pressed
148 PEN(13) -> true if the right mouse button is pressed
149 PEN(14) -> true if the middle mouse button is pressed
150 * </pre>
151 *
152 * @note The PEN(x) function
153 *
154 * @param code is the information code
155 * @return a value based on 'code'
156 */
157int osd_getpen(int mode);
158
159/**
160 * @ingroup lgraf
161 *
162 * writes a string to the SB's console
163 *
164 * this routine must supports the following control codes:
165 *
166 * <pre>
167 \t tab
168 \a beep
169 \n next line (cr/lf)
170 \xC clear screen
171 \e[K clear to end of line
172 \e[0m reset all attributes to their defaults
173 \e[1m set bold on
174 \e[4m set underline on
175 \e[7m reverse video
176 \e[21m set bold off
177 \e[24m set underline off
178 \e[27m set reverse off
179 \e[nG move cursor to specified column
180 \e[8xm select system font (x is the font-number)
181 if there are no fonts, do nothing
182 \e[9xm select buildin font (x is the font-number)
183 if there are no fonts, do nothing
184 * </pre>
185 *
186 * @param str the string
187 */
188void osd_write(const char *str);
189
190/**
191 * @ingroup lgraf
192 *
193 * sets the foreground color. if the color is >= 0 the driver uses the standard 16 VGA colors,
194 * if the color is negative, the driver it must use RGB (-color) color value.
195 *
196 * @param color the foreground color
197 */
198void osd_setcolor(long color);
199
200/**
201 * @ingroup lgraf
202 *
203 * sets the foreground and the background color.
204 * if the color is >= 0 the driver uses the standard 16 VGA colors,
205 * if the color is negative, the driver it must use RGB (-color) color value.
206 *
207 * if the fg or the bg has -1 value, the settextcolor must ignore them.
208 * (-1 means use the current color)
209 *
210 * @param fg the foreground color
211 * @param bg the background color
212 */
213void osd_settextcolor(long fg, long bg);
214
215/**
216 * @ingroup lgraf
217 *
218 * sets the pixel's value
219 *
220 * @param x the x position
221 * @param y the y position
222 */
223void osd_setpixel(int x, int y);
224
225/**
226 * @ingroup lgraf
227 *
228 * Returns the pixel's value.
229 * Since in SB the basic colors are the 16 standard VGA colors,
230 * the driver must returns 0-15 if the pixel match to VGA palette
231 * or -RGB if it is not.
232 *
233 * @param x the x position
234 * @param y the y position
235 * @return the color
236 */
237long osd_getpixel(int x, int y);
238
239/**
240 * @ingroup lgraf
241 *
242 * draw a line using foreground color
243 *
244 * @param x1 line coordinates
245 * @param y1 line coordinates
246 * @param x2 line coordinates
247 * @param y2 line coordinates
248 */
249void osd_line(int x1, int y1, int x2, int y2);
250
251/**
252 * @ingroup lgraf
253 *
254 * draw parallelogram (filled or not)
255 *
256 * @param x1 upper-left corner
257 * @param y1 upper-left corner
258 * @param x2 lower-right corner
259 * @param y2 lower-right corner
260 * @param fill non-zero to fill it with foreground color
261 */
262void osd_rect(int x1, int y1, int x2, int y2, int fill);
263
264/**
265 * @ingroup lgraf
266 *
267 * draw an ellipse using foreground color
268 *
269 * @param xc x-center
270 * @param yc y-center
271 * @param xr x-radius
272 * @param yr y-radius
273 * @param fill non-zero to fill it with foreground color
274 */
275void osd_ellipse(int xc, int yc, int xr, int yr, int fill);
276
277/**
278 * @ingroup lgraf
279 *
280 * draw an arc
281 *
282 * @param xc x-center
283 * @param yc y-center
284 * @param r radius
285 * @param as angle-start in rad
286 * @param ae angle-end in rad
287 * @param aspect x/y (use 1)
288 */
289void osd_arc(int xc, int yc, double r, double as, double ae, double aspect);
290
291/**
292 * @ingroup lgraf
293 *
294 * plays an OGG or MP3 file
295 *
296 * @param path the path to the OGG or MP3 file
297 */
298void osd_audio(const char *path);
299
300/**
301 * @ingroup lgraf
302 *
303 * produce a tone. if the driver has no sound, it can use
304 * an add-on driver like dev_oss, or do nothing.
305 *
306 * the background play means to store the tones on a queue
307 * and play them in its time.
308 *
309 * osd_refresh() can help on that if the system does not
310 * supports threads.
311 *
312 * @param freq is the frequency
313 * @param dur_ms is the duration in milliseconds
314 * @param vol_prc is the volume (0-99)
315 * @param bgplay non-zero for play the tone in background
316 */
317void osd_sound(int frq, int dur, int vol, int bgplay);
318
319/**
320 * @ingroup lgraf
321 *
322 * clears background-sound queue
323 */
324void osd_clear_sound_queue();
325
326/**
327 * @ingroup lgraf
328 *
329 * produce the standard system's beep :)
330 */
331void osd_beep(void);
332
333/**
334 * @ingroup lgraf
335 *
336 * this routine it is called by SB every ~50ms.
337 * if framebuffer technique is used; this routine must write buffer to video-ram
338 */
339void osd_refresh(void);
340
341#if defined(__cplusplus)
342}
343#endif
344#endif
345