Virtual Screen

	{
	   char *workbuf;
	   unsigned wsize = 264;
	   ...
	   workbuf = (char *)malloc(wsize);
	   _set_vsworkbuf(workbuf, wsize);  /* set up work buffer */
	   ...
	}

	#include <inline.h>
	   	  ...
	   	  malloc(264);
	   	  mov si,ax
	   	  mov cx,264
		set_vsworkbuf();/* set up work buffer */
		...

See also

_vscreen_bufsize, _vscreen_create

_vscreen_bufsize

Descrip

Returns the required buffer size for a specified virtual screen.

Syntax

#include <vscreen.h>
unsigned int _vscreen_bufsize(const vscrn *vdescrip);

Returns

The required buffer size, in bytes, for the specified virtual screen.

Notes

This function determines the size of the memory or disk buffer required to buffer the virtual screen defined by vdescrip. The result is calculated using the initial screen dimensions specified in the dimens field of the specified descriptor. If -1 is specified for dimens, then the current dimensions are assumed on the adapter specified by the adapter field in vdescrip. The size of the required buffer is returned.

The returned value should be used to allocate screen buffers only for screens which will not be resized by the application. If a screen may be resized, then a fixed buffer size of 16K is recommended since text screens commonly support resolutions as high as 132x60 (132x60x2=15840 bytes).

WARNING! This function only determines the buffer size based on the initial screen and adapter information provided in vdescrip. The calculated buffer size is NOT based on the current screen size. This means that the returned size will not reflect the actual needs of the screen if the screen has already been created and resized.

	{
	   vscrn scr1;
	   unsigned scr1_size;
	   .../* initialize scr1 descriptor */
	   scr1_size = _vscreen_bufsize(&scr1);
	   .../* determine necessary bufsize */
	}

	#include <inline.h>
	{
	   vscrn scr1;
	   ...
	   lea si,scr1	    /* SI -> scr1 descriptor */
	   vscreen_bufsize();/* AX = required buffer size */
	   ...
	}

See also

_screen_bufsize, _vscreen_create

_vscreen_create

Descrip

Creates and initializes a virtual screen.

Syntax

#include <vscreen.h>
int _vscreen_create(const vscrn *vdescrip)

Returns

0 if the virtual screen was successfully created.
-1 if the screen could not be created.
e_code error code

Notes

This function creates a new virtual screen. The screen is established and initialized to reside on the adapter and video page specified in vdescrip, with the initial screen dimensions, video mode, and video refresh characteristics also specified in vdescrip. 0 is returned if the function is successful. -1 is returned and an error code is returned in e_code if the screen could not be created.

The new screen always inherits the remainder of its video state (cursor type, text attributes, bkbold mode, etc.) from the currently-open screen on the specified adapter or from the current hardware state of that adapter if it has no open screen. In addition, the new screen inherits the text and attributes on its video page, including current and default text attributes, if: 1) the inherit flag is set in vdescrip; and 2) the display adapter is currently programmed for the specified video mode and screen dimensions. Otherwise, the new screen is blanked. _console_init does NOT need to be called on the newly-created screen.

If the open flag is set, the new screen is automatically opened when it is created. However, the new screen is NOT automatically selected as the active screen unless the open flag is set and the new screen supersedes STDSCR when it is opened.

vdescrip is a screen descriptor of type vscrn (defined in VSCREEN.H) which defines the initial state of the screen, as follows:

typedef struct {
char adapter; /* display adapter (-1=primary) */
char vmode; /* video mode (-1=current) */
char vpage; /* video page (-1=current) */
char refresh; /* refresh state (1=on,0=off,-1=current) */
int dimens; /* screen dimensions (-1=current) */
char inherit; /* inherit contents (1=inherit,0=blank) */
char open; /* auto-open flag (1=open,0=do not open) */
int handle; /* DOS file handle (-1=not disk buffered) */
void far * buffer; /* buffer address */
unsigned int bufsize;/* buffer size (0=unbuffered) */
char reserved[?]; /* console I/O and windowing data */
} vscrn;

WARNING! The vscrn structure shown above is a simplified representation and is provided only to identify structure elements which are required for _vscreen_create. The actual structure definition in VSCREEN.H should be used any time screen descriptors must be allocated or defined.

See the Virtual Screen technical notes for a detailed description of each screen descriptor field.

If handle is set to a value other than -1, then a disk buffer is used by the virtual screen system to preserve the screen contents. The buffer resides in the file associated with handle at the file offset specified by buffer. If handle is -1, then buffer is treated as an address (in segment:offset form, offset first) of a screen buffer in memory.

