CLIPSCRN 1.0 - C Functions that allow Clipper programmers to save and
restore screen images in compressed format.

Copyright 1988 Gary Menchen.
RFD # Box 4015
Brunswick, ME 04011

SUMMARY

CLIPSCRN is a small collection of functions, written in C and compiled with
the Microsoft C Compiler Version 5.1, that allow Clipper programmers to
save and restore screen images in compressed format, greatly reducing the
memory overhead required for windowing. Typical compressed screen images
may save as much as 80% of the amount of memory that the original images
required. Functions are included that will compress and expand screen
images created with Clipper's SAVESCREEN() function; will directly access
video memory, saving an area of the screen in compressed format, and expand
a compressed screen image by writing it directly to video memory. All
attribute information is retained.

COPYRIGHT NOTICE

CLIPSCRN is copyrighted, and all rights are reserved. It is being released
as shareware. It may be tested, copied, uploaded to public access bulletin
boards, and distributed in any manner where the recipient pays for no more
than the cost of the distribution. All original files must be included.
CLIPSCRN may not be bundled with any other programs, libraries, or functions
without the written permission of the author.

RESTRICTIONS

CLIPSCRN functions may not be used in any application, for other than testing
purposes, by unregistered users. They may not be included in any application
that is in its final form, without registration.

DISCLAIMER

No guarantee of any kind is made in regards to these functions.

REGISTRATION

Use of CLIPSCRN may be registered by sending ten dollars to its author.
Any registered user may include the CLIPSCRN functions in any of his or her
applications that are for personal or corporate use, or that are distibuted
as .EXE applications. They are also entitled to make use of any upgrades
to the CLIPSCRN functions that are publicly available as shareware within
24 months of their original registration.

Note that registration does not provide the right to include CLIPSCRN
functions as part of any library of functions. Registration provides the
right to include CLIPSCRN functions only in applications distributed as .EXE
files.

To register, send $10.00 to: Gary Menchen
RFD 3 Box 4015
Brunswick, Maine 04011
U.S.A.

Source code is available for an additional $25.00.

FILES

The following files should be included with CLIPSCRN 1.0

CLIPSCRN.LIB - The library file containing the CLIPSCRN functions.
CLIPSCRN.MAP - Map of the library file. Each function has been
separately compiled. THe map file will show the
memory overhead requried to access each function.
CLIPSCRN.DOC - Documentation.


DOCUMENTATION

Introduction

Clipper's SAVESCREEN() and RESTSCREEN() functions provide a very
efficient basis for windowing within Clipper applications. However,
one of Clipper's greatest weaknesses is the large amount of memory
consumed by even quite small applications. With large applications
the memory cost of saving screen images can be burdensome. CLIPSCRN's
functions are designed to greatly reduce the memory used to store screen
images.

Two functions are available for compressing screen images.

SCRNPACK() - compresses a screen image created by Clipper's
SAVESCREEN() function.
SAVEPACK() - directly accesses video memory, saving all or a
portion of the screen in compressed format.

One function expands a compressed screen image back to normal format.

SCRNEXPN() - Expands a compressed screen image to normal format so
that it could, or example, to restored to the screen
using Clipper's RESTSCREEN() function.

And one function expands a compressed screen image by writing it directly
to video memory.

RESTPACK() - Writes a compressed screen image to video memory.

An internal function - _vmode - is used to check the video mode. This
function is not directly callable from within a Clipper program.

List of Functions

RESTPACK()

Syntax: RESTPACK(,,,,)

Usuage: To write a compressed screen image directly to video memory,
bypassing the memory overhead of first expanding it to conventional
format and then using RESTSCREEN() to write it back to the screen.

Argument:
- Top row of screen image to be written to screen
- Left column
- Bottom row
- Right column
- Compressed screen image.

Return Value: None.

Example:

* Example 1
scrn1 = SAVEPACK(5,10,12,60)
* display other materials on the screen
RESTPACK(5,10,12,60,scrn1) && restore the image


SAVEPACK()

