bbc

/* Copyright 1996 Acorn Computers Ltd
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/****************************************************************************
 * This source file was written by Acorn Computers Limited. It is part of   *
 * the RISCOS library for writing applications in C for RISC OS. It may be  *
 * used freely in the creation of programs for Archimedes. It should be     *
 * used with Acorn's C Compiler Release 3 or later.                         *
 *                                                                          *
 ***************************************************************************/

/*
 * 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. */

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

#define  bbc_DefTextWindow   28
#define  bbc_DefGraphOrigin  29
#define  bbc_HomeText        30
#define  bbc_MoveText        31

/* ------------ bbc_vdu ------------
 * output single character.
 *
 */
os_error *bbc_vdu(int);


/* ------------ bbc_vduw -----------
 * output double character.
 *
 */
os_error *bbc_vduw(int);


/* ------------ 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.
 */
os_error *bbc_vduq(int ctl,...);


/* -------- bbc_stringprint --------
 * display null-terminated string.
 *
 */
os_error *bbc_stringprint(char *);


/* ------------ bbc_cls ------------
 * clear text window.
 *
 */
os_error *bbc_cls(void);


/* ---------- bbc_colour -----------
 * set text colour.
 *
 */
os_error *bbc_colour(int);


/* ------------ bbc_pos ------------
 * returns X coordinate of
 * text cursor.
 *
 */
int bbc_pos(void);


/* ------------ bbc_vpos -----------
 * return Y coordinate of
 * text cursor.
 *
 */
int bbc_vpos(void);


/* ------------ bbc_tab ------------
 * position text cursor at
 * given coordinates.
 *
 */
os_error *bbc_tab(int,int);


/* ----------------------- Graphics output functions -------------------- */

/* Plot codes to be used with the bbc_plot function. */

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

#define  bbc_SpritePlot      0xE8


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

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


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

#define  bbc_BMoveRel        0
#define  bbc_BMoveRectRel    1
#define  bbc_BCopyRectRel    2

#define  bbc_BMoveAbs        4
#define  bbc_BMoveRectAbs    5
#define  bbc_BCopyRectAbs    6

/* ------------- bbc_plot -------------
 * do a given plot operation.
 *
 */
os_error *bbc_plot(int plotnumber, int x, int y);


/* ------------- bbc_mode -------------
 * set the screen mode.
 *
 */
os_error *bbc_mode(int);


/* ------------- bbc_move -------------
 * move graphics cursor to given
 * absolute coordinates.
 *
 */
os_error *bbc_move(int, int);


/* ------------ bbc_moveby ------------
 * move graphics cursor to position
 * relative to its current text cursor
 * position.
 */
os_error *bbc_moveby(int, int);


/* ------------- bbc_draw -------------
 * draw a line to given absolute
 * coordinates.
 *
 */
os_error *bbc_draw(int, int);


/* ------------ bbc_drawby ------------
 * draw a line to position relative to
 * current graphics cursor.
 *
 */
os_error *bbc_drawby(int, int);


/* --------- bbc_rectangle ------------
 * plot a rectangle, given:
 *       LeftX, BottomY, Width, Height.
 *
 */
os_error *bbc_rectangle(int,int,int,int);


/* -------- bbc_rectanglefill ---------
 * plot a solid rectangle, given:
 *       LeftX, BottmY, Width, Height.
 *
 */
os_error *bbc_rectanglefill(int,int,int,int);


/* ------------ bbc_circle ------------
 * draw a circle, given:
 *       Xcoord, Ycoord, Radius.
 *
 */
os_error *bbc_circle(int, int, int);


/* ---------- bbc_circlefill ----------
 * draw a solid circle, given:
 *       Xcoord, Ycoord, Radius.
 *
 */
os_error *bbc_circlefill(int, int, int);


/* ------------ bbc_origin ------------
 * move graphics origin to given absolute
 * coordinates.
 *
 */
os_error *bbc_origin(int,int);


