VSPACE

VSPACE is a subroutine that handles virtual space operations within Advanced Revelation.

VSPACE(function, status, screen, op_parameters)

Just as virtual memory refers to memory space that exceeds available hardware memory, so does virtual space refer to display area that is beyond the dimensions of the monitor. You can create video displays using VSPACE that only appear on the monitor when the window of cur­ rent display space is positioned somewhere within the virtual display area.

Use VSPACE to handle windowing applications that would normally display more data than the monitor can display. By isolating various segments of data within virtual windows, you can scroll a particular virtual window without affecting other screen data that might be displayed at the same time.

Virtual space is created as two string variables. The first (v_screen) is a virtual screen that you dimension (size) and then control (display, print to, hide, resize, etc.). The second (background) is a snapshot of the current video image (video RAM). This snapshot is used to redisplay areas of the original physical display that are uncovered as the user moves or sizes the window you have created.

By using the VSPACE subroutine, you can access any part of the virtual screen string using simple column and row offsets into the rectangular representation of that string, greatly simplifying maintenance of the data represented within the virtual space area.

You first initialize the entire space that is to be available as potential display area for your application. Within that overall virtual area, you can then define a window for display to the monitor. That window can be moved and/or expanded as you choose.

First, call VSPACE with the VINIT function to create a virtual space of a specific size. This does not determine where on the screen data will be displayed, but simply reserves a space in memory for future virtual space activity.

v_cols= 150
v_rows= 100
VSPACE(VINIT, status, v_screen, v_cols, v_rows)

Then, store the dimensions and other data about the available display area by calling VSPACE with the VBACK function.

background=""
VSPACE(VBACK, status, background, cols, rows)

You may now begin to dimension and manipulate data areas and windows within the virtual display space.

When you write data to a virtual window, that data does not appear on screen until the dimensions of the virtual area match those of the display area. Further control of what is displayed is possible through several VSPACE functions. Specifically, a window is not made visible until VWSET (or other related function) has run.

It is important to handle message printing tasks only through such safe tools as MSG, because when working in virtual space, the area in which a message is to be printed cannot be easily defined for such tools as PRINT. MSG overlays the virtual space, assuming its coordinates refer to the actual display space, not the virtual display space.

It is important to keep in mind the different worlds that are created and manipulated by VSPACE. The virtual screen is the total area you want available and within which to create and position (sometimes reposition) a window. The window itself is a particular area of the virtual screen, and its dimensions must be within those of the actual display area (as stored in background). The third factor is the display screen. Each of these three elements has a particular size and/or dimension (although the virtual screen and the window can be resized dynamically), and it is only when an area falls within the dimensions of all three elements that something is visible on the screen (and even that visibility can be controlled).

VINIT determines the size of a virtual screen. You can use VSIZE later to change that size. VBACK stores the characteristics of the available physical display device.

VWSET makes an area of the virtual screen visible as a window. If text has been written into the specified area of the virtual screen, it will become visible after VWSET executes. VSOFF performs exactly the same function as VWSET, except that the window remains invisible. However, any window-related VSPACE function that executes after VSOFF has run makes visible either the entire window or the most recently printed text. A VPRNT call prints visibly, but will not make the rest of the window visible. Window-related functions include VPRNT, VWMOV, VWEXP, VWPAN, VWSET. VPOFF is identical to VPRNT, but what it prints is not visible.

VSAVE stores the specified portion of the virtual screen in save_scrn. VRSTR restores (or transfer to anotlier virtual screen) a portion of the virtual screen passed in save_scrn. VSCRL scrolls or pans within a portion of the virtual screen. Whether text is displayed depends on the location of a visible window in relation to the virtual screen portion being scrolled or panned. VGETC and VGETA return the character and attribute, respectively, at the cursor.

VCMPR and VEXPN compress and uncompress, respectively, virtual screen variables.

Use function to pass the VSPACE function operand. Include in your code the VIRTUAL.PARAMS record from the INCLUDE file. That record has the following values:

VSPACE returns error codes in status. It returns O unless an error has occurred.

For all but one function, screen contains the virtual screen data variable, v_screen. That exception, VBACK, stores data from the CRT display in background before virtual display manipulation begins, so it is important that the data returned to v_screen after execution of the VBACK function be saved in background for later use by other functions.

A virtual screen is composed of a 25-byte header and a string of character:attribute byte pairs. All screen variables used by VSPACE are built in this fashion. Because Advanced Revelation variables are restricted to 64K, this means that the maximum number of characters in a variable is less than 32K

Each VSPACE function operates with a subset of the total number of parameters available to VSPACE. It is therefore useful to invoke each function with a call of standard format:

VSPACE(VINIT, status, v_screen, v_cols, v_rows)