Syntax: SAVEPACK([,,,])

Purpose: To save a portion of the screen in compressed format.

Argument: Four optional parameters specify the coordinates
of the portion of the screen to be saved.
- top row
- left column
- bottom row
- right column

If four numeric parameters are not passed then the coordinates default
to 0,0,24,79.

If numeric parameters are passed that are "out of bounds" then the
results are unpredictable.

Return Value: the compressed screen image.

Examples:

* Example1
scrn1 = SAVEPACK(5,10,12,60)

* Example2
scrn2 = SAVEPACK() && Save the entire screen

SCRNEXPN()

Syntax: SCRNEXPN([,])

Purpose: To expanded a screen image from CLIPSCRN's compressed format
to conventional character string format.

Arguments:
is the compressed screen image, created by either SCRNPACK()
or SAVEPACK().
is an optional parameter that specifies the maximum size of
the screen image in character format. This defaults to 4000 if
a second numeric parameter is not passed. Note that the screen image
returned by the function will be the proper length, and the second
numeric parameter exists only to provide the opportunity to
minimize temporary memory allocation requirements.

Return Value: A screen image in Clipper's conventional character
format.

Examples:

* Example 1
scrn2 = SCRNEXPN(scrn1) && scrn1 was created by SAVEPACK()

* Example 2
* If the original screen area was 5,10,12,60
* that represents 8 rows by 51 columns * 2 (1 character, 1 attribute)
* for an original length of 8 * 51 * 2 = 816
scrn3 = SCRNEXPN(scrn1,816) && minimize memory allocation



SCRNPACK()

Syntax: SCRNPACK()

Purpose: To compress a screen image stored as a Clipper character
string - such as is created by Clipper's SAVESCREEN() function.

Argument: - a screen image stored as a character string.

Return Value: the screen image stored in CLIPSCRN's compressed
format.

Usage: SCRNPACK may be used to reduce the storage space required
for saving screen images. It may be used whenever the screen image
already exists in memory - possibly through use of some kind of
windowing system - or when hardware incompatibilities prevent the
use of SAVEPACK().

Examples:

* Example 1
scrn1 = SAVESCREEN(5,10,12,60)
scrn2 = SCRNPACK(scrn1)

* Example 2
scrn3 = SCRNPACK(SAVESCREEN(5,10,12,60))


PERFORMANCE

The table below contains some figures on the performance of these
functions. Tests were performed on an 8 Mghz AT compatible, and each
function was repeated 1000 times, after which the loop overhead was
subtracted and the remaining figure divided by 1000. Naturally
the performance of the CLIPSCRN functions will vary depending upon the
size of the screen area being contracted or expanded, as well as the
complexity of its content.

All functions were tested after the following screen commands.

CLEAR
SET COLOR TO R/W+
FOR i = 1 TO 5
@ i,20 SAY "This is a test"
NEXT
SET COLOR TO GR/R
FOR i = 1 TO 15
@ i,40 SAY "This is a test"
NEXT
SET COLOR TO W+/B
FOR i = 8 TO 16
@ i,60 SAY "This is a test"
NEXT

The figures below are for function calls with dimensions of 3,10,19,65. The
figures should provide a guide to the functions' relative performance.

All timings are given in seconds.

Function 1000 Repititions Single Repitition

SAVESCREEN 5.60 .0056
RESTSCREEN 6.48 .00648

SAVEPACK 40.69 .04069
SCRNPACK 37.78 .03778
SCRNEXPN 22.35 .02235
RESTPACK 26.14 .02614

In the example described above, the length of the screen image when
saved via SAVESCREEN() was 1,904 bytes while the length of the
compressed screen image was 479 bytes.

The CLIPSCRN functions require roughly from three to six times as much
time as the Clipper functions, due to the extensive manipulation of the
screen images; however the slowest in the example above takes only
about two one-hundredths of a second. In any case the functions have
a very specific purpose - freeing memory space from the demands placed
upon it by windowing - and are not intended as general replacements for
SAVESCREEN/RESTSCREEN.