(*
 * Title  : bbc.h
 * Purpose: provides bbc-style graphics and mouse/keyboard control.
 *
 *)

# ifndef __bbc_h
# define __bbc_h
 
# ifndef __os_h
# include "os.h"
# endif

(* ----------------------- Text output functions --------------------------
 * Decsription:   The following functions provide BBC-style text output
 *                functions.  For brevity only a short description is
 *                given per function.
 *                NOTE: these functions are retained to allow "old-style"
 *                operations. You should preferably use SWI calls via
 *                kernel.h in the C library.
 *)

(* VDU commands. *)

const   bbc_CharToPrinter   = 1;
        bbc_EnablePrinter   = 2;
        bbc_DisablePrinter  = 3;
        bbc_TextToText      = 4;
        bbc_TextToGraph     = 5;
        bbc_EnableVDU       = 6;
        bbc_Bell            = 7;
        bbc_MoveOneBack     = 8;
        bbc_MoveOneOn       = 9;
        bbc_MoveDownOne     = 10;
        bbc_MoveUpOne       = 11;
        bbc_ClearText       = 12;
        bbc_MoveToStart     = 13;
        bbc_PageOn          = 14;
        bbc_PageOff         = 15;
        bbc_ClearGraph      = 16;
        bbc_DefTextColour   = 17;
        bbc_DefGraphColour  = 18;
        bbc_DefLogical      = 19;
        bbc_RestoreLogical  = 20;
        bbc_DisableVDU      = 21;
        bbc_ScreenMode      = 22;
        bbc_MultiPurpose    = 23;
        bbc_DefGraphWindow  = 24;
        bbc_PlotCommand     = 25;
        bbc_DefaultWindow   = 26;

        bbc_DefTextWindow   = 28;
        bbc_DefGraphOrigin  = 29;
        bbc_HomeText        = 30;
        bbc_MoveText        = 31;

(* ------------ bbc_vdu ------------ 
 * output single character.
 *
 *)
procedure bbc_vdu(c : integer) : os_error; extern;


(* ------------ bbc_vduw ----------- 
 * output double character.
 *
 *)
procedure bbc_vduw(w : integer) : os_error; extern;


