/*
 * bbc.h
 *
 * Interface to various vaguely BBC-like bits of the OS
 *
 * © 1994-1998 Straylight
 */

/*----- Licensing note ----------------------------------------------------*
 *
 * This file is part of Straylight's Steel library.
 *
 * Steel is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2, or (at your option)
 * any later version.
 *
 * Steel is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with Steel.  If not, write to the Free Software Foundation,
 * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 */

#ifndef __bbc_h
#define __bbc_h

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

/*----- VDU driver interface ----------------------------------------------*
 *
 * It's highly unlikely that any of these calls will return an error unless
 * you're trying to use them from a print loop.
 */

/* --- bbc_vdu --- *
 *
 * Write character c to the VDU drivers
 */

typedef enum
{
  bbc_Null=0,
  bbc_CharToPrinter,
  bbc_EnablePrinter,
  bbc_DisablePrinter,
  bbc_TextToText,
  bbc_TextToGraph,
  bbc_EnableVDU,
  bbc_Bell,
  bbc_MoveOneBack,
  bbc_MoveOneOn,
  bbc_MoveDownOne,
  bbc_MoveUpOne,
  bbc_ClearText,
  bbc_MoveToStart,
  bbc_PageOn,
  bbc_PageOff,
  bbc_ClearGraph,
  bbc_DefTextColour,
  bbc_DefGraphColour,
  bbc_DefLogical,
  bbc_RestoreLogical,
  bbc_DisableVDU,
  bbc_ScreenMode,
  bbc_MultiPurpose,
  bbc_DefGraphWindow,
  bbc_PlotCommand,
  bbc_DefaultWindow,
  bbc_DoesntDoAnything,
  bbc_DefTextWindow,
  bbc_DefGraphOrigin,
  bbc_HomeText,
  bbc_MoveText
}
bbc_vduCode;

os_error *bbc_vdu(bbc_vduCode c);

/* --- bbc_vduw --- *
 *
 * Write halfword hw to the VDU drivers (e.g. for coordinates)
 */

os_error *bbc_vduw(int hw);

/* --- bbc_vduq --- *
 *
 * Write a stream of characters to the VDU drivers.  The correct number of
 * characters for the VDU command given in the first character is expected:
 * strange things may happen if you don't give the right number.
 */

os_error *bbc_vduq(bbc_vduCode c,...);

/* --- bbc_stringprint --- *
 *
 * Writes a null-terminated string pointed to by p to the VDU drivers
 */

os_error *bbc_stringprint(const char *p);

/* --- bbc_cls --- *
 *
 * Clears the screen
 */

os_error *bbc_cls(void);

/* --- bbc_colour --- *
 *
 * Sets the text colour to be col.  Set bit 7 of col to set the background
 * colour.
 */

os_error *bbc_colour(int col);

/* --- bbc_pos and bbc_vpos --- *
 *
 * Return the x or y position of the text cursor respectively.
 */

int bbc_pos(void);
int bbc_vpos(void);

/* --- bbc_tab --- *
 *
 * Moves the text cursor to a specified position on the screen.
 */

os_error *bbc_tab(int x,int y);

/*----- Graphics interface ------------------------------------------------*/

/* --- bbc_plot --- *
 *
 * Plots something specified by action at position x,y
 */

typedef enum
{
  bbc_SolidBoth=0x00,
  bbc_SolidExFinal=0x08,
  bbc_DottedBoth=0x10,
  bbc_DottedExFinal=0x18,
  bbc_SolidExInit=0x20,
  bbc_SolidExBoth=0x28,
  bbc_DottedExInit=0x30,
  bbc_DottedExBoth=0x38,
  bbc_Point=0x40,
  bbc_HorizLineFillNB=0x48,
  bbc_TriangleFill=0x50,
  bbc_HorizLineFillB=0x58,
  bbc_RectangleFill=0x60,
  bbc_HorizLineFillF=0x68,
  bbc_ParallelFill=0x70,
  bbc_HorizLineFillNF=0x78,
  bbc_FloodToBack=0x80,
  bbc_FloodToFore=0x88,
  bbc_Circle=0x90,
  bbc_CircleFill=0x98,
  bbc_CircleArc=0xA0,
  bbc_Segment=0xA8,
  bbc_Sector=0xB0,
  bbc_Block=0xB8,
  bbc_Ellipse=0xC0,
  bbc_EllipseFill=0xC8,
  bbc_GraphicsChar=0xD0,
  bbc_SpritePlot=0xE8
}
bbc_plotAction;

typedef enum
{
  bbc_MoveCursorRel,
  bbc_DrawRelFore,
  bbc_DrawRelInverse,
  bbc_DrawRelBack,
  bbc_MoveCursorAbs,
  bbc_DrawAbsFore,
  bbc_DrawAbsInverse,
  bbc_DrawAbsBack
}
bbc_plotType;

os_error *bbc_plot(int action,int x,int y);

/* --- bbc_move --- *
 *
 * Moves the graphics cursor to x,y
 */

