!bestlib.doc

supplementary source file 1 for The BESTLibrary

_16_p_read_xy.......read a pixel color of any "_16_c_save"ed image by (x,y)
_16_p_show..........write any "_16_p_save"ed image to the screen

- - - - - - - - - - - - - - - - - PLANE IMAGE  - - - - - - - - - - - - - - - - -
_16_c_to_i........X.convert any "_16_c_save"ed image to a "_16_i_save"ed image
_16_i_need..........calculate the memory requirement of any "_16_i_save"ed image
_16_i_read_off......read a pixel color of any "_16_i_save"ed image by offset
_16_i_read_xy.......read a pixel color of any "_16_c_save"ed image by (x,y)
_16_i_save..........store an image from the screen on a plane by plane algorithm
_16_i_show..........write any "_16_i_save"ed image to the screen
_16_p_to_i..... ..X.convert any "_16_p_save"ed image to a "_16_i_save"ed image
_16_restore_bg......restore from RAM a region of the screen background

  ----------------------------------------------------------------------------
------------------------------------ VGA256 ------------------------------------

_256_floodall.......flood the screen all one color
_256_pixel..........change the color of a pixel

--------------------------------------------------------------------------------


================================================================================
====================  BEGINNING OF LIBRARY DOCUMENTATION  ======================
================================================================================

                            !!! IMPORTANT NOTES !!!

*** NOTE  all functions in THE BEST LIBRARY require FAR calls -- if you are
          using a C compiler, set it to the Large Memory Model

*** NOTE  these variables need to be declared globally:
            asciiscan  keyp;    /* global structure "keyp"   */
            cursordata cursor;  /* global structure "cursor" */
            mousedata  msdata;  /* global structure "msdata" */

*** NOTE  a VGA display is assumed by all functions

*** NOTE  abscissa refers to x-coordinate and ordinate refers to y-coordinate

*** NOTE  if the speaker beeps unexpectedly, something illegal was attempted
          (ie. if "str_show" is not passed a NULL-terminated string)

