XINIT - High Resolution Graphics Support Module Documentation - Version 1.0
(c) Paul Bradshaw 72177,2032 (July 15th, '87)


  The XINIT program initializes the graphics "environment", and allows you to
set several parameters and select among the many different features supported
by this environment.  When first invoked, XINIT installs a small "module" into
high memory.  This MUST be done from TRSDOS Ready, and *not* from within
Basicg, or some other program.  After that, you may SYSGEN the module into
place, and use XINIT from within Basic or other programs to set certain
features.  The module installed is REQUIRED for the operation of most programs
in the graphics environment, and the data located there may be used freely by
your own programs (see Technical Notes for details in accessing this data).

  The format of the command is as follows (items within square brackets are
optional):

XINIT [(parms)]

The parameters are:

      BUFFER=n  -  Specify a bank (1-31) for use as a storage buffer for
                "frames" (see XCUT/XPASTE).  Specifying BUFFER=0 will release
                the bank currently reserved (may be abbreviated to 'B').

      CLEAR     -  Clears the currently defined BUFFER bank.

      IMAGE=n   -  Specify a bank (1-31) for use as an IMAGE buffer (not
                currently supported).  IMAGE=0 will release any reserved bank.

      DISK=n    -  Specify a bank (1-31) for use as a Disk Input/Output buffer
                (for use by XLOAD/XSAVE/etc).  DISK=0 will release the bank.

      GRON      -  Turns the graphics screen on, and sets "graphics on" as the
                default screen mode.  If not specified, then mode is unchanged

      TEXT      -  Turns the graphics screen off, and sets "text only" as the
                default screen mode.  If not specified, then mode is unchanged

      SLOW      -  Turns Video Waits on, and sets "waits on" as the default
                mode.  SLOW=NO will turn waits off; otherwise mode is unchanged

      MIXED     -  Turns on the mixed text/graphics mode (RS board only).
                MIXED=NO will restore "graphics only".  Default is MIXED=YES.

      XVIEW=n   -  Scrolls graphics display over to column 'n' (RS board only).
                XVIEW=0 restores "normal" display.  Unchanged if not specified.

      YVIEW=n   -  Scrolls graphis display up to row 'n' (RS board only).
                YVIEW=0 restores "normal" display.  Unchanged if not spedified.

      NO        -  Suppresses all output to the display.  This is for use
                within another program (such as BASICG), where you don't
                want to disturb what's on the display.  Also suppresses all
                error messages except "Parameter Error", so be careful!

      REMOVE    -  Attempts to remove the High Memory module that XINIT
                installed to reclaim the memory.  This is not always possible.

  All parameters may be abbreviated to their first character (i.e. "B=1" for
"BUFFER=1", etc).  If you don't specify any parameters, and the high memory
module as already been installed, then XINIT will display the message "Nothing
Done!"  

  You may use XINIT as many times as you wish.  When FIRST used, XINIT will
install the High Memory Module (this must be done from DOS Ready).  It may THEN
be used from within BASICG via the SYSTEM"XINIT (parms)" command (i.e.
SYSTEM"XINIT (B=1)" is perfectly legal to reserve the buffer bank as bank 1
once the XINIT module is installed). You should use XINIT to change the status
of the graphics board instead of using the old GRON and GROFF commands. XINIT
is required for operation of XCUT, XPASTE and XCLS (and other future programs
in this series). 

  When operating XINIT, or other graphics utility, from within BASICG, please
note that any error that results in a return to the "Ready" prompt will disable
the graphics screen.  Any subsequent graphics command will bring the graphics
screen back up.  Also note that when using the INPUT command, the graphics
screen is disabled.  To overcome this quirk, use the LINE INPUT command, as it
leaves the graphics screen alone.  Also note that you can use ON ERROR GOTO to
trap any errors returned by these programs.  You may then use the "_ERRRTN"
location within the XINIT high memory module to determine what sort of error
occured (see Technical Notes for more details).

  Using the SLOW=N parameter disables video waits, and speeds up the operation
of any program that accesses the graphics screen (such as XCUT and XPASTE).
There is a trade-off for this extra speed, however -- the screen will appear
"snowy" during any graphics access.  If speed is important at the expense of a
clear display , then use the SLOW=N parameter.  If the apperance of the display
is of importance and time is not at a premium, then use the SLOW parameter.
Note, that if the graphics screen is NOT being displayed, then the SLOW=N
parameter doesn't have any affect on the display, and SHOULD be specified to
speed things up.

Special Note for Micor-Labs board owners:
  Several parameters (MIXED, XVIEW and YVIEW) have no effect when used with the
Micro-Labs board.  This is because that board lacks some special features of
the Radio Shack graphics board.  Also note that the function of the SLOW
parameter serves the same function as the MIXED parameter does for the Radio
Shack boards -- When SLOW is specified, then Mixed Text/Graphics mode is
enabled.  The mode is disabled by SLOW=N instead of MIXED=N.  There is no way
to alter the status of video waits on the Micro Labs boards.  Video waits are
always on.  Programmers who wish to keep their programs portable across both
boards should take note of
these differences.

Error Messages
==============

'No HIGH memory available for module'
 -- You are attempting to install the high memory module with XINIT from within
another program (such as from within BASICG).  Other possibilities include High
Memory is full (you already have many modules in high memory), or some program
has "locked" high memory.  Use XINIT from LS-DOS (or TRSDOS) Ready to install
the module (i.e. the first time you use XINIT), or SYSGEN the module so that it
will always be available without having to re-install it each time.

'Nothing Done!'
 -- You didn't specify any parameters to do anything, and the high memory
module was already found in memory

'Parameter Error!'
 -- You mis-spelled a parameter, or you used a parameter other than BUFFER,
IMAGE, DISK, CLEAR, TEXT, GRON, SLOW, and NO.

'xxxx Bank is Out of Range!'
 -- the requested bank ("xxxx" is "BUFFER", "IMAGE" or "DISK I/O") is beyond
the range permitted by the various memory boards available for the TRS80
Model 4.  Bank numbers must range from 1 to 31.

'Requested Bank  x is Not Available'
 -- The bank you requested with the BUFFER=, IMAGE= or DISK= parameters is
being used by some other program.  Select another bank number and try again.
Will also occur if you refer to a bank that is not in your system (i.e. you
specify BUFFER=3, in a 128K system that doesn't have a bank number 3).

'XINIT Module not found -- Cannot Remove!'
 -- You used the REMOVE parameter of XINIT when the high memory module was not
installed.

'Can't reclaim High Memory -- XINIT not Removed'
 -- The XINIT high memory module is "trapped" in high memory by other
modules.  Use a program such as UNSET.CMD (from DL6 of the LDOS SIG of
CompuServe) to free up the high memory, or press the RESET button of the
computer to regain the memory.

'xxxx Already in Use.'
 -- The requested buffer ("xxxx" is "BUFFER", "IMAGE" or "DISK I/O") is already
assigned to a bank.  Use xxxx=0 to release the bank if you wish to re-assign
it.  Note that when you release a bank via "xxxx=0", you lose all information
in that bank.

'xxxx is Already Unassigned!'
 -- The requested buffer ("xxxx" is "BUFFER", "IMAGE", or "DISK I/O") was
"released" with xxxx=0, when it had not previously been assigned to
anything.  Assign the buffer with xxxx=n, where n=1 to 31.

'No Frame Buffer Specified -- Cannot CLEAR!'
 -- You specified the CLEAR parameter to clear the Frame Buffer, when no Frame
Buffer had been defined.  Use BUFFER=n to define a Frame Buffer first.

===================

  This program, and the entire graphics environment and documentation, is
copyright 1987 by Paul Bradshaw, and is distributed as "ShareWare".  This means
that I am a starving college student, and if you like this program, you are
encouraged to send a contribution of $5, along with your mailing address and
CompuServe ID number, to encourage further developement of this and other
programs, offset the cost of developing and distributing this program, and to
keep food on my table.  For this $5, you will become a registered user of this
software, and will be immediately notified of any fixes, updates, and/or
further additions and enhancements of the software.  If response is good, and a
major update of this software is issued, it will be mailed directly to all
registered users -- not uploaded here to CompuServe.  I will support this
software to registered users only, to the best of my ability, and strongly
encourage your comments, suggestions, and criticisms of this software.
Contributions should be mailed to:

Paul Bradshaw [72177,2032]
1372 West Second Ave
Columbus OH 43212

  Be sure to state the software you are registering, and give a brief
description of your system (drives, memory, which graphics board, etc).  This
contribution will register you for XINIT, XCUT, and XPASTE.  Further additions
to the graphics environment may be separately registered.  Your generosity is
greatly appreciated!

  You are free to copy and/or give away this software to anyone, or post it on
other bulletin boards, for private use PROVIDING that the program and
documentation (including this statement) are kept intact, unaltered, and
bundled together, and that no charge shall be made for such distribution of any
kind without the written permission of the author.  For rights to distribute
this software commercially, or as part of a collection of software, please
contact me either on Compuserve or at home, at the above address.  If you are
not happy with the program, do not intend to use it, or do not intend to
register yourself as a user, please erase this program and documentation from
your disks.