VSPACE(VSIZE, status, v_screen, v_cols, v_rows)

VSPACE(VBACK, status, background, cols, rows)

VSPACE(VPRNT, status, v_screen, v_col, v_row, string)

VSPACE(VWMOV, status, v_screen, chg_x, chg_y, background, border)

VSPACE(VWEXP, status, v_screen, chg_wid, chg_dep, background, border)

VSPACE(VWPAN, status, v_screen, chg_vx, chg_vy, background)

VSPACE(VCMPR, status, v_screen)

VSPACE(VEXPN, status, v_screen)

VSPACE(VCPOS, status, v_screen, v_col, v_row)

VSPACE(VGETC, status, v_screen, v_col, v_row, character)

VSPACE(VGETA, status, v_screen, v_col, v_row, attribute)

VSPACE(VSAVE, status, v_screen, tl_vcol, tl_vrow, br_vcol, br_vrow, save_scrn)

VSPACE(VRSTR, status, v_screen, tl_vcol, tl_vrow, br_vcol, br_vrow, save_scrn)

VSPACE(VSCRL, status, v_screen, tl_vcol, tl_vrow, br_vcol, br_vrow, scrl_cols, scrl_rows)

VSPACE(VWGET, status, v_screen, tl_col, tl_row, br_col, br_row, v_col, v_row, background, border)

VSPACE(VWSET, status, v_screen, tl_col, tl_row, br_col, br_row, v_col, v_row, background, border)

VSPACE(VPOFF, status, v_screen, v_col, v_row, string)

VSPACE(VSOFF, status, v_screen, tl_col, tl_row, br_col, br_row, v_col, v_row, background, border)

The following table describes the variables used above:

VSPACE returns an error code in status. VINIT returns the virtual screen image in v_screen, and VBACK returns the current display parameters in background. VGETC and VGETA return the character and attribute, respectively, at the cursor position in character and attribute. VWGET returns window parameters in several variables. VCPOS returns the current cursor position in the virtual screen. VSAVE returns the specified portion of the virtual screen in save_scrn.

/* The following code demonstrates various VSPACE functions: */

$INSERT INCLUDE, VIRTUAL.PARAMS

DECLARE SUBROUTINE MSG, INPUT.CHAR, DELAY, VSPACE, MONITOR
DECLARE FUNCTION VIDEO.RW

border = 0

* must be initialized
v_cols = 80
v_rows = 100
cols = @CRTWIDE
rows = @CRTHIGH
stringl = "Hello, World!"
string2 = "Hello, Moon!"
string3 = "Hello, Sun!"

left = 0
top = 0

right = @CRTWIDE-1
bottom = @CRTHIGH-1

display = CHAR(177)
back = CHAR(7)
monochrome = 5
bgrd_color = 14 ;* dark magenta
frgr-color =  ;* light yellow
color = (bgrd_color * 16) + frgr_color

verrors = "" ;*      VIDEO.RW error messages
verrors<l> = "Out of memory during read attempt"
verrors<2> = "Display is not memory-mapped"
verrors<3> = "Col or Row is out of range"
verrors<4> = "Left col is greater than right col, or"
verrors<4,-1> = "top row is greater than bottom row" 
verrors<5> = "MODE is not 'C', 'R', **'W'"**
verrors<6> = "Size of saved image is less than area to be restored"

map = "" ;* MSG field
map<l> = "Tl"
map<13> = 1

GOSUB Clearscreen

v_row = 5
v_col= 50         ;* location on virtual screen of string start 

GOSUB Setup_Window

* now, make it visible
tl_row = 5
tl_col= 10         ;* location of window on display screen 
br_col = 30
br_row = 10

vrow   = 5
vcol   = 50        ;* area of virtual screen placed at window's 0,0 

VSPACE(VWSET, status, v_screen, tl_col, tl_row, br_col, br_row, vcol, vrow, background, border)

DELAY(1)

* Now, we'll move the window 

chg_x = 2
chg_y = 1

FOR i = 1 TO 5
     VSPACE(VWMOV, status, v_screen, chg_x, chg_y, background, border)
     DELAY(l/2)
NEXT i

* Now, we'll pan the text across the window

chg_vx = 1
chg_vy = 0

FOR i = 1 TO 10
     VSPACE(VWPAN, status, v_screen, chg_vx, chg_vy, background)
     DELAY(l/2)
NEXT i

* Let's bring it back

chg_vx = -1

FOR i = 1 TO 10
     VSPACE(VWPAN, status, v_screen, chg_vx, chg_vy, background)
     delay(l/2)
NEXT i

* Let's make the window bigger

chg_wid = 10
chg_dep = 4
VSPACE(VWEXP, status, v_screen, chg_wid, chg_dep, background, border)
 

