Turbo Toolbox/Turbo_Toolbox.iso/sharew/asic400/lib/ibrary.doc

Text File | 1993-04-23 | 25.1 KB | 735 lines

                    IBRARY: An ASIC Library
                  =-------------------------=
                          Version 1.0

       IBRARY  Copyright (c) 1993  Thomas G. Hanlin III



This is IBRARY, a library of over 135 routines written in
assembly language for use with David A. Visti's ASIC compiler.
You will need ASIC 4.0 or later and a linker to use IBRARY.  An
assembler is not necessary.  The IBRARY collection is
copyrighted and may be distributed only under the following
conditions:

   All IBRARY files must be distributed together as a unit.
   No files may be altered, added, or deleted from this unit.

YOU USE THIS LIBRARY AT YOUR OWN RISK.  I have tested it on my
own computer, but I will not assume any responsibility for any
problems which IBRARY may cause you.  If you do run into a
problem, please let me know about it, and I will do my best to
verify and repair it.

It is expected that if you find IBRARY useful, you will
register your copy.  You may not use IBRARY routines in
programs intended for sale unless you have registered.

Registration gets you the latest version of IBRARY, complete
with full source code.  The assembly language code is designed
for MASM 6.0 and may require alteration for other assemblers.
See the ORDER.FRM file for ordering information.

Warning: Unregistered use of IBRARY for more than 30 days may
cause the author to practice yodeling outside your bedroom
window at night.  Don't let this happen to you!

                       Table of Contents                 page 2



 Synopsis and Legal Info .................................... 1

 Table of Contents .......................................... 2

 Overview ................................................... 3

 Equipment Info ............................................. 4

 Extended Math .............................................. 8

 Graphics ................................................... 9

 Interrupts ................................................ 12

 Joystick Support .......................................... 13

 Mouse Support ............................................. 14

 Miscellaneous ............................................. 17

                           Overview                      page 3



As of version 4.0, ASIC became a much more powerful language,
with the introduction of library support.  A library is very
like an extension to a compiler.  It provides capabilities
which are perhaps insufficiently general-purpose to add into
the language itself, but which may nonetheless be of use to
many people.  Libraries let you customize a language to suit
your particular needs.

The routines in IBRARY are contained in a library file, which
is denoted by the extension .LIB.  So, the IBRARY library is
named IBRARY.LIB.  How you access this library depends on which
version of the compiler you use: ASIC.EXE or ASICC.EXE.

In the case of ASICC.EXE, the command to compile a program
which uses IBRARY looks something like this:

   ASICC progname B/OBJ LIB=IBRARY LNK=C:\DOS

Here, "progname" is the name of the program to compile.  When
you use a library, compilation turns into a multi-part process.
ASIC first turns your .ASI code into an .OBJ file.  It then
calls your LINK.EXE program to combine the .OBJ file with the
routines you need from IBRARY.LIB, turning the result into an
.EXE program.  In the above command line, the LNK=C:\DOS part
tells ASIC that it can find LINK.EXE in a directory called
C:\DOS.  You will need to use the appropriate directory for
your computer.  Note that LINK.EXE does not come with ASIC.  It
is provided with Microsoft languages and many DOS versions,
though.  Borland also has a linker, called TLINK.EXE.

IBRARY includes a batch file, ASICMAKE.BAT, to make all this
easier.  You will need to modify it to have the appropriate
LNK= setting, but once that's done, you can simply type:

   ASICMAKE progname

...in order to compile and link your program.

In the case of the editor/environment, the initial setup is a
bit different.  From the Compiler menu, pick Advanced Options.
From the Advanced Options menu, do the following:

   choose .OBJ output file generation
   set library name to IBRARY
   set link path to wherever your LINK.EXE is (e.g., C:\DOS)

It's as easy as that!  You are now set up to use libraries.  A
good first test would be to compile the IBRARY quick demo,
subtly entitled DEMO.ASI.  Give it a try!

                        Equipment Info                   page 4