To avoid disk full errors, disk buffer files should be created and sized before they are used. It is recommended that 16K be allocated within the file for each screen which may be buffered, since text screens commonly support resolutions as high as 132x60 (132x60x2=15840 bytes). The exact size of the required buffer may be obtained by calling _vscreen_bufsize. -1 is returned and e_code returns E_INSMEM if the specified buffer size is inadequate for the initial screen dimensions. _set_vsworkbuf must be called before _vscreen_create is used to create a disk buffered screen.

If inherit is set and open is clear, the new screen must either be buffered or it must be the first screen assigned to its video page. Otherwise, a blank screen will be inherited.

WARNING! Using _set_dimens or _set_vmode, it is possible to increase the dimensions of a screen after it has been created. If the specified bufsize becomes insufficient for a virtual screen, the virtual screen system will treat that screen as if it were unbuffered. This will cause the screen to appear blank whenever it is obscured and reopened.

_vscreen_init must be called before this function may be used. In addition, _adapter_init must be called before a virtual screen may be created on the secondary adapter.

	{
	   vscrn scr1;
	   unsigned bufsize = 15840;
	   ...
	   scr1.adapter = -1;
	   scr1.vmode = -1;
	   scr1.vpage = -1;
	   scr1.refresh = -1;
	   scr1.dimens = -1;
	   scr1.inherit = 1;
	   scr1.open = 0;
	   scr1.handle = -1;
	   scr1.buffer = (char *)malloc(bufsize);
	   scr1.bufsize = bufsize;
	   _vscreen_create(&scr1);/* create a virtual screen */
	   ...
	}

	#include <inline.h>
	{
	   vscrn scr1;
	   unsigned bufsize = 15840;
	   ...
	   scr1.adapter = -1;
	        scr1.vmode = -1;
	   scr1.vpage = -1;
	   scr1.refresh = -1;
	   scr1.dimens = -1;
	   scr1.inherit = 1;
	   scr1.open = 0;
	   scr1.handle = -1;
	   scr1.buffer = (char *)malloc(bufsize);
	   scr1.bufsize = bufsize;
	   lea si,scr1	    /* SI -> scr1 descriptor */
	   vscreen_create();/* create a virtual screen */
	   ...
	}

See also

_set_vsworkbuf, _vscreen_bufsize, _vscreen_init, _vscreen_remove

_vscreen_init

Descrip

Initializes the virtual screen system.

Syntax

#include <vscreen.h>
void _vscreen_init(void);

Returns

None

Notes

This function initializes the virtual screen system, creates STDSCR on the active video page of the active display adapter, and selects STDSCR as the active screen. _console_init is automatically called to initialize STDSCR.

If _vscreen_init is called when the virtual screen system is active, all virtual screens are removed as if _vscreen_remove had been called, and the virtual screen system is re-initialized to support STDSCR. The new STDSCR inherits the state and contents of the previously-open screen on the display adapter of the previously-active screen.

	   ...
	   _vscreen_init(); /* initialize virtual screen system */
	   ...

	#include <inline.h>
	   	  ...
	   	  vscreen_init();
	   	  	 /* initialize virtual screen system */
	   	  ...

See also

_adapter_init, _vscreen_create, _vscreen_resume, _vscreen_suspend

_vscreen_open

Descrip

Opens a virtual screen.

Syntax

#include <vscreen.h>
void _vscreen_open(const vscrn *vdescrip);

Returns

None

Notes

This function opens the screen associated with vdescrip. This makes the specified screen visible on its adapter. The screen is displayed in its current console I/O and windowing state, including its current video mode, video page, and screen dimensions. The current contents of the screen are displayed if the screen is buffered; the screen is blanked in its default text attribute if the screen is unbuffered and is not already open or physically present on its assigned video page. The newly-opened screen is automatically selected as the active screen ONLY if the previously-open screen on the same display adapter was STDSCR. _vscreen_select must be called before console I/O and windowing may be performed on the specified screen if the screen is not already active.

If another buffered screen is already open on the specified adapter and video page, then that screen is flushed to its buffer to preserve its state before the new screen is opened.

WARNING! This function assumes that vdescrip is a valid screen descriptor for a screen which has already been created by calling _vscreen_create and which has not been removed by calling _vscreen_remove. Use of an invalid screen descriptor will produce undefined results.

	{
	   vscrn scr1;
	   .../* initialize scr1 descriptor */
	   _vscreen_open(&scr1); /* display scr1 */
	   ...
	}

	#include <inline.h>
	{
	   vscrn scr1;
	   ... 	 	/* initialize scr1 descriptor */
	   lea si,scr1
	   vscreen_open();    /* display scr1 */
	   ...
	}

See also