* Now, we'll scroll 

tl_vcol   = 10
tl_vrow   = 0
br_vcol   = 80
br_vrow   = 10
scrl_cols = 0
scrl_rows = 1


;* a part of the virtual screen

;* these four values define the section of

;* virtual screen that is to be scrolled

;* make it big enough to avoid the effects of

;* destructive nature of VSCRL


MSG("Here comes a virtual scroll", map,"","","")

GOSUB Add_3_Lines

FOR i = 1 TO 6
     VSPACE(VSCRL, status, v_screen, tl_vcol, br_vrow, scrl_cols, scrl_rows)
     DELAY(l/2)
NEXT i

* We'll re-Join the separated segments

scrl_cols= 0
scrl_rows = -1
MSG("Now, it's coming back...", map, "","","")

FOR i = 1 TO 6
     VSPACE(VSCRL, status, v screen, tl vcol, tl vrow, br vcol, obr vrow, scrl cols, scrl rows)
     IF status THEN GOSUB Vspace_Error; STOP
     DELAY(l/2)
NEXT i

MSG("Notice the destructive nature of the scroll.", "", "","")

* Return the character at a specified location on the virtual screen

v_col = 0
v_row = 0
string = "Can you find this string?" 
found_string = ""
VSPACE(VPRNT, status, v_screen, v_col, v_row, string)
IF status THEN GOSUB Vspace_Error; STOP

FOR i = 0 TO 23
     VSPACE(VGETC, status, v_screen, v_col+i, v_row, character)
     IF status THEN GOSUB Vspace_Error; STOP
     found_string := character
NEXT i


message = ""
message<l> = "Here is the string written to 0,0 of the virtual oscreen:"
message<2> = ' 11' : found string:'?'"
MSG(message, "", "", "")
message= "This concludes the demonstration of VSPACE functions..."
map<l> = "T3"
MSG(message, map, "","","")

INPUT.CHAR(a)      ;* let's pause

GOSUB Restore_Screen

STOP  ;* end of program

************************************************************
* Internal Subroutines
************************************************************

Clearscreen:

operator= "R"

vstatus = VIDEO.RW(left, top, right, bottom, operator, image)

IF vstatus THEN
     MSG(verrors<vstatus>, map, "","","")
     STOP
END

MONITOR(type_of_display)

operator=" "         ;* clear the screen

IF type_of_display= 7 THEN
     back_image= display_back:monochrome
END ELSE
     back_image = display_back:color
END
vstatus = VIDEO.RW{left, top, right, bottom, operator, back_image)

IF vstatus THEN
     MSG(verrors<vstatus>, map,"","","")
     STOP
END
RETURN



Setup_Window:

VSPACE{VINIT, status, v_screen, v_cols, v_rows)
IF status THEN GOSUB Vspace_Error; STOP
VSPACE{VBACK, status, background, cols, rows)
IF status THEN GOSUB Vspace_Error; STOP
VSPACE{VPRNT, status, v_screen, v_col, v_row, string1)
IF status THEN GOSUB Vspace_Error; STOP
VSPACE(VPRNT, status, v_screen, v_col, v_row+l, string2)
IF status THEN GOSUB Vspace_Error; STOP
VSPACE{VPRNT, status, v_screen, v_col, v_row+2, string3)
IF status THEN GOSUB Vspace_Error; STOP
save_v_col= v_col
save_v_row= v_row
RETURN-




Restore Screen:

operator= "W"
vstatus = VIDEO.RW{left, top, right, bottom, operator, image)
IF vstatus THEN
     MSG{verrors<vstatus>, map,"","","")
END
RETURN




Vspace_Error:

vs_error    = ""

vs_error<l> = "invalid operand"
vs_error<2> = "not memory mapped"
vs_error<3> = "out of string space"
vs_error<4> = "V SCREEN is too large (32K)"
vs_error<S> = "one of the variables is corrupt"
vs_error<6> = "too few parameters for this function"
MSG(vs_error<status>, "", "", "")
RETURN




Add_3_Lines:
string4 = "Hello, Uranus!"
string5 = "Hello, Neptune!"
string6 = "Hello, Pluto!"
v_col = save_v_col
v_row = save_v_row
VSPACE(VPRNT, status, v_screen, v_col, v_row+3, stringl) 
IF status THEN GOSUB Vspace_Error; STOP
VSPACE(VPRNT, status, v_screen, v_col, v_row+4, string2)
IF status THEN GOSUB Vspace_Error; STOP
VSPACE(VPRNT, status, v_screen, v_col, v_row+S, string3)
IF status THEN GOSUB Vspace_Error; STOP
RETURN                    -