/*
 SCREEN.DOX

 License CC0 PUBLIC DOMAIN

 To the extent possible under law, Mark J. Olesen has waived all copyright
 and related or neighboring rights to FDOSTUI Library. This work is published
 from: United States.
*/


/*! \file screen.h
\brief screen drawing routines (no clipping)
The draw.h module contians clipping routines.
*/

/*!
\enum foreground
\brief foreground colors

\var foreground::fcolor_black
	black

\var foreground::fcolor_blue
	blue

\var foreground::fcolor_green
	green

\var foreground::fcolor_cyan
	cyan

\var foreground::fcolor_red
	red

\var foreground::fcolor_magenta
	magenta

\var foreground::fcolor_brown
	brown

\var foreground::fcolor_light_gray
	light gray

\var foreground::fcolor_gray
	gray

\var foreground::fcolor_light_blue
	light blue

\var foreground::fcolor_light_green
	light green

\var foreground::fcolor_light_cyan
	light cyan

\var foreground::fcolor_light_red
	light red

\var foreground::fcolor_light_magenta
	light magenta

\var foreground::fcolor_yellow
	light yellow

\var foreground::fcolor_white
	light white

*/

/*!
\enum background
\brief background color

\var background::bcolor_black
	black

\var background::bcolor_blue
	blue

\var background::bcolor_green
	green

\var background::bcolor_cyan
	cyan

\var background::bcolor_red
	red

\var background::bcolor_magenta
	magenta

\var background::bcolor_brown
	brown

\var background::bcolor_light_gray
	light gray
*/

/*!
\var _video_cols
	number of video columns
*/

/*!
\var _video_rows;
	number of video rows
*/

/*!
\fn int screen_init()
\brief configures the display screen
\returns 0 suceess display initialized
\returns !0 error unable to initalize the disply
*/

/*!
\fn void screen_deinit()
\brief returns the screen to mode on entry
\returns none
*/

/*!
\fn int screen_set25lines()
\brief set 25 line screen mode
\returns 0 success
\returns !0 failure
*/

/*!
\fn int screen_set50lines()
\brief set 50 line screen mode
\returns 0 success
\returns !0 failure
*/

/*!
\fn void screen_fill(
    unsigned char const                 i_char,
    enum foreground const               i_fcolor,
    enum background const               i_bcolor)
\brief fill entire screen display
\param[in] i_char fill character
\param[in] i_color foreground color
\param[in] i_bcolor background color
\returns none
*/

/*!
\fn void screen_fill_area(
    int const                           i_col,
    int const                           i_row,
    unsigned int const                  i_columns,
    unsigned int const                  i_rows,
    unsigned char const                 i_char,
    enum foreground const               i_fcolor,
    enum background const               i_bcolor);
\brief fill an area of the screen
\param[in] i_col column 
\param[in] i_row row
\param[in] i_columns number of columns
\param[in] i_rows number of rows
\param[in] i_char fill character
\param[in] i_fcolor foreground color
\param[in] i_bcolor background color
\returns none
*/

/*! 
\fn void screen_putc(
    int const                           i_col,
    int const                           i_row,
    unsigned char const                 i_char,
    unsigned int const                  i_repeat_count,
    enum foreground const               i_fcolor,
    enum background const               i_bcolor)
\brief draw a character to the screen
\param[in] i_col column 
\param[in] i_row row
\param[in] i_repeat_count number of times to repeat horizontally
\param[in] i_fcolor foreground color
\param[in] i_bcolor background color
\returns none
*/

/*!
\fn void screen_putvc(
    int const                           i_col,
    int const                           i_row,
    unsigned char const                 i_char,
    unsigned int const                  i_repeat_count,
    enum foreground const               i_fcolor,
    enum background const               i_bcolor);
\brief draw a character to the screen
\param[in] i_col column 
\param[in] i_row row
\param[in] i_repeat_count number of times to repeat vertically
\param[in] i_fcolor foreground color
\param[in] i_bcolor background color
\returns none
*/

/*!
\fn void screen_puts(
    int const                           i_col,
    int const                           i_row,
    unsigned char const __FAR*          i_string,
    unsigned int const                  i_length,
    enum foreground const               i_fcolor,
    enum background const               i_bcolor)
\brief draw a string to the screen
\param[in] i_col column 
\param[in] i_row row
\param[in] i_string string to write
\param[in] i_length length of string
\param[in] i_fcolor foreground color
\param[in] i_bcolor background color
\returns none
*/


/*!
\fn void screen_set_color(
    int const                           i_col,
    int const                           i_row,
    unsigned int const                  i_repeat_count,
    enum foreground const               i_fcolor,
    enum background const               i_bcolor);
\brief sets the foreground and background color of a horizontal region
\param[in] i_col column 
\param[in] i_row row
\param[in] i_repeat_count number of times to repeat horizontally
\param[in] i_fcolor foreground color
\param[in] i_bcolor background color
*/

/*!
\fn int screen_getc(
    int const                           i_col,
    int const                           i_row)
\brief reads  a character and it's attribute from the screen
\param[in] i_col column
\param[in] i_row rwo
\returns  character and attribute
*/

/*!
\fn screen_block_t __FAR*  screen_read(
    screen_block_t __FAR*               o_block,
    unsigned int const                  i_columns,
    int const                           i_col,
    int const                           i_row)
\brief read a line of screen memory
\param[out] o_block memory block to place screen data (must be large enough)
\param[in] i_columns number of columns to read
\param[in] i_col column
\param[in] i_row row
\returns ending address of block

curses version will add a null termination byte. 
Therefore, \a o_block must be \a i_columns+1 long.
The return address will be the termination
byte \a o_block+i_columns.
*/

/*!
\fn screen_block_t __FAR* screen_write(
    int const                           i_col,
    int const                           i_row,
    screen_block_t const __FAR *        i_block,
    unsigned int const                  i_columns)
\brief write a line of screen memory
\param[in] i_col column
\param[in] i_row row
\param[in] i_block block of memory containing data to write toscreen
\param[in] i_columns number of columns to write
\returns ending address of memory block
*/