The equipment routines give you information about the computing
environment. This includes both installed software and hardware.

The first function allows you to determine if an "enhanced"
keyboard (101-key) is installed.  It may not be able to figure
out what the keyboard is on some older not-quite-clone PCs, in
which case it will take the safe way out and report that there
is no enhanced keyboard.  This routine returns -1 if there is
an enhanced keyboard present, 0 if not.

   CALL SUB "KbdType" Enhanced

Want to know the type of processor (CPU) being used?  Can do!

   CALL SUB "Processor" CPUType

The results will be returned as a number which can be decoded
as follows:

   0    NEC V20
   1    8088 or 8086
   2    80186
   3    80286
   4    80386
   5    80486

Maybe you'd like to check for a CD-ROM drive:

   CALL SUB "CDROM" Drives

This tells you how many logical drives exist, if there is a
CD-ROM available. If not, it will return 0.  Note that the
CD-ROM installation check conflicts with the GRAPHICS.COM
installation check for DOS 4.0, due to some screw-up at IBM or
Microsoft.

The number of floppy drives installed is retrieved like this:

   CALL SUB "Floppies" Drives

                        Equipment Info                   page 5



There may be up to four floppy drives in a system; however, the
AT CMOS data area only directly supports two. This makes it
easy to find out what kind of drives the first two are, but not
the second two.  Oh well, guess we'll have to settle for what
we can get, right?

   CALL SUB "FloppyType" Drive1 Drive2

The results from FloppyType are returned as follows:

   0    no drive
   1    5 1/4"    360K
   2    5 1/4"    1.2M
   3    3 1/2"    720K
   4    3 1/2"    1.44M

Result codes of 5-7 are available, but not yet defined.  One
might guess that the 2.88M drive supported by DOS 5.0 will be
drive type 5.  Has anybody seen one of those puppies yet?

New memory types sure have burgeoned over the years...
expanded, extended, and now XMS.  There are routines to check
all of these:

   REM get total extended memory installed
   CALL SUB "AllExtMem" AllExt&

   REM get BIOS extended memory installed
   CALL SUB "GetExtM" BiosExt&

   REM get expanded (EMS) memory installed
   CALL SUB "GetEMSm" TotalPages FreePages

   REM get XMS memory installed
   CALL SUB "GetXMSm" BigFree& TotalFree&

When you're dealing with extended memory, whether it be
BIOS-type or using the XMS standard, the results are returned
in kilobytes.  Multiply 'em by 1024 to convert to bytes.  When
you're dealing with expanded memory (EMS), the results are in
pages of 16,384 bytes.

I might note, by the way, that Microsoft seems to have
intentionally crippled the XMS standard.  It can only support a
maximum of 64 megabytes.  This may seem like a lot now, but
it'll seem cramped soon enough.

A few more routines to get the versions of EMS and XMS, if any:

   CALL SUB "GetEMSv" MajorV MinorV
   CALL SUB "GetXMSv" MajorV MinorV

These return the major and minor version numbers as two
separate integers. For example, EMS 4.0 would return major
version 4, minor version 0.

                        Equipment Info                   page 6



It's nice to know a little about the operating environment.
With the below routines, you can find out what the DOS version
is; what version of 4DOS, if any, is in use; and whether
Microsoft Windows is running.

   CALL SUB "GetDOSv" MajorV MinorV
   CALL SUB "Get4DOSv" MajorV MinorV
   CALL SUB "WinCheck" MajorV MinorV

These return results as major and minor version numbers, as
discussed on the previous page.  The Get4DOSv and WinCheck
routines return zeroes if 4DOS and Windows, respectively, are
not available.