*** NOTE  when allocating memory for strings, always remember to allocate
          [the length of the largest string] + 1 bytes
          (ex. for an 8 character maximum input into string "str":
str = (char *) malloc(9);                    /* [maximum length of input] + 1 */
txt_get_let(TCUR, TCUR, str, 8, '_', "What is your name? ", WHITE, BLUE, "Ted");
          will print  What is your name? Ted_____ at the current text cursor
          coordinates (TCUR, TCUR) and position the cursor under the T in Ted
          (Ted is the default name); a maximum of eight characters will be
          accepted

*** NOTE  all video output functions check the global variable "mousepresent"
          defined by mouse unit; if it is FALSE, the mouse cursor is ignored
          and if it is TRUE, the mouse cursor is hidden before performing any
          video output and shown again after the function finishes

*** NOTE  all video output (text and graphics modes) is performed with direct
          screen writes (the BIOS is not used) unless otherwise stated

*** NOTE  all coordinates are (0,0) - (MAXX-1, MAXY-1)
          - the text screen is usually 80x25, so the coordinates would be
            (0,0) - (79,24)
          - the VGA graphic screen is usually 640x480, so the coordinates
            would be (0,0) - (639,479)

*** NOTE  each text page has its own cursor position and cursor shape

*** NOTE  the cursor position is not modified by a function unless stated in
          the description of that function

*** NOTE  all functions that use the cursor use the cursor on the active text
	  page and not the visual text page (make the active text page the
	  same as the visual text page to operate on the visual text page)

*** NOTE  those parameters that ask for an "x" and a "y" will accept TCUR or
          MCUR, as described:
          - if "x" = TCUR, the text cursor abscissa is used
                   = MCUR, the mouse cursor abscissa is used
          - if "y" = TCUR, the text cursor ordinate is used
                   = MCUR, the mouse cursor ordinate is used
          in addition, some functions also accept MEM, which is explicity
          stated in the function's description

*** NOTE  those parameters that ask for a "length" and a "height" will accept
          negative numbers (to mean opposite direction)
          - positive "length" is to the right whereas negative is to the left
          - positive "height" is downward whereas negative is upward
          - ex: /* both draw the same box */
                boxfill(10, 10, 5, 5, YELLOW, COPY_IMAGE);
                boxfill(14, 14, -5, -5, YELLOW, COPY_IMAGE);

*** NOTE  all graphic images have a maximum size of exactly 65517 bytes

*** NOTE  all strings have a maximum length of 65531 characters

*** NOTE  some functions directly correspond to those offered by your compiler;
          the functions provided in THE BEST LIBRARY are more efficient and
          should be used over the compiler's functions

*** NOTE  the few functions that are still under development may be completed
          by the time you are reading this text; call me, George Vanous, at
          the phone number listed at the end of this document to verify the
          status of these functions

*** NOTE  if you have any questions or comments, feel free to contact me by
          phone or mail

*** NOTE  see !BESTLIB.H for a more brief description of every function

==========================--------------------------============================
----------------------------  GLOBAL DEFINITIONS  ------------------------------
                          --------------------------
/* COLOR DEFINITIONS */

BLACK.................... 0x0  0
BLUE..................... 0x1  1
GREEN.................... 0x2  2
CYAN..................... 0x3  3
RED...................... 0x4  4
MAGENTA.................. 0x5  5
BROWN.................... 0x6  6
LIGHTGREY................ 0x7  7
DARKGREY................. 0x8  8
LIGHTBLUE................ 0x9  9
LIGHTGREEN............... 0xA  10
LIGHTCYAN................ 0xB  11
LIGHTRED................. 0xC  12
LIGHTMAGENTA............. 0xD  13
YELLOW................... 0xE  14
WHITE.................... 0xF  15
BLINKCHAR................ 0x8  value to add to background color for blinking

--------------------------------------------------------------------------------

/* NUMBER DEFINITIONS */

ZERO.................... 0x00  0
ONE..................... 0x01  1
TWO..................... 0x02  2
THREE................... 0x03  3
FOUR.................... 0x04  4
FIVE.................... 0x05  5
SIX..................... 0x06  6
SEVEN................... 0x07  7
EIGHT................... 0x08  8
NINE.................... 0x09  9
TEN..................... 0x0A  10
ELEVEN.................. 0x0B  11
TWELVE.................. 0x0C  12
THIRTEEN................ 0x0D  13
FOURTEEN................ 0x0E  14
FIFTEEN................. 0x0F  15
SIXTEEN................. 0x10  16
SEVENTEEN............... 0x11  17
EIGHTEEN................ 0x12  18
NINETEEN................ 0x13  19
TWENTY.................. 0x14  20

PI...................... 3.141593  the venerable pi
PIx2.................... 6.283185  2 * pi
PIx4.................... 12.56637  4 * pi
PIby2................... 1.570796  pi / 2 (180 degrees)
PIby3................... 1.047197  pi / 3 ( 60 degrees)
PIby4................... 0.785398  pi / 4 ( 45 degrees)
PIby6................... 0.523599  pi / 6 ( 30 degrees)
E....................... 2.718282  the venerable e
SQRT2................... 1.414214  sqrt(2)
SQRT3................... 1.732051  sqrt(3)
GOLDEN.................. 1.618034  the golden ratio
DtoR.................... 0.017453  convert degrees to radians
RtoD.................... 57.29578  convert radians to degrees


--------------------------------------------------------------------------------

/* GENERAL-PURPOSE DEFINITIONS */

CR....................... '\r' carriage return character
LF....................... '\n' linefeed character
NO........................ -1  logical constant
YES....................... +1  logical constant
NONE......................  0  logical constant
OFF.......................  0  logical constant
ON........................ +1  logical constant
BOTH...................... +2  logical constant
UNMODIFY.................. +2  logical constant
FALSE...................... 0  logical constant
TRUE.................!(FALSE)  logical constant
BACKWARD.................. -1  logical constant
FORWARD................... +1  logical constant
WARM.................. 0x1234  warm boot identifier (like pressing ctrl-alt-del)
COLD....................... 0  cold boot identifier (like pressing reset button)
MAX....................... -1  logical constant
MIN....................... -2  logical constant
MAXX..................... 640  total screen x-length
MAXXHALF................. 320  half screen x-length
MAXMAXX.................. 640  total (screen)+(virtual screen) x-length
MAXMAXXHALF.............. 320  half (screen)+(virtual screen) x-length
MAXY..................... 480  total screen y-height
MAXYHALF................. 240  half screen y-height
MAXMAXY.................. 816  total (screen)+(virtual screen) y-height
MAXMAXYHALF.............. 408  half (screen)+(virtual screen) y-height
WATCH_MAX................ 100  maximum number of stopwatches
SIGNED.................... -1  signed number
UNSIGNED................... 1  unsigned number
TCUR...................... -1  text cursor
MCUR...................... -2  mouse cursor
MEM....................... -3  memory cursor (coordinates stored in memory)
TEXTSAVE................... 0  store text video memory
TEXTSHOW................... 1  restore text video memory
TEXT....................... 1  text mode
TEXT25..................... 3  25-line text mode
TEXT50..................... 2  50-line text mode
TEXT25F................... -1  forced 25-line text mode
TEXT50F................... -2  forced 50-line text mode
VGA16..................... 18  640x480x16 graphics mode
VGA256.................... 19  320x200x256 graphics mode
TEXTPAGE1.................. 0  text video page 1
TEXTPAGE2.................. 1  text video page 2
TEXTPAGE3.................. 2  text video page 3
TEXTPAGE4.................. 3  text video page 4
TEXTPAGE5.................. 4  text video page 5
TEXTPAGE6.................. 5  text video page 6
TEXTPAGE7.................. 6  text video page 7
TEXTPAGE8.................. 7  text video page 8
TEXTPAGELAST.............. 16  last video page: 4 for 50 lines, 8 for 25 lines
TEXTPAGEACTIVE............ -1  current active text video page
TEXTPAGEVISUAL............ -2  current visual text video page
TEXTIMAGE_OVERHEAD........  8  overhead, in bytes, of "textimagedata"ed objects
TOP.......................  1  top (same as up)
UP........................  1  upward direction
LEFT......................  2  leftward direction
RIGHT.....................  4  rightward direction
DOWN......................  8  downward direction
BOTTOM....................  8  bottom (same as down)
ALIGN_NONE................ -1  perform no alignment when outputting text
ALIGN_HORZ................. 0  horizontal center, shifting odd length left
ALIGN_VERT................. 1  vertical center, shifting odd length up
ALIGN_CENTER............... 2  horizontal and vertical center
ALIGN_RIGHT................ 3  right justify the text
COPY_IMAGE............ 0x0003  hexadecimal code for performing a direct copy
AND_IMAGE............. 0x0803  hexadecimal code for performing a logical AND
OR_IMAGE.............. 0x1003  hexadecimal code for performing a locical OR
XOR_IMAGE............. 0x1803  hexadecimal code for performing an eXclusive OR
COPY_IMAGE_SET........ 0x0013  perform a direct copy and set to scroll
AND_IMAGE_SET......... 0x0813  perform a logical AND and set to scroll
OR_IMAGE_SET.......... 0x1013  perform a locical OR  and set to scroll
XOR_IMAGE_SET......... 0x1813  perform an eXclusive OR and set to scroll

--------------------------------------------------------------------------------

/* ASCII CODE CONSTANTS */