os_error *bbc_move(int x,int y);

/* --- bbc_moveby --- *
 *
 * Translates the graphics cursor by x,y
 */

os_error *bbc_moveby(int x,int y);

/* --- bbc_draw --- *
 *
 * Draws a line from the graphics cursor position to x,y
 */

os_error *bbc_draw(int x,int y);

/* --- bbc_drawby --- *
 *
 * Draws a line from the graphics cursor position to the point x to the 
 * right of and y above the graphics cursor position
 */

os_error *bbc_drawby(int x,int y);

/* --- bbc_rectangle --- *
 *
 * Draws a rectangle with bottom left point at x,y, width w and height h
 */

os_error *bbc_rectangle(int x,int y,int w,int h);

/* --- bbc_rectanglefill --- *
 *
 * Draws a filled rectangle with bottom left point at x,y, width w and
 * height h
 */

os_error *bbc_rectanglefill(int x,int y,int w,int h);

/* --- bbc_circle --- *
 *
 * Draws a circle, centre at x,y with radius r
 */

os_error *bbc_circle(int x,int y,int r);

/* --- bbc_circlefill --- *
 *
 * Draws a filled in circle, centre at x,y with radius r
 */

os_error *bbc_circlefill(int x,int y,int r);

/* --- bbc_origin --- *
 *
 * Sets the graphics origin to the point x,y (relative to the bottom left
 * corner of the screen)
 */

os_error *bbc_origin(int x,int y);

/* --- bbc_gwindow --- *
 *
 * Sets the graphics clipping window to the rectangle whose bottom left and
 * top right corners are x0,y0 and x1,y1
 */

os_error *bbc_gwindow(int x0,int y0,int x1,int y1);

/* --- bbc_clg --- *
 *
 * Clears the graphics clipping window
 */

os_error *bbc_clg(void);

/* --- bbc_fill --- *
 *
 * Flood fills the area containing the point x,y to the current foreground
 * colour.  The area is expected to currently be coloured in the current
 * background colour
 */

os_error *bbc_fill(int x,int y);

/* --- bbc_gcol --- *
 *
 * Sets the current GCOL action to action and the current graphics colour to
 * col.  Set bit 7 of col to choose the background colour.
 */

os_error *bbc_gcol(int action,int col);

/* --- bbc_tint --- *
 *
 * Sets the current tint (if in a 256-colour mode) to tint specified.  Note
 * that tint values should be between 0 and 3, not 0x00 to 0xC0.
 */

typedef enum
{
  bbc_TextForegroundTint,
  bbc_TextBackgroundTint,
  bbc_GraphicsForegroundTint,
  bbc_GraphicsBackgroundTint
}
bbc_tintAction;

os_error *bbc_tint(bbc_tintAction action,int col);

/* --- bbc_palette --- *
 *
 * Sets logical colour col to be `physical' colour mode, or to the palette
 * entry red,green,blue.
 */

typedef enum
{
  /* --- BBC-style solid colours --- */

  bbc_palBlack,
  bbc_palRed,
  bbc_palGreen,
  bbc_palYellow,
  bbc_palBlue,
  bbc_palMagenta,
  bbc_palCyan,
  bbc_palWhite,

  /* --- BBC-style really yukky flashing colours --- */

  bbc_palFlashBlackWhite,
  bbc_palFlashRedCyan,
  bbc_palFlashGreenMagenta,
  bbc_palFlashYellowBlue,
  bbc_palFlashBlueYellow,
  bbc_palFlashMagentaGreen,
  bbc_palFlashCyanRed,
  bbc_palFlashWhiteBack,

  /* --- Other special values (use red,green,blue values) --- */

  bbc_palSolidRGB,
  bbc_palFirstFlashRGB,
  bbc_palSecondFlashRGB,
  bbc_palBorderRGB,
  bbc_palMouseRGB,

  /* --- Special flags to OR in --- */

  bbc_palSupremacy
}
bbc_palMode;

os_error *bbc_palette(int col,bbc_palMode mode,int red,int green,int blue);

/* --- bbc_point --- *
 *
 * Returns the logical colour of the point at position x,y.  Doesn't return
 * the tint in 256-colour modes.  Returns 255 if the point is offscreen or
 * an error occurred.
 */

int bbc_point(int x,int y);

/*----- Screen mode handling ----------------------------------------------*/

/* --- bbc_mode --- *
 *
 * Sets the screen mode to mode
 */

os_error *bbc_mode(int mode);

/* --- bbc_vduvar --- *
 *
 * Reads the value of the VDU variable var and returns it
 */