/* ------------ bbc_gwindow -----------
 * set up graphics window, given:
 *     BottomLeftX, BottomLeftY,
 *     TopRightX, TopRightY.
 */
os_error *bbc_gwindow(int, int, int, int);


/* ------------- bbc_clg -------------
 * clear graphics window.
 *
 */
os_error *bbc_clg(void);


/* ------------ bbc_fill -------------
 * flood-fill area X,Y
 * fills from X,Y til either non_background
 * colour or edge of screen.
 *
 */
os_error *bbc_fill(int, int);


/* ------------- bbc_gcol ------------
 * set graphics colour to given value.
 *
 */
os_error *bbc_gcol(int, int);


/* ------------- bbc_tint ------------
 * Set grey level of a colour: use tint 0-3, as it gets shifted for you.
 *
 */
os_error *bbc_tint(int,int);


/* ------------- bbc_palette ---------
 * Physical to logical colour definition.
 * Logical colour, Physical colour,
 * Red level, Green level, Blue level.
 *
 */
os_error *bbc_palette(int,int,int,int,int);


/* ------------- bbc_point -----------
 * Find the logical colour of a pixel at
 * indicated coordinates. x, y.
 *
 */
int bbc_point(int,int);


/* ------------------------- VDU and Mode Variables. --------------------- */

/* VDU variables. */

typedef enum {
  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
} bbc_vduvariable;

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


/* ------------- bbc_vduvar ---------
 * Read a single VDU or mode variable
 * value, for the current screen mode
 *
 */
int bbc_vduvar(int varno);


/* ------------- 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
 *
 */
os_error *bbc_vduvars(int *vars /*in*/, int *values /*out*/);


/* ------------- bbc_modevar -------
 * Read a single mode variable, for the
 * given screen mode.
 *
 */
int bbc_modevar(int mode, int varno);


/* ------------------------------- Other calls. -------------------------- */

/* ------------- bbc_get ---------
 * Return a character from the input
 * stream. 0x1xx is returned if an
 * escape condition exists
 *
 */
int bbc_get(void);


/* ------------- bbc_cursor ---------
 * Alter cursor appearance. Argument
 * takes values 0 to 3
 *
 */
os_error *bbc_cursor(int);


/* ------------- bbc_adval ---------
 * Read data from analogue ports or
 * give buffer data.
 *
 */
int bbc_adval(int);


/* ----------- bbc_getbeat -------
 * Return current beat value
 *
 */
int bbc_getbeat(void);


/* ----------- bbc_getbeats ------
 * read beat counter cycle length
 *
 */
int bbc_getbeats(void);


/* ---------- bbc_gettempo ------
 * read rate at which beat counter
 * counts
 *
 */
int bbc_gettempo(void);


/* ---------- bbc_inkey ---------
 * Return character code from an
 * input stream or the keyboard
 *
 */
int bbc_inkey(int);

/* ---------- bbc_setbeats ------
 * Set beat counter cycle length
 *
 */
os_error *bbc_setbeats(int);


/* ------------ bbc_settempo ---
 * Set rate at which beat counter
 * counts
 *
 */
os_error *bbc_settempo(int);


/* ----------- bbc_sound --------
 * Make or schedule a sound.
 * Params: Channel, Amplitude,
 * Pitch, Duration, Future Time
 *
 */
os_error *bbc_sound(int, int, int, int, int);


/* ------------ bbc_soundoff ----
 * Deactivate sound system
 *
 */
os_error *bbc_soundoff(void);


/* ----------- bbc_soundon -------
 * Activate sound system
 *
 */
os_error *bbc_soundon(void);
/* Activate sound system. */


/* ------------ bbc_stereo -------
 * Set stereo position for specified
 * channel. Params: Channel, Position
 *
 */
os_error *bbc_stereo(int, int);


/* ----------- bbc_voices --------
 * Set number of sound channels
 * 1, 2, 4 or 8.
 *
 */
os_error *bbc_voices(int);

#endif

/* end of bbc.h */