_vscreen_create, _vscreen_init, _vscreen_remove, _vscreen_select

_vscreen_remove

Descrip

Removes a virtual screen.

Syntax

#include <vscreen.h>
void _vscreen_remove(const vscrn *vdescrip);

Returns

None

Notes

This function removes the screen associated with vdescrip from the virtual screen system. If the screen is active when it is removed, STDSCR is automatically selected as the new active screen on the same adapter as the removed screen. The appearance of the physical screen attached to the display adapter remains unchanged.

WARNING! This function assumes that vdescrip is a valid screen descriptor for a screen which has already been created by calling _vscreen_create and which has not been removed by calling _vscreen_remove. Use of an invalid screen descriptor will produce undefined results.

	{
	   vscrn scr1;
	   .../* initialize scr1 descriptor */
	   _vscreen_create(&scr1); /* add scr1 to virtual screen system */
	   ...
	   _vscreen_remove(&scr1); /* display scr1 */
	   ...
	}

	#include <inline.h>
	{
	   vscrn scr1;
	   ... 	 	/* initialize scr1 descriptor */
	   lea si,scr1	    /* SI -> scr1 descriptor */
	   vscreen_create();/* add scr1 to vscreen system */
	   ... 	 	/* manipulate screens */
	   lea si,scr1	    /* reset SI -> descriptor */
	   vscreen_remove();/* remove scr1 */
	   ...
	}

See also

_vscreen_create

_vscreen_resume

Descrip

Resumes virtual screen support.

Syntax

#include <vscreen.h>
void _vscreen_resume(void);

Returns

None

Notes

This function resumes virtual screen support after it has been suspended by calling _vscreen_suspend. Specifically, this function re-selects the originally-active and originally-open screens. Text and attributes are only restored on buffered screens or screens with active windowing systems. All unbuffered screens without active windowing systems are blanked in the default text attribute.

This function has no effect if _vscreen_suspend was not previously called.

	   ...
	   _vscreen_restore(); /* restore virtual screen system */
	   ...

	#include <inline.h>
	   ...
	   vscreen_restore(); /* restore virtual screen system */
	   ...

See also

_vscreen_suspend

_vscreen_select

Descrip

Selects the active virtual screen.

Syntax

#include <vscreen.h>
void _vscreen_select(const vscrn *vdescrip);

Returns

None

Notes

This function selects the virtual screen associated with vdescrip as the new active screen. The active screen is the screen to which all console I/O and windowing is directed and is the only screen affected by these functions. The selected screen is NOT automatically opened (made visible) unless it is disk buffered and it is assigned to a video page or mode which conflicts with the currently-open screen. The active screen may be accessed using console I/O and windowing functions whether or not it is open.

This function may be used to select STDSCR ("standard screen") by passing -1 (STDSCR) in vdescrip. STDSCR is a temporary, unbuffered screen which is automatically re-created and opened each time it is selected. STDSCR is always open and inherits the state and contents of the previously-open screen on the display adapter of the previously-active screen each time it is selected. (See the Virtual Screen technical notes for more information about STDSCR.)

WARNING! This function assumes that vdescrip is a valid screen descriptor for a screen which has already been created by calling _vscreen_create and which has not been removed by calling _vscreen_remove. Use of an invalid screen descriptor will produce undefined results.

	{
	   vscrn scr1;
	   ...	  /* initialize scr1 descriptor */
	   _vscreen_select(&scr1);/* select scr1 for active scr */
	   ...
	}

	#include <inline.h>
	{
	   vscrn scr1;
	   ... 	 	/* initialize scr1 descriptor */
	   lea si,scr1
	   vscreen_select();/* select scr1 for active scr */
	   ...
	}

See also

_set_adapter, _vscreen_create, _vscreen_open

_vscreen_suspend

Descrip

Temporarily suspends the virtual screen system.

Syntax

#include <vscreen.h>
void _vscreen_suspend(void):

Returns

None

Notes

This function temporarily suspends the virtual screen system. Specifically, this function flushes all screens to their buffers, places the virtual screen system into single-screen mode, and initializes the console I/O system to inherit the state and contents of the previously-open screen on the display adapter of the previously-active screen. The appearance of the system screens are unaffected. This function is normally used prior to executing another application which could reprogram a display adapter or disturb the contents of any video page.

This function does NOT restore the video state to the state which was active when _vscreen_init was called. _save_vstate and _restore_vstate (or their equivalents) must be used for this purpose if this is required.

	   ...
	   _vscreen_suspend();  /* suspend virtual screen system */
	   ...

	#include <inline.h>
	   ...
	   vscreen_suspend();  /* suspend virtual screen system */
	   ...

See also

_vscreen_resume