There are a couple of curious features of GetDOSv to keep in
mind.  If the version is 10 or higher, you're running in OS/2
compatibility mode.  DOS version 10 is actually OS/2 1.0,
version 20 is OS/2 2.0, and so on. Secondly, if you're using
DOS 5.0, the version reported may not be 5.0-- DOS 5.0 can be
told to reply with a lower version number to allow some older
software (which checks for a specific DOS version) to run
properly.

One final routine that should be of some value is the one that
allows you to find out what kind of display is available.  It
tells you the specific adapter and whether the display is color
or monochrome.  There is one case in which it can be confused,
however-- if the adapter is CGA, the display is assumed to be
color, since there is no way for the computer to know any
differently.  So, although this routine provides a good idea of
what is available, it would be a good idea to provide an option
to tell the program that a monochrome display is attached.
Microsoft normally uses "/B" for this purpose, so that might be
a good standard to stick with.

   CALL SUB "GetDisplay" Adapter Mono

This returns Mono = -1 for a monochrome display, or Mono = 0
for a color display.  The Adapter may be any of the following:

   1    MDA
   2    Hercules
   3    CGA
   4    EGA
   5    MCGA
   6    VGA

                        Equipment Info                   page 7



Aside from some of the oldest semi-clones, it's possible to
find out what sort of machine you're using by looking at a
specific data byte.  You can access this as follows:

   CALL SUB "PCType" PcType

The result will need decoding.  Here are some known values:

   255   PC or XT
   254   XT
   253   PCjr
   252   PC AT
   251   XT
   250   PS/2 Model 30
   249   PC Convertible
   248   PS/2 Model 70 or 80
   154   Compaq Portable
    45   Compaq Portable

Likewise, all but some of the oldest semi-clones maintain a
BIOS date value which tells you how old the BIOS ROM is.  This
can be retrieved with the following routine:

   CALL SUB "PCDate" PCDate$

If your program is running on one of the rare old machines
which don't maintain a valid BIOS date, this routine will
return "No Date " instead of an actual date.

As far as a program is concerned, DR DOS is essentially the
same as MS-DOS.  Still, it's always nice to know what sort of
operating environment you have.  You can find out whether your
program is running under DR DOS with the following function:

   CALL SUB "DrDos" DrDos
   IF DRDOS = 0 THEN
      PRINT "MS-DOS"
   ELSE
      PRINT "DR DOS"
   ENDIF

The number of serial and parallel ports available can be
readily obtained:

   CALL SUB "CommPorts" CommPorts

   CALL SUB "PrtPorts" PrtPorts

                         Extended Math                   page 8



The extended math routines provide a number of simple binary
functions which operate on an integer as a stream of bits.  You
may shift or rotate the bits in an integer by an arbitrary
amount in either direction.

Note that the normal ASIC integer has a length of 16 bits.

   CALL SUB "LShift" Number ShiftCount

   CALL SUB "RShift" Number ShiftCount

   CALL SUB "LRotate" Number ShiftCount

   CALL SUB "RRotate" Number ShiftCount

An identical set of routines is provided for long integers,
which have a length of 32 bits.

   CALL SUB "LShiftL" Number& ShiftCount

   CALL SUB "RShiftL" Number& ShiftCount

   CALL SUB "LRotateL" Number& ShiftCount

   CALL SUB "RRotateL" Number& ShiftCount

                       Graphics Support                  page 9



Much of the design of ASIC appears to be oriented on the notion
of creating the smallest possible programs.  In that respect,
it is perhaps not surprising that ASIC doesn't include strong
graphics support.  IBRARY provides support for EGA and VGA
modes which ASIC doesn't.  A future version of IBRARY will
include advanced support for many more video modes.

  Mode   Description
  ====   ================================================
    8    640x200,  16 colors, 80x25 text, EGA or better
   11    640x480,   2 colors, 80x25 text, VGA or better
   12    640x480,  16 colors, 80x25 text, VGA or better
   13    320x200, 256 colors, 40x25 text, VGA or better
   N0    360x480, 256 colors, 45x60 text, VGA or better
   N1    320x400, 256 colors, 40x25 text, VGA or better

