POINT Software Programming/PPROG1.ISO/basic/pbasmlib/screen.doc

Text File | 1994-02-12 | 17.1 KB | 485 lines

PBASMLIB Assembly Language Routines for PB3C
Version 1.0
Text Screen/Memory Routines (SCREEN.ASM)
(C) Copyright 1994 by Tim Gerchmez
All Rights Reserved.

This module includes routines that let you manipulate text screens
and memory directly (read FAST!).  It is included in the PBASMLIB.PBL
library, and the routines contained herein will be immediately accessible
to your programs by using the statements $INCLUDE "PBASMLIB.INC" and
$LINK "PBASMLIB.PBL" at the top of your programs.

Note: For fastest speed possible, these routines do not
      do "snow checking" on CGA monitors.  If this feature
      is requested in a future version, it may be added.

All routines that directly manipulate the text screen work
with the currently visible page, unless otherwise noted.
All routines support 80x25 color text mode.  Some routines
will support other modes (40x25, 80x43, etc).  When in doubt
try the mode you want with a particular routine - it won't do
any damage.

================================================================================
sub blankin  <MCGA, VGA ONLY>

Makes the contents of the screen reappear instantly after using FADEOUT
or BLANKOUT.  FADEIN does the same thing, but slowly.  Note that you
cannot use blankin while the screen is visible - it must have been blanked
with BLANKOUT or faded with FADEOUT first.

Example: blankout  'Hide the screen
         color 15,1:cls
         print "This is a test"
         blankin   'Make the screen visible

================================================================================
sub blankout   <MCGA, VGA ONLY>

Blanks the contents of the screen out instantly.  You can then
change the screen contents "behind the scenes," and use FADEIN to
fade the new screen contents into view, or BLANKIN to instantly reshow
the screen.  Note that you cannot use blankout after using fadeout - the
screen contents must be currently faded in (visible) for this routine to work.

Example:  CLS  'clears the screen first
          call blankout  'Blanks screen, preparing for fadein
          locate 10,10:print "THIS IS A TEST"  'This won't show up right away
          fadein 20         'Fade the screen in slowly now

================================================================================
SUB blockfill (seg??,ofs??,nbytes??,byte%)

Fills an area of memory with a byte value.

seg??: Set to start segment of memory area to fill
ofs??: Set to start offset of memory area to fill
nbytes??: Set to number of bytes to fill (1-65535)
byte%: Set to byte value to fill memory with

Example: blockfill &hb800,0,4000,32  'Clear Screen

================================================================================
SUB Blockmove(sseg??,sofs??,dseg??,dofs??,nbytes??)