(* ------------ bbc_vduq ----------- 
 * output multiple characters. ctl is a 
 * control charcter, number of further 
 * parameters is appropriate to ctl 
 *(vduq knows how many to expect, and
 * assumes correct params passed.
 *)
procedure bbc_vduq(ctl : integer; ..) : os_error; extern;

 
(* -------- bbc_stringprint -------- 
 * display null-terminated string.
 *
 *)
procedure bbc_stringprint(s : string) : os_error; extern;


(* ------------ bbc_cls ------------ 
 * clear text window.
 *
 *)
procedure bbc_cls : os_error; extern;


(* ---------- bbc_colour ----------- 
 * set text colour.
 *
 *)
procedure bbc_colour(c : integer) : os_error; extern;


(* ------------ bbc_pos ------------ 
 * returns X coordinate of
 * text cursor.
 *
 *)
function bbc_pos : integer; extern;


(* ------------ bbc_vpos ----------- 
 * return Y coordinate of
 * text cursor.
 *
 *)
function bbc_vpos : integer; extern;


(* ------------ bbc_tab ------------ 
 * position text cursor at
 * given coordinates.
 *
 *)
procedure bbc_tab(i, j : integer) : os_error; extern;


(* ----------------------- Graphics output functions -------------------- *)
(* Plot codes to be used with the bbc_plot function. *)

const   bbc_SolidBoth       = $00;
        bbc_SolidExFinal    = $08;
        bbc_DottedBoth      = $10;
        bbc_DottedExFinal   = $18;
        bbc_SolidExInit     = $20;
        bbc_SolidExBoth     = $28;
        bbc_DottedExInit    = $30;
        bbc_DottedExBoth    = $38;
#define bbc_Point             $40  (* Clashes with bbc_point *)
        bbc_HorizLineFillNB = $48;
        bbc_TriangleFill    = $50;
        bbc_HorizLineFillB  = $58;
#define bbc_RectangleFill     $60  (* Clashes with bbc_rectanglefill *)
        bbc_HorizLineFillF  = $68;
        bbc_ParallelFill    = $70;
        bbc_HorizLineFillNF = $78;
        bbc_FloodToBack     = $80;
        bbc_FloodToFore     = $88;
#define bbc_Circle            $90  (* Clashes with bbc_circle *)
#define bbc_CircleFill        $98  (* Clashes with bbc_circlefill *)
        bbc_CircleArc       = $A0;
        bbc_Segment         = $A8;
        bbc_Sector          = $B0;
        bbc_Block           = $B8;
        bbc_Ellipse         = $C0;
        bbc_EllipseFill     = $C8;
        bbc_GraphicsChar    = $D0;

        bbc_SpritePlot      = $E8;       


(* Within each block of eight the offset from the base number has the 
   following meaning : *)

        bbc_MoveCursorRel   = 0;
        bbc_DrawRelFore     = 1;
        bbc_DrawRelInverse  = 2;
        bbc_DrawRelBack     = 3;
        bbc_MoveCursorAbs   = 4;
        bbc_DrawAbsFore     = 5;
        bbc_DrawAbsInverse  = 6;
        bbc_DrawAbsBack     = 7;


(* The above applies except for bbc_Block where the codes are as follows : *)

        bbc_BMoveRel        = 0;
        bbc_BMoveRectRel    = 1;
        bbc_BCopyRectRel    = 2;

        bbc_BMoveAbs        = 4;
        bbc_BMoveRectAbs    = 5;
        bbc_BCopyRectAbs    = 6;

(* ------------- bbc_plot ------------- 
 * do a given plot operation.
 *
 *)
procedure bbc_plot(plotnumber, x, y : integer) : os_error; extern;


(* ------------- bbc_mode ------------- 
 * set the screen mode.
 *
 *)
procedure bbc_mode(m : integer) : os_error; extern;


(* ------------- bbc_move ------------- 
 * move graphics cursor to given 
 * absolute coordinates.
 *
 *)
procedure bbc_move(x, y : integer) : os_error; extern;


(* ------------ bbc_moveby ------------ 
 * move graphics cursor to position
 * relative to its current text cursor
 * position.
 *)
procedure bbc_moveby(dx, dy : integer) : os_error; extern;


(* ------------- bbc_draw ------------- 
 * draw a line to given absolute
 * coordinates.
 *
 *)
procedure bbc_draw(x, y : integer) : os_error; extern;


(* ------------ bbc_drawby ------------ 
 * draw a line to position relative to
 * current graphics cursor.
 *
 *)
procedure bbc_drawby(dx, dy : integer) : os_error; extern;


(* --------- bbc_rectangle ------------ 
 * plot a rectangle, given:
 *       LeftX, BottomY, Width, Height.
 *
 *)
procedure bbc_rectangle(leftx, bottomy,
                        width, height : integer) : os_error; extern;


(* -------- bbc_rectanglefill --------- 
 * plot a solid rectangle, given:
 *       LeftX, BottmY, Width, Height.
 *
 *)
procedure bbc_rectanglefill(leftx, bottomy,
                        width, height : integer) : os_error; extern;


(* ------------ bbc_circle ------------ 
 * draw a circle, given:
 *       Xcoord, Ycoord, Radius.
 *
 *)
procedure bbc_circle(x, y, r : integer) : os_error; extern;


(* ---------- bbc_circlefill ---------- 
 * draw a solid circle, given:
 *       Xcoord, Ycoord, Radius.
 *
 *)
procedure bbc_circlefill(x, y, r : integer) : os_error; extern;


(* ------------ bbc_origin ------------ 
 * move graphics origin to given absolute
 * coordinates.
 *
 *)
procedure bbc_origin(x, y : integer) : os_error; extern;


(* ------------ bbc_gwindow ----------- 
 * set up graphics window, given:
 *     BottomLeftX, BottomLeftY,
 *     TopRightX, TopRightY.
 *)
procedure bbc_gwindow(bottomleftx, bottomlefty,
                toprightx, toprighty : integer) : os_error; extern;


(* ------------- bbc_clg ------------- 
 * clear graphics window.
 *
 *)
procedure bbc_clg : os_error; extern;


(* ------------ bbc_fill ------------- 
 * flood-fill area X,Y
 * fills from X,Y til either non_background
 * colour or edge of screen.
 *
 *)
procedure bbc_fill(x, y : integer) : os_error; extern;


(* ------------- bbc_gcol ------------ 
 * set graphics colour to given value.
 *
 *)
procedure bbc_gcol(action, colour : integer) : os_error; extern;


(* ------------- bbc_tint ------------
 * Set grey level of a colour: use tint 0-3, as it gets shifted for you.
 *
 *)
procedure bbc_tint(_type, value : integer) : os_error; extern;


(* ------------- bbc_palette ---------
 * Physical to logical colour definition.
 * Logical colour, Physical colour, 
 * Red level, Green level, Blue level.
 *
 *)
procedure bbc_palette(l, p, r, g, b : integer) : os_error; extern;


(* ------------- bbc_point -----------
 * Find the logical colour of a pixel at
 * indicated coordinates. x, y.
 *
 *)
function bbc_point(x, y : integer) : integer; extern;


(* ------------------------- VDU and Mode Variables. --------------------- *)

(* VDU variables. *)

const
  bbc_GWLCol          = 128;     (* graphics window (ic) *)
  bbc_GWBRow          = 129;     (* (left, bottom, right, top) *)
  bbc_GWRCol          = 130;
  bbc_GWTRow          = 131;
  bbc_TWLCol          = 132;     (* text window *)
  bbc_TWBRow          = 133;     (* (left, bottom, right, top) *)
  bbc_TWRCol          = 134;
  bbc_TWTRow          = 135;
  bbc_OrgX            = 136;     (* graphics origin (ec) *)
  bbc_OrgY            = 137;
  bbc_GCsX            = 138;     (* graphics cursor (ec) *)
  bbc_GCsY            = 139;
  bbc_OlderCsX        = 140;     (* oldest graphics cursor (ic) *)
  bbc_OlderCsY        = 141;
  bbc_OldCsX          = 142;     (* previous graphics cursor (ic) *)
  bbc_OldCsY          = 143;
  bbc_GCsIX           = 144;     (* graphics cursor (ic) *)
  bbc_GCsIY           = 145;
  bbc_NewPtX          = 146;     (* new point (ic) *)
  bbc_NewPtY          = 147;
  bbc_ScreenStart     = 148;     (* start of screen memory *)
  bbc_DisplayStart    = 149;     (* start of display screen memory *)
  bbc_TotalScreenSize = 150;     (* size of configured screen memory *)
  bbc_GPLFMD          = 151;     (* GCOL action for foreground colour *)
  bbc_CPLBMD          = 152;     (* GCOL action for background colour *)
  bbc_GFCOL           = 153;     (* foreground/background colours *)
  bbc_GBCOL           = 154;
  bbc_TForeCol        = 155;     (* text foreground/background colours *)
  bbc_TBackCol        = 156;
  bbc_GFTint          = 157;     (* graphics tints *)
  bbc_GBTint          = 158;
  bbc_TFTint          = 159;     (* text tints *)
  bbc_TBTint          = 160;
  bbc_MaxMode         = 161;     (* highest mode number available *)
  bbc_GCharSizeX      = 162;     (* size of VDU-5 system font in pixels *)
  bbc_GCharSizeY      = 163;
  bbc_GCharSpaceX     = 164;     (* spacing of VDU-5 system font *)
  bbc_GCharSpaceY     = 165;
  bbc_HLineAddr       = 166;
  bbc_TCharSizeX      = 167;     (* text chars (in pixels) *)
  bbc_TCharSizeY      = 168;
  bbc_TCharSpaceX     = 169;
  bbc_TCharSpaceY     = 170;

type bbc_vduvariable_ptr = ^bbc_vduvariable;
     bbc_vduvariable = integer;

const
  bbc_ModeFlags = 0;             (* bit0->non-graphic,
                                    bit1->teletext,
                                    bit2->gap *)
  bbc_ScrRCol = 1;               (* max text col number *)
  bbc_ScrBCol = 2;               (* max text row number *)
  bbc_NColour = 3;               (* max logical colour: 1, 3, 15 or 63 *)
  bbc_XEigFactor = 4;            (* OS-unit->pixel shift factor.
                                    0 -> OS-units = pixels,
                                    1 -> 2 OS-units per pixel,
                                    2 -> 4 OS-units per pixel, etc. *)
  bbc_YEigFactor = 5;
  bbc_LineLength = 6;            (* bytes per pixel row. *)
  bbc_ScreenSize = 7;            (* bytes per screen. *)
  bbc_YShftFactor = 8;           (* DEPRECATED; Log(2) of LineLength/5. *)
  bbc_Log2BPP = 9;               (* log base 2 of bits per pixel. *)
  bbc_Log2BPC = 10;              (* log base 2 of bytes per character. *)
  bbc_XWindLimit = 11;           (* pixels across - 1 *)
  bbc_YWindLimit = 12;           (* pixels up - 1 *)

type bbc_modevariable_ptr = ^bbc_modevariable;
     bbc_modevariable = integer;


(* ------------- bbc_vduvar ---------
 * Read a single VDU or mode variable
 * value, for the current screen mode
 *
 *)
function bbc_vduvar(varno : integer) : integer; extern;


(* ------------- bbc_vduvars --------
 * read several VDU or mode variable
 * values. vars points to a sequence
 * of ints, terminated by -1. Each is
 * a VDU or mode variable number, and the
 * corresponding values will be
 * replaced by the value of that variable
 *
 *)
procedure bbc_vduvars(vars : bbc_vduvariable_ptr;
                values : pointer) : os_error; extern;


(* ------------- bbc_modevar -------
 * Read a single mode variable, for the
 * given screen mode.
 *
 *)
function bbc_modevar(mode, varno : integer) : integer; extern;


(* ------------------------------- Other calls. -------------------------- *)

(* ------------- bbc_get ---------
 * Return a character from the input
 * stream. $1xx is returned if an
 * escape condition exists
 *
 *)
function bbc_get : integer; extern;


(* ------------- bbc_cursor ---------
 * Alter cursor appearance. Argument
 * takes values 0 to 3
 *
 *)
procedure bbc_cursor(n : integer) : os_error; extern;


(* ------------- bbc_adval ---------
 * Read data from analogue ports or
 * give buffer data.
 *
 *)
function bbc_adval(x : integer) : integer; extern;


(* ----------- bbc_getbeat -------
 * Return current beat value
 *
 *)
function bbc_getbeat : integer; extern;


(* ----------- bbc_getbeats ------
 * read beat counter cycle length
 *
 *)
function bbc_getbeats : integer; extern;


(* ---------- bbc_gettempo ------
 * read rate at which beat counter
 * counts
 *
 *)
function bbc_gettempo : integer; extern;


(* ---------- bbc_inkey ---------
 * Return character code from an
 * input stream or the keyboard
 *
 *)
function bbc_inkey(n : integer) : integer; extern;

(* ---------- bbc_setbeats ------
 * Set beat counter cycle length
 *
 *)
procedure bbc_setbeats(l : integer) : os_error; extern;


(* ------------ bbc_settempo ---
 * Set rate at which beat counter
 * counts
 *
 *)
procedure bbc_settempo(newtempo : integer) : os_error; extern;


(* ----------- bbc_sound --------
 * Make or schedule a sound.
 * Params: Channel, Amplitude,
 * Pitch, Duration, Future Time
 *
 *)
procedure bbc_sound(chan, amp,
                pitch, dur, futime : integer) : os_error; extern;


(* ------------ bbc_soundoff ----
 * Deactivate sound system
 *
 *)
procedure bbc_soundoff : os_error; extern;


(* ----------- bbc_soundon -------
 * Activate sound system
 *
 *)
procedure bbc_soundon : os_error; extern;


(* ------------ bbc_stereo -------
 * Set stereo position for specified
 * channel. Params: Channel, Position
 *
 *)
procedure bbc_stereo(channel, position : integer) : os_error; extern;


(* ----------- bbc_voices --------
 * Set number of sound channels
 * 1, 2, 4 or 8.
 *
 *)
procedure bbc_voices(channels : integer) : os_error; extern;

#endif

(* end of bbc.h *)
