chiark - git - mdw - ssr/blob - StraySrc/Libraries/Steel/h/bbc

   1 /*
   2  * bbc.h
   3  *
   4  * Interface to various vaguely BBC-like bits of the OS
   5  *
   6  * © 1994-1998 Straylight
   7  */
   8
   9 /*----- Licensing note ----------------------------------------------------*
  10  *
  11  * This file is part of Straylight's Steel library.
  12  *
  13  * Steel is free software; you can redistribute it and/or modify
  14  * it under the terms of the GNU General Public License as published by
  15  * the Free Software Foundation; either version 2, or (at your option)
  16  * any later version.
  17  *
  18  * Steel is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU General Public License for more details.
  22  *
  23  * You should have received a copy of the GNU General Public License
  24  * along with Steel.  If not, write to the Free Software Foundation,
  25  * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  26  */
  27
  28 #ifndef __bbc_h
  29 #define __bbc_h
  30
  31 #ifndef __os_h
  32   #include "os.h"
  33 #endif
  34
  35 /*----- VDU driver interface ----------------------------------------------*
  36  *
  37  * It's highly unlikely that any of these calls will return an error unless
  38  * you're trying to use them from a print loop.
  39  */
  40
  41 /* --- bbc_vdu --- *
  42  *
  43  * Write character c to the VDU drivers
  44  */
  45
  46 typedef enum
  47 {
  48   bbc_Null=0,
  49   bbc_CharToPrinter,
  50   bbc_EnablePrinter,
  51   bbc_DisablePrinter,
  52   bbc_TextToText,
  53   bbc_TextToGraph,
  54   bbc_EnableVDU,
  55   bbc_Bell,
  56   bbc_MoveOneBack,
  57   bbc_MoveOneOn,
  58   bbc_MoveDownOne,
  59   bbc_MoveUpOne,
  60   bbc_ClearText,
  61   bbc_MoveToStart,
  62   bbc_PageOn,
  63   bbc_PageOff,
  64   bbc_ClearGraph,
  65   bbc_DefTextColour,
  66   bbc_DefGraphColour,
  67   bbc_DefLogical,
  68   bbc_RestoreLogical,
  69   bbc_DisableVDU,
  70   bbc_ScreenMode,
  71   bbc_MultiPurpose,
  72   bbc_DefGraphWindow,
  73   bbc_PlotCommand,
  74   bbc_DefaultWindow,
  75   bbc_DoesntDoAnything,
  76   bbc_DefTextWindow,
  77   bbc_DefGraphOrigin,
  78   bbc_HomeText,
  79   bbc_MoveText
  80 }
  81 bbc_vduCode;
  82
  83 os_error *bbc_vdu(bbc_vduCode c);
  84
  85 /* --- bbc_vduw --- *
  86  *
  87  * Write halfword hw to the VDU drivers (e.g. for coordinates)
  88  */
  89
  90 os_error *bbc_vduw(int hw);
  91
  92 /* --- bbc_vduq --- *
  93  *
  94  * Write a stream of characters to the VDU drivers.  The correct number of
  95  * characters for the VDU command given in the first character is expected:
  96  * strange things may happen if you don't give the right number.
  97  */
  98
  99 os_error *bbc_vduq(bbc_vduCode c,...);
 100
 101 /* --- bbc_stringprint --- *
 102  *
 103  * Writes a null-terminated string pointed to by p to the VDU drivers
 104  */
 105
 106 os_error *bbc_stringprint(const char *p);
 107
 108 /* --- bbc_cls --- *
 109  *
 110  * Clears the screen
 111  */
 112
 113 os_error *bbc_cls(void);
 114
 115 /* --- bbc_colour --- *
 116  *
 117  * Sets the text colour to be col.  Set bit 7 of col to set the background
 118  * colour.
 119  */
 120
 121 os_error *bbc_colour(int col);
 122
 123 /* --- bbc_pos and bbc_vpos --- *
 124  *
 125  * Return the x or y position of the text cursor respectively.
 126  */
 127
 128 int bbc_pos(void);
 129 int bbc_vpos(void);
 130
 131 /* --- bbc_tab --- *
 132  *
 133  * Moves the text cursor to a specified position on the screen.
 134  */
 135
 136 os_error *bbc_tab(int x,int y);
 137
 138 /*----- Graphics interface ------------------------------------------------*/
 139
 140 /* --- bbc_plot --- *
 141  *
 142  * Plots something specified by action at position x,y
 143  */
 144
 145 typedef enum
 146 {
 147   bbc_SolidBoth=0x00,
 148   bbc_SolidExFinal=0x08,
 149   bbc_DottedBoth=0x10,
 150   bbc_DottedExFinal=0x18,
 151   bbc_SolidExInit=0x20,
 152   bbc_SolidExBoth=0x28,
 153   bbc_DottedExInit=0x30,
 154   bbc_DottedExBoth=0x38,
 155   bbc_Point=0x40,
 156   bbc_HorizLineFillNB=0x48,
 157   bbc_TriangleFill=0x50,
 158   bbc_HorizLineFillB=0x58,
 159   bbc_RectangleFill=0x60,
 160   bbc_HorizLineFillF=0x68,
 161   bbc_ParallelFill=0x70,
 162   bbc_HorizLineFillNF=0x78,
 163   bbc_FloodToBack=0x80,
 164   bbc_FloodToFore=0x88,
 165   bbc_Circle=0x90,
 166   bbc_CircleFill=0x98,
 167   bbc_CircleArc=0xA0,
 168   bbc_Segment=0xA8,
 169   bbc_Sector=0xB0,
 170   bbc_Block=0xB8,
 171   bbc_Ellipse=0xC0,
 172   bbc_EllipseFill=0xC8,
 173   bbc_GraphicsChar=0xD0,
 174   bbc_SpritePlot=0xE8
 175 }
 176 bbc_plotAction;
 177
 178 typedef enum
 179 {
 180   bbc_MoveCursorRel,
 181   bbc_DrawRelFore,
 182   bbc_DrawRelInverse,
 183   bbc_DrawRelBack,
 184   bbc_MoveCursorAbs,
 185   bbc_DrawAbsFore,
 186   bbc_DrawAbsInverse,
 187   bbc_DrawAbsBack
 188 }
 189 bbc_plotType;
 190
 191 os_error *bbc_plot(int action,int x,int y);
 192
 193 /* --- bbc_move --- *
 194  *
 195  * Moves the graphics cursor to x,y
 196  */
 197
 198 os_error *bbc_move(int x,int y);
 199
 200 /* --- bbc_moveby --- *
 201  *
 202  * Translates the graphics cursor by x,y
 203  */
 204
 205 os_error *bbc_moveby(int x,int y);
 206
 207 /* --- bbc_draw --- *
 208  *
 209  * Draws a line from the graphics cursor position to x,y
 210  */
 211
 212 os_error *bbc_draw(int x,int y);
 213
 214 /* --- bbc_drawby --- *
 215  *
 216  * Draws a line from the graphics cursor position to the point x to the
 217  * right of and y above the graphics cursor position
 218  */
 219
 220 os_error *bbc_drawby(int x,int y);
 221
 222 /* --- bbc_rectangle --- *
 223  *
 224  * Draws a rectangle with bottom left point at x,y, width w and height h
 225  */
 226
 227 os_error *bbc_rectangle(int x,int y,int w,int h);
 228
 229 /* --- bbc_rectanglefill --- *
 230  *
 231  * Draws a filled rectangle with bottom left point at x,y, width w and
 232  * height h
 233  */
 234
 235 os_error *bbc_rectanglefill(int x,int y,int w,int h);
 236
 237 /* --- bbc_circle --- *
 238  *
 239  * Draws a circle, centre at x,y with radius r
 240  */
 241
 242 os_error *bbc_circle(int x,int y,int r);
 243
 244 /* --- bbc_circlefill --- *
 245  *
 246  * Draws a filled in circle, centre at x,y with radius r
 247  */
 248
 249 os_error *bbc_circlefill(int x,int y,int r);
 250
 251 /* --- bbc_origin --- *
 252  *
 253  * Sets the graphics origin to the point x,y (relative to the bottom left
 254  * corner of the screen)
 255  */
 256
 257 os_error *bbc_origin(int x,int y);
 258
 259 /* --- bbc_gwindow --- *
 260  *
 261  * Sets the graphics clipping window to the rectangle whose bottom left and
 262  * top right corners are x0,y0 and x1,y1
 263  */
 264
 265 os_error *bbc_gwindow(int x0,int y0,int x1,int y1);
 266
 267 /* --- bbc_clg --- *
 268  *
 269  * Clears the graphics clipping window
 270  */
 271
 272 os_error *bbc_clg(void);
 273
 274 /* --- bbc_fill --- *
 275  *
 276  * Flood fills the area containing the point x,y to the current foreground
 277  * colour.  The area is expected to currently be coloured in the current
 278  * background colour
 279  */
 280
 281 os_error *bbc_fill(int x,int y);
 282
 283 /* --- bbc_gcol --- *
 284  *
 285  * Sets the current GCOL action to action and the current graphics colour to
 286  * col.  Set bit 7 of col to choose the background colour.
 287  */
 288
 289 os_error *bbc_gcol(int action,int col);
 290
 291 /* --- bbc_tint --- *
 292  *
 293  * Sets the current tint (if in a 256-colour mode) to tint specified.  Note
 294  * that tint values should be between 0 and 3, not 0x00 to 0xC0.
 295  */
 296
 297 typedef enum
 298 {
 299   bbc_TextForegroundTint,
 300   bbc_TextBackgroundTint,
 301   bbc_GraphicsForegroundTint,
 302   bbc_GraphicsBackgroundTint
 303 }
 304 bbc_tintAction;
 305
 306 os_error *bbc_tint(bbc_tintAction action,int col);
 307
 308 /* --- bbc_palette --- *
 309  *
 310  * Sets logical colour col to be `physical' colour mode, or to the palette
 311  * entry red,green,blue.
 312  */
 313
 314 typedef enum
 315 {
 316   /* --- BBC-style solid colours --- */
 317
 318   bbc_palBlack,
 319   bbc_palRed,
 320   bbc_palGreen,
 321   bbc_palYellow,
 322   bbc_palBlue,
 323   bbc_palMagenta,
 324   bbc_palCyan,
 325   bbc_palWhite,
 326
 327   /* --- BBC-style really yukky flashing colours --- */
 328
 329   bbc_palFlashBlackWhite,
 330   bbc_palFlashRedCyan,
 331   bbc_palFlashGreenMagenta,
 332   bbc_palFlashYellowBlue,
 333   bbc_palFlashBlueYellow,
 334   bbc_palFlashMagentaGreen,
 335   bbc_palFlashCyanRed,
 336   bbc_palFlashWhiteBack,
 337
 338   /* --- Other special values (use red,green,blue values) --- */
 339
 340   bbc_palSolidRGB,
 341   bbc_palFirstFlashRGB,
 342   bbc_palSecondFlashRGB,
 343   bbc_palBorderRGB,
 344   bbc_palMouseRGB,
 345
 346   /* --- Special flags to OR in --- */
 347
 348   bbc_palSupremacy
 349 }
 350 bbc_palMode;
 351
 352 os_error *bbc_palette(int col,bbc_palMode mode,int red,int green,int blue);
 353
 354 /* --- bbc_point --- *
 355  *
 356  * Returns the logical colour of the point at position x,y.  Doesn't return
 357  * the tint in 256-colour modes.  Returns 255 if the point is offscreen or
 358  * an error occurred.
 359  */
 360
 361 int bbc_point(int x,int y);
 362
 363 /*----- Screen mode handling ----------------------------------------------*/
 364
 365 /* --- bbc_mode --- *
 366  *
 367  * Sets the screen mode to mode
 368  */
 369
 370 os_error *bbc_mode(int mode);
 371
 372 /* --- bbc_vduvar --- *
 373  *
 374  * Reads the value of the VDU variable var and returns it
 375  */
 376
 377 typedef enum
 378 {
 379   bbc_GWLCol=128,
 380   bbc_GWBRow,
 381   bbc_GWRCol,
 382   bbc_GWTRow,
 383   bbc_TWLCol,
 384   bbc_TWBRow,
 385   bbc_TWRCol,
 386   bbc_TWTRow,
 387   bbc_OrgX,
 388   bbc_OrgY,
 389   bbc_GCsX,
 390   bbc_GCsY,
 391   bbc_OlderCsX,
 392   bbc_OlderCsY,
 393   bbc_OldCsX,
 394   bbc_OldCsY,
 395   bbc_GCsIX,
 396   bbc_GCsIY,
 397   bbc_NewPtX,
 398   bbc_NewPtY,
 399   bbc_ScreenStart,
 400   bbc_DisplayStart,
 401   bbc_TotalScreenSize,
 402   bbc_GPLFMD,
 403   bbc_CPLBMD,
 404   bbc_GFCOL,
 405   bbc_GBCOL,
 406   bbc_TForeCol,
 407   bbc_TBackCol,
 408   bbc_GFTint,
 409   bbc_GBTint,
 410   bbc_TFTint,
 411   bbc_TBTint,
 412   bbc_MaxMode,
 413   bbc_GCharSizeX,
 414   bbc_GCharSizeY,
 415   bbc_GCharSpaceX,
 416   bbc_GCharSpaceY,
 417   bbc_HLineAddr,
 418   bbc_TCharSizeX,
 419   bbc_TCharSizeY,
 420   bbc_TCharSpaceX,
 421   bbc_TCharSpaceY
 422 }
 423 bbc_vduvariable;
 424
 425 typedef enum
 426 {
 427   bbc_ModeFlags,
 428   bbc_ScrRCol,
 429   bbc_ScrBCol,
 430   bbc_NColour,
 431   bbc_XEigFactor,
 432   bbc_YEigFactor,
 433   bbc_LineLength,
 434   bbc_ScreenSize,
 435   bbc_YShftFactor,
 436   bbc_Log2BPP,
 437   bbc_Log2BPC,
 438   bbc_XWindLimit,
 439   bbc_YWindLimit
 440 }
 441 bbc_modevariable;
 442
 443 int bbc_vduvar(int var);
 444
 445 /* --- bbc_vduvars --- *
 446  *
 447  * Reads a collection of VDU variables into an array.  The variables to be
 448  * read are held in the `in' array, which is terminated by a -1 entry.  The
 449  * values are stored in the same order in the `out' array.
 450  */
 451
 452 os_error *bbc_vduvars(int in[],int out[]);
 453
 454 /* --- bbc_modevar --- *
 455  *
 456  * Returns the value of mode variable var for mode m
 457  */
 458
 459 int bbc_modevar(int m,int var);
 460
 461 /*----- Keyboard and cursor handling --------------------------------------*/
 462
 463 /* --- bbc_get --- *
 464  *
 465  * Waits for a keypress and returns the ASCII code.  Returns 0x1?? if Escape
 466  * was pressed.
 467  */
 468
 469 int bbc_get(void);
 470
 471 /* --- bbc_inkey --- *
 472  *
 473  * Return value depends on action:
 474  *
 475  * action == 0xFF00: Return OS version identifier
 476  * action == 0xFFkk: Return whether key with internal code kk ^ 255 is
 477  *                   pressed
 478  * action == 0xtttt: Wait tttt centiseconds for a keypress and return ASCII
 479  *                   code
 480  */
 481
 482 int bbc_inkey(int action);
 483
 484 /* --- bbc_cursor --- *
 485  *
 486  * Sets cursor mode according to value of action:
 487  *
 488  * action == 0: Turn cursor off
 489  * action == 1: Turn cursor on
 490  * action == 2: Make cursor steady
 491  * action == 3: Make cursor flash
 492  */
 493
 494 os_error *bbc_cursor(int action);
 495
 496 /*----- Mouse control -----------------------------------------------------*/
 497
 498 /* --- bbc_mouse --- *
 499  *
 500  * Reads the mouse coordinates into *x,*y, button status int *b and time of
 501  * mouse event into *t.  Any of these may be 0 to indicate `don't care'.
 502  */
 503
 504 os_error *bbc_mouse(int *x,int *y,int *b,int *t);
 505
 506 /* --- bbc_mouserect --- *
 507  *
 508  * Sets the mouse bounding rectangle to have bottom left coordinate x0,y0
 509  * and top right coordinate x1,y1
 510  */
 511
 512 os_error *bbc_mouserect(int x0,int y0,int x1,int y1);
 513
 514 /*----- Strangeness -------------------------------------------------------*/
 515
 516 /* --- bbc_adval --- *
 517  *
 518  * If I knew, I wouldn't be here.
 519  */
 520
 521 int bbc_adval(int);
 522
 523 /*----- Sound calls -------------------------------------------------------*/
 524
 525 /* --- bbc_getbeat --- *
 526  *
 527  * Reads the beat counter
 528  */
 529
 530 int bbc_getbeat(void);
 531
 532 /* --- bbc_getbeats --- *
 533  *
 534  * Reads the length of a bar in beats
 535  */
 536
 537 int bbc_getbeats(void);
 538
 539 /* --- bbc_setbeats --- *
 540  *
 541  * Sets the bar length
 542  */
 543
 544 os_error *bbc_setbeats(int beats);
 545
 546 /* --- bbc_gettempo --- *
 547  *
 548  * Reads the beat speed
 549  */
 550
 551 int bbc_gettempo(void);
 552
 553 /* --- bbc_settempo --- *
 554  *
 555  * Sets the beat speed
 556  */
 557
 558 os_error *bbc_settempo(int tempo);
 559
 560 /* --- bbc_sound --- *
 561  *
 562  * Makes a sound on channel chan with amplitude a, pitch p and duration d
 563  * at time t.  t==-2 for `right now'.  Doesn't return an error.
 564  */
 565
 566 os_error *bbc_sound(int chan,int a,int p,int d,int t);
 567
 568 /* --- bbc_soundoff and bbc_soundon --- *
 569  *
 570  * Disable and enable the sound system
 571  */
 572
 573 os_error *bbc_soundoff(void);
 574 os_error *bbc_soundon(void);
 575
 576 /* --- bbc_stereo --- *
 577  *
 578  * Sets the stereo position of channel chan to pos
 579  */
 580
 581 os_error *bbc_stereo(int chan,int pos);
 582
 583 /* --- bbc_voices --- *
 584  *
 585  * Sets the number of voices (channels ) to be n
 586  */
 587
 588 os_error *bbc_voices(int n);
 589
 590 #endif