typedef enum
{
  bbc_GWLCol=128,
  bbc_GWBRow,
  bbc_GWRCol,
  bbc_GWTRow,
  bbc_TWLCol,
  bbc_TWBRow,
  bbc_TWRCol,
  bbc_TWTRow,
  bbc_OrgX,
  bbc_OrgY,
  bbc_GCsX,
  bbc_GCsY,
  bbc_OlderCsX,
  bbc_OlderCsY,
  bbc_OldCsX,
  bbc_OldCsY,
  bbc_GCsIX,
  bbc_GCsIY,
  bbc_NewPtX,
  bbc_NewPtY,
  bbc_ScreenStart,
  bbc_DisplayStart,
  bbc_TotalScreenSize,
  bbc_GPLFMD,
  bbc_CPLBMD,
  bbc_GFCOL,
  bbc_GBCOL,
  bbc_TForeCol,
  bbc_TBackCol,
  bbc_GFTint,
  bbc_GBTint,
  bbc_TFTint,
  bbc_TBTint,
  bbc_MaxMode,
  bbc_GCharSizeX,
  bbc_GCharSizeY,
  bbc_GCharSpaceX,
  bbc_GCharSpaceY,
  bbc_HLineAddr,
  bbc_TCharSizeX,
  bbc_TCharSizeY,
  bbc_TCharSpaceX,
  bbc_TCharSpaceY
}
bbc_vduvariable;

typedef enum
{
  bbc_ModeFlags,
  bbc_ScrRCol,
  bbc_ScrBCol,
  bbc_NColour,
  bbc_XEigFactor,
  bbc_YEigFactor,
  bbc_LineLength,
  bbc_ScreenSize,
  bbc_YShftFactor,
  bbc_Log2BPP,
  bbc_Log2BPC,
  bbc_XWindLimit,
  bbc_YWindLimit
}
bbc_modevariable;

int bbc_vduvar(int var);

/* --- bbc_vduvars --- *
 *
 * Reads a collection of VDU variables into an array.  The variables to be
 * read are held in the `in' array, which is terminated by a -1 entry.  The
 * values are stored in the same order in the `out' array.
 */

os_error *bbc_vduvars(int in[],int out[]);

/* --- bbc_modevar --- *
 *
 * Returns the value of mode variable var for mode m
 */

int bbc_modevar(int m,int var);

/*----- Keyboard and cursor handling --------------------------------------*/

/* --- bbc_get --- *
 *
 * Waits for a keypress and returns the ASCII code.  Returns 0x1?? if Escape
 * was pressed.
 */

int bbc_get(void);

/* --- bbc_inkey --- *
 *
 * Return value depends on action:
 *
 * action == 0xFF00: Return OS version identifier
 * action == 0xFFkk: Return whether key with internal code kk ^ 255 is
 *                   pressed
 * action == 0xtttt: Wait tttt centiseconds for a keypress and return ASCII
 *                   code
 */

int bbc_inkey(int action);

/* --- bbc_cursor --- *
 *
 * Sets cursor mode according to value of action:
 *
 * action == 0: Turn cursor off
 * action == 1: Turn cursor on
 * action == 2: Make cursor steady
 * action == 3: Make cursor flash
 */

os_error *bbc_cursor(int action);

/*----- Mouse control -----------------------------------------------------*/

/* --- bbc_mouse --- *
 *
 * Reads the mouse coordinates into *x,*y, button status int *b and time of
 * mouse event into *t.  Any of these may be 0 to indicate `don't care'.
 */

os_error *bbc_mouse(int *x,int *y,int *b,int *t);

/* --- bbc_mouserect --- *
 *
 * Sets the mouse bounding rectangle to have bottom left coordinate x0,y0
 * and top right coordinate x1,y1
 */

os_error *bbc_mouserect(int x0,int y0,int x1,int y1);

/*----- Strangeness -------------------------------------------------------*/

/* --- bbc_adval --- *
 *
 * If I knew, I wouldn't be here.
 */

int bbc_adval(int);

/*----- Sound calls -------------------------------------------------------*/

/* --- bbc_getbeat --- *
 *
 * Reads the beat counter
 */

int bbc_getbeat(void);

/* --- bbc_getbeats --- *
 *
 * Reads the length of a bar in beats
 */

int bbc_getbeats(void);

/* --- bbc_setbeats --- *
 *
 * Sets the bar length
 */

os_error *bbc_setbeats(int beats);

/* --- bbc_gettempo --- *
 *
 * Reads the beat speed
 */

int bbc_gettempo(void);

/* --- bbc_settempo --- *
 *
 * Sets the beat speed
 */

os_error *bbc_settempo(int tempo);

/* --- bbc_sound --- *
 *
 * Makes a sound on channel chan with amplitude a, pitch p and duration d
 * at time t.  t==-2 for `right now'.  Doesn't return an error.
 */

os_error *bbc_sound(int chan,int a,int p,int d,int t);

/* --- bbc_soundoff and bbc_soundon --- *
 *
 * Disable and enable the sound system
 */

os_error *bbc_soundoff(void);
os_error *bbc_soundon(void);

/* --- bbc_stereo --- *
 *
 * Sets the stereo position of channel chan to pos
 */

os_error *bbc_stereo(int chan,int pos);

/* --- bbc_voices --- *
 *
 * Sets the number of voices (channels ) to be n
 */

os_error *bbc_voices(int n);

#endif