Moves a block of memory from one place to another
(actually makes a copy, doesn't change original).

sseg??: Set to source segment to move
sofs??: Set to source offset to move
dseg??: Set to destination segment to move
dofs??: Set to destination offset to move
nbytes??: Set to number of bytes to move (1-65535)

Example: blockmove &hb800,0,&hb800,&h1000,4000 'Copy text page 0 to page 1

================================================================================
FUNCTION calcaddr(y%,x%)

Calculates an absolute screen offset address,
given Y and X positions.

y%: Set to Y location (row) (1-25) on screen
x%: Set to X location (column) (1-80) on screen
calcaddr: Returns absolute text screen offset address
(80x25 screen) - 0-4000.

Example: print calcaddr(15,5)

================================================================================
FUNCTION calcattr(fgd%,bckg%)

Returns an attribute byte value, given a foreground
and background color.  Opposite of calcucolors.

fgd%: Set to foreground character color
bckg%: Set to background character color
calcattr: Returns attribute byte value (FN)

Example: a%=calcattr(10,1)

================================================================================
SUB calcucolors(attr%, foregd%, bckg%)

Given a screen attribute value, returns foreground
and background colors to be used with the COLOR statement.
Opposite of CALCATTR.

attr%: Set to attribute value (0-255)
foregd%: Returns foreground character color value
bckg%: Returns background character color value

Example: calcucolors 31,f%,b%

================================================================================
SUB calcyx(offset%,y%,x%)

Given an absolute text screen offset address,
calculates the Y (row) and X (column) locations
on the screen (80x25 screen).  Opposite of CALCADDR.

offset%: Set to absolute text screen offset value
y%: Returns Y position (1-25) in y%
x%: Returns X position (1-80) in x%

Example: calcyx 320,y%,x%

================================================================================
SUB caveincls(delay%)

Clears the screen by "caving it in" on itself.
Uses the current color values set by COLOR.

d%: Set to delay value (15-20 is about right)

Example: caveincls 15

================================================================================
SUB caveoutcls(delay%)

Clears the screen by "caving it outward."
Uses the current color values set by COLOR.

d%: Set to delay value (15-20 is about right)

Example: caveoutcls 15

================================================================================
SUB clearline(ln%)

Clears the text screen line specified.

ln%: Set to screen line to clear (normally 1-25)

Example: clearline 25  'clear bottom screen line

================================================================================
SUB clsto(fgd%,bkg%)

Similar to CLS, but works only in text modes, and lets
you "clear to" any color you want without changing the
COLOR attributes or the cursor location.  Essentially a
way of changing screen background colors, but clears the
screen at the same time.

fgd%: Set to foreground color of new, cleared screen
bkg%: Set to background color of new, cleared screen

Example: clsto 31  'Blue screen, bright white "spaces"

================================================================================
SUB dscroll (uly%,ulx%,lry%,lrx%,atr%)

Scrolls a portion of the screen down by one row.

uly%: Set to upper left Y position (1-25)
ulx%: Set to upper left X position (1-80)
lry%: Set to lower right Y position (1-25)
lrx%: Set to lower right X position (1-80)
atr%: Set to attribute to scroll into blanked area

Example: dscroll 1,1,25,80,1

================================================================================
sub fadein(dly%)      <MCGA, VGA ONLY>

Fades the screen in after fading it out with FADEOUT or blanking with
BLANKOUT.  You can change the contents of the screen while it's faded out,
then call fadein to fade the new screen in.  See FADEOUT and BLANKOUT for
more information.  The delay value you provide lengthens the time it takes
to fade in as the value increases.  Fadein works with most screen modes,
graphics and text included.

dly%: Set to delay value (0-32767)

Example: fadein 20  'Fade the screen in with a delay value of 20

================================================================================
sub fadeout(dly%)   <MCGA, VGA ONLY>

Allows you to slowly fade the contents of the screen out in any
screen mode, graphics or text.  You can then change the contents of
the screen if desired, and fade it back in using FADEIN, or make it
reappear instantly using BLANKIN.  The delay value you provide to
FADEOUT will lengthen the time it takes to fade out as the value gets
higher.

dly%: Set to delay value (0-32767)

Example: fadeout 20   'Fade the screen out
         sleep        'Wait for a keypress
         fadein 20    'Fade the screen back in

================================================================================
sub faderestore  <MCGA, VGA  with PC/AT or PS/2 ONLY>

Restores the normal screen if CTRL-BREAK was pressed during a FADEIN
or FADEOUT.  This will leave the screen in a partially faded state, and
FADERESTORE will change the screen back to its default values.  If this
routine is used on a PC/XT, the screen will be cleared and screen contents
lost, or the result may be unpredictable.

Example: call faderestore

================================================================================
SUB fastprint(s$,attrib%,y%,x%)

Prints very quickly to the screen, using direct
video buffer access.  Prints to currently visible
page.

s$: Set to string to print.  Cursor is not updated
    and no CRLF is performed afterward.
attrib%: Set to attribute to print string in
y%: Set to Y position (normally 1-25) on screen to print at
x%: Set to X position (normally 1-80) on screen to print at

Example: fastprint "Testing",7,1,1

================================================================================
SUB fillattr(x%)

Fills the text screen with the attribute specified.
CALL fillattr(x%), where x%=0-255.
Uses current visual screen page (normally 0).

Example: fillattr 31  'Set screen to white-on-blue

================================================================================
SUB fillchar(x%)

Fills the text screen with the ASCII character specified.
Syntax: CALL fillchar(x%), where x%=0 to 255
Uses PowerBASIC's "active" screen page (normally 0).

Example: fillchar 65  'Fill screen with "A"

================================================================================
SUB lscroll(uly%,ulx%,lry%,lrx%,atr%)

Scrolls a portion of the screen left by one column.

uly%: Set to upper left Y position (1-25)
ulx%: Set to upper left X position (1-80)
lry%: Set to lower right Y position (1-25)
lrx%: Set to lower right X position (1-80)
atr%: Set to attribute to scroll into blanked area

Example: call lscroll(uly%,ulx%,lry%,lrx%,atr%)

================================================================================
SUB pgcopy(source%,dest%)

Allows copying of one text-screen page to another,
mimicking QuickBASIC's PCOPY command in text mode.
This will not work with a monochrome card, since
only one screen page is available.
No check is done for illegal values, so be careful.


source%: Set to source page (0-3 CGA, 0-7 EGA/VGA) to copy
dest%: Set to destination page (0-3 CGA, 0-7 EGA/VGA) to copy

Example: pgcopy 0,1

================================================================================
SUB pglayer(source%,dest%)

Similar to PGCOPY, but only stores the source to the
destination if the destination is blank at the stored
spots.  This has the effect of "layering" the source
screen onto the destination screen.  Will not work with
monochrome card, since only one page is available.  No
check is done for illegal values, so be careful.

source%: Set to source page (0-3 CGA, 0-7 EGA/VGA)
dest%: Set to destination page (0-3 CGA, 0-7 EGA/VGA)

Example: pglayer 1,0

================================================================================
SUB pgswap(page1%,page2%)

Allows you to swap the contents of two text-screen pages,
replacing one with the other.  Won't work with a monochrome
card, as only one screen page is available.  No check is done
for illegal values, so be careful.

page1%:Set to first page (0-3 CGA, 0-7 EGA/VGA)
page2%: Set to second page (0-3 CGA, 0-7 EGA/VGA)

Example: pgswap 0,1  'Swaps the contents of page 0 and page 1

================================================================================
SUB readchar(y%,x%,ch%,atr%)

Reads a character from the visible text screen page
(80x25 only), and returns character/attribute values.
MUCH faster than using the SCREEN function.

y%: Set to text screen Y offset (1-25) to read
x%: Set to text screen X offset (1-80) to read
ch%: Returns character value at y%,x%
atr%: Returns attribute value at y%,x%

Example: readchar 1,1,ch%,atr%

================================================================================
SUB reattr(oldattr%,newattr%)

Changes all specified attributes on the text screen
(visible page) to a new attribute.  This allows you to
recolor only specific portions of the screen.

oldattr%: Set to old attribute to change
newattr%: Replaces all old attributes found with new attributes

Example: reattr 7,31

================================================================================
SUB rechar(oldchar%,newchar%)

Changes all specified characters on the text screen
(visible page) to a new character.

oldchar%: Set to old character to change
newchar%: Replaces all old characters found with new character

Example: rechar 32,asc(".")  'Changes all spaces on screen to dots

================================================================================
SUB restorearea(uly%,ulx%,s$)

Allows you to restore an area of the screen
previously saved with SAVEAREA$.

uly%: Set to upper-left Y position to restore area to
ulx%: Set to upper-left X position to restore area to
s$: Set to string previously retrieved with SAVEAREA$

Example: restorearea 1,1,s$

================================================================================
SUB restoretextarea(uly%,ulx%,s$)

Restores an area of the screen (text portion only)
previously saved with SAVETEXTAREA.

uly%: Set to upper-left Y position to restore area to
ulx%: Set to upper-left X position to restore area to
s$: Set to string previously retrieved with SAVETEXTAREA$

Example: restoretextarea 1,1,s$

================================================================================
SUB rscroll(uly%,ulx%,lry%,lrx%,atr%)

Scrolls a portion of the screen right by one column.

uly%: Set to upper left Y position (1-25)
ulx%: Set to upper left X position (1-80)
lry%: Set to lower right Y position (1-25)
lrx%: Set to lower right X position (1-80)
atr%: Set to attribute to scroll into blanked area

Example: rscroll 1,1,25,80,7

================================================================================
function savearea$(uly%,ulx%,lry%,lrx%)

Saves an area of the text screen (visual page)
and returns a string holding the saved area.

uly%: Set to upper left Y position
ulx%: Set to upper left X position
lry%: Set to lower right Y position
lrx%: Set to lower right X position
savearea$: Returns string (see RESTOREAREA)

Example: s$=savearea$(1,1,25,80) 'Returns 4004-byte string

================================================================================
function savetextarea$(uly%,ulx%,lry%,lrx%)

Saves only the text portion of an area of the screen,
thus using only half the memory.  Use RESTORETEXTAREA
with the string returned by this routine to restore the
saved area.

uly%: Set to upper left Y position
ulx%: Set to upper left X position
lry%: Set to lower right Y position
lrx%: Set to lower right X position
savetextarea$: Returns string (see RESTORETEXTAREA)

Example: s$=savetextarea$(1,1,25,80) 'returns 2004-byte string

================================================================================
SUB stepfill(seg??,ofs??,nbytes??,stepval%,byte%)

Fills an area of memory with a byte value, using a
given step value.  Similar to a FOR-NEXT loop using
a step value and POKE.  The fill starts at the given
offset, and skips stepval%-1 bytes between each store.
Useful for filling different types of arrays, and the screen.

seg??: Set to start segment of memory area to fill
ofs??: Set to start offset of memory area to fill
nbytes??: Set to number of bytes to fill (1-65535)
stepval%: Set to step value (for example, stepval of
          2 will fill every other byte, starting with
          the first byte indicated in ofs??).
byte%: Set to byte value to fill memory with

Example: stepfill &hb800,0,2000,2,asc("A") 'Fill the screen with "A"
        stepfill &hb800,1,2000,2,31 'Then fill attribute bytes

================================================================================
SUB tearcls(delay%)

Clears the screen so that it appears to "tear" apart.

delay%: Set to delay value (15-20 is about right).

Example: tearcls 15

================================================================================
SUB uscroll (uly%,ulx%,lry%,lrx%,atr%)

Scrolls a portion of the screen up by one row.

uly%: Set to upper left Y position (1-25)
ulx%: Set to upper left X position (1-80)
lry%: Set to lower right Y position (1-25)
lrx%: Set to lower right X position (1-80)
atr%: Set to attribute to scroll into blanked area

Example: uscroll 1,1,25,80,7

================================================================================
FUNCTION vidseg

Returns current text-screen segment -
&hb000 for monochrome or &hb800 for color.

vidseg: Returns video segment (FN)

Example: print vidseg

================================================================================
SUB writechar(y%,x%,ch%,atr%)

Writes a character to the active text screen page
(80x25 only) using specified attribute value.
MUCH faster than locate/color/print combination, and
doesn't disturb cursor or COLOR settings.

y%: Set to text screen Y offset (1-25)
x%: Set to text screen X offset (1-80)
ch%: Set to ASCII value of character to write (0-255)
atr%: Set to attribute value to write

Example:  writechar 1,1,1,31