The graphics routines all use the same nomenclature: a G,
followed by a mode number, followed by the specific name.  This
generic naming convention is used so that this chapter can
refer to all available modes.  For example, if I say "G#Color"
and you're using mode 12, you'd actually use "G12Color" in your
program.  Ok?

You just use G#Mode with a non-zero value to enter graphics
mode, or zero to restore text mode.  The text mode is assumed
to be the normal 80x25 color mode.  If this would not be your
choice, you can safely use the ASIC SCREEN statement to pick a
mode that's more to your liking.

Here's an example for typical handling of one of the non-SVGA
modes (in this case, mode 12):

   CALL SUB "G12Mode" 1
   REM *** your main program goes here ***
   CALL SUB "G12Mode" 0

                       Graphics Support                 page 10



One difference between ASIC and IBRARY is that, instead of
each "draw" command requiring a color parameter as in ASIC,
IBRARY provides a separate color command:

   CALL SUB "G#Color" Foreground Background

The foreground color is used by all graphics routines.  The
background color is used by the G#Cls routine.  Both foreground
and background colors are used in by G#Write and G#WriteLn.

Here is a list of the corresponding routines, first ASIC, then
IBRARY (replace the "#" with the appropriate mode number):

   REM get the color of a specified point
   colour = POINT(x, y)
   CALL SUB "G#GetPel" x y colour

   REM set the color of a specified point
   PSET (x, y), colour
   CALL SUB "G#Color" colour, backgnd
   CALL SUB "G#Plot" x y

   REM clear the screen and home the cursor (if any)
   CLS
   CALL SUB "G#Cls"

   REM get the current cursor position
   Row = CSRLIN
   Column = POS(0)
   CALL SUB "G#GetLocate" Row Column

   REM set the current cursor position
   LOCATE Row, Column
   CALL SUB "G#Locate" Row Column

   REM display a string without a carriage return and linefeed
   PRINT St$;
   CALL SUB "G#Write" St$

   REM display a string with a carriage return and linefeed
   PRINT St$
   CALL SUB "G#WriteLn" St$

If you need to print a number rather than a string, just use
the BASIC function STR$ to convert it.  If you don't want a
leading space, you can use the IBRARY routine, StrNB:

   CALL SUB "StrNB" Number St$

                       Graphics Support                 page 11



The IBRARY library has other graphics routines which have no
ASIC equivalent.  Here's a list:

   REM get the current colors
   CALL SUB "G#GetColor" Foreground Background

   REM draw a line
   CALL SUB "G#Line" x1 y1 x2 y2

   REM draw a box (set filled = 0 for frame, = 1 to fill it)
   CALL SUB "G#Box" x1 y1 x2 y2 filled

   REM get a VGA palette value
   CALL SUB "GetPalRGB" Colour RedI GreenI BlueI

   REM set a VGA palette value
   CALL SUB "SetPalRGB" Colour RedI GreenI BlueI


The most obvious aspect of palettes is in the ability to select
a set of colors suited to a specific application.  When showing
a picture of the sea, you might want mostly blues and greens,
for instance.  There are other implications in the ability to
quickly change a color across the entire screen, however.  It
allows for simple animation, the ability to fade in or fade
out, and other interesting effects.  Let your imagination run
loose and experiment a little!  You'll be surprised by the
power of palette manipulation.

                           Interrupts                   page 12



The interrupt routines give you access to some of the more
common BIOS and DOS interrupts, with a couple of convenience
features thrown in for good measure.

NOTE that these routines access the computer at a very low
level.  If you don't know what you're doing or make a mistake,
you could cause serious trouble.  Be warned!

Three routines are provided for accessing common interrupts.
They allow you to set the AX, BX, CX, and DX registers, and
return the new values of the same, plus the flags.

   REM  access to INT 21h, the DOS function handler
   CALL SUB "DosInt" AX BX CX DX Flags

   REM  access to INT 10h, the BIOS video handler
   CALL SUB "VidInt" AX BX CX DX Flags

   REM  access to INT 16h, the BIOS keyboard handler
   CALL SUB "KbdInt" AX BX CX DX Flags

Each of the 16-bit registers AX, BX, CX and DX can be divided
in half and accessed as 8-bit values: AH, AL, BH, BL, and so
on.  To make it easier to work with the registers as either
8-bit or 16-bit quantities, IBRARY includes routines to split a
16-bit word into two 8-bit bytes, and vice versa:

   CALL SUB "SplitWord" Word HiByte LoByte

   CALL SUB "JoinBytes" HiByte LoByte Word

The Flags value is a set of bit flags indicating the value of
the processor's flag register.  Bit 0 contains the carry flag
and bit 6 contains the zero flag.  There are a few other flags
involved, but you should never need to access them.

                       Joystick Support                 page 13



The joystick routines allow you to read the positions and
buttons of up to two joysticks.  If only one joystick is
attached, the results for the second joystick will usually be
meaningless.  In the case of the FlightStick joystick, if only
one joystick is attached, the value for the Y position of the
second joystick will indicate the FlightStick throttle setting.

The joysticks are labeled "A" and "B" for these routines, where
"A" is the first joystick.

You can read the joystick buttons individually or all at once.
If speed is an issue, you should read the buttons all at once,
as this is considerably faster than reading them one at a time
(assuming you wish to read more than one button).

   CALL SUB "JButtonA1" Pressed
   CALL SUB "JButtonA2" Pressed
   CALL SUB "JButtonB1" Pressed
   CALL SUB "JButtonB2" Pressed

   CALL SUB "JButtons" A1Pressed A2Pressed B1Pressed B2Pressed

The value returned will be -1 if the button is pressed or 0 if
it is not pressed.

You can also get the position of the joysticks.  This is
returned as a pair of X,Y coordinates for each joystick.  The
starting and ending positions depend on the individual
joystick, game adapter, and computer, so your program must
calibrate itself to the individual joystick.  I find a range of
about 5-140 on my FlightStick; your mileage may vary.

   CALL SUB "JPos" AX AY BX BY

Note that the joystick routines are BIOS-dependent.  They will
not work on some of the oldest PCs (those made before 1983 or
thereabouts).

                         Mouse Support                  page 14



The mouse routines provide full-featured mouse support.  You
can see if a mouse is available and how many buttons it has,
get the cursor position (either the current position or the
position at the last press or release of a specified button),
set the cursor position, change the cursor, set the mouse
range, get hardware information about the mouse, and so on.

There are two unusual mouse modes to be aware of.  One is text
mode, which is mapped to a 640x200 virtual display.  So, to
convert the results to text format, you need to divide the
cursor position by eight and add one.  To convert from text
format, subtract one and multiply by eight.

The second unusual mode is 320x200 CGA mode, which is also
mapped to 640x200. To convert the coordinates to this mode,
divide X by two.  To convert from this mode, multiply the X
coordinate by two.

All other modes use the actual display coordinates instead of a
bizarro virtual screen.  Why the peculiar CGA and text modes?
Well, evidently Microsoft never thought there'd be any video
adapters besides MDA and CGA, and decided to create a single
virtual screen size that worked for all modes. Not a bad idea,
I guess, but rather shortsighted.  Oh well.

One other nuisance that you may run into is that the mouse
cursor can't be directly turned on or off.  A "cursor
visibility" count is maintained-- if the mouse cursor was
turned on twice, you'll need to turn it off twice before it
will actually disappear.

Before using the mouse, you must initialize it.  The
initialization routine also checks to make sure that a mouse is
installed and tells you how many buttons it has.  It's best to
initialize the mouse after setting the screen mode, so the
mouse driver understands what mode you're using.  Not all mouse
drivers support all screen modes, but you can reasonably expect
any current mouse driver to support MDA, CGA, EGA, and VGA.
Hercules graphics mode is rarely supported, as it must be set
through direct hardware access rather than the standard
techniques, so the mouse driver has little way of knowing that
you've changed the mode.

The mouse routines will work equally well with two-button or
three-button rodents.  The middle button functions will return
0 with two-button mice.

                         Mouse Support                  page 15



I won't go into great detail on these routines, because they're
pretty much self-explanatory.  The mouse is a fairly easy
device to deal with, despite the quirks of Microsoft's driver.

You can initialize the mouse driver like so:

   CALL SUB "MInit" Buttons

This returns the number of mouse buttons available.  If there
is no mouse, zero will be returned.  Initialize the mouse AFTER
setting the screen mode, so it knows what the screen is like.

You can make the mouse cursor visible or invisible.  It will
function just as well in either state.  See the previous page
for some quirks.

   CALL SUB "MShow"
   CALL SUB "MHide"

There are many ways to get the mouse cursor position.  You can
get the current position, the position at which the mouse was
located when a particular button was pressed, or the position
when a button was released. If you choose a past position, you
can also find out how many presses or releases of the button
have taken place since you last checked.

   REM current coordinates
   CALL SUB "MWhereX" X
   CALL SUB "MWhereY" Y

   REM number of presses of a given button
   REM and mouse position at last press
   CALL SUB "MLClick" Count X Y
   CALL SUB "MMClick" Count X Y
   CALL SUB "MRClick" Count X Y

   REM number of releases of a given button
   REM and mouse position at last release
   CALL SUB "MLRelease" Count X Y
   CALL SUB "MMRelease" Count X Y
   CALL SUB "MRRelease" Count X Y

                         Mouse Support                  page 16



If you'd prefer to find out which buttons are currently
pressed, no problem:

   CALL SUB "MLButton" IsDown
   CALL SUB "MMButton" IsDown
   CALL SUB "MRButton" IsDown

Of course, you can also set the cursor location:

   CALL SUB "MLocate" X Y

The mouse cursor range can be restricted to a given area of the
screen.  This area is expressed by giving the upper left corner
and lower right corner of the rectangular area to which to
restrict the cursor.

   CALL SUB "MWindow" X1 Y1 X2 Y2

There are a variety of cursor shapes available for graphics
mode:

    0    hourglass ("please wait, program is working" symbol)
    1    pointing arrow (default)
    2    pointing hand
    3    crosshair
    4    target (box in a box)
    5    grabbing hand

If you have ideas for more, let me know and I'll see what I can
do.  Cursor shapes are not unduly difficult to define, although
it's technical enough so that I decided to avoid confusion by
leaving direct handling out of IBRARY.

   CALL SUB "MCursorG" CursorNr

                         Miscellaneous                  page 17



If there are not (yet) enough routines in a category to give
them their own classification, they come to roost here, in good
ol' Miscellaneous.  At the moment, this consists of a string
routine and some DOS output routines.

The StrNB routine works like ASIC's built-in STR$ function, but
strips all leading blanks from the result.  It works on plain
integers.

   CALL SUB "StrNB" Number Result$

The DOS output routines allow you to send output to the default
DOS device-- normally the screen, although it can be redirected
by the user to another device or to a file.  We start with a
generic PRINT replacement:

   CALL SUB "DosPrint" St$

That sends a string to standard output.  If you want a carriage
return and linefeed, you must add them yourself:

   CrLf$ = CHR$(13) + CHR$(10)
   St$ = St$ + CrLf$

The rest of the DOS output routines require ANSI.SYS or another
ANSI driver to be loaded.  They send the appropriate ANSI codes
to standard output.

   CALL SUB "DosCls"

   CALL SUB "DosColor" Foreground Background

   CALL SUB "DosLocate" Row Column