Category : C Source Code
Archive   : LSPD05-2.ZIP
Filename : LSPEED.REF

 
Output of file : LSPEED.REF contained in archive : LSPD05-2.ZIP

















LIGHT SPEED

SUPER FAST GRAPHICS PROGRAMMING LIBRARY






ÜÜ ÜÜ ÜÜ ÜÜÜÜ ÜÜÜÜÜ ÜÜ Ü Ü Ü ÜÜÜ ÜÜÜÜ tm
ÛÛ ßÛÜÜÛß ÛÛ ÜÜ ÜÜ ßÛÛ ÛÜ ÛÜ ÜÛ ßÛ ÛÛ ÜÜÜ
ßß ßß ÛÛ ÛÛ ÛÛ ÛÛ ÛÜ ÛÜÛ ÜÛß ßÛ ßßÛÜ Û
ßßßßß ßß ßßßß ßß ßß ß ß ßßßßßß ß ßßßß







Version 0.05 (pre-release version)

21 October, 1991

Copyright (C) 1991. All rights reserved

by Darren Lyon





Programmers Reference Guide


















Table of Contents
-----------------


Introduction........................................... 1

General Information................... 1
Library Features...................... 1
Source Code Information............... 2
Registration Information.............. 3
Registration Form..................... 4
How to Contact the Author............. 5
Disclaimer............................ 5
Trademarks............................ 5

The Light Speed Graphics Library Reference ............ 6

Graphics Drawing Primitives........... 6
ega_andcircle..................... 8
ega_andellipse.................... 9
ega_andline....................... 10
ega_andpixel...................... 11
ega_andpoly....................... 12
ega_andrectangle.................. 13
ega_andtriangle................... 14
ega_clearpage..................... 15
ega_fillarea...................... 16
ega_filledcircle.................. 17
ega_filledellipse................. 19
ega_filledrectangle............... 21
ega_andtriangle................... 23
ega_getpixel...................... 25
ega_orcircle...................... 26
ega_orellipse..................... 27
ega_orline........................ 28
ega_orpixel....................... 29
ega_orpoly........................ 30
ega_orrectangle................... 31
ega_ortriangle.................... 32
ega_putcircle..................... 33
ega_putellipse.................... 35
ega_putline....................... 37
ega_putpixel...................... 40
ega_putpoly....................... 42
ega_putrectangle.................. 44
ega_puttriangle................... 47
ega_scanlinefill.................. 51
ega_xorcircle..................... 52
ega_xorellipse.................... 53
ega_xorline....................... 54
ega_xorpixel...................... 55
ega_xorpoly....................... 56
ega_xorrectangle.................. 57
ega_xortriangle................... 58
set320x200........................ 59
set40x25.......................... 60
set640x200........................ 61
set640x350........................ 62
set80x25.......................... 63


i




Table of Contents
-----------------


Graphics Display Paging............... 64
ega_flipapage..................... 65
ega_flippage...................... 66
ega_flipvpage..................... 67
ega_getapage...................... 68
ega_getvpage...................... 69
ega_readorigin.................... 70
ega_setapage...................... 71
ega_setoffset..................... 72
ega_setorigin..................... 73
ega_setvpage...................... 74

Video System Status Information....... 75
display_type...................... 76
ega_bytesperline.................. 78
ega_displayheight................. 80
ega_displaywidth.................. 81
ega_firstpageaddress.............. 82
ega_maxscanline................... 84
ega_memory........................ 85
char ega_readregister............. 86
ega_retrace....................... 87
int ega_secondpageaddress......... 88
ega_writepallete.................. 89
ega_writeregister................. 91
find_primary...................... 92
get_mode.......................... 93
second_adapter.................... 95

Graphics Mode Text Output............. 96
ega_broadch....................... 100
ega_computerch.................... 101
ega_crispch....................... 102
ega_fontheight.................... 103
ega_fontwidth..................... 105
ega_formattext.................... 106
ega_italicch...................... 108
ega_nicech........................ 109
ega_oldenglishch.................. 110
ega_plainch....................... 111
ega_plasmach...................... 112
ega_scriptch...................... 113
ega_smallch....................... 114
ega_standardch.................... 115
ega_tallch........................ 116
ega_writechar..................... 117
ega_writecharacter................ 118
registerbroadfont................. 120
registercomputerfont.............. 121
registercrispfont................. 122
registeritalicfont................ 123
registernicefont.................. 124
registeroldenglishfont............ 125
registerplainfont................. 126
registerplasmafont................ 127


ii




Table of Contents
-----------------


registerscriptfont................ 128
registersmallfont................. 129
registerstandardfont.............. 130
registertallfont.................. 131

Mouse Interface Control Routines...... 132
get_mouse_pos..................... 133
get_mouse_presses................. 134
get_mouse_releases................ 135
hide_mouse........................ 136
init_mouse........................ 137
left_button....................... 138
middle_button..................... 139
mouse_buttons..................... 140
mouse_installed................... 141
read_mouse_motions................ 142
right_button...................... 143
set_mouse_pos..................... 144
set_mouse_pointer................. 145
set_mouse_xrange.................. 148
set_mouse_yrange.................. 149
set_pointer_arrows................ 150
set_pointer_cross................. 151
set_pointer_crosshair............. 152
set_pointer_hand.................. 153
set_pointer_hourglass............. 154
set_pointer_pointer............... 155
set_pointer_questionmark.......... 156
set_pointer_tick.................. 157
set_pointer_watch................. 158
show_mouse........................ 159
wait_for_mouse.................... 160

Graphics Image Routines............... 161
ega_andimage...................... 166
ega_extractsize................... 167
ega_getimage...................... 169
ega_imagesize..................... 170
ega_orimage....................... 171
ega_putimage...................... 172
ega_xorimage...................... 173

Miscellaneous Functions............... 174
disable_screen.................... 175
ega_capture_area_byte............. 176
ega_capture_screen_byte........... 179
ega_restore_area_byte............. 182
ega_restore_screen_byte........... 183
enable_screen..................... 184
getxch............................ 185
reset_keyboard.................... 187

Appendix A - Registering your own user fonts........... 188

Appendix B - Light Speed Colours....................... 191


iii




Table of Contents
-----------------


Appendix C - External Programs......................... 192 Font
Conversion Program........... 192
Mouse Pointer Design Program...... 192
EGA Screen Capture Program........ 193
EGA Post Processing Program....... 194




















































iv




Light Speed
High Speed Graphics Programming


General Information
-------------------

Anyone who has had any experience with graphics programming will
know that it is a very complex field, and many hours can be spent
writing even the most simple code. Compiler manufacturers have also
realized this fact, and with most compilers you will find a customized
graphics system - Borland uses the Borland Graphics Interface (BGI), for
example.

What seems so mysterious about the use of the graphics systems in
most of the compilers is the fact that they can easily add an extremely
large amount to the source of your compiled code, and they also do not
perform at high speed, often referencing large sections of internal data
for simple graphics primitives.

This is where the Light Speed Graphics Library steps in. The Light
Speed library contains a set of highly optimized drawing routines, with
the largest routines only being several hundred bytes. The smallest
routine in the Borland library, however, is over 2500 bytes in size.

There is another trade off to the routines being small - they
execute extremely fast. Plus, the routines have been hand optimized, with
almost every one of them written in pure assembly language. Now, you can
unleash the real power of graphics, at a fraction of the price you would
have to pay for commercial graphics libraries...


Library Features
----------------

* A variety of graphics primitives - including pixel, line, circle
and image manipulation - as well as many advanced features for
almost any graphics application.

* Highly optimized hand coded assembly gives your programs power and
speed, as well as flexibility to run in a variety of graphics
modes.

* Mouse support that easily ties into the graphics system. There are
functions that allow you to re-define the graphics cursor, set
ranges, and read mouse button press details in an instant.

* Only routines that are essential need be used - there is no linking
in of extra information that may never be accessed in your program.
Standard graphics libraries are notorious for this, and that is
also one of their greatest failings.

* Keyboard routines that allow you to the values of keys pressed on
the normal and extended keyboards







-- Page 1 --




Light Speed
High Speed Graphics Programming


Library Features (cont.)
------------------------

* Simple linking in of the graphics features, and no need to specify
many separate files for linking in. The library also needs no
customization to run on any compiler - all of this has been handled
in a simple manner when the routines were written.

* Complete source code availability, and as this is the pre-release
version, an update scheme that is incredibly hard to match. Nowhere
will you find graphics routines of this callibre for the low price
of this library.

* A mouse pointer design program, which removes the tedious work in
calculating pointer patterns, and then converting them into
hexadecimal values. All of this is made simple, and happens
automatically as you design the pointer.

* Some of the planned features for the official release version are:
for a completely incredibly high speed animation system (much like
those found in commercial games, except more powerful), a mouse
pointer system that allows you to program the pointer in full
colour, graphics screen printing, enhanced text functions that can
draw text on angles and directions, enhanced sound routines -
similar to 'RealSound', and a variety of other routines still in
development.


Source Code Information
-----------------------

The complete source code for this version of the library is
available, and can be bought by itself or as part of the update package
for the official release. The source code for each routine is coded as a
separate module, and also included are routines to recompile the modules
and rebuild the library.

The source code is extensively commented, and every module is
formatted in the same way. This means that once you have mastered the
descriptions and found the routines necessary for your own particular
purpose, they are as easy to customize as if you had written the yourself.


Registration Information
------------------------

This version of the library is compiled to support the small or tiny
memory model. This package is only as a demo, and any serious graphics
programming would definitely require routines that are compatible with any
mode. The registered version of the source code is, making the library
much more capable.






-- Page 2 --




Light Speed
High Speed Graphics Programming


Currently there are two plans for registration:

(a) source code only - all you receive is the source code, and
the chance to update to the official release version at a
reduced price

(b) full registration - you receive all of the source code, as
well as definite receipt of the official release as soon as
it becomes available

The prices of the two type of registration are priced accordingly,
and they are very reasonable considering the cost of the equivalent
libraries if they were bought commercially:

(a) source code package - $(AUS) 40, with the update to next
version of the library costing only $(AUS) 30

(b) full registration package - $(AUS) 60, saving you ten dollars
on the source code only deal

(Note: $(AUS) signifies Australian currency)

The registration form is included in the file REG_FORM.TXT, as well
as on the following page. Either version can be used, and it is structured
so that it is easy to complete.
































-- Page 3 --




Light Speed
High Speed Graphics Programming


Light Speed Graphics Programmers Library
Registration form, Version 0.05 (pre-release)


NAME: ____________________________________________

COMPANY: ____________________________________________________

ADDRESS: ____________________________________________________

__________________________________ ZIP: _________

CITY: ___________ STATE: ___________ COUNTRY: _____________

PHONE: (____) _____________

WHERE DID YOU RECEIVE LIGHT SPEED? _________________________________

_________________________________________________________________


--------------------------------------------------------------------------


Source code only registration at $40 ________
(with update plan and any memory
model compatible library)

Full registration at $60 ________
(with memory model update and
immediate receipt of the next
release version when available)

Postage $10 (outside Australia $20) ________


TOTAL: $________

Disk Format (circle): 3«" 5¬"

--------------------------------------------------------------------------

All payments must be in Australian dollars, drawn on an Australian bank,
and sent to:

Darren Lyon

38 Wilcannia Way
Armadale WA 6112
Australia

--------------------------------------------------------------------------

Please use the back of the form for any problems you have encountered,
any suggestions, or features you would like added to the library.


-- Page 4 --




Light Speed
High Speed Graphics Programming


How to Contact the Author
-------------------------

If you encounter any problems with the library, or have any questions
you would like cleared up, please do not hesitate to contact me. There are
a variety of methods:

The C_ECHO: I receive the C_ECHO regularly, and can easily reply to
any mail through there (if you are unsure of how to
contact the C_ECHO, ask a local SysOp, I'm sure he will
be able to help)

Lightning BBS: This bulletin board is situated in Perth, Western
Australia, so may not be feasible for people with
lower speed modems. The phone number is
(09) 344 7199, parameters 8-N-1, with speeds up to
14,400bps (if you are unsure on how to use this
information, consult your terminal programs' manual
and/or a local SysOp). (Country codes are needed.)

Standard post address:

Darren Lyon

38 Wilcannia Way
Armadale WA 6112
Australia


Disclaimer
----------

The author, Darren Lyon, disclaims any responsibility for the damage
of personal equipment through the use of these routines, and assumes no
responsibility for the fitfullness of theses routines to any particular
purpose. The routines are distributed in an "as is" condition, with no
expressed or implied warranties. Darren Lyon reserves the right to change
any feature of the library, with no prior notification, and has no
liability for any losses incurred, either directly or indirectly, by the
use of these routines. Use of these routines is completely at your own
risk.


Trademarks
----------

Borland, BGI, Turbo C - registered trademarks of Borland International.
Microsoft C, QuickC - registered trademarks of Microsoft Corporation.
IBM, IBM EGA, IBM VGA - registered trademarks of International
Business Machines.
Lightning BBS - trademark of Simon Blears.
Light Speed Graphics Toolkit, Lyonware - trademarks of Darren Lyon,
the author.




-- Page 5 --




Light Speed
High Speed Graphics Programming


Graphics Drawing Primitives
---------------------------

The Light Speed Library supports most of the common graphics drawing
primitives as of this release. There are, however, a few functions that
will be added in the next release to make the list complete.

All of the graphics output is controlled by the active and visual
paging mechanism (see that specific section for more details). Therefore,
you should always make sure that you have the correct active page set for
your graphics output. All output is directed to the active page only.

Several functions in the following list will be updated or re-written
in assembly language in the next release, to make their performance much
better (even though as at the moment they are highly optimized C code).

All of the bitwise pixel operations are supported: and, xor, or and
put. If you do not understand the different modes of operation, you need
only use the ega_putXXX function for any output. The following tables show
the results of the various logic operations:

The logic for the 'and' operation, only operating on 1 bit of
information:

Background Buffer Screen Result
-----------------------------------------------
blank blank blank
blank set blank
set blank blank
set set set

The only major use for this operation is when you are trying to
compare the values in the primitive with those on the screen. The result
will show which pixels were set in both.

The logic for the 'or' operation, only operating on 1 bit of
information:

Background Buffer Screen Result
-----------------------------------------------
blank blank blank
blank set set
set blank set
set set set

The logic for the xor operation, only operating on 1 bit of
information:

Background Buffer Screen Result
-----------------------------------------------
blank blank blank
blank set set
set blank set
set set blank



-- Page 6 --




Light Speed
High Speed Graphics Programming


The major benefit to the XOR operation is that you can use xor to
place the primitive on the screen, then another xor in exactly the same
spot to remove it.

The graphics primitives featured in the Light Speed library are
unusual in that they have drawn away from the need for interdependency on
graphics mode information. Most graphics drawing systems need to know and
incredible amount of data for them to operate properly, and therefore take
a while to get used to.

The Light Speed graphics primitives, however, do not need any prior
setting up, other than a simple mode set (set640x350() for example). Once
this has been done, there are a few internal variables that are set to mode
specific information, such as the number of byte stored in one screen
line.

Once the mode has been changed, the graphics primitives will work
independently of the mode, only accessing one or two internal variables.
This means that the operations are very fast, as accessing of pre-stored
information tends to slow graphics routines down.

The colours used to draw the graphics can be passed as a number
ranging from 0 to 15 if you know what each one is, or you can use the more
meaningful textual descriptions of the colours featured in appendix B. The
primitive functions...
































-- Page 7 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_andcircle

Purpose:

AND a circle to the screen.

Calling Protocol:

void ega_andcircle(xloc, yloc, radius, colour)

int xloc, yloc; /* (x,y) of centre of the circle */
int radius; /* The radius of the circle */
int colour; /* The colour of the circle */

Description:

This function will place a circle on the screen using the AND bitwise
operation. The algotrithm used was developed by Bresenham, and is the
fastest known method of drawing a circle. There is no use of the
trigonometric sin and cos functions.

Example:

See the ega_putcircle function, as for ega_putcircle.

See Also:

ega_putcircle, ega_orcircle, ega_xorcircle, ega_filledcircle



























-- Page 8 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_andellipse

Purpose:

AND an ellipse to the screen.

Calling Protocol:

void ega_andellipse(xloc, yloc, height, width, colour)

int xloc, yloc; /* (x,y) of centre of the ellipse */
int height; /* Height of the ellipse */
int width; /* Width of the ellipse */
int colour; /* Colour of the ellipse */

Description:

This function uses the AND operation to draw an ellipse on the screen.
The height and width of the ellipse (passed as arguments) vary the shape of
the ellipse. You can also draw circles using this function, if you pass the
height and width variables as the same value (a radius), and it will only
take slightly longer than the circle drawing algorithm.

The algorithm implemented to draw the ellipse was developed by
Bresenham, and is the fastest without using the sin and cos functions.

Example:

See ega_putellipse, as for ega_putellipse

See Also:

ega_putellipse, ega_orellipse, ega_xorellipse, ega_filledellipse






















-- Page 9 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_andline

Purpose:

AND a line to the screen.

Calling Protocol:

void ega_andline(first, firsty, secondx, secondy, colour)

int firstx, firsty; /* First (x,y) co-ordinate */
int secondx, secondy; /* Second (x,y) co-ordinate */
int colour; /* Colour to draw the line */

Description:

This function will place a line on the screen, using the AND
operation. The algorithm used is another of Bresenham's, and is again
the fastest method for drawing lines.

Example:

See ega_putline, as for ega_putline

See Also:

ega_putline, ega_orline, ega_andline




























-- Page 10 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_andpixel

Purpose:

AND a pixel to the screen.

Calling Protocol:

void ega_andpixel(xloc, yloc, colour)

int xloc, yloc; /* (x,y) co-ordinate of the pixel */
int colour; /* Colour of the pixel */

Description:

This function will place one pixel on the screen, at the specified
co-ordinate. The pixel is written using the graphics controller registers,
so that there is no tedious work involved for the computer. This also means
that the pixel update is almost instentaneous. You could use this fuction
for any graphics primitives of your own that you are developing.

Example:

See ega_putpixel, as for ega_putpixel

See Also:

ega_putpixel, ega_orpixel, ega_xorpixel, ega_getpixel



























-- Page 11 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_andpoly

Purpose:

AND a polygon to the screen.

Calling Protocol:

void ega_andpoly(colour, ...)

int colour; /* Colour to draw the polygon */
... /* Variable list of arguments, see description */

Description:

This function is used to draw any type of polygon on the screen. The
locations of each of the co-ordinate pairs are passed as arguments to the
function, with the last set being (-1,-1) to end the polygon drawing.

You MUST end the list of co-ordinates with (-1,-1) otherwise the
routine will not exit from the drawing procedure. You can pass as many
sets of co-ordinate arguments as you need, there is no fixed limit (the
function is programmed to use variable argument lists).

Example:

See ega_putpoly, as for ega_putpoly

See Also:

ega_putpoly, ega_orpoly, ega_xorpoly
























-- Page 12 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_andrectangle

Purpose:

AND a rectangle on the screen.

Calling Protocol:

void ega_andrectangle(topx, topy, bottomx, bottomy, colour)

int topx, topy; /* Top left corner (x,y) co-ord. */
int bottomx, bottomy; /* Bottom right corner (x,y) co-ord. */
int colour; /* Colour of the rectangle */

Description:

This function will draw a rectangle on the screen, using the AND
operation. The routine used to draw the rectangle is an adapted version of
the line drawing function, only catering for horizontal and vertical lines.
This means the routine will execute faster than if four calls to the line
drawing function were made.

The co-ordinates of the rectangle do not have to be in a specific
top/bottom order, as the routine can handle rectangles that are passed with
the co-ordinates upside down.

Example:

See ega_putrectangle, as for ega_putrectangle

See Also:

ega_putrectangle, ega_orrectangle, ega_xorrectangle,
ega_filledrectangle





















-- Page 13 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_andtriangle

Calling Protocol:

void ega_andtriangle(firstx, firsty, secondx, secondy,
thirdx, thirdy, colour)

int firstx, firsty; /* (x,y) location of first vertice */
int secondx, secondy; /* (x,y) location of second vertice */
int thirdx, thirdy; /* (x,y) location of third vertice */
int colour; /* Colour of the triangle */

Description:

This function will draw a triangle on the screen using the AND bitwise
operation. The passed co-ordinates can be in any specific order, as the
routine does not need to draw the lines in any special order either.

The main work of this function is spent in three calls to the line
drawing routine, drawing lines from the first point to the second point,
the second point to the third point, and the third point back to the first
point.

Example:

See ega_puttriangle, as for ega_puttriangle

See Also:

ega_puttriangle, ega_ortriangle, ega_xortriangle, ega_filledtriangle

























-- Page 14 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_clearpage

Purpose:

Clear the graphics page.

Calling Protocol:

void ega_clearpage(void)

Description:

This function is used to clear the contents of the current active
page. If you wish to clear out both pages of video memory, you can use the
mode set routine to acheive the same result as two calls to ega_clearpage
would.

Example:

/* Light Speed Reference Example Program */
/* Clear the graphics screen */
#include "lspeed.h"

main()
{
/* Set graphics mode, register font */
set640x350();
registernicefont();

/* Write a message */
ega_writetext(10, 10, LS_YELLOW, LS_BLUE, NICE_FONT,
" Press a key to clear the screen... ");

/* Wait for a key, clear the screen, exit */
getxch();
ega_clearpage();
set80x25();
}

Please note that the above program is only here as an example - there
is not much you can do to demonstrate the effect of a screen clear. The
almost instentaneous call to set80x25() when exiting the program almost
defies the use of the ega_clearpage function anyway, as a mode set will
clear whole video buffer.

See Also:

ega_setapage







-- Page 15 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_fillarea

Purpose:

Fill an area on the screen.

Calling Protocol:

void ega_fillarea(xloc, yloc, fillcolour, bordercolour)

int xloc, yloc; /* Seed point to start fill from */
int fillcolour; /* Colour to use for fill */
int bordercolour; /* Colour of the border pixels of the area */

Description:

This is used to fill an area with a specified colour. The function
uses the seed point as a point to start the filling from, and will fill up
to the boundary specified by the bordercolour value. If the shape is not
enclose, the fill will leak out into the screen, and fill up to the edges
of the screen.

Example:

No example provided.






























-- Page 16 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_filledcircle

Purpose:

Fill a circle as it is drawn.

Calling Protocol:

void ega_filledcircle(xloc, yloc, radius, colour)

int xloc, yloc; /* (x,y) of centre of circle */
int radius; /* Radius of circle */
int colour; /* Colour of the filled circle */

Description:

This function is similar to the ega_putcircle function, except that as
the circle is drawn on the screen, it is filled with the drawing colour.
The filling takes place as the circle is drawn, so the circle will overlap
any other drawing underneath.

Example:

/* Light Speed Reference Example Program */
/* Filled circles */
#include "lspeed.h"
#include
#include

main()
{
/* Set the graphics mode, register font */
set640x350();
registernicefont();

/* Seed the random numbers */
randomize();

/* Print the press a key message */
ega_writetext(220, 335, LS_YELLOW, LS_BLUE, NICE_FONT,
" Press a key to stop... ");

/* While there is no key... */
while (!kbhit())
{
/* Place a random circle on the screen */
ega_filledcircle(50+random(535), 50+random(235), random(50),
random(16));
}






-- Page 17 --




Light Speed
High Speed Graphics Programming


/* Get the key, exit */
getxch();
set80x25();
}

See Also:

ega_putcircle, ega_andcircle, ega_orcircle, ega_xorcircle

















































-- Page 18 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_filledellipse

Purpose:

Fill an ellipse as it is drawn.

Calling Protocol:

void ega_filledellipse(xloc, yloc, height, width, colour)

int xloc, yloc; /* (x,y) of centre of the ellipse */
int height; /* Height of the ellipse */
int width; /* Width of the ellipse */
int colour; /* Colour of the filled ellipse */

Description:

This function is similar to the ega_putcircle function, except that
as the ellipse is drawn on the screen, it is filled with the drawing
colour. The filling takes place as the ellipse is drawn, so the ellipse
will overlap any other drawing underneath.

Example:

/* Light Speed Reference Example Program */
/* Filled ellipses */
#include "lspeed.h"
#include
#include

main()
{
/* Set the graphics mode, register font */
set640x350();
registernicefont();

/* Seed the random numbers */
randomize();

/* Print the press a key message */
ega_writetext(220, 335, LS_YELLOW, LS_BLUE, NICE_FONT,
" Press a key to stop... ");

/* While there is no key... */
while (!kbhit())
{
/* Place a random ellipse on the screen */
ega_filledellipse(50+random(540), 50+random(235), random(50),
random(50), random(16));
}





-- Page 19 --




Light Speed
High Speed Graphics Programming


/* Get the key, exit */
getxch();
set80x25();
}

See Also:

ega_putellipse, ega_andellipse, ega_orellipse, ega_xorellipse

















































-- Page 20 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_filledrectangle

Purpose:

Draw and fill a rectangle.

Calling Protocol:

void ega_filledrectangle(topx, topy, bottomx, bottomy, colour)

int topx, topy; /* Top left corner (x,y) co-ord. */
int bottomx, bottomy; /* Bottom right corner (x,y) co-ord. */
int colour; /* Colour of the filled rectangle */

Description:

This function is similar to the ega_putrectangle function, except
that as the rectangle is drawn on the screen, it is filled with the
drawing colour. The filling takes place as the rectangle is drawn, so the
rectangle will overlap any other drawing underneath.

The co-ordinates of the rectangle do not have to be in a specific
top/bottom order, as the routine can handle rectangles that are passed with
the co-ordinates upside down.

The algorithm use to fill the rectangle is not the a standard
recursive fill. Instead, it uses writes to the video buffer to fill
different portions of the rectangle each time. This means it is much faster
than a fill done by drawing lines.

Example:

/* Light Speed Reference Example Program */
/* Filled rectangles */
#include "lspeed.h"
#include
#include

main()
{
/* Set the graphics mode, register font */
set640x350();
registernicefont();

/* Seed the random numbers */
randomize();

/* Print the press a key message */
ega_writetext(220, 335, LS_YELLOW, LS_BLUE, NICE_FONT,
" Press a key to stop... ");





-- Page 21 --




Light Speed
High Speed Graphics Programming


/* While there is no key... */
while (!kbhit())
{
/* Draw a random rectangle */
ega_filledrectangle(random(640), random(335), random(640),
random(335), random(16));
}

/* Get the key, exit */
getxch();
set80x25();
}

See Also:

ega_putrectangle, ega_orrectangle, ega_xorrectangle, ega_andrectangle









































-- Page 22 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_filledtriangle

Purpose:

Draw and fill a triangle.

Calling Protocol:

void ega_andtriangle(firstx, firsty, secondx, secondy,
thirdx, thirdy, colour)

int firstx, firsty; /* (x,y) location of first vertice */
int secondx, secondy; /* (x,y) location of second vertice */
int thirdx, thirdy; /* (x,y) location of third vertice */
int colour; /* Colour of the triangle */

Description:

This function is similar to the ega_puttriangle function, except that
as the triangle is drawn on the screen, it is filled with the drawing
colour. The filling takes place as the triangle is drawn, so the triangle
will overlap any other drawing underneath.

Example:

/* Light Speed Reference Example Program */
/* Filled triangles */
#include "lspeed.h"
#include
#include

main()
{
/* Set the graphics mode, register font */
set640x350();
registernicefont();

/* Seed the random numbers */
randomize();

/* Print the press a key message */
ega_writetext(220, 335, LS_YELLOW, LS_BLUE, NICE_FONT,
" Press a key to stop... ");

/* While there is no key... */
while (!kbhit())
{
/* Draw a random triangle */
ega_filledtriangle(random(640), random(335), random(640),
random(335), random(640), random(335),
random(16));
}



-- Page 23 --




Light Speed
High Speed Graphics Programming


/* Get the key, exit */
getxch();
set80x25();
}

See Also:

ega_puttriangle, ega_xortriangle, ega_ortriangle, ega_andtriangle

















































-- Page 24 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_getpixel

Purpose:

Read a pixel value.

Calling Protocol

int ega_getpixel(xloc, yloc)

int xloc, yloc; /* (x,y) location of pixel */

Description:

This function is used to read the value of a pixel from the screen.
The value returned can be used in subsequent calls to ega_putpixel (or a
similar function), or for testing the properties of certain pixels.

Example:

See ega_putpixel.

See Also:

ega_putpixel, ega_andpixel, ega_orpixel, ega_xorpixel






























-- Page 25 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_orcircle

Purpose:

OR a circle to the screen.

Calling Protocol:

void ega_orcircle(xloc, yloc, radius, colour)

int xloc, yloc; /* (x,y) of centre of the circle */
int radius; /* The radius of the circle */
int colour; /* The colour of the circle */

Description:

This function will place a circle on the screen using the OR bitwise
operation. The algorithm used was developed by Bresenham, and is the
fastest known method of drawing a circle. There is no use of the
trigonometric sin or cos functions.

Example:

See the ega_putcircle function, as for ega_putcircle.

See Also:

ega_putcircle, ega_andcircle, ega_xorcircle, ega_filledcircle



























-- Page 26 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_orellipse

Purpose:

OR an ellipse to the screen.

Calling Protocol:

void ega_orellipse(xloc, yloc, height, width, colour)

int xloc, yloc; /* (x,y) of centre of the ellipse */
int height; /* Height of the ellipse */
int width; /* Width of the ellipse */
int colour; /* Colour of the ellipse */

Description:

This function uses the OR operation to draw an ellipse on the screen.
The height and width of the ellipse (passed as arguments) vary the shape of
the ellipse. You can also draw circles using this function, if you pass the
height or width variables as the same value (a radius), and it will only
take slightly longer than the circle drawing algorithm.

The algorithm implemented to draw the ellipse was developed by
Bresenham, and is the fastest without using the sin or cos functions.

Example:

See ega_putellipse, as for ega_putellipse

See Also:

ega_putellipse, ega_andellipse, ega_xorellipse, ega_filledellipse






















-- Page 27 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_orline

Purpose:

OR a line to the screen.

Calling Protocol:

void ega_orline(first, firsty, secondx, secondy, colour)

int firstx, firsty; /* First (x,y) co-ordinate */
int secondx, secondy; /* Second (x,y) co-ordinate */
int colour; /* Colour to draw the line */

Description:

This function will place a line on the screen, using the OR
operation. The algorithm used is another of Bresenham's, and is again
the fastest method for drawing lines.

Example:

See ega_putline, as for ega_putline

See Also:

ega_putline, ega_andline, ega_xorline




























-- Page 28 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_orpixel

Purpose:

OR a pixel to the screen.

Calling Protocol:

void ega_orpixel(xloc, yloc, colour)

int xloc, yloc; /* (x,y) co-ordinate of the pixel */
int colour; /* Colour of the pixel */

Description:

This function will place one pixel on the screen, at the specified
co-ordinate. The pixel is written using the graphics controller registers,
so that there is no tedious work involved for the computer. This also means
that the pixel update is almost instentaneous. You could use this fuction
for any graphics primitives of your own that you are developing.

Example:

See ega_putpixel, as for ega_putpixel

See Also:

ega_putpixel, ega_andpixel, ega_xorpixel, ega_getpixel



























-- Page 29 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_orpoly

Purpose:

OR a polygon to the screen.

Calling Protocol:

void ega_orpoly(colour, ...)

int colour; /* Colour to draw the polygon */
... /* Variable list of arguments, see description */

Description:

This function is used to draw any type of polygon on the screen. The
locations of each of the co-ordinate pairs are passed as arguments to the
function, with the last set being (-1,-1) to end the polygon drawing.

You MUST end the list of co-ordinates with (-1,-1) otherwise the
routine will not exit from the drawing procedure. You can pass as many
sets of co-ordinate arguments as you need, there is no fixed limit (the
function is programmed to use variable argument lists).

Example:

See ega_putpoly, as for ega_putpoly

See Also:

ega_putpoly, ega_andpoly, ega_xorpoly
























-- Page 30 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_orrectangle

Purpose:

OR a rectangle on the screen.

Calling Protocol:

void ega_orrectangle(topx, topy, bottomx, bottomy, colour)

int topx, topy; /* Top left corner (x,y) co-ord. */
int bottomx, bottomy; /* Bottom right corner (x,y) co-ord. */
int colour; /* Colour of the rectangle */

Description:

This function will draw a rectangle on the screen, using the OR
operation. The routine used to draw the rectangle is an adapted version of
the line drawing function, only catering for horizontal or vertical lines.
This means the routine will execute faster than if four calls to the line
drawing function were made.

The co-ordinates of the rectangle do not have to be in a specific
top/bottom order, as the routine can handle rectangles that are passed with
the co-ordinates upside down.

Example:

See ega_putrectangle, as for ega_putrectangle

See Also:

ega_putrectangle, ega_andrectangle, ega_xorrectangle,
ega_filledrectangle





















-- Page 31 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_ortriangle

Calling Protocol:

void ega_ortriangle(firstx, firsty, secondx, secondy,
thirdx, thirdy, colour)

int firstx, firsty; /* (x,y) location of first vertice */
int secondx, secondy; /* (x,y) location of second vertice */
int thirdx, thirdy; /* (x,y) location of third vertice */
int colour; /* Colour of the triangle */

Description:

This function will draw a triangle on the screen using the OR bitwise
operation. The passed co-ordinates can be in any specific order, as the
routine does not need to draw the lines in any special order either.

The main work of this function is spent in three calls to the line
drawing routine, drawing lines from the first point to the second point,
the second point to the third point, and the third point back to the first
point.

Example:

See ega_puttriangle, as for ega_puttriangle

See Also:

ega_puttriangle, ega_andtriangle, ega_xortriangle, ega_filledtriangle

























-- Page 32 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_putcircle

Purpose:

Draw a circle to the screen.

Calling Protocol:

void ega_putcircle(xloc, yloc, radius, colour)

int xloc, yloc; /* (x,y) of centre of the circle */
int radius; /* The radius of the circle */
int colour; /* The colour of the circle */

Description:

This function will draw a circle on the screen. The algorithm used
was developed by Bresenham, and is the fastest known method of drawing a
circle. There is no use of the trigonometric sin and cos functions.

Example:

/* Light Speed Reference Example Program */
/* Random circles */
#include "lspeed.h"
#include
#include

main()
{
/* Set the graphics mode, register font */
set640x350();
registernicefont();

/* Seed the random numbers */
randomize();

/* Print the press a key message */
ega_writetext(220, 335, LS_YELLOW, LS_BLUE, NICE_FONT,
" Press a key to stop... ");

/* While there is no key... */
while (!kbhit())
{
/* Place a random circle on the screen */
putcircle(50+random(540), 50+random(235),
random(50), random(16));
}

/* Get the key, exit */
getxch();
set80x25();
}


-- Page 33 --




Light Speed
High Speed Graphics Programming



/* Draw a circle 3 lines wide */
putcircle(xloc, yloc, radius, colour)
int xloc, yloc;
int radius;
int colour;
{
if (radius<3)
return;
ega_putcircle(xloc, yloc, radius, colour);
ega_putcircle(xloc, yloc, radius-1, colour);
ega_putcircle(xloc, yloc, radius-2, colour);
}

See Also:

ega_orcircle, ega_andcircle, ega_xorcircle, ega_filledcircle








































-- Page 34 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_putellipse

Purpose:

Draw an ellipse to the screen.

Calling Protocol:

void ega_putellipse(xloc, yloc, height, width, colour)

int xloc, yloc; /* (x,y) of centre of the ellipse */
int height; /* Height of the ellipse */
int width; /* Width of the ellipse */
int colour; /* Colour of the ellipse */

Description:

This function draws an ellipse on the screen. The height and width of
the ellipse (passed as arguments) vary the shape of the ellipse. You can
also draw circles using this function, if you pass the height and width
variables as the same value (a radius), and it will only take slightly
longer than the circle drawing alorithm.

The algorithm implemented to draw the ellipse was developed by
Bresenham, and is the fastest without using the sin and cos functions.

Example:

/* Light Speed Reference Example Program */
/* Random ellipses */
#include "lspeed.h"
#include
#include

main()
{
/* Set the graphics mode, register font */
set640x350();
registernicefont();

/* Seed the random numbers */
randomize();

/* Print the press a key message */
ega_writetext(220, 335, LS_YELLOW, LS_BLUE, NICE_FONT,
" Press a key to stop... ");









-- Page 35 --




Light Speed
High Speed Graphics Programming


/* While there is no key... */
while (!kbhit())
{
/* Place a random ellipse on the screen */
putellipse(50+random(540), 50+random(235),
random(50), random(50), random(16));
}

/* Get the key, exit */
getxch();
set80x25();
}

/* Draw an ellipse 3 lines wide */
putellipse(xloc, yloc, radius1, radius2, colour)
int xloc, yloc;
int radius1, radius2;
int colour;
{
if (radius1<3 || radius2<3)
return;
ega_putellipse(xloc, yloc, radius1, radius2, colour);
ega_putellipse(xloc, yloc, radius1-1, radius2-1, colour);
ega_putellipse(xloc, yloc, radius1-2, radius2-2, colour);
}

See Also:

ega_orellipse, ega_andellipse, ega_xorellipse, ega_filledellipse




























-- Page 36 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_putline

Purpose:

Draw a line to the screen.

Calling Protocol:

void ega_putline(first, firsty, secondx, secondy, colour)

int firstx, firsty; /* First (x,y) co-ordinate */
int secondx, secondy; /* Second (x,y) co-ordinate */
int colour; /* Colour to draw the line */

Description:

This function will place a line on the screen, in the specified
colour. The algorithm used is another of Bresenham's, and is again the
fastest method of drawing lines.

Example:

/* Light Speed Reference Example Program */
/* Line drawing */
#include "lspeed.h"
#include
#include

main()
{
/* Variables */
int lines[4][32], left_x_inc, right_x_inc, up_y_inc, down_y_inc;
unsigned char curline;

/* Set the graphics mode, register font */
set640x350();
registernicefont();

/* Seed the random numbers, set variables */
randomize();
left_x_inc=-2;
right_x_inc=2;
up_y_inc=2;
down_y_inc=2;

/* Print the press a key message */
ega_writetext(220, 335, LS_YELLOW, LS_BLUE, NICE_FONT,
" Press a key to stop... ");







-- Page 37 --




Light Speed
High Speed Graphics Programming


/* Set up some lines */
lines[0][0] = 320;
lines[1][0] = 170;
lines[2][0] = 320;
lines[3][0] = 170;
for (curline=1; curline<32; curline++)
{
lines[0][curline] = lines[0][curline-1]+left_x_inc;
lines[1][curline] = lines[1][curline-1]+up_y_inc;
lines[2][curline] = lines[2][curline-1]+right_x_inc;
lines[3][curline] = lines[3][curline-1]+down_y_inc;
}

/* Draw the lines */
for (curline=0; curline<32; curline++)
ega_putline(lines[0][curline], lines[1][curline],
lines[2][curline], lines[3][curline], curline);
curline=31;

/* While there is no key... */
while (!kbhit())
{
curline++;

/* Erase the last line */
ega_putline(lines[0][curline&31], lines[1][curline&31],
lines[2][curline&31], lines[3][curline&31], 0);

/* Increment the first point */
lines[0][curline&31] = lines[0][(curline-1)&31]+left_x_inc;
if (lines[0][curline&31]<0) /* Out of range? */
{
left_x_inc=random(11)+3;
lines[0][curline&31]=0;
}
if (lines[0][curline&31]>639) /* Out of range? */
{
left_x_inc=-10+random(11)-3;
lines[0][curline&31]=639;
}

/* Increment the second point */
lines[1][curline&31] = lines[1][(curline-1)&31]+up_y_inc;
if (lines[1][curline&31]<0) /* Out of range? */
{
up_y_inc=random(11)+3;
lines[1][curline&31]=0;
}
if (lines[1][curline&31]>334) /* Out of range? */
{
up_y_inc=-10+random(11)-3;
lines[1][curline&31]=334;
}




-- Page 38 --




Light Speed
High Speed Graphics Programming


/* Increment the third point */
lines[2][curline&31] = lines[2][(curline-1)&31]+right_x_inc;
if (lines[2][curline&31]<0) /* Out of range? */
{
right_x_inc=random(11)+3;
lines[2][curline&31]=0;
}
if (lines[2][curline&31]>639) /* Out of range? */
{
right_x_inc=-10+random(11)-3;
lines[2][curline&31]=639;
}

/* Increment the last point */
lines[3][curline&31] = lines[3][(curline-1)&31]+down_y_inc;
if (lines[3][curline&31]<0) /* Out of range? */
{
down_y_inc=random(11)+3;
lines[3][curline&31]=0;
}
if (lines[3][curline&31]>334) /* Out of range? */
{
down_y_inc=-10+random(11)-3;
lines[3][curline&31]=334;
}

/* Draw the newly updated line */
ega_putline(lines[0][curline&31], lines[1][curline&31],
lines[2][curline&31], lines[3][curline&31], curline);

/* Small microprocessor delay */
delay(5);
}

/* Exit the program */
getxch();
set80x25();
}

See Also:

ega_orline, ega_andline, ega_xorline















-- Page 39 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_putpixel

Purpose:

Draw a pixel to the screen.

Calling Protocol:

void ega_putpixel(xloc, yloc, colour)

int xloc, yloc; /* (x,y) co-ordinate of the pixel */
int colour; /* Colour of the pixel */

Description:

This function will place one pixel on the screen, at the specified
co-ordinate. The pixel is written using the graphics controller registers,
so that there is no tedious work involved for the computer. This also means
that the pixel update is almost instentaneous. You could use this fuction
for any graphics primitives of your own that you are developing.

Example:

/* Light Speed Reference Example Program */
/* Random pixels */
#include "lspeed.h"
#include
#include

main()
{
/* Variables */
int xloc, yloc, colour;

/* Set the graphics mode, register font */
set640x350();
registernicefont();

/* Seed the random numbers */
randomize();

/* Print the press a key message */
ega_writetext(220, 335, LS_YELLOW, LS_BLUE, NICE_FONT,
" Press a key to stop... ");

/* While there is no key... */
while (!kbhit())
{
/* Place a random pixel on the screen */
xloc = random(640);
yloc = random(335);
colour = random(16);



-- Page 40 --




Light Speed
High Speed Graphics Programming


/* Don't update already used locations */
if (!ega_getpixel(xloc, yloc))
ega_putpixel(xloc, yloc, colour);
}

/* Get the key, exit */
getxch();
set80x25();
}

See Also:

ega_putpixel, ega_andpixel, ega_xorpixel, ega_getpixel













































-- Page 41 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_putpoly

Purpose:

Draw a polygon to the screen.

Calling Protocol:

void ega_putpoly(colour, ...)

int colour; /* Colour to draw the polygon */
... /* Variable list of arguments, see description */

Description:

This function is used to draw any type of polygon on the screen. The
locations of each of the co-ordinate pairs are passed as arguments to the
function, with the last set being (-1,-1) to end the polygon drawing.

You MUST end the list of co-ordinates with (-1,-1) otherwise the
routine will not exit from the drawing procedure. You can pass as many
sets of co-ordinate arguments as you need, there is no fixed limit (the
function is programmed to use variable argument lists).

Example:

/* Light Speed Reference Example Program */
/* Random polygons */
#include "lspeed.h"
#include
#include

main()
{
/* Variables */
int locations[20][2], loop, looptop;

/* Set the graphics mode, register font */
set640x350();
registernicefont();

/* Seed the random numbers */
randomize();

/* Print the press a key message */
ega_writetext(220, 335, LS_YELLOW, LS_BLUE, NICE_FONT,
" Press a key to stop... ");








-- Page 42 --




Light Speed
High Speed Graphics Programming


/* While there is no key... */
while (!kbhit())
{
/* Place a random polygon on the screen */
ega_putpoly(random(16), random(640), random(335), random(640),
random(335), random(640), random(335), random(640),
random(335), random(640), random(335), random(640),
random(335), -1, -1);

/* Small time delay */
delay(125);
}

/* Get the key, exit */
getxch();
set80x25();
}

See Also:

ega_orpoly, ega_andpoly, ega_xorpoly




































-- Page 43 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_putrectangle

Purpose:

Draw a rectangle on the screen.

Calling Protocol:

void ega_putrectangle(topx, topy, bottomx, bottomy, colour)

int topx, topy; /* Top left corner (x,y) co-ord. */
int bottomx, bottomy; /* Bottom right corner (x,y) co-ord. */
int colour; /* Colour of the rectangle */

Description:

This function will draw a rectangle on the screen. The routine used to
draw the rectangle is an adapted version of the line drawing function, only
catering for horizontal and vertical lines. This means the routine will
execute faster than if four calls to the line drawing function were made.

The co-ordinates of the rectangle do not have to be in a specific
top/bottom order, as the routine can handle rectangles that are passed with
the co-ordinates upside down.

Example:

/* Light Speed Reference Example Program */
/* Rectangle drawing */
#include "lspeed.h"
#include
#include

main()
{
/* Variables */
int lines[4][16], left_x_inc, right_x_inc, up_y_inc, down_y_inc;
unsigned char curline;

/* Set the graphics mode, register font */
set640x350();
registernicefont();

/* Seed the random numbers, set variables */
randomize();
left_x_inc=-5;
right_x_inc=5;
up_y_inc=-5;
down_y_inc=5;

/* Print the press a key message */
ega_writetext(220, 335, LS_YELLOW, LS_BLUE, NICE_FONT,
" Press a key to stop... ");


-- Page 44 --




Light Speed
High Speed Graphics Programming


/* Set up some lines */
lines[0][0] = 320;
lines[1][0] = 170;
lines[2][0] = 320;
lines[3][0] = 170;
for (curline=1; curline<16; curline++)
{
lines[0][curline] = lines[0][curline-1]+left_x_inc;
lines[1][curline] = lines[1][curline-1]+up_y_inc;
lines[2][curline] = lines[2][curline-1]+right_x_inc;
lines[3][curline] = lines[3][curline-1]+down_y_inc;
}

/* Draw the lines */
for (curline=0; curline<16; curline++)
ega_putrectangle(lines[0][curline], lines[1][curline],
lines[2][curline], lines[3][curline], curline);
curline=15;

/* While there is no key... */
while (!kbhit())
{
curline++;

/* Erase the last rectangle */
ega_putrectangle(lines[0][curline&15], lines[1][curline&15],
lines[2][curline&15], lines[3][curline&15], 0);

/* Increment first point */
lines[0][curline&15] = lines[0][(curline-1)&15]+left_x_inc;
if (lines[0][curline&15]<0) /* Out of range? */
{
left_x_inc=random(11)+3;
lines[0][curline&15]=0;
}
if (lines[0][curline&15]>639) /* Out of range? */
{
left_x_inc=-10+random(11)-3;
lines[0][curline&15]=639;
}

/* Increment the second point */
lines[1][curline&15] = lines[1][(curline-1)&15]+up_y_inc;
if (lines[1][curline&15]<0) /* Out of range? */
{
up_y_inc=random(11)+3;
lines[1][curline&15]=0;
}
if (lines[1][curline&15]>334) /* Out of range? */
{
up_y_inc=-10+random(11)-3;
lines[1][curline&15]=334;
}




-- Page 45 --




Light Speed
High Speed Graphics Programming


/* Increment the third point */
lines[2][curline&15] = lines[2][(curline-1)&15]+right_x_inc;
if (lines[2][curline&15]<0) /* Out of range? */
{
right_x_inc=random(11)+3;
lines[2][curline&15]=0;
}
if (lines[2][curline&15]>639) /* Out of range? */
{
right_x_inc=-10+random(11)-3;
lines[2][curline&15]=639;
}

/* Increment the last point */
lines[3][curline&15] = lines[3][(curline-1)&15]+down_y_inc;
if (lines[3][curline&15]<0) /* Out of range? */
{
down_y_inc=random(11)+3;
lines[3][curline&15]=0;
}
if (lines[3][curline&15]>334) /* Out of range? */
{
down_y_inc=-10+random(11)-3;
lines[3][curline&15]=334;
}
ega_putrectangle(lines[0][curline&15], lines[1][curline&15],
lines[2][curline&15], lines[3][curline&15], curline);

delay(15);
}


/* Get the key, exit */
getxch();
set80x25();
}

See Also:

ega_orrectangle, ega_andrectangle, ega_xorrectangle,
ega_filledrectangle

















-- Page 46 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_puttriangle

Calling Protocol:

void ega_puttriangle(firstx, firsty, secondx, secondy,
thirdx, thirdy, colour)

int firstx, firsty; /* (x,y) location of first vertice */
int secondx, secondy; /* (x,y) location of second vertice */
int thirdx, thirdy; /* (x,y) location of third vertice */
int colour; /* Colour of the triangle */

Description:

This function will draw a triangle on the screen in the specified
colour. The passed co-ordinates can be in any specific order, as the
routine does not need to draw the lines in any special order either.

The main work of this function is spent in three calls to the line
drawing routine, drawing lines from the first point to the second point,
the second point to the third point, and the third point back to the first
point.

Example:

/* Light Speed Reference Example Program */
/* Triangle drawing */
#include "lspeed.h"
#include
#include

main()
{
/* Variables */
int lines[6][16], first_x_inc, second_x_inc, first_y_inc;
int second_y_inc, third_x_inc, third_y_inc;
unsigned char curline;

/* Set the graphics mode, register font */
set640x350();
registernicefont();

/* Seed the random numbers, set variables */
randomize();
first_x_inc=0;
second_x_inc=2;
third_x_inc=-2;
first_y_inc=-2;
second_y_inc=2;
third_y_inc=2;





-- Page 47 --




Light Speed
High Speed Graphics Programming


/* Print the press a key message */
ega_writetext(220, 335, LS_YELLOW, LS_BLUE, NICE_FONT,
" Press a key to stop... ");

/* Set first some lines */
lines[0][0] = 320;
lines[1][0] = 170;
lines[2][0] = 320;
lines[3][0] = 170;
lines[4][0] = 320;
lines[5][0] = 170;

for (curline=1; curline<16; curline++)
{
lines[0][curline] = lines[0][curline-1]+first_x_inc;
lines[1][curline] = lines[1][curline-1]+first_y_inc;
lines[2][curline] = lines[2][curline-1]+second_x_inc;
lines[3][curline] = lines[3][curline-1]+second_y_inc;
lines[4][curline] = lines[4][curline-1]+third_x_inc;
lines[5][curline] = lines[5][curline-1]+third_y_inc;
}

/* Draw the lines */
for (curline=0; curline<16; curline++)
ega_puttriangle(lines[0][curline], lines[1][curline],
lines[2][curline], lines[3][curline],
lines[4][curline], lines[5][curline],
curline&15);
curline=15;

/* While there is no key... */
while (!kbhit())
{
curline++;

/* Erase the last triangle */
ega_puttriangle(lines[0][curline&15], lines[1][curline&15],
lines[2][curline&15], lines[3][curline&15],
lines[4][curline&15], lines[5][curline&15], 0);

/* Increment the first point */
lines[0][curline&15] = lines[0][(curline-1)&15]+first_x_inc;
if (lines[0][curline&15]<0) /* Out of range? */
{
first_x_inc=random(11)+3;
lines[0][curline&15]=0;
}
if (lines[0][curline&15]>639) /* Out of range? */
{
first_x_inc=-10+random(11)-3;
lines[0][curline&15]=639;
}





-- Page 48 --




Light Speed
High Speed Graphics Programming


/* Increment the second point */
lines[1][curline&15] = lines[1][(curline-1)&15]+first_y_inc;
if (lines[1][curline&15]<0) /* Out of range? */
{
first_y_inc=random(11)+3;
lines[1][curline&15]=0;
}
if (lines[1][curline&15]>334) /* Out of range? */
{
first_y_inc=-10+random(11)-3;
lines[1][curline&15]=334;
}


/* Increment the third point */
lines[2][curline&15] = lines[2][(curline-1)&15]+second_x_inc;
if (lines[2][curline&15]<0) /* Out of range? */
{
second_x_inc=random(11)+3;
lines[2][curline&15]=0;
}
if (lines[2][curline&15]>639) /* Out of range? */
{
second_x_inc=-10+random(11)-3;
lines[2][curline&15]=639;
}

/* Increment the fourth point */
lines[3][curline&15] = lines[3][(curline-1)&15]+second_y_inc;
if (lines[3][curline&15]<0) /* Out of range? */
{
second_y_inc=random(11)+3;
lines[3][curline&15]=0;
}
if (lines[3][curline&15]>334) /* Out of range? */
{
second_y_inc=-10+random(11)-3;
lines[3][curline&15]=334;

}

/* Increment the fifth point */
lines[4][curline&15] = lines[4][(curline-1)&15]+third_x_inc;
if (lines[4][curline&15]<0) /* Out of range? */
{
third_x_inc=random(11)+3;
lines[4][curline&15]=0;
}
if (lines[4][curline&15]>639) /* Out of range? */
{
third_x_inc=-10+random(11)-3;
lines[4][curline&15]=639;
}






-- Page 49 --




Light Speed
High Speed Graphics Programming


/* Increment the last point */
lines[5][curline&15] = lines[5][(curline-1)&15]+third_y_inc;
if (lines[5][curline&15]<0) /* Out of range? */
{
third_y_inc=random(11)+3;
lines[5][curline&15]=0;
}
if (lines[5][curline&15]>334) /* Out of range? */
{
third_y_inc=-10+random(11)-3;
lines[5][curline&15]=334;
}

/* Draw the new triangle */
ega_puttriangle(lines[0][curline&15], lines[1][curline&15],
lines[2][curline&15], lines[3][curline&15],
lines[4][curline&15], lines[5][curline&15],
curline);


delay(5);
}

/* Exit the program */
getxch();
set80x25();
}

See Also:

ega_ortriangle, ega_andtriangle, ega_xortriangle, ega_filledtriangle


























-- Page 50 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_scanlinefill

Purpose:

Fill a scan line.

Calling Protocol:

void ega_scanlinefill(start, end, scanline, colour)

int start; /* Start column on scanline */
int end; /* Start column on scanline */
int scanline; /* Scanline number to fill */
int colour; /* Colour to fill scanline with */

Description:

This function will sill a specified scan line with a certain colour.
The scanline is the number of the row on the screen to fill, with different
modes having a different number of scanlines.

The starting and ending co-ordinates of the scanline are the columns
that specify the starting and ending address for the fill. The whole
scanline is not filled, just the portion specified by the starting and
ending position.

It is not a good idea to pass aout of bounds value to this function,
as no testing of the variables is performed. Passing scanline values that
are greater than the maximum available scanline would probably overwrite
the other page in the graphics memory.

Example:

No example provided.

See Also:

ega_maxscanline

















-- Page 51 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_xorcircle

Purpose:

XOR a circle to the screen.

Calling Protocol:

void ega_xorcircle(xloc, yloc, radius, colour)

int xloc, yloc; /* (x,y) of centre of the circle */
int radius; /* The radius of the circle */
int colour; /* The colour of the circle */

Description:

This function will place a circle on the screen using the XOR bitwise
operation. The algotrithm used was developed by Bresenham, and is the
fastest known method of drawing a circle. There is no use of the
trigonometric sin and cos functions.

Example:

See the ega_putcircle function, as for ega_putcircle.

See Also:

ega_putcircle, ega_orcircle, ega_andcircle, ega_filledcircle



























-- Page 52 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_xorellipse

Purpose:

XOR an ellipse to the screen.

Calling Protocol:

void ega_xorellipse(xloc, yloc, height, width, colour)

int xloc, yloc; /* (x,y) of centre of the ellipse */
int height; /* Height of the ellipse */
int width; /* Width of the ellipse */
int colour; /* Colour of the ellipse */

Description:

This function uses the XOR operation to draw an ellipse on the screen.
The height and width of the ellipse (passed as arguments) vary the shape of
the ellipse. You can also draw circles using this function, if you pass the
height and width variables as the same value (a radius), and it will only
take slightly longer than the circle drawing algorithm.

The algorithm implemented to draw the ellipse was developed by
Bresenham, and is the fastest without using the sin and cos functions.

Example:

See ega_putellipse, as for ega_putellipse

See Also:

ega_putellipse, ega_orellipse, ega_andellipse, ega_filledellipse






















-- Page 53 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_xorline

Purpose:

XOR a line to the screen.

Calling Protocol:

void ega_xorline(first, firsty, secondx, secondy, colour)

int firstx, firsty; /* First (x,y) co-ordinate */
int secondx, secondy; /* Second (x,y) co-ordinate */
int colour; /* Colour to draw the line */

Description:

This function will place a line on the screen, using the XOR
operation. The algorithm used is another of Bresenham's, and is again
the fastest method for drawing lines.

Example:

See ega_putline, as for ega_putline

See Also:

ega_putline, ega_orline, ega_andline




























-- Page 54 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_xorpixel

Purpose:

XOR a pixel to the screen.

Calling Protocol:

void ega_xorpixel(xloc, yloc, colour)

int xloc, yloc; /* (x,y) co-ordinate of the pixel */
int colour; /* Colour of the pixel */

Description:

This function will place one pixel on the screen, at the specified
co-ordinate. The pixel is written using the graphics controller registers,
so that there is no tedious work involved for the computer. This also means
that the pixel update is almost instentaneous. You could use this fuction
for any graphics primitives of your own that you are developing.

Example:

See ega_putpixel, as for ega_putpixel

See Also:

ega_putpixel, ega_orpixel, ega_andpixel, ega_getpixel



























-- Page 55 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_xorpoly

Purpose:

XOR a polygon to the screen.

Calling Protocol:

void ega_xorpoly(colour, ...)

int colour; /* Colour to draw the polygon */
... /* Variable list of arguments, see description */

Description:

This function is used to draw any type of polygon on the screen. The
locations of each of the co-ordinate pairs are passed as arguments to the
function, with the last set being (-1,-1) to end the polygon drawing.

You MUST end the list of co-ordinates with (-1,-1) otherwise the
routine will not exit from the drawing procedure. You can pass as many
sets of co-ordinate arguments as you need, there is no fixed limit (the
function is programmed to use variable argument lists).

Example:

See ega_putpoly, as for ega_putpoly

See Also:

ega_putpoly, ega_orpoly, ega_andpoly
























-- Page 56 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_xorrectangle

Purpose:

XOR a rectangle on the screen.

Calling Protocol:

void ega_xorrectangle(topx, topy, bottomx, bottomy, colour)

int topx, topy; /* Top left corner (x,y) co-ord. */
int bottomx, bottomy; /* Bottom right corner (x,y) co-ord. */
int colour; /* Colour of the rectangle */

Description:

This function will draw a rectangle on the screen, using the XOR
operation. The routine used to draw the rectangle is an adapted version of
the line drawing function, only catering for horizontal and vertical lines.
This means the routine will execute faster than if four calls to the line
drawing function were made.

The co-ordinates of the rectangle do not have to be in a specific
top/bottom order, as the routine can handle rectangles that are passed with
the co-ordinates upside down.

Example:

See ega_putrectangle, as for ega_putrectangle

See Also:

ega_putrectangle, ega_orrectangle, ega_andrectangle,
ega_filledrectangle





















-- Page 57 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_xortriangle

Calling Protocol:

void ega_xortriangle(firstx, firsty, secondx, secondy,
thirdx, thirdy, colour)

int firstx, firsty; /* (x,y) location of first vertice */
int secondx, secondy; /* (x,y) location of second vertice */
int thirdx, thirdy; /* (x,y) location of third vertice */
int colour; /* Colour of the triangle */

Description:

This function will draw a triangle on the screen using the XOR bitwise
operation. The passed co-ordinates can be in any specific order, as the
routine does not need to draw the lines in any special order either.

The main work of this function is spent in three calls to the line
drawing routine, drawing lines from the first point to the second point,
the second point to the third point, and the third point back to the first
point.

Example:

See ega_puttriangle, as for ega_puttriangle

See Also:

ega_puttriangle, ega_ortriangle, ega_andtriangle, ega_filledtriangle

























-- Page 58 --




Light Speed
High Speed Graphics Programming


Function Name:

set320x200

Purpose:

Set 320x200 graphics mode

Calling Protocol:

void set320x200(void)

Description:

This function will set the computer into 320x200 graphics mode, with
sixteen colours. All of the internal variables will be reset to their
correct values, and a clear of the video buffer will be performed.

You should not change modes using the BIOS video services (interrupt
10h, function 0h). The screen change will be performed, but the updating of
the variables for the Light Speed functions will not. This means that the
Light Speed routines willl still think they are in the last set graphics
mode. None of the routines will work as expected, in this case.

Example:

See the various example programs.

See Also:

set40x25, set640x200, set640x350, set80x25


























-- Page 59 --




Light Speed
High Speed Graphics Programming


Function Name:

set40x25

Purpose:

Set 40x25 text mode

Calling Protocol:

void set40x25(void)

Description:

This function will set the computer into 40x25 text mode, with
sixteen colours. The text modes are not supported by the library, so a
change mode to text will not reset any Light Speed values. You can use any
text mode function library (e.g. TCXL) in the text modes.

When you wish to return to graphics mode, you can call the function to
set the graphics, mode, and the parameters will be reset correctly.

Example:

See the various example programs.

See Also:

set320x200, set640x200, set640x350, set80x25




























-- Page 60 --




Light Speed
High Speed Graphics Programming


Function Name:

set640x200

Purpose:

Set 640x200 graphics mode

Calling Protocol:

void set640x200(void)

Description:

This function will set the computer into 640x200 graphics mode, with
sixteen colours. All of the internal variables will be reset to their
correct values, and a clear of the video buffer will be performed.

You should not change modes using the BIOS video services (interrupt
10h, function 0h). The screen change will be performed, but the updating of
the variables for the Light Speed functions will not. This means that the
Light Speed routines willl still think they are in the last set graphics
mode. None of the routines will work as expected, in this case.

Example:

See the various example programs.

See Also:

set320x200, set640x350, set80x25, set40x25


























-- Page 61 --




Light Speed
High Speed Graphics Programming


Function Name:

set640x350

Purpose:

Set 640x350 graphics mode

Calling Protocol:

void set640x350(void)

Description:

This function will set the computer into 640x350 graphics mode, with
sixteen colours. All of the internal variables will be reset to their
correct values, and a clear of the video buffer will be performed.

You should not change modes using the BIOS video services (interrupt
10h, function 0h). The screen change will be performed, but the updating of
the variables for the Light Speed functions will not. This means that the
light speed routines willl still think they are in the last set graphics
mode. None of the routines will work as expected, in this case.

Example:

See the various example programs.

See Also:

set320x200, set640x200, set80x25, set40x25


























-- Page 62 --




Light Speed
High Speed Graphics Programming


Function Name:

set80x25

Purpose:

Set 80x25 text mode

Calling Protocol:

void set80x25(void)

Description:

This function will set the computer into 80x25 text mode, with
sixteen colours. The text modes are not supported by the library, so a
change mode to text will not reset any Light Speed values. You can use any
text mode function library (e.g. TCXL) in the text modes.

When you wish to return to graphics mode, you can call the function to
set the graphics, mode, and the parameters will be reset correctly.

Example:

See the various example programs.

See Also:

set40x25, set640x200, set640x350, set320x200




























-- Page 63 --




Light Speed
High Speed Graphics Programming


Graphics Display Paging
-----------------------

The Light Speed library supports and advanced system of video paging,
all for seperate active and visual pages, as well as writing to off screen
pages and flipping them so that incredibly smooth animation can be seen.

In all of the graphics modes, there are two available pages, each
independent of the other. There are two available pointers to access the
video pages: the 'active' page, and the 'visual' page. The two pointers
work independently of eachother.

The active page is the page that is used by all of the graphics
functions for any writes to the screen. There is no need to specify which
page you need to write to, as all output is automatically directed to the
active page. The active page may or may not be the same as the visual page,
so it easy to write all output to a hidden page, then set the visual page
to show the update. This would mean the update would be instantaneous, and
the user would not see any of the real updating process.

The visual page is the page that is shown on the display. Both the
visual page and the active page are set to page one when a call to the
graphics mode initialization is made. This means that all writes to the
screen will be displayed as they happen. However, if the first thing your
program does is set the visual page to number two, then you can update the
screen without the user seeing it.

The values of the active and visual pages are stored by a set of
internal variables in the graphics initialization code. Each time a call to
a set function is made, the values are reset to there defaults. It is not
wise to play with these values directly, as problems will result if the
values are set inaccurately. The addresses of the pages are also stored,
so playing with these values may corrupt data that should be safe.

Any calls to the page control commands safe, however, so there is no
need to worry about stray values being set. The routines have been tested
thoroughly, be an animation program I wrote, which is not part of this
package. The page flipping commands (especially flipping both pages at
once), can be especially useful real-time, full screen animation. Programs
like flight simulators use the page mechanism heavily, and that is how the
smooth transition of objects is made.

Also included in the page control functions are routines that can be
used to set the video buffer origin and offset addressed. These can be used
in programs where screen scrolling is necessary. There is no real support
for the functions in this release, as most of the routines are programmed
to work from the two constant page addresses, not an offset into the
graphics buffer. There is also no support for enlarging the screen size,
but that will be featured in the next release.

There are no examples provided, as most of the functions are self
explanantory in their use. However, unless you know exactly what you are
trying to acheive, it is not adivisable to use the origin and offset
control routines. The page control functions are perfectly safe, however.
Now, the functions...


-- Page 64 --




Light Speed
High Speed Graphics Programming



Fucntion Name:

ega_flipapage

Purpose:

Exchange the active page.

Calling Protocol:

void ega_flipapage(void)

Description:

This function will exchange the values for the currently active page.
If the active page is page 1 before the call, it will be page 2 afterwards,
and vice-versa.

See Also:

ega_setapage, ega_flippage, ega_getapage



































-- Page 65 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_flippage

Purpose:

Flip both active and visual pages.

Calling Protocol:

void ega_flippage(void)

Description:

This function will exchange the values for both the currently ative
and visual pages.

This can be useful if the pages are set at opposite values, and you
are doing frame animation. If the pages are at opposites, then a call to
this function will leave them opposite still, but the other way around,
which means you can draw the next frame and continue the process.

When this function is called with both the active and visual page the
same, it will enable the other page for updating, and allow the updates to
be seen. This is how you can emulate a function that will set _both_ values
to the same, without having to call ega_setapage and ega_setvpage to set
the two pages independently.

See Also:

ega_setapage, ega_flipapage, ega_setvpage, ega_flipvpage,
ega_getapage, ega_getvpage

























-- Page 66 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_flipvpage

Purpose:

Exchange the visual page.

Calling Protocol:

void ega_flipvpage(void)

Description:

This function will exchange the values for the current visual page.
If the visual page is page 1 before the call, it will be page 2 afterwards,
and vice-versa.

See Also:

ega_setvpage, ega_flippage, ega_getvpage




































-- Page 67 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_getapage

Purpose:

Find the current active page.

Calling Protocol:

int ega_getapage(void)

Description:

This function will read the value of the currently active page from
the variables stored by the page control functions. This allows you to
determine which page updates are currently being written to.

The value returned will be in either one or two.

See Also:

ega_setapage, ega_flipapage


































-- Page 68 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_getvpage

Purpose:

Find the current visual page.

Calling Protocol:

int ega_getvpage(void)

Description:

This function will read the value of the currently visual page from
the variables stored by the page control functions. This allows you to
determine which page is currently being displayed on the sceen.

The value returned will be in either one or two.

See Also:

ega_setvpage, ega_flipvpage, ega_getvpage


































-- Page 69 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_readorigin

Purpose:

Read the origin of the display.

Calling Protocol:

unsigned int ega_readorigin(void)

Desription:

This function can be used to determine the current origin of the
graphics display. This routine is not used by the paging mechanism, but
can be used if you are going to scroll the screen, or something similar.

The origin value returned is an offset address from the video segment,
at 0A000h. When scrolling the screen, this value will move the screen of
increments of one byte, so for fine tuning the ega_setoffset function can
be used to set the eight smaller increments in between.

See Also:

ega_setorigin, ega_setoffset































-- Page 70 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_setapage

Purpose:

Set the current active page.

Calling Protocol:

void ega_setapage(page)

int page; /* Page number, 1 or 2 */

Description:

This function will set the value of the currently active page. The
two active pages are numbered 1 or 2. This allows you set which page will
recieve the graphics output from all of the Light Speed functions.

The value can either one or two. Any other value will set the active
page to page 1.

See Also:

ega_getapage, ega_flipapage































-- Page 71 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_setoffset

Purpose:

Set the offset from the origin.

Calling Protocol:

void ega_setoffset(offset)

char offset; /* Value of offset */

Description:

This function will set the value of the offset from the origin. The
offset is the value used to move the display by any one bit, unlike the
function ega_setorigin which will mode the display by a one byte value.

Using this function, and the ega_setoffset function together will
allow you to scroll the screen one bit at a time, or in other words, will
allow for a 'perfect' scroll. There is no possible way to acheive and
smaller scrolling increment.

The value passed to ega_setoffset is the number of the bit to enable
at the top left of the display, in the range of 0 to 7. It is not the
binary value of the offset, as in 1, 2, 4, etc.

See Also:

ega_setorigin, ega_getorigin

























-- Page 72 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_setorigin

Purpose:

Set the origin address of the video display.

Calling Protocol:

void ega_setorigin(origin)

unsigned int origin; /* Value of the origin address */

Description:

This function is similar to that used by the paging functions to set
the active and visual page, but ega_setorigin allows for any possible
values as the origin address (the video pages are fixed for each graphics
mode).

The value passed to ega_setorigin as the byte value where the start of
the video display will begin. The origin value is used as an offset from
the start of the video segment, at 0A000h. The page control functions work
independently of this address, so will reset the value whenever a call to
flip or set either the active or visual pages is made.

Used in conjunction with ega_setoffset, you can perform perfect
scrolling. See the ega_setoffset function for more details.

See Also:

ega_setoffset, ega_getorigin
























-- Page 73 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_setvpage

Purpose:

Set the current visual page.

Calling Protocol:

void ega_setvpage(page)

int page; /* Page number, 1 or 2 */

Description:

This function will set the value of the currently visual page. The
two visual pages are numbered 1 or 2. This allows you set which page is
being displayed on the screen at the after the call.

The value can either one or two. Any other value will set the visual
page to page 1.

See Also:

ega_getvpage, ega_flipvpage































-- Page 74 --




Light Speed
High Speed Graphics Programming


Video System Status Information
-------------------------------

The Light Speed library maintains control over the graphics
hardware through a series of internal variables. These variables are
the core of the library, allowing such things as multiple pages, mode
independent routines and easy access to the video configuration.

The routines that follow in this section are used whenever the
programmer needs to find out specific information about the video
system, but cannot be used to change any of the values. As of this
release version, the system video is kept safe at all times, and there
are no routines provided to change it. However, in the next release,
such additional features as screen size, will allow these variables to
be accessed.

One final note: these variables are declared in an object module
found in the library, not in the header file. All references to these
variables are made via 'extern' or 'extrn' statements in the variaous
modules. This allows for programs to be built that have multiple
modules accessing the graphics functions, without each module
maintaining its own set of parameters.

For example, if a section of your code initializes the program
and video display, then passes control over to a completely different
module, the change is transparent to the graphics routines. The
opposite of this is that if the variables were declared in the header
file, the second module would not know whether the video was
initialized or not, and would probably crash the computer.




























-- Page 75 --




Light Speed
High Speed Graphics Programming


Function Name:

display_type

Purpose:

Find the current display adapter.

Calling Protocol:

int display_type(void)

Description:

This function determines the installed display adapter card,
except for the MCGA adapter. The MCGA adapter is an on-board chip in
the PS/2 range, and avoids detection.

The return values are defined in the header file, and are a
numerical value:

Defined adapter Return
-------------------------------------
LS_NODISPLAY 0
LS_EGADISPLAY 3
LS_CGADISPLAY 4
LS_MONODISPLAY 5
LS_VGAMONODISPLAY 7
LS_VGACOLORDISPLAY 8


Example:

/* Light Speed Reference Example Program */
/* Find adapter type */
#include "lspeed.h"

main()
{
/* Print the starting message */
printf("The computer has ");
















-- Page 76 --




Light Speed
High Speed Graphics Programming


/* Find display type */
switch (display_type())
{
case LS_NODISPLAY : printf("no display card.\n");
break;
case LS_EGADISPLAY : printf("an EGA display adapter.\n");
break;
case LS_CGADISPLAY : printf("a CGA display adapter.\n");
break;
case LS_MONODISPLAY : printf("a Monochrome display card.\n");
break;
case LS_VGAMONODISPLAY : printf("a Mono VGA display card.\n");
break;
case LS_VGACOLORDISPLAY : printf("a colour VGA display card.\n");
break;
default : printf("an unknown display card.\n");
break;
}
}

See Also:

get_mode, find_primary, second_adapter

Notes:

This routine will be enhanced in the next verison to cover all of
the available adapters, using another set of detection routines.





























-- Page 77 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_bytesperline

Description:

Read number of bytes per line in display memory.

Calling Protocol:

int ega_bytesperline(void)

Description:

This function reads the internal variable that stores the number
of bytes per line for the current video mode. This is one of the main
variables that allows for mode independant routines.

You can use this function for routines that you write that need to
be able to act in any EGA mode, and use the value of a byte read from a
pixel plane.

Example:

/* Light Speed Reference Example Program */
/* Read the number of bytes stored per line */
#include "lspeed.h"

main()
{
/* Variables */
int bytes;

/* Set a graphics mode, register font */
registerstandardfont();
set640x350();

/* Assign value, print it */
bytes = ega_bytesperline();
ega_formattext(10, 10, LS_WHITE, LS_BLACK, STANDARD_FONT,
"The computer has %d bytes per line!", bytes);
ega_writetext(10, 20, LS_WHITE, LS_BLACK, STANDARD_FONT,
"Press a key...");
getxch();

/* Close graphics, exit */
set80x25();
}

See Also:

ega_displaywidth





-- Page 78 --




Light Speed
High Speed Graphics Programming


Notes:

This value will be use when the screen re-sizing routines are
added to the library, therfore still allowing any graphics function to
access display memory without knowing anything about screen
dimensions.



















































-- Page 79 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_displayheight

Purpose:

Find the height of the current graphics screen.

Calling Protocol:

int ega_displayheight(void)

Description:

This function will read the internal variable that contains the
height of the mode. This value has no purpose in the library other
than to let the program no the current screen dimensions. But it is
garaunteed to be set for any specfic mode, however, including text
(whereas most of the values are not).

Example:

/* Light Speed Reference Example Program */
/* Find display size */
#include "lspeed.h"

main()
{
/* Variables */
int height, width;

/* Set a screen mode */
set40x25();

/* Assign values */
height = ega_displayheight();
width = ega_displaywidth();

/* Report values, restore 80x25 and exit */
printf("Screen height is %d\n", height);
printf("Screen width is %d\n", width);
printf("Press a key...");
getxch();
set80x25();
}

See also:

ega_displaywidth, ega_maxscanline








-- Page 80 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_displaywidth

Purpose:

Find the width of the current graphics screen.

Calling Protocol:

int ega_displaywidth(void)

Description:

This function will read the internal variable that contains the
width of the mode. This value has no purpose in the library other
than to let the program no the current screen dimensions. But it is
garaunteed to be set for any specfic mode, however, including text
(whereas most of the values are not).

Example:

See ega_displayheight

See also:

ega_displayheight, ega_maxscanline






























-- Page 81 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_firstpageaddress

Purpose:

Find the value of the first pages' address.

Calling Protocol:

unsigned int ega_firstpageaddress(void)

Description:

This function returns that value that is used to address the first
page in video memory. This and the other page variables are the control
system for the 'active page' and 'visual page' functions.

The value returned is an offset address from the video segment,
which as at A000h. The first pages' address will always be set at
A000:0000h. The second page may be A800:0000h, for example.

Video paging is _not_ supported in text modes. When in text mode,
the value returned, will be the value set from the last graphics mode
set operation. For text paging, there should be suitable functions in
text _only_ libraries.

Example:

/* Light Speed Reference Example Program */
/* Find the page addresses of the current mode */
#include "lspeed.h"

main()
{
/* Variables */
firstp, secondp;

/* Set graphics mode, register font */
set640x350();
registerstandardfont();

/* Assign the values, print output */
firstp = ega_firstpageaddress();
secondp = ega_secondpageaddress();
ega_formattext(10, 10, LS_WHITE, LS_BLACK, STANDARD_FONT,
"First page address is %04X:0000", firstp);
ega_formattext(10, 20, LS_WHITE, LS_BLACK, STANDARD_FONT,
"Second page address is %04X:0000", secondp);








-- Page 82 --




Light Speed
High Speed Graphics Programming


/* Wait for key, restore text, exit */
ega_writetext(10, 30, LS_WHITE, LS_BLACK, STANDARD_FONT,
"Press a key...");
getxch();
set80x25();
}

See Also:

ega_secondpageaddress, 'Graphics Page Control' section















































-- Page 83 --




Light Speed
High Speed Graphics Programming



Function Name:

ega_maxscanline

Purpose:

Read the maximum scan line in current graphics mode.

Calling Protocol:

int ega_maxscanline(void)

Description:

This function will read the adapter card to find the value of the
bottom most accessable scan line. The value is not used by any of
the graphics function, but can be used to return status about the
monitor. This value is display type dependent.

Example:

/* Light Speed Reference Example Program */
/* Read the maximum scan line */
#include "lspeed.h"

main()
{
/* Variables */
int maxscan;

/* Set graphics, register font */
set640x350();
registerstandardfont();

/* Assign and print value */
maxscan = ega_maxscanline();
ega_formattext(10, 10, LS_WHITE, LS_BLACK, STANDARD_FONT,
"Maximum scan line is %d", maxscan);

/* Wait for key, restore text, exit */
ega_writetext(10, 20, LS_WHITE, LS_BLACK, STANDARD_FONT,
"Press a key...");
getxch();
set80x25();
}

See Also:

ega_displayheight







-- Page 84 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_memory

Purpose:

Read the amount of memory installed on card.

Calling Protocol:

int ega_memory(void)

Description:

This function returns the amount of memory that has been detected
on the graphics adapter card. The value returned is read fromthe
adapter, and is the size in kilobytes.

Example:

/* Light Speed Reference Example Program */
/* Find memory on card */
#include "lspeed.h"

main()
{
/* Read/print memory available */
printf("Memory available on graphics adapter: %dk\n",
ega_memory());
}


Notes:

So far this routine has only been tested on cards with less that
256k of graphics memory. I do not have access to any graphics adapters
with a larger address space, but from the references I have use, the
function should work on any adapter card, including SuperVGA's.




















-- Page 85 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_readregister

Purpose:

Read the value from a specific adapter card register.

Calling protocol:

unsigned char ega_readregister(regnum)

int regnum; /* The register number to read */

Description:

This function can be used to read the value from a register on the
graphics card. The operation performed is similar to the assembly
language instruction 'in al, regnum'. The value returned has a decimal
value in the range of 0-255;

Example:

No example has been programmed because of the necessity for accessing
a specific register on the adapter, and most of these are write only.
Any routine that needs to access a value itself, does so via assembly
language anyway. You can use this function freely however, if you know
which registers you need to access and for whatever reason.

See also:

ega_writeregister

























-- Page 86 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_retrace

Purpose:

Wait for the monitor to complete its next vertical retrace.

Calling Protocol:

void ega_retrace(void)

Description:

This function will halt the program until the monitor completes
its next vertical retrace, and is returning to the start of the
display. The main use of this is when routines update the screen very
quickly, and a shearing effect can be seen where some of the new data
has been updated, and some hasn't.

This is because the monitor has already read the data from display
memory, and does not know that there has been an update. Functions
that can execute in the time it takes for the lasers in the monitor to
return to the top of the screen (I am not sure of the actual timings),
can benefit greatly from this routine.

Example:

/* Light Speed Reference Example Program */
/* Wait for vertical retrace */
#include "lspeed.h"

main()
{
/* Tell the user what is happening */
printf("Waiting for next vertical retrace...\n");

/* Wait for retrace... */
ega_retrace();
printf("Retrace done!\n");

/* Exit */
}














-- Page 87 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_secondpageaddress

Purpose:

Find the value of the second pages' address.

Calling Protocol:

unsigned int ega_secondpageaddress(void)

Description:

This function returns that value that is used to address the
second page in video memory. This and the other page variables are the
control system for the 'active page' and 'visual page' functions.

The value returned is an offset address from the video segment,
which as at A000h. The second pages' address varies according to the
current graphics mode, but is constant:

Mode Offset
-------------------------
320x200 2000h
640x200 4000h
640x350 8000h

Video paging is _not_ supported in text modes. When in text mode,
the value returned, will be the value set from the last graphics mode
set operation. For text paging, there should be suitable functions in
text _only_ libraries.

Example:

See ega_firstpageaddress

See Also:

ega_firstpageaddress, 'Graphics Page Control' section

















-- Page 88 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_writepallete

Purpose:

Update the pallete registers with new values.

Calling Protocol:

void ega_writepallete(paldata)

int paldata[16]; /* Values for the pallete registers */

Description:

This function can be used when reprogrammig the pallete,
especially for such functions as fading. The pallete information is an
integer array sixteen values long, and contains the values that the
pallete register should be updated with. Each value in the points to
the pallete number that it should be updated with.

The new pallete value is determined not from the colour currently
at that location in the pallete, but fromthe sizteen default pallete
colours. Therefore, If you wish to restore a colour, you
can just specify the number of the original pallete number, there is
no need to start swapping colours so that there will always be the
sixteen colours available. There is _always_ sixteen colours available
no matter what has been done to the pallete.

Pallete programming is a very complex field, and this function is
only the tip of the ice berg as far as colours are concerned.
Unfortunately, due to EGA limitations, only 16 colours can ever be
accessed. However, when the library can handle the VGA 256 colour
modes, their will be much more flexible routines allowing for the
Red-Green-Blue registers of the video DAC, allowing for the full
262,144 allowable colours.

Example:

/* Light Speed Reference Example Program */
/* Setting pallete registers */
#include "lspeed.h"
#include

main()
{
/* Variables */
int newpallete[16] = /* Reverse yellow and white, black and blue */
{ 1, 0, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 15, 14 };







-- Page 89 --




Light Speed
High Speed Graphics Programming


/* Write some text, wait for ready to read it */
textcolor(WHITE);
textbackground(BLACK);
cprintf("This will change from white/black to yellow/blue!\n\r");
cprintf("Press a key...\n\r");
getxch();

/* Re-define pallete, wait for next keypress */
ega_writepallete(newpallete);
cprintf("See! Press a key to restore old pallete and quit.\n\r");
getxch();

/* Restore values, exit */
newpallete[0] = 0; newpallete[1] = 1;
newpallete[14] = 14; newpallete[15] = 15;
}

See Also:

ega_writeregister





































-- Page 90 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_writeregister

Purpose:

Update a specific graphics controller register with a new value.

Calling Protocol:

void ega_writeregister(regnum, value)

int regnum; /* Register number to update */
unsigned char value; /* Value to use for update */

Description:

This function is the opposite of the ega_readregister function,
and can be use to write to the registers. The operation performed by
this function is similar to the 'out regnum, value' instruction in
Assembly language. The 'value' has a range of 0-255, whereas any
register number can be accessed.

Example:

No example has been programmed because of the necessity for accessing
a specific register on the adapter. Any routine that needs to write a
value itself (and almost every function does), does so via assembly
language anyway. You can use this function freely however, if you know
which registers you need to access and for whatever reason.

See also:

ega_readregister, ega_writepallete























-- Page 91 --




Light Speed
High Speed Graphics Programming


Function Name:

find_primary

Purpose:

Find the type of primary display.

Calling Protocol:

int find_primary(void)

Description:

This function reads the value that the adapter card was booted up
in. There are three available modes, and all adapter card will boot up
in compatability with them:

Mode Value
--------------------------------
LS_PRIMARY_EGA 1
LS_PRIMARY_CGA 2
LS_PRIMARY_MONOHERC 3

Example:

/* Light Speed Reference Example Program */
/* Find primary adapter type */
#include "lspeed.h"

main()
{
/* Print the starting message */
printf("The computer was booted up in ");

/* Find primary display mode */
switch (find_primary())
{
case LS_PRIMARY_EGA : printf("EGA");
break;
case LS_PRIMARY_CGA : printf("CGA");
break;
case LS_PRIMARY_MONOHERC : printf("Monochrome/Hercules");
break;
}

/* Print ending message, exit */
printf(" mode.\n");
}

See Also:

second_adapter, display_type




-- Page 92 --




Light Speed
High Speed Graphics Programming


Function Name:

get_mode

Purpose:

Read the current video mode.

Calling Protocol:

int get_mode(void)

Description:

This function uses the BIOS to read the current video mode. The
defined return values are only applicable to EGA adapters, but any
mode value can be returned (for example, mode 13h is only available on
VGA/MCGA adapters, and can be returned by this function, but there is
no supported definition for the return value).

Mode Value
-----------------------------
EGA_640x350 10h
EGA_320x200 0Dh
EGA_640x200 0Eh
EGA_80x25 03h
EGA_40x25 01h

Example:

/* Light Speed Reference Example Program */
/* Read the graphics mode - no functionality, however */
#include "lspeed.h"

main()
{
/* Find mode, act on it */
switch (get_mode())
{
case EGA_640x350 : /* 640 by 350 graphics mode */ .....
break;
case EGA_640x200 : /* 640 by 200 graphics mode */ .....
break;
case EGA_320x300 : /* 320 by 200 graphics mode */ .....
break;
case EGA_80x25 : /* 80 by 25 text mode */ .....
break;
case EGA_40x25 : /* 40 by 25 text mode */ .....
break;
default : /* Some other mode */ .....
break;
}
}




-- Page 93 --




Light Speed
High Speed Graphics Programming


See Also:

display_type






















































-- Page 94 --




Light Speed
High Speed Graphics Programming


Function Name:

second_adapter

Purpose:

Check for the presence of a second adapter.

Calling Protocol:

int second_adapter(void)

Description:

This routine uses several methods to determine if there is a
second adapter installed in the machine. A return of '0' means no
adapter was found, a return of '1' means one was found.

Example:

/* Light Speed Reference Example Program */
/* See if a second adapter is present */
#include "lspeed.h"

main()
{
/* Test for second adapter, print message according to return */
if (second_adapter())
printf("This computer has a second adapter!\n");
else
printf("This computer only has one adapter!\n");
}

See Also:

display_type

Notes:

This routine is as yet untested by me, as I do not have access to
any computers with a second adapter installed.
















-- Page 95 --




Light Speed
High Speed Graphics Programming


Graphics Mode Text Output
-------------------------

The Light Speed library has twelve inbuilt fonts, as well as the
ability for you to link in your own font styles. There are a multitude of
methods for generating character output, and all are simple and easy to
use.

One of the benefits of the Light Speed font system is that font styles
are linked straight into the program, and only the specific fonts you need
are used. Most of the font data is about 1k in size, so linking in just one
font for all of your graphics output makes little difference to the
resulting size of your executable file. Although font styles of your own
can be linked in, the operation should not be attempted until you have a
thorough understanding of how the text output procedures work.

The available text fonts are defined in the lspeed.h header file,
according to the following names:

Font Style Definition Variable
---------------------------------------------------------
Broad Text BROAD_FONT 1
Computer Text COMPUTER_FONT 2
Plasma Display PLASMA_FONT 3
EGA Small Font SMALL_FONT 4
EGA Standard STANDARD_FONT 5
Tall Text TALL_FONT 6
Script Flow SCRIPT_FONT 7
Nice Font NICE_FONT 8
Crisp Character CRISP_FONT 9
Old English OLD_ENGLISH_FONT 10
Plain Text PLAIN_FONT 11
Italic Font ITALIC_FONT 12

When you call a text output function that supports all of the text
styles, you can specify either the font definition (NICE_FONT for example),
or the font number (8 for Nice Font). Specifying the definition is much
easier, however.

The text output system supports not only character and string output,
but the ability to output text to be formatted, similar to the printf()
statement in text modes. The reformatting of text is transparent to the
application, and removes messy sprintf()'s from your code. Reformatting
means transposing values into positions in the text. The following two
pieces of code achieve the same effect in text and graphics modes:

Text mode:
printf("Data value = %d!", value);
Graphics mode:
registerbroadfont();
formattext(10, 10, LS_WHITE, LS_BLACK, BROAD_FONT,
"Data value = %d!", value)





-- Page 96 --




Light Speed
High Speed Graphics Programming


Do not worry about all of the extra parameters to the graphics mode
call for the moment, and consider just the printing of the 'value'
variable. The same call has been used in _both_ examples!

Another feature of the text system is that it allows characters to be
written in both a foreground and background colour. This means that be
over-writing old text, you can easily update the screen with new
information, without clearing the old text first. The only difference
between standard text mode output and graphics mode output is that the
graphics mode allows for _all_ sixteen colours in the background, unlike
text mode limit of only the first eight.

Before any font can be used, it must be registered by calling the
appropriate registerXXXXXXfont function. The Light Speed library maintains
a set of internal variables to specify if a font has been registered, so
all of the functions will not produce stray output if the font has not been
registered. For more information about the structure of a font file, and
adding your own fonts to the Library, see Appendix A.

The code that follows is an excerpt from the demo program that will
display all of the fonts. This alleviates the need for an example program
for each new font style. There are, however, a few example programs for the
string output functions, as they deserve a demonstration in their own
right.

/* Light Speed Reference Example Program */
/* Show all of the font styles */
#include "lspeed.h"

/* Define the various text styles as their names */
char *fontstyles[] = {
"Broad Text", "Computer Text",
"Plasma Display", "EGA Small Font",
"EGA Standard", "Tall Text",
"Script Flow", "Nice Font",
"Crisp Character", "Old English",
"Plain Text", "Italic Font" };

main()
{
/* Variables */
int loop;

/* Set graphics mode */
set640x350();












-- Page 97 --




Light Speed
High Speed Graphics Programming


/* Install all of the fonts */
registerbroadfont();
registercomputerfont();
registertallfont();
registersmallfont();
registerscriptfont();
registerplasmafont();
registerplainfont();
registeroldenglishfont();
registernicefont();
registeritalicfont();
registerstandardfont();
registercrispfont();

/* Loop through all twelve fonts */
for (loop=1; loop<=12; loop++)
demonstrate_font(loop);

/* Close down the graphics and return */
set80x25();
}

/* DEMONSTRATE_FONT - called with the value of the font to use, */
/* this function will provide several */
/* graphics mode ouput tests. */
demonstrate_font(font)
int font;
{
/* Variables */
int foreloop, backloop;

/* Clear the graphics screen */
ega_clearpage();

/* Tell the user the font we are displaying */
ega_formattext(10, 10, LS_YELLOW, LS_BLACK, STANDARD_FONT,
"Demonstrating %s!", fontstyles[font-1]);

/* Print out the standard alphabet in the text style */
ega_writetext(20, 30, LS_WHITE, LS_BLACK, font,
"The standard character set:");
ega_formattext(25, 30+ega_fontheight(font), LS_CYAN, LS_BLACK, font,
" !%c#$%&'()*+,-./0123456789:;<=>?@", 34);
ega_writetext(25, 30+ega_fontheight(font)*2, LS_CYAN, LS_BLACK, font,
"ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`");
ega_writetext(25, 30+ega_fontheight(font)*3, LS_CYAN, LS_BLACK, font,
"abcdefghijklmnopqrstuvwxyz{|}~");










-- Page 98 --




Light Speed
High Speed Graphics Programming


/* Tell a bit more about the text system */
ega_writetext(15, 120, LS_YELLOW, LS_BLACK, font,
"The above is only a demonstration of the font...");
ega_writetext(15, 120+ega_fontheight(font), LS_YELLOW, LS_BLACK, font,
"The real power lies in foreground/background colours!");
for (foreloop=0; foreloop<=15; foreloop++)
for (backloop=0; backloop<=7; backloop++)
ega_writetext(30+foreloop*32, 160+backloop*ega_fontheight(font),
foreloop, backloop, font, " WOW ");

/* Write a message and wait for the next keypress */
ega_writetext(15, 320, LS_WHITE, LS_BLUE, STANDARD_FONT,
" Press any key to continue... ");
getxch();
}

As you can see, it is relatively simple to write text in graphics
mode, and the entire demo program with all twelve fonts added compiled
out to be only 22k! Now, onto the text system functions...






































-- Page 99 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_broadch

Purpose:

Write a character in Broad Text.

Calling Protocol:

int ega_broadch(character, xloc, yloc, foreground, background)

int character; /* ASCII value of the character (32-127) */
int xloc, yloc; /* (x,y) of upper left corner */
int foreground; /* Foreground colour of character */
int background; /* Background colour of character */

Description:

This function will write one character to the screen, with the
character specified as the first parameter. Only the displayable text
characters are defined (the example program lists all of them), being
the ASCII characters in the range of 32 to 127.

The specified (x,y) location is that of the top left corner, with
the text taking shape leftward and downward. The foreground and
background colour values are those defined in lspeed.h in the range of 0
to 15.

The function checks to see whether the broad font style has been
loaded first, and returns -1 if not. Otherwise the routine returns a
value of 0. There is no checking on the input character, so calling with
values out of the specified ranges may crash the system.

This function does no need to be called as the only way of getting
text output in the broad font - you can call ega_writecharacter and
specify BROAD_FONT as the font style. ega_writecharacter is the general
purpose character output routine.

Example:

See the program at the start of this section

See Also:

ega_computerch, ega_crispch, ega_italicch, ega_nicech,
ega_oldenglishch, ega_plainch, ega_plasmach, ega_scriptch,
ega_smallch, ega_standardch, ega_tallch, ega_writecharacter









-- Page 100 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_computerch

Purpose:

Write a character in Computer Text.

Calling Protocol:

int ega_computerch(character, xloc, yloc, foreground, background)

int character; /* ASCII value of the character (32-127) */
int xloc, yloc; /* (x,y) of upper left corner */
int foreground; /* Foreground colour of character */
int background; /* Background colour of character */

Description:

This function will write one character to the screen, with the
character specified as the first parameter. Only the displayable text
characters are defined (the example program lists all of them), being
the ASCII characters in the range of 32 to 127.

The specified (x,y) location is that of the top left corner, with
the text taking shape leftward and downward. The foreground and
background colour values are those defined in lspeed.h in the range of 0
to 15.

The function checks to see whether the computer font style has been
loaded first, and returns -1 if not. Otherwise the routine returns a
value of 0. There is no checking on the input character, so calling with
values out of the specified ranges may crash the system.

This function does no need to be called as the only way of getting
text output in the computer font - you can call ega_writecharacter and
specify COMPUTER_FONT as the font style. ega_writecharacter is the general
purpose character output routine.

Example:

See the program at the start of this section

See Also:

ega_broadch, ega_crispch, ega_italicch, ega_nicech,
ega_oldenglishch, ega_plainch, ega_plasmach, ega_scriptch,
ega_smallch, ega_standardch, ega_tallch, ega_writecharacter









-- Page 101 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_crispch

Purpose:

Write a character in Crisp Character.

Calling Protocol:

int ega_crispch(character, xloc, yloc, foreground, background)

int character; /* ASCII value of the character (32-127) */
int xloc, yloc; /* (x,y) of upper left corner */
int foreground; /* Foreground colour of character */
int background; /* Background colour of character */

Description:

This function will write one character to the screen, with the
character specified as the first parameter. Only the displayable text
characters are defined (the example program lists all of them), being
the ASCII characters in the range of 32 to 127.

The specified (x,y) location is that of the top left corner, with
the text taking shape leftward and downward. The foreground and
background colour values are those defined in lspeed.h in the range of 0
to 15.

The function checks to see whether the crisp font style has been
loaded first, and returns -1 if not. Otherwise the routine returns a
value of 0. There is no checking on the input character, so calling with
values out of the specified ranges may crash the system.

This function does no need to be called as the only way of getting
text output in the crisp font - you can call ega_writecharacter and
specify CRISP_FONT as the font style. ega_writecharacter is the general
purpose character output routine.

Example:

See the program at the start of this section

See Also:

ega_broadch, ega_computerch, ega_italicch, ega_nicech,
ega_oldenglishch, ega_plainch, ega_plasmach, ega_scriptch,
ega_smallch, ega_standardch, ega_tallch, ega_writecharacter









-- Page 102 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_fontheight

Purpose:

Find height of fonts.

Calling Protocol:

int ega_fontheight(font)

int font; /* Number of font who's height to read */

Description:

This function read a value from the internal look up table about the
fonts, and returns the height. There is no checking for out of range fonts,
or fonts that have not been registered, so you must call this function
carefully. It does not matter if the font has not been registered, as the
look up table is set at the start of any program that needs the fonts. Just
watch out for stray font numbers.

The return value will be he height of the font, in pixels. The sizes
are as follows:

Font Style Height
--------------------------------
Broad Text 1
Computer Text 2
Plasma Display 3
EGA Small Font 4
EGA Standard 5
Tall Text 6
Script Flow 7
Nice Font 8
Crisp Character 9
Old English 10
Plain Text 11
Italic Font 12

This function can be especially useful if you are printing multiple
lines of text in a variety of fonts, and want each line to touch at the top
and bottom (an example of this is in the font demo program at the start of
this section).












-- Page 103 --




Light Speed
High Speed Graphics Programming


Example:

/* Light Speed Reference Example Program */
/* Font height and width functions */
#include "lspeed.h"

main()
{
printf("Width of Tall font is %d,\n", ega_fontwidth(TALL_FONT));
printf("Height of Tall font is %d.\n", ega_fontheight(TALL_FONT));
printf("Width of Small font is %d,\n", ega_fontwidth(SMALL_FONT));
printf("Height of Small font is %d.\n", ega_fontheight(SMALL_FONT));
}

See Also:

ega_fontwidth








































-- Page 104 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_fontwidth

Purpose:

Find width of fonts.

Calling Protocol:

int ega_fontwidth(font)

int font; /* Number of font who's width to read */

Description:

All of the fonts in this release have a width of eight pixels, so this
function is implemented as a macro the returns 8 to the program. In a
future release, variable font sizes will be available.

Example:

See ega_fontheight

See Also:

ega_fontheight






























-- Page 105 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_formattext

Purpose:

Provide formatted text output in graphics mode.

Calling protocol:

int ega_formattext(xloc, yloc, foregrnd, backgrnd, font, format, ...)

int xloc, yloc; /* (x,y) location of upper left corner */
int foregrnd; /* Foreground character colour */
int backgrnd; /* Background character colour */
int font; /* Number of font to use */
char *format; /* Format control string */
... /* Additional parameters for string */

Description:

This function is used to implement the standard printf routine in
graphics mode. The (x,y) location specifies the top left starting
location for the string, with the string extending to the left and down.

The foreground and background values specify the colours of the
respective pixels on the graphics screen. The font specified will be
used to output the string to the display.

A return of -1 from the function designates that the font has not
been registered into memory, while a return of 0 means that the routine
was successful.

The format control string is composed of plain text and conversion
characters. Plain text is just copied straight to the graphics screen,
while the conversion characters fecth each variable in turn from the
argument list, and apply the specified formatting to them.

The available format specifications are in the following format:

% [flags] [width] [.prec] [F | N | h | l | L] type

Every conversion specification must begin the the '%' symbol, followed
by the appropriate arguments. The arguments must be in specific order:

(a) optional sequence of flag characters ([flags])
(b) optional width specifier ([width])
(c) optional precision modifier ([.prec])
(d) optional input size modifier ([F | N | h | l | L])
(c) compulsory conversion type character (type)

For a complete explanation of all of the available formatting
controllers, consult a C language manual, under the 'printf' function.




-- Page 106 --




Light Speed
High Speed Graphics Programming


Example:

/* Light Speed Reference Example Program */
/* Formatted graphics text output */
#include "lspeed.h"

main()
{
/* Assign a few variables for formatting */
int number=25;
char text[] = "Hello there!";

/* Set graphics, register font */
set640x350();
registerstandardfont();

/* Print a formatted text string */
ega_formattext(10, 10, LS_WHITE, LS_BLACK, STANDARD_FONT,
"%s Value equals %d...", text, number);
ega_writetext(10, 20, LS_YELLOW, LS_BLACK, STANDARD_FONT,
"The input format was %s Value equals %d...");
ega_writetext(10, 30, LS_CYAN, LS_BLACK, STANDARD_FONT,
"See the conversion applied to 'text' and 'number'");

/* Get a keypress, restore text and exit */
ega_writetext(5, 55, LS_WHITE, LS_BLUE, STANDARD_FONT,
"Press a key to exit...");
getxch();
set80x25();
}

See Also:

ega_writetext, ega_writechar, ega_writecharacter























-- Page 107 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_italicch

Purpose:

Write a character in Italic Font.

Calling Protocol:

int ega_italicch(character, xloc, yloc, foreground, background)

int character; /* ASCII value of the character (32-127) */
int xloc, yloc; /* (x,y) of upper left corner */
int foreground; /* Foreground colour of character */
int background; /* Background colour of character */

Description:

This function will write one character to the screen, with the
character specified as the first parameter. Only the displayable text
characters are defined (the example program lists all of them), being
the ASCII characters in the range of 32 to 127.

The specified (x,y) location is that of the top left corner, with
the text taking shape leftward and downward. The foreground and
background colour values are those defined in lspeed.h in the range of 0
to 15.

The function checks to see whether the italic font style has been
loaded first, and returns -1 if not. Otherwise the routine returns a
value of 0. There is no checking on the input character, so calling with
values out of the specified ranges may crash the system.

This function does no need to be called as the only way of getting
text output in the italic font - you can call ega_writecharacter and
specify ITALIC_FONT as the font style. ega_writecharacter is the general
purpose character output routine.

Example:

See the program at the start of this section

See Also:

ega_broadch, ega_computerch, ega_crispch, ega_nicech,
ega_oldenglishch, ega_plainch, ega_plasmach, ega_scriptch,
ega_smallch, ega_standardch, ega_tallch, ega_writecharacter









-- Page 108 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_nicech

Purpose:

Write a character in Nice Font.

Calling Protocol:

int ega_nicech(character, xloc, yloc, foreground, background)

int character; /* ASCII value of the character (32-127) */
int xloc, yloc; /* (x,y) of upper left corner */
int foreground; /* Foreground colour of character */
int background; /* Background colour of character */

Description:

This function will write one character to the screen, with the
character specified as the first parameter. Only the displayable text
characters are defined (the example program lists all of them), being
the ASCII characters in the range of 32 to 127.

The specified (x,y) location is that of the top left corner, with
the text taking shape leftward and downward. The foreground and
background colour values are those defined in lspeed.h in the range of 0
to 15.

The function checks to see whether the nice font style has been
loaded first, and returns -1 if not. Otherwise the routine returns a
value of 0. There is no checking on the input character, so calling with
values out of the specified ranges may crash the system.

This function does no need to be called as the only way of getting
text output in the nice font - you can call ega_writecharacter and
specify NICE_FONT as the font style. ega_writecharacter is the general
purpose character output routine.

Example:

See the program at the start of this section

See Also:

ega_broadch, ega_computerch, ega_crispch, ega_italicch,
ega_oldenglishch, ega_plainch, ega_plasmach, ega_scriptch,
ega_smallch, ega_standardch, ega_tallch, ega_writecharacter









-- Page 109 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_oldenglishch

Purpose:

Write a character in Old English.

Calling Protocol:

int ega_oldenglishch(character, xloc, yloc, foreground, background)

int character; /* ASCII value of the character (32-127) */
int xloc, yloc; /* (x,y) of upper left corner */
int foreground; /* Foreground colour of character */
int background; /* Background colour of character */

Description:

This function will write one character to the screen, with the
character specified as the first parameter. Only the displayable text
characters are defined (the example program lists all of them), being
the ASCII characters in the range of 32 to 127.

The specified (x,y) location is that of the top left corner, with
the text taking shape leftward and downward. The foreground and
background colour values are those defined in lspeed.h in the range of 0
to 15.

The function checks to see whether the oldenglish font style has been
loaded first, and returns -1 if not. Otherwise the routine returns a
value of 0. There is no checking on the input character, so calling with
values out of the specified ranges may crash the system.

This function does no need to be called as the only way of getting
text output in the oldenglish font - you can call ega_writecharacter and
specify OLD_ENGLISH_FONT as the font style. ega_writecharacter is the
general purpose character output routine.

Example:

See the program at the start of this section

See Also:

ega_broadch, ega_computerch, ega_crispch, ega_italicch,
ega_nicechch, ega_plainch, ega_plasmach, ega_scriptch,
ega_smallch, ega_standardch, ega_tallch, ega_writecharacter









-- Page 110 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_plainch

Purpose:

Write a character in Plain Text.

Calling Protocol:

int ega_plainch(character, xloc, yloc, foreground, background)

int character; /* ASCII value of the character (32-127) */
int xloc, yloc; /* (x,y) of upper left corner */
int foreground; /* Foreground colour of character */
int background; /* Background colour of character */

Description:

This function will write one character to the screen, with the
character specified as the first parameter. Only the displayable text
characters are defined (the example program lists all of them), being
the ASCII characters in the range of 32 to 127.

The specified (x,y) location is that of the top left corner, with
the text taking shape leftward and downward. The foreground and
background colour values are those defined in lspeed.h in the range of 0
to 15.

The function checks to see whether the plain font style has been
loaded first, and returns -1 if not. Otherwise the routine returns a
value of 0. There is no checking on the input character, so calling with
values out of the specified ranges may crash the system.

This function does no need to be called as the only way of getting
text output in the plain font - you can call ega_writecharacter and
specify PLAIN_FONT as the font style. ega_writecharacter is the general
purpose character output routine.

Example:

See the program at the start of this section

See Also:

ega_broadch, ega_computerch, ega_crispch, ega_italicch,
ega_nicech, ega_oldenglishch, ega_plasmach, ega_scriptch,
ega_smallch, ega_standardch, ega_tallch, ega_writecharacter









-- Page 111 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_plasmach

Purpose:

Write a character in Plasma Display.

Calling Protocol:

int ega_plasmach(character, xloc, yloc, foreground, background)

int character; /* ASCII value of the character (32-127) */
int xloc, yloc; /* (x,y) of upper left corner */
int foreground; /* Foreground colour of character */
int background; /* Background colour of character */

Description:

This function will write one character to the screen, with the
character specified as the first parameter. Only the displayable text
characters are defined (the example program lists all of them), being
the ASCII characters in the range of 32 to 127.

The specified (x,y) location is that of the top left corner, with
the text taking shape leftward and downward. The foreground and
background colour values are those defined in lspeed.h in the range of 0
to 15.

The function checks to see whether the plasma font style has been
loaded first, and returns -1 if not. Otherwise the routine returns a
value of 0. There is no checking on the input character, so calling with
values out of the specified ranges may crash the system.

This function does no need to be called as the only way of getting
text output in the plasma font - you can call ega_writecharacter and
specify PLASMA_FONT as the font style. ega_writecharacter is the general
purpose character output routine.

Example:

See the program at the start of this section

See Also:

ega_broadch, ega_computerch, ega_crispch, ega_italicch,
ega_nicech, ega_oldenglishch, ega_plainch, ega_scriptch,
ega_smallch, ega_standardch, ega_tallch, ega_writecharacter









-- Page 112 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_scriptch

Purpose:

Write a character in Script Flow.

Calling Protocol:

int ega_scriptch(character, xloc, yloc, foreground, background)

int character; /* ASCII value of the character (32-127) */
int xloc, yloc; /* (x,y) of upper left corner */
int foreground; /* Foreground colour of character */
int background; /* Background colour of character */

Description:

This function will write one character to the screen, with the
character specified as the first parameter. Only the displayable text
characters are defined (the example program lists all of them), being
the ASCII characters in the range of 32 to 127.

The specified (x,y) location is that of the top left corner, with
the text taking shape leftward and downward. The foreground and
background colour values are those defined in lspeed.h in the range of 0
to 15.

The function checks to see whether the script font style has been
loaded first, and returns -1 if not. Otherwise the routine returns a
value of 0. There is no checking on the input character, so calling with
values out of the specified ranges may crash the system.

This function does no need to be called as the only way of getting
text output in the script font - you can call ega_writecharacter and
specify SCRIPT_FONT as the font style. ega_writecharacter is the general
purpose character output routine.

Example:

See the program at the start of this section

See Also:

ega_broadch, ega_computerch, ega_crispch, ega_italicch,
ega_nicech, ega_oldenglishch, ega_plainch, ega_plasmach,
ega_smallch, ega_standardch, ega_tallch, ega_writecharacter









-- Page 113 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_smallch

Purpose:

Write a character in EGA Small Font.

Calling Protocol:

int ega_smallch(character, xloc, yloc, foreground, background)

int character; /* ASCII value of the character (32-127) */
int xloc, yloc; /* (x,y) of upper left corner */
int foreground; /* Foreground colour of character */
int background; /* Background colour of character */

Description:

This function will write one character to the screen, with the
character specified as the first parameter. Only the displayable text
characters are defined (the example program lists all of them), being
the ASCII characters in the range of 32 to 127.

The specified (x,y) location is that of the top left corner, with
the text taking shape leftward and downward. The foreground and
background colour values are those defined in lspeed.h in the range of 0
to 15.

The function checks to see whether the small font style has been
loaded first, and returns -1 if not. Otherwise the routine returns a
value of 0. There is no checking on the input character, so calling with
values out of the specified ranges may crash the system.

This function does no need to be called as the only way of getting
text output in the small font - you can call ega_writecharacter and
specify SMALL_FONT as the font style. ega_writecharacter is the general
purpose character output routine.

Example:

See the program at the start of this section

See Also:

ega_broadch, ega_computerch, ega_crispch, ega_italicch,
ega_nicech, ega_oldenglishch, ega_plainch, ega_plasmach,
ega_scriptch, ega_standardch, ega_tallch, ega_writecharacter









-- Page 114 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_standardch

Purpose:

Write a character in EGA Standard.

Calling Protocol:

int ega_standardch(character, xloc, yloc, foreground, background)

int character; /* ASCII value of the character (32-127) */
int xloc, yloc; /* (x,y) of upper left corner */
int foreground; /* Foreground colour of character */
int background; /* Background colour of character */

Description:

This function will write one character to the screen, with the
character specified as the first parameter. Only the displayable text
characters are defined (the example program lists all of them), being
the ASCII characters in the range of 32 to 127.

The specified (x,y) location is that of the top left corner, with
the text taking shape leftward and downward. The foreground and
background colour values are those defined in lspeed.h in the range of 0
to 15.

The function checks to see whether the standard font style has been
loaded first, and returns -1 if not. Otherwise the routine returns a
value of 0. There is no checking on the input character, so calling with
values out of the specified ranges may crash the system.

This function does no need to be called as the only way of getting
text output in the standard font - you can call ega_writecharacter and
specify STANDARD_FONT as the font style. ega_writecharacter is the general
purpose character output routine.

Example:

See the program at the start of this section

See Also:

ega_broadch, ega_computerch, ega_crispch, ega_italicch,
ega_nicech, ega_oldenglishch, ega_plainch, ega_plasmach,
ega_scriptch, ega_smallch, ega_tallch, ega_writecharacter









-- Page 115 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_tallch

Purpose:

Write a character in Small Text.

Calling Protocol:

int ega_tallch(character, xloc, yloc, foreground, background)

int character; /* ASCII value of the character (32-127) */
int xloc, yloc; /* (x,y) of upper left corner */
int foreground; /* Foreground colour of character */
int background; /* Background colour of character */

Description:

This function will write one character to the screen, with the
character specified as the first parameter. Only the displayable text
characters are defined (the example program lists all of them), being
the ASCII characters in the range of 32 to 127.

The specified (x,y) location is that of the top left corner, with
the text taking shape leftward and downward. The foreground and
background colour values are those defined in lspeed.h in the range of 0
to 15.

The function checks to see whether the tall font style has been
loaded first, and returns -1 if not. Otherwise the routine returns a
value of 0. There is no checking on the input character, so calling with
values out of the specified ranges may crash the system.

This function does no need to be called as the only way of getting
text output in the tall font - you can call ega_writecharacter and
specify SMALL_FONT as the font style. ega_writecharacter is the general
purpose character output routine.

Example:

See the program at the start of this section

See Also:

ega_broadch, ega_computerch, ega_crispch, ega_italicch,
ega_nicech, ega_oldenglishch, ega_plainch, ega_plasmach,
ega_scriptch, ega_smallch, ega_standardch, ega_writecharacter









-- Page 116 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_writechar

Purpose:

Place a character on the screen.

Calling Protocol:

void ega_writechar(character, xloc, yloc, foregrnd, backgrnd, fontptr)

int character; /* ASCII value of character (32-127) */
int xloc, yloc; /* (x,y) of upper left corner of character */
int foregrnd; /* Colour of foreground pixels */
int backgrnd; /* Colour of background pixels */
char far *fontptr; /* Pointer to the font table */

Description:

This function should _not_ be used to provide general purpose
character output to the screen. It is called internally by the other
character output routines, with the correct values set for each parameter.

The purpose of this function is to actually write the character into
video memory, according to the data found at the offset from the pointer to
the character data table. For more information about this specific
function, and adding your own font styles to the library, consult Appendix
A. This should only be attempted by people who have a thorough
understanding of the font system, however.

ega_writecharacter is the general purpose character routine, use that,
or a specific routine for the specified font, for character output.

Example:

For a complete example, see Appendix A

See Also:

ega_writecharacter, Appendix A

















-- Page 117 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_writecharacter

Purpose:

Write a character in any font style.

Calling Protocol:

int ega_writecharacter(charnum, xloc, yloc, foregrnd, backgrnd, font)

int charnum; /* ASCII value of character (0-255) */
int xloc, yloc; /* (x,y) location of upper left corner */
int foregrnd; /* Foreground colour of character */
int backgrnd; /* Background colour of character */
int font; /* Type of font to write in */

Description:

This function kis the general purpose character output routine, and
can write a character to the screen in any of the available font styles.
This routine, or the appropriate one for the specified font style, both
have the same purpose, but it is much easier to call this routine with the
font specified with an argument, than it is to call the font specific
routine.

The character is represented by its ASCII value, in the range of 32 to
127. Values other than that may be passed to the routine, but they will
have unknown results. Ths (x,y) location specified where the top left hand
corner of the character will be placed, with the character expanding down
and to the right.

The foreground and background colours are the colours that will be
used when writing the pixel to the screen. The colours can be spcified via
their numbers (if you know them), or the appropriate defined colour
(LS_YELLOW, for example). Appendix B contains all of the character colours.

The font is specified by sending the appropriate number or defined
font style to the routine. For example '1' and 'BROAD_FONT' both achieve
the same results. If the chracter set has not been registered in first, a
value of -1 will be returned from the function. A return of 0 means
everything was ok. The defined fonts are listed in a table at the start of
this section.

Example:

/* Light Speed Reference Example Program */
/* Write a string, with a character in each font */
#include "lspeed.h"

main()
{
/* Variables */
int loop;


-- Page 118 --




Light Speed
High Speed Graphics Programming


/* Set graphics mode and register all fonts */
set640x350();
registerbroadfont();
registercomputerfont();
registertallfont();
registersmallfont();
registerscriptfont();
registerplasmafont();
registerplainfont();
registeroldenglishfont();
registernicefont();
registeritalicfont();
registerstandardfont();
registercrispfont();

/* Write a YELLOW string, with a character in each font */
ega_writecharacter('H', 10, 10, LS_YELLOW, LS_BLACK, 1);
ega_writecharacter('e', 18, 10, LS_YELLOW, LS_BLACK, 2);
ega_writecharacter('l', 24, 10, LS_YELLOW, LS_BLACK, 3);
ega_writecharacter('l', 32, 10, LS_YELLOW, LS_BLACK, 4);
ega_writecharacter('o', 40, 10, LS_YELLOW, LS_BLACK, 5);
ega_writecharacter(' ', 48, 10, LS_YELLOW, LS_BLACK, 6);
ega_writecharacter('W', 56, 10, LS_YELLOW, LS_BLACK, 7);
ega_writecharacter('o', 64, 10, LS_YELLOW, LS_BLACK, 8);
ega_writecharacter('r', 72, 10, LS_YELLOW, LS_BLACK, 9);
ega_writecharacter('l', 80, 10, LS_YELLOW, LS_BLACK, 10);
ega_writecharacter('d', 88, 10, LS_YELLOW, LS_BLACK, 11);
ega_writecharacter('!', 96, 10, LS_YELLOW, LS_BLACK, 12);

/* Small font was not used, so use it for the key message */
ega_writetext(10, 40, LS_WHITE, LS_BLUE, SMALL_FONT,
"Press a key to continue!");

/* Wait for key, return to text and exit */
getxch();
set80x25();
}

See Also:

ega_writechar, ega_broadch, ega_computerch, ega_crispch,
ega_italicch, ega_nicech, ega_oldenglishch, ega_plainch,
ega_plasmach, ega_scriptch, ega_smallch, ega_standardch,
ega_tallch













-- Page 119 --




Light Speed
High Speed Graphics Programming


Function Name:

registerbroadfont

Purpose:

Register the Broad font into memory.

Calling Protocol:

void registerbroadfont(void)

Description:

This function will load the Broad font into memory, and point the
correct font pointers to the data area. The registered font table will also
be updated to show that the font is now ready to use. Multiple calls to
this function do not re-load the font table each time, they have no effect.
This means that only one copy of the font data can be in memory at a time,
saving data space.

Example:

See the example program at the start of this section

See Also:

registercomputerfont, registercrispfont, registeritalicfont,
registernicefont, registeroldenglishfont, registerplainfont,
registerplasmafont, registerscriptfont, registersmallfont,
registerstandardfont, registertallfont


























-- Page 120 --




Light Speed
High Speed Graphics Programming


Function Name:

registercomputerfont

Purpose:

Register the Computer font into memory.

Calling Protocol:

void registercomputerfont(void)

Description:

This function will load the Computer font into memory, and point the
correct font pointers to the data area. The registered font table will also
be updated to show that the font is now ready to use. Multiple calls to
this function do not re-load the font table each time, they have no effect.
This means that only one copy of the font data can be in memory at a time,
saving data space.

Example:

See the example program at the start of this section

See Also:

registerbroadfont, registercrispfont, registeritalicfont,
registernicefont, registeroldenglishfont, registerplainfont,
registerplasmafont, registerscriptfont, registersmallfont,
registerstandardfont, registertallfont


























-- Page 121 --




Light Speed
High Speed Graphics Programming


Function Name:

registercrispfont

Purpose:

Register the Crisp font into memory.

Calling Protocol:

void registercrispfont(void)

Description:

This function will load the Crisp font into memory, and point the
correct font pointers to the data area. The registered font table will also
be updated to show that the font is now ready to use. Multiple calls to
this function do not re-load the font table each time, they have no effect.
This means that only one copy of the font data can be in memory at a time,
saving data space.

Example:

See the example program at the start of this section

See Also:

registerbroadfont, registercomputerfont, registeritalicfont,
registernicefont, registeroldenglishfont, registerplainfont,
registerplasmafont, registerscriptfont, registersmallfont,
registerstandardfont, registertallfont


























-- Page 122 --




Light Speed
High Speed Graphics Programming


Function Name:

registeritalicfont

Purpose:

Register the Italic font into memory.

Calling Protocol:

void registeritalicfont(void)

Description:

This function will load the Italic font into memory, and point the
correct font pointers to the data area. The registered font table will also
be updated to show that the font is now ready to use. Multiple calls to
this function do not re-load the font table each time, they have no effect.
This means that only one copy of the font data can be in memory at a time,
saving data space.

Example:

See the example program at the start of this section

See Also:

registerbroadfont, registercomputerfont, registercrispfont,
registernicefont, registeroldenglishfont, registerplainfont,
registerplasmafont, registerscriptfont, registersmallfont,
registerstandardfont, registertallfont


























-- Page 123 --




Light Speed
High Speed Graphics Programming


Function Name:

registernicefont

Purpose:

Register the Nice font into memory.

Calling Protocol:

void registernicefont(void)

Description:

This function will load the Nice font into memory, and point the
correct font pointers to the data area. The registered font table will also
be updated to show that the font is now ready to use. Multiple calls to
this function do not re-load the font table each time, they have no effect.
This means that only one copy of the font data can be in memory at a time,
saving data space.

Example:

See the example program at the start of this section

See Also:

registerbroadfont, registercomputerfont, registercrispfont,
registeritalicfont, registeroldenglishfont, registerplainfont,
registerplasmafont, registerscriptfont, registersmallfont,
registerstandardfont, registertallfont


























-- Page 124 --




Light Speed
High Speed Graphics Programming


Function Name:

registeroldenglishfont

Purpose:

Register the Old English font into memory.

Calling Protocol:

void registeroldenglishfont(void)

Description:

This function will load the Old English font into memory, and point
the correct font pointers to the data area. The registered font table will
also be updated to show that the font is now ready to use. Multiple calls
to this function do not re-load the font table each time, they have no
effect. This means that only one copy of the font data can be in memory at a
time, saving data space.

Example:

See the example program at the start of this section

See Also:

registerbroadfont, registercomputerfont, registercrispfont,
registeritalicfont, registernicefont, registerplainfont,
registerplasmafont, registerscriptfont, registersmallfont,
registerstandardfont, registertallfont


























-- Page 125 --




Light Speed
High Speed Graphics Programming


Function Name:

registerplainfont

Purpose:

Register the Plain font into memory.

Calling Protocol:

void registerplainfont(void)

Description:

This function will load the Plain font into memory, and point the
correct font pointers to the data area. The registered font table will also
be updated to show that the font is now ready to use. Multiple calls to
this function do not re-load the font table each time, they have no effect.
This means that only one copy of the font data can be in memory at a time,
saving data space.

Example:

See the example program at the start of this section

See Also:

registerbroadfont, registercomputerfont, registercrispfont,
registeritalicfont, registernicefont, registeroldenglishfont,
registerplasmafont, registerscriptfont, registersmallfont,
registerstandardfont, registertallfont


























-- Page 126 --




Light Speed
High Speed Graphics Programming


Function Name:

registerplasmafont

Purpose:

Register the Plasma font into memory.

Calling Protocol:

void registerplasmafont(void)

Description:

This function will load the Plasma font into memory, and point the
correct font pointers to the data area. The registered font table will also
be updated to show that the font is now ready to use. Multiple calls to
this function do not re-load the font table each time, they have no effect.
This means that only one copy of the font data can be in memory at a time,
saving data space.

Example:

See the example program at the start of this section

See Also:

registerbroadfont, registercomputerfont, registercrispfont,
registeritalicfont, registernicefont, registeroldenglishfont,
registerplainfont, registerscriptfont, registersmallfont,
registerstandardfont, registertallfont


























-- Page 127 --




Light Speed
High Speed Graphics Programming


Function Name:

registerscriptfont

Purpose:

Register the Script font into memory.

Calling Protocol:

void registerscriptfont(void)

Description:

This function will load the Script font into memory, and point the
correct font pointers to the data area. The registered font table will also
be updated to show that the font is now ready to use. Multiple calls to
this function do not re-load the font table each time, they have no effect.
This means that only one copy of the font data can be in memory at a time,
saving data space.

Example:

See the example program at the start of this section

See Also:

registerbroadfont, registercomputerfont, registercrispfont,
registeritalicfont, registernicefont, registeroldenglishfont,
registerplainfont, registerplasmafont, registersmallfont,
registerstandardfont, registertallfont


























-- Page 128 --




Light Speed
High Speed Graphics Programming


Function Name:

registersmallfont

Purpose:

Register the EGA Small font into memory.

Calling Protocol:

void registersmallfont(void)

Decription:

This function will load the EGA Small font into memory, and point the
correct font pointers to the data area. The registered font table will also
be updated to show that the font is now ready to use. Multiple calls to
this function do not re-load the font table each time, they have no effect.
This means that only one copy of the font data can be in memory at a time,
saving data space.

Example:

See the example program at the start of this section

See Also:

registerbroadfont, registercomputerfont, registercrispfont,
registeritalicfont, registernicefont, registeroldenglishfont,
registerplainfont, registerplasmafont, registerscriptfont,
registerstandardfont, registertallfont


























-- Page 129 --




Light Speed
High Speed Graphics Programming


Function Name:

registerstandardfont

Purpose:

Register the EGA Standard font into memory.

Calling Protocol:

void registerstandardfont(void)

Destandardion:

This function will load the EGA Standard font into memory, and point
the correct font pointers to the data area. The registered font table will
also be updated to show that the font is now ready to use. Multiple calls
to this function do not re-load the font table each time, they have no
effect. This means that only one copy of the font data can be in memory at a
time, saving data space.

Example:

See the example program at the start of this section

See Also:

registerbroadfont, registercomputerfont, registercrispfont,
registeritalicfont, registernicefont, registeroldenglishfont,
registerplainfont, registerplasmafont, registerscriptfont,
registersmallfont, registertallfont


























-- Page 130 --




Light Speed
High Speed Graphics Programming


Function Name:

registertallfont

Purpose:

Register the Tall font into memory.

Calling Protocol:

void registertallfont(void)

Detallion:

This function will load the Tall font into memory, and point the
correct font pointers to the data area. The registered font table will also
be updated to show that the font is now ready to use. Multiple calls to
this function do not re-load the font table each time, they have no effect.
This means that only one copy of the font data can be in memory at a time,
saving data space.

Example:

See the example program at the start of this section

See Also:

registerbroadfont, registercomputerfont, registercrispfont,
registeritalicfont, registernicefont, registeroldenglishfont,
registerplainfont, registerplasmafont, registerscriptfont,
registersmallfont, registerstandardfont


























-- Page 131 --




Light Speed
High Speed Graphics Programming


Mouse Interface Control Routines
--------------------------------

The Light Speed library provides an easy link between the interrupt
system used by the mouse driver and the high level programming language.
Every mouse function that should be necessary to the programmer is
available. There also many pre-defined mouse pointer styles available, so
that you can easily select a pointer without having to draw a new one up,
convert the codes, and then program the set pointer routines yourself.

Nine pre-defined pointers are supported:

Arrows - four arrows pointing out from the centre to the top,
left, right and down
Cross - an 'X' shaped pointer
Crosshair - a '+' shaped pointer
Hand - a hand with the pointing finger extended
Hourglass - the classic 'wait a moment' symbol
Pointer - the standard mouse pointer
Question mark - the question mark symbol
Tick - the tick (correct) symbol, similar to û
Watch - a newer version of the Hourglass

There are also routines that allow you to test for certain button
press states, set active ranges, and much more...

Please note that there are no example programs for any of the mouse
functions. Their use is quite self explanatory, and the description for the
particular function should clear up any mis-conceptions. There are also no
'See Also' descriptors, as all of the mouse functions tie in together, as
no program can rely on just one function alone.


























-- Page 132 --




Light Speed
High Speed Graphics Programming


Function Name:

get_mouse_pos

Purpose:

n Find the current mouse position.

Calling Protocol:

int get_mouse_pos(&xpos, &ypos)

int xpos, ypos; /* The (x,y) location storage variables */

Description:

This function is used to find the current position of the mouse. The
values passed to the routine are used as pointers to memory variables -
that is why they are passed by their addresses (&).

If there is no mouse installed, the variables will remain un-touched,
and the function will return a value of 0. If all is ok, the mouse position
(drawn from the cursor hotspot) will be returned in the variables, and the
function will return a value of 1.

































-- Page 133 --




Light Speed
High Speed Graphics Programming


Function Name:

get_mouse_presses

Purpose:

Read the press state of a button.


Calling Protocol:

int get_mouse_presses(button, &releases, &lastx, &lasty)

int button; /* Button to test */
int releases; /* Number of presses for that button */
int lastx, lasty; /* (x,y) location of the last button press */

Description:

This function is used to read the number of presses that a button
has received, and where the location of the last press was. A call to
this function will clear out the internal mouse press counter for the
specified button. The buttons are defined as:

Button Value
--------------------------
MOUSE_LEFT 0
MOUSE_RIGHT 1
MOUSE_MIDDLE 2

The values passed as addresses, are used to store the information that
is returned by the function. The function itself will return a value of 1
for success (which does not mean that any buttons were pressed, or even
that the test was called with a real button number), or a 0 if the mouse is
not installed.






















-- Page 134 --




Light Speed
High Speed Graphics Programming


Function Name:

get_mouse_releases

Purpose:

Read the release state of a button.

Calling Protocol:

int get_mouse_releases(button, &releases, &lastx, &lasty)

int button; /* Button to test */
int releases; /* Number of releases for that button */
int lastx, lasty; /* (x,y) location of last button release */

Description:

This function is used to read the number of releases that a button
has received, and where the location of the last release was. A call to
this function will clear out the internal mouse release counter for the
specified button. The buttons are defined as:

Button Value
--------------------------
MOUSE_LEFT 0
MOUSE_RIGHT 1
MOUSE_MIDDLE 2

The values passed as addresses, are used to store the information that
is returned by the function. The function itself will return a value of 1
for success (which does not mean that any buttons were released, or even
that the test was called with a real button number), or a 0 if the mouse is
not installed.























-- Page 135 --




Light Speed
High Speed Graphics Programming


Function Name:

hide_mouse

Purpose:

Hide the mouse cursor.

Calling Protocol:

int hide_mouse(void)

Description:

This function can be used to hide the mouse pointer fro the graphcis
display. This should be used _every_ time the screen is being updated, as
writes to the screen where a pointer is resting will be corrupted. You can
also hide the mouse for any purpose that you feel necessary, but hiding
whenever the screen is updated is essential for proffessional looking
programs.

Hiding and unhiding the mouse all of the time can cause flicker of the
pointer, so it is essential that mouse graphics routines are well written
to allow for this, and make as few calls as possible to this and the
show_moue functions.

The function will return a 0 for no mouse installed, or a 1 for
success.





























-- Page 136 --




Light Speed
High Speed Graphics Programming


Function Name:

init_mouse

Purpose:

Initialize the mouse driver.

Calling Protocol:

int init_mouse(void)

Description:

This function is used to initialize the mouse driver for your program
to use. If you do not call this routine, none of the mouse functions will
work as expected, even if the mouse driver is installed (the two routines
work independantly of eachother).

The function will return the number of buttons available on the mouse,
or a 0 if no mouse is installed. The number of buttons available should be
used as a limit to any of the other routines that can accept up to three
buttons - it is no good calling for a button press state on the middle
button (number 2), if only two buttons are available.

Both the MicroSoft and Mouse Systems mice are supported. MicroSoft
mice have two buttons, whereas Mouse Systems mice have three.

A call to init_mouse does _not_ display the graphics pointer, it only
resets all of the internal mouse pointer parameters. You can call this
routine once at the start of the program to initialize the mouse, and then
any time thereafter to reset the mouse. You should also call init_mouse if
you change screen modes in the middle of a program.
























-- Page 137 --




Light Speed
High Speed Graphics Programming


Function Name:

left_button

Purpose:

Check if left button is pressed.

Calling Protocol:

int left_button(void)

Description:

This function is used to test if the left mouse button is being held
down explicitly at the time of the call. A return of 0 (or false) means
that the button is not being held down, 1 (or true) means that it is. A
good use for this function is to make the program pause until the left
button is pressed... 'while (!left_button()) ;', which would loop
until the left button was pressed.

The save area for the left button is not reset by calling this
function.


































-- Page 138 --




Light Speed
High Speed Graphics Programming


Function Name:

middle_button

Purpose:

Check if middle button is pressed.

Calling Protocol:

int middle_button(void)

Description:

This function is used to test if the middle mouse button is being held
down explicitly at the time of the call. A return of 0 (or false) means that
the button is not being held down, 4 means that it is. A good use for this
function is to make the program pause until the middle button is
pressed... 'while (!middle_button()) ;', which would loop until the
middle button was pressed.

The save area for the middle button is not reset by calling this
function.


































-- Page 139 --




Light Speed
High Speed Graphics Programming


Function Name:

mouse_buttons

Purpose:

Read state of all pressed buttons.

Calling Protocol:

int mouse_buttons(void)

Description:

This function read the state of all of the available buttons, to see
if they are pressed at the time of the call. The internal storage areas for
the buttons are not reset by calling this function.

The value returned by this function is bit encoded:

Bit 7 6 5 4 3 2 1 0
. . . . . . X . 1 = left button pressed, 0 = released
. . . . . X . . 1 = right button pressed, 0 = released
. . . . X . . . 1 = middle button pressed, 0 = released
X X X X . . . . Unused

A return value for the middle button is applicable only on the Mouse
Systems mouse, on MicroSoft mice it should always be set to 0.





























-- Page 140 --




Light Speed
High Speed Graphics Programming


Function Name:

mouse_installed

Purpose:

Check if mouse is installed.

Calling Protocol:

int mouse_installed(void)

Description:

This function is used to see if the mouse driver is installed in
memory. It does so not via an interrupt to the mouse driver (which can be
dangerous if there is not one present), but by reading the interrupt
pointers in low memory to check for redirection of interrupt 0x33, the
standard mouse interrupt.

A return of 0 (or false) means that no mouse driver is installed, a
return of 1 (or true) means that one is available. A call to this function
should preceed the call to the init_mouse function, but is not meant as a
replacement. The two routines can be used together to make sure that the is
not an interrupt to a non existant location.
































-- Page 141 --




Light Speed
High Speed Graphics Programming


Function Name:

read_mouse_motions

Purpose:

Read the internal mouse motion counters.

Calling Protocol:

int read_mouse_motions(&xmotion, &ymotion)

int xmotion; /* The number of horizontal motions */
int ymotion; /* The number of vertical motions */

Description:

The mouse driver maintains a set of internal mouse movement registers
that store the distance that the mouse has moved since the last call to
this function. The motion values (passed via pointers) are both positive
and negative - a negative motion means a move upwards in the vertical
direction, or leftwards in the horizontal direction, a positive motion
number means a move downwards or rightwards respectively.

The return of this function is 0 if no mouse is installed, 1 if all is
okay. Once this function has been called, the mouse motion counters are
reset by the mouse driver, so that the next call is taken from the exact
same spot as where the last motions stopped.





























-- Page 142 --




Light Speed
High Speed Graphics Programming


Function Name:

right_button

Purpose:

Check if right button is pressed.

Calling Protocol:

int right_button(void)

Description:

This function is used to test if the right mouse button is being held
down explicitly at the time of the call. A return of 0 (or false) means that
the button is not being held down, 2 means that it is. A good use for this
function is to make the program pause until the right button is
pressed... 'while (!right_button()) ;', which would loop until the
right button was pressed.

The save area for the right button is not reset by calling this
function.


































-- Page 143 --




Light Speed
High Speed Graphics Programming


Function Name:

set_mouse_pos

Purpose:

Set a new mouse (x,y) location.

Calling Protocol:

int set_mouse_pos(newx, newy)

int newx, newy; /* New (x,y) position of mouse pointer */

Description:

This function is used to set the mouse pointer to a new location. The
new location is calulate from the current pointer patterns' hot spot, not
from the upper left corner of the pointer.

The function will return a 0 if no mouse is installed, 1 if all is
okay.



































-- Page 144 --




Light Speed
High Speed Graphics Programming


Function Name:

set_mouse_pointer

Purpose:

Set a new mouse pointer.

Calling Protocol:

int set_mouse_pointer(pattern, hotx, hoty)

unsigned int pattern[32]; /* New pointer pattern */
int hotx; /* New hotspot x co-ordinate */
int hoty; /* New hotspot y co-ordinate */

Description:

This function is used to set the mouse pointer to a new pattern. A
mouse pointer consists of two sections - a sixteen word screen mask and a
sixteen word cursor mask. The size of the pointer is 16x16, in any graphics
mode.

To calculate one row of either mask, you need a binary to hexidecimal
converter (if you are doing it by hand). Or, you can use the mouse pointer
design program included in the package (see appendix C). The following
information can be used as a technical background if you use the pointer
design program, as the conversion is calulated for you (for both the cursor
and screen masks).

To assemble one row, convert a sixteen bit wide word from binary to
hexadecimal, and this becomes the member of the table. When constructing
images from scratch, the following conditions apply to every pixel in the
mouse pointer:

Screen Cursor Resulting
mask mask screen
bit bit bit
----------------------------
0 0 0
0 1 1
1 0 unchanged
1 1 inverted

The only colours available in the mouse pointer are black and white,
the underlying colours that show through in regions set to show the
bakground (which depend on over what the pointer is placed) or values that
have been set to xor with the background (which elso depend on over what
the pointer is placed).

The first sixteen values of the pointer table are the screen mask
(values [0] - [15]), the last sixteen are the cursor mask (values
[16] - [31]). An example mouse pointer, a hollow box:




-- Page 145 --




Light Speed
High Speed Graphics Programming


Screen bitmap = 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0x0000
0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 2 0x0000
0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 3 0x0000
0 0 0 0 1 1 1 1 1 1 1 0 0 0 0 4 0x0ff0
0 0 0 0 1 1 1 1 1 1 1 0 0 0 0 5 0x0ff0
0 0 0 0 1 1 1 1 1 1 1 0 0 0 0 6 0x0ff0
0 0 0 0 1 1 1 1 1 1 1 0 0 0 0 7 0x0ff0
0 0 0 0 1 1 1 1 1 1 1 0 0 0 0 8 0x0ff0
0 0 0 0 1 1 1 1 1 1 1 0 0 0 0 9 0x0ff0
0 0 0 0 1 1 1 1 1 1 1 0 0 0 0 10 0x0ff0
0 0 0 0 1 1 1 1 1 1 1 0 0 0 0 11 0x0ff0
0 0 0 0 1 1 1 1 1 1 1 0 0 0 0 12 0x0ff0
0 0 0 0 1 1 1 1 1 1 1 0 0 0 0 13 0x0ff0
0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 14 0x0000
0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 15 0x0000
0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 16 0x0000

Cursor bitmap = 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0xffff
1 0 0 0 0 0 0 0 0 0 0 0 0 0 1 2 0x8001
1 0 0 1 1 1 1 1 1 1 1 1 0 0 1 3 0x9ff9
1 0 0 1 0 0 0 0 0 0 0 1 0 0 1 4 0x9009
1 0 0 1 0 0 0 0 0 0 0 1 0 0 1 5 0x9009
1 0 0 1 0 0 0 0 0 0 0 1 0 0 1 6 0x9009
1 0 0 1 0 0 0 0 0 0 0 1 0 0 1 7 0x9009
1 0 0 1 0 0 0 0 0 0 0 1 0 0 1 8 0x9009
1 0 0 1 0 0 0 0 0 0 0 1 0 0 1 9 0x9009
1 0 0 1 0 0 0 0 0 0 0 1 0 0 1 10 0x9009
1 0 0 1 0 0 0 0 0 0 0 1 0 0 1 11 0x9009
1 0 0 1 0 0 0 0 0 0 0 1 0 0 1 12 0x9009
1 0 0 1 0 0 0 0 0 0 0 1 0 0 1 13 0x9009
1 0 0 1 1 1 1 1 1 1 1 1 0 0 1 14 0x9ff9
1 0 0 0 0 0 0 0 0 0 0 0 0 0 1 15 0x8001
1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 16 0xffff

This defines a box with a hollow centre, and a marking line on the
inside and outside edges. The marking lines are white, the insides of the
lines are black.

The conversion for this pointer was done by hand, which is very
tedious. It is much easier to use the pointer design program, which will
specify the sixteen values needed both of the masks.

One note about programming the mouse hotspot position: any call that
is made to the mouse driver that set or returns a position, will use the
offset into the pointer to the hotspot as its co-ordinate, not the actual
pointers' upper left corner. This means that if you set the hotspot at
location (10,10) inside the pointer, and a call to the position function
was made, the following could be determined:

(a) the _hotspot_ is at the returned location
(b) the actual top left corner is at
(x position minus 10, y position minus 10)





-- Page 146 --




Light Speed
High Speed Graphics Programming


The pointer can easily go out of range of the screen, and the only limiting
factor is when the hotspot reaches the horizontal or vertical limites set
by either the mouse driver or the programmer.

A return of 0 from this function means that no mouse driver was
installed, a return of 1 means that the mouse pointer should have been set
(if all parameters were alright). Sending stray parameters to this function
(like a shorter pointer array) can cause unpredictable results, or even
cause a system crash.
















































-- Page 147 --




Light Speed
High Speed Graphics Programming


Function Name:

set_mouse_xrange

Purpose:

Set a horizontal mouse range.

Calling Protocol:

int set_mouse_xrange(leftlimit, rightlimit)

int leftlimit, rightlimit; /* Left/right screen limits */

Description:

This function can be used to set up the boundaries of the area the
mouse can travel in. The two arguments passed to the function specify the
left and right edges of the boundary, and the hotspot of the cursor will
stop when it reaches either of them.

The two edges may be larger than the screen size, but if the mouse
travels off the screen, it will not be seen (even though it will continue
right up to the boundary edge).

The function will return a 1 for success, or a 0 to signify that it
could not find the mouse driver. A call to init_mouse will reset the
these values to the driver defaults.

Notes:

When the mouse is initialized in some of the video modes, the driver
may not set the correct values for the ranges. You can call this and the
set_mouse_yrange function to fix up the values to the edges of the screen.























-- Page 148 --




Light Speed
High Speed Graphics Programming


Function Name:

set_mouse_yrange

Purpose:

Set a vertical mouse range.

Calling Protocol:

int set_mouse_yrange(toplimit, bottomlimit)

int toplimit, bottomlimit; /* Top/bottom screen limits */

Description:

This function can be used to set up the boundaries of the area the
mouse can travel in. The two arguments passed to the function specify the
top and bottom edges of the boundary, and the hotspot of the cursor will
stop when it reaches either of them.

The two edges may be larger than the screen size, but if the mouse
travels off the screen, it will not be seen (even though it will continue
roght up to the boundary edge).

The function will return a 1 for success, or a 0 to signify that it
could not find the mouse driver. A call to init_mouse will reset the
these values to the driver defaults.

Notes:

When the mouse is initialized in some of the video modes, the driver
may not set the correct values for the ranges. You can call this and the
set_mouse_xrange function to fix up the values to the edges of the screen.























-- Page 149 --




Light Speed
High Speed Graphics Programming


Function Name:

set_pointer_arrows

Purpose:

Set mouse cursor to arrows.

Calling Protocol:

void set_pointer_arrows(void)

Description:

This function will set the mouse cursor to the 'arrows' shape (drawn
below). The function does not return a value, but will not function if
there is no mouse installed. The mouse also has to have the cursor
displayed for the effect to be seen, but if the cursor is hidden, the next
call to show_mouse will display the new cursor.

The 'arrows' pattern:

ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
³ ³
³ ÛÛ ³
³ ÛÛÛÛÛÛ ³
³ ÛÛÛÛÛÛÛÛÛÛ ³
³ ÛÛ ³
³ ÛÛ ÛÛ ÛÛ ³
³ ÛÛÛÛ ÛÛ ÛÛÛÛ ³
³ ÛÛÛÛÛÛÛÛÛÛÛÛxxÛÛÛÛÛÛÛÛÛÛÛÛ ³
³ ÛÛÛÛ ÛÛ ÛÛÛÛ ³
³ ÛÛ ÛÛ ÛÛ ³
³ ÛÛ ³
³ ÛÛÛÛÛÛÛÛÛÛ ³
³ ÛÛÛÛÛÛ ³
³ ÛÛ ³
³ ³
³ ³
ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ

Hot spot at 'xx', (7,7). The hotspot pixel is not set.















-- Page 150 --




Light Speed
High Speed Graphics Programming


Function Name:

set_pointer_cross

Purpose:

Set mouse cursor to a cross.

Calling Protocol:

void set_pointer_cross(void)

Description:

This function will set the mouse cursor to the 'cross' shape (drawn
below). The function does not return a value, but will not function if
there is no mouse installed. The mouse also has to have the cursor
displayed for the effect to be seen, but if the cursor is hidden, the next
call to show_mouse will display the new cursor.

The 'cross' pattern:

ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
³ ³
³ ÛÛ ÛÛ ³
³ ÛÛ ÛÛ ³
³ ÛÛ ÛÛ ³
³ ÛÛ ÛÛ ³
³ ÛÛ ÛÛ ³
³ ÛÛ ÛÛ ³
³ xx ³
³ ÛÛ ÛÛ ³
³ ÛÛ ÛÛ ³
³ ÛÛ ÛÛ ³
³ ÛÛ ÛÛ ³
³ ÛÛ ÛÛ ³
³ ÛÛ ÛÛ ³
³ ³
³ ³
ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ

Hot spot at 'xx', (7,7). The hotspot pixel is not set.















-- Page 151 --




Light Speed
High Speed Graphics Programming


Function Name:

set_pointer_crosshair

Purpose:

Set mouse cursor to a crosshair.

Calling Protocol:

void set_pointer_crosshair(void)

Description:

This function will set the mouse cursor to the 'crosshair' shape
(drawn below). The function does not return a value, but will not function
if there is no mouse installed. The mouse also has to have the cursor
displayed for the effect to be seen, but if the cursor is hidden, the next
call to show_mouse will display the new cursor.

The 'crosshair' pattern:

ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
³ ³
³ ÛÛ ³
³ ÛÛ ³
³ ÛÛ ³
³ ÛÛ ³
³ ÛÛ ³
³ ÛÛ ³
³ ÛÛÛÛÛÛÛÛÛÛÛÛxxÛÛÛÛÛÛÛÛÛÛÛÛ ³
³ ÛÛ ³
³ ÛÛ ³
³ ÛÛ ³
³ ÛÛ ³
³ ÛÛ ³
³ ÛÛ ³
³ ³
³ ³
ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ

Hot spot at 'xx', (7,7). The hotspot pixel is set to XOR.















-- Page 152 --




Light Speed
High Speed Graphics Programming


Function Name:

set_pointer_hand

Purpose:

Set mouse cursor to a hand.

Calling Protocol:

void set_pointer_hand(void)

Description:

This function will set the mouse cursor to the 'hand' shape (drawn
below). The function does not return a value, but will not function if
there is no mouse installed. The mouse also has to have the cursor
displayed for the effect to be seen, but if the cursor is hidden, the next
call to show_mouse will display the new cursor.

The 'hand' pattern:

ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
³ xx ³
³ ÛÛÛÛ ³
³ ÛÛÛÛ ³
³ ÛÛÛÛ ³
³ ÛÛÛÛ ³
³ ÛÛÛÛ ÛÛÛÛ ³
³ ÛÛÛÛ ÛÛÛÛ ÛÛÛÛ ³
³ ÛÛÛÛ ÛÛÛÛÛÛÛÛÛÛ ÛÛÛÛ ÛÛÛÛ ³
³ ÛÛÛÛ ÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛ ÛÛÛÛ ³
³ ÛÛÛÛ ÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛ ³
³ ÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛ ³
³ ÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛ ³
³ ÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛ ³
³ ÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛ ³
³ ÛÛÛÛÛÛÛÛÛÛÛÛÛÛ ³
³ ³
ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ

Hot spot at 'xx', (4,0). The hotspot pixel is not set.















-- Page 153 --




Light Speed
High Speed Graphics Programming


Function Name:

set_pointer_hourglass

Purpose:

Set mouse cursor to an hourglass.

Calling Protocol:

void set_pointer_hourglass(void)

Description:

This function will set the mouse cursor to the 'hourglass' shape
(drawn below). The function does not return a value, but will not function
if there is no mouse installed. The mouse also has to have the cursor
displayed for the effect to be seen, but if the cursor is hidden, the next
call to show_mouse will display the new cursor.

The 'hourglass' pattern:

ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
³ ³
³ ÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛ ³
³ ÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛ ³
³ ÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛ ³
³ ÛÛ ÛÛÛÛÛÛÛÛÛÛÛÛÛÛ ÛÛ ³
³ ÛÛ ÛÛÛÛÛÛÛÛÛÛ ÛÛ ³
³ ÛÛ ÛÛÛÛÛÛ ÛÛ ³
³ ÛÛ xx ÛÛ ³
³ ÛÛ ÛÛÛÛÛÛ ÛÛ ³
³ ÛÛ ÛÛÛÛÛÛÛÛÛÛ ÛÛ ³
³ ÛÛ ÛÛÛÛÛÛÛÛÛÛÛÛÛÛ ÛÛ ³
³ ÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛ ³
³ ÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛ ³
³ ÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛ ³
³ ³
³ ³
ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ

Hot spot at 'xx', (7,7). The hotspot pixel is set.















-- Page 154 --




Light Speed
High Speed Graphics Programming


Function Name:

set_pointer_pointer

Purpose:

Set mouse cursor to a pointer.

Calling Protocol:

void set_pointer_pointer(void)

Description:

This function will set the mouse cursor to the 'pointer' shape (drawn
below). The function does not return a value, but will not function if
there is no mouse installed. The mouse also has to have the cursor
displayed for the effect to be seen, but if the cursor is hidden, the next
call to show_mouse will display the new cursor.

The 'pointer' pattern:

ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
³ ³
³ xx ³
³ ÛÛÛÛ ³
³ ÛÛÛÛÛÛ ³
³ ÛÛÛÛÛÛÛÛ ³
³ ÛÛÛÛÛÛÛÛÛÛ ³
³ ÛÛÛÛÛÛÛÛÛÛÛÛ ³
³ ÛÛÛÛÛÛÛÛÛÛÛÛÛÛ ³
³ ÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛ ³
³ ÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛ ³
³ ÛÛÛÛÛÛÛÛÛÛ ³
³ ÛÛ ÛÛÛÛ ³
³ ÛÛÛÛ ³
³ ÛÛÛÛ ³
³ ÛÛÛÛ ³
³ ÛÛÛÛ ³
ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ

Hot spot at 'xx', (1,1). The hotspot pixel is set.















-- Page 155 --




Light Speed
High Speed Graphics Programming


Function Name:

set_pointer_questionmark

Purpose:

Set mouse cursor to a question mark pointer.

Calling Protocol:

void set_pointer_questionmark(void)

Description:

This function will set the mouse cursor to the 'question mark' shape
(drawn below). The function does not return a value, but will not function
if there is no mouse installed. The mouse also has to have the cursor
displayed for the effect to be seen, but if the cursor is hidden, the next
call to show_mouse will display the new cursor.

The 'question mark' pattern:

ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
³ ³
³ ÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛ ³
³ ÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛ ³
³ ÛÛÛÛÛÛ ÛÛÛÛÛÛ ³
³ ÛÛÛÛ ÛÛÛÛ ³
³ ÛÛÛÛ ³
³ ÛÛÛÛÛÛ ³
³ ÛÛÛÛÛÛÛÛ ³
³ xxÛÛÛÛÛÛ ³
³ ÛÛÛÛÛÛ ³
³ ÛÛÛÛ ³
³ ÛÛÛÛ ³
³ ³
³ ÛÛÛÛ ³
³ ÛÛÛÛ ³
³ ³
ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ

Hot spot at 'xx', (7,7). The hotspot pixel is not set.















-- Page 156 --




Light Speed
High Speed Graphics Programming


Function Name:

set_pointer_tick

Purpose:

Set mouse cursor to a tick.

Calling Protocol:

void set_pointer_tick(void)

Description:

This function will set the mouse cursor to the 'tick' shape (drawn
below). The function does not return a value, but will not function if
there is no mouse installed. The mouse also has to have the cursor
displayed for the effect to be seen, but if the cursor is hidden, the next
call to show_mouse will display the new cursor.

The 'tick' pattern:

ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
³ ³
³ ³
³ ÛÛÛÛ ³
³ ÛÛÛÛ ³
³ ÛÛÛÛ ³
³ ÛÛÛÛ ³
³ ÛÛÛÛ ³
³ ÛÛÛÛ ³
³ ÛÛÛÛ ÛÛÛÛ ³
³ ÛÛÛÛ ÛÛÛÛ ³
³ ÛÛÛÛ ÛÛÛÛ ³
³ ÛÛÛÛ ÛÛÛÛ ³
³ ÛÛxxÛÛÛÛ ³
³ ÛÛÛÛ ³
³ ³
³ ³
ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ

Hot spot at 'xx', (5,12). The hotspot pixel is set.















-- Page 157 --




Light Speed
High Speed Graphics Programming


Function Name:

set_pointer_watch

Purpose:

Set mouse cursor to a watch.

Calling Protocol:

void set_pointer_watch(void)

Description:

This function will set the mouse cursor to the 'watch' shape (drawn
below). The function does not return a value, but will not function if
there is no mouse installed. The mouse also has to have the cursor
displayed for the effect to be seen, but if the cursor is hidden, the next
call to show_mouse will display the new cursor.

The 'watch' pattern:

ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
³ ÛÛÛÛÛÛ ³
³ ÛÛ ÛÛ ³
³ ÛÛ ÛÛ ³
³ ÛÛÛÛÛÛÛÛÛÛ ³
³ ÛÛÛÛ ÛÛ ÛÛÛÛ ³
³ ÛÛ ÛÛ ÛÛ ³
³ ÛÛ ÛÛ ÛÛ ³
³ ÛÛ xx ÛÛ ³
³ ÛÛ ÛÛ ÛÛ ³
³ ÛÛ ÛÛ ÛÛ ³
³ ÛÛÛÛ ÛÛÛÛ ³
³ ÛÛÛÛÛÛÛÛÛÛ ³
³ ÛÛ ÛÛ ³
³ ÛÛ ÛÛ ³
³ ÛÛÛÛÛÛ ³
³ ³
ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ

Hot spot at 'xx', (7,7). The hotspot pixel is set.















-- Page 158 --




Light Speed
High Speed Graphics Programming


Function Name:

show_mouse

Purpose:

Show the mouse cursor.

Calling Protocol:

int show_mouse(void)

Description:

This function can be used to show the mouse pointer on the graphcis
display. This should be used to display the pointer again after a call to
hide_mouse, or after a call to init_mouse has been used to reset the mouse
driver. See hide_mouse for more details about the best times to use the
hide_mouse and show_mouse functions.

The function will return a 0 for no mouse installed, or a 1 for
success.



































-- Page 159 --




Light Speed
High Speed Graphics Programming


Function Name:

wait_for_mouse

Purpose:

Wait until a button is pressed.

Calling Protocol:

int wait_for_mouse(void)

Description:

This function will wait until the mouse buttons have been pressed. The
program will halt until any of the available buttons are pressed.

If there is no mouse installed the program the use of this function
will lock up the program, so you must use it carefully.

Notes:

The function will lock up the program, because there is a while
statement used to wait. The function returns when the while statement
receives a return value of 1, 2, or 4. If there is no mouse installed, the
value will _always_ be set to 0.































-- Page 160 --




Light Speed
High Speed Graphics Programming


Graphics Image Routines
-----------------------

The functions available in the Light Speed library for image handling
are very fast, but, as of this release, not in abundance. The routines
included here form the very basics of image maniputlation - storing and
retieving images on disk (see the Miscellaneous Functions section),
capturing images from the display, writing the images back to the display
in various forms, and extracting size data.

However, very complex control systems (and will) be built on top of
these primitives - there are already designs for a high speed timer driven
image system, capable of handling everything independent of the program.
For example, on of the examples of the routines in design will speed up the
timer interrupt by about five times (about 80 times per second), and update
the screen images whenever an interrupt occurs, and leave the program to
continue as though it had done it itself. Then, if an image hits the edge
of the screen, or collides with another, various trigger routines will be
enabled. All of this means that the programmer does not need to take care
of _any_ of the real hard core sprite controls, and can spend time adding
extra features to the meat of the program.

Anyway, that will be in a later release, as interrupt programming is
not the easiest of tasks to accomplish. But, however, in the next release
of the library, the following set of primitives will be enriched by
functions that allow for overlaying images (I spent several nights working
on this, but the routine had a small problem in it), saving of image data
to a file instead of image areas, and that type of thing.

The example program that follows demonstrates how easy it is to
write a program using the image manipulation routines. The helicopter
featured in the demonstration is a portion from a game I am working on,
which proves that the routines can be used for animation in game programs
as well. One note: the program must have the file 'HELI.IMG' in the
current directory.






















-- Page 161 --




Light Speed
High Speed Graphics Programming


/* Light Speed Reference Example Program */
/* Demonstrate the image manipulation routines */
#include "lspeed.h"

/* Memory allocation */
#include
#include

/* Global variables */
char far *heli1, far *heli2, far *heli3, far *heli4;

main()
{
/* Variables */
int loop, xloc, yloc;
unsigned char image;
unsigned int key;

/* Set graphics, install the font */
set320x200();
registerstandardfont();

/* Write a 'wait' message */
ega_writetext(10, 10, LS_YELLOW, LS_BLACK, STANDARD_FONT,
"Please wait, loading data...");

/* Allocate data for the images */
heli1=farmalloc(ega_imagesize(0,0,46,40));
heli2=farmalloc(ega_imagesize(0,0,46,40));
heli3=farmalloc(ega_imagesize(0,0,46,40));
heli4=farmalloc(ega_imagesize(0,0,46,40));

/* Check for any that didn't allocate */
if (heli1==NULL || heli2==NULL || heli3==NULL || heli4==NULL)
{
/* De-allocate all images */
farfree(heli1); farfree(heli2);
farfree(heli3); farfree(heli4);
set80x25();
printf("Did not have enough memory to load data!\n");
exit(1);
}

/* Load into the hidden page */
ega_setapage(2);
if (ega_restore_area_byte("heli.img",0,0,187,37,0,2)==-2)
{
farfree(heli1); farfree(heli2);
farfree(heli3); farfree(heli4);
set80x25();
printf("Could not find 'HELI.IMG' image file...\n");
exit(1);
}




-- Page 162 --




Light Speed
High Speed Graphics Programming


/* Save the images */
ega_getimage( 0, 0, 46, 40, heli1);
ega_getimage( 47, 0, 93, 40, heli2);
ega_getimage( 94, 0,140, 40, heli3);
ega_getimage(141, 0,187, 40, heli4);

/* Clear all pages, initialize mouse */
set320x200();

/* Write instructions */
ega_writetext(0, 0, LS_WHITE, LS_BLACK, STANDARD_FONT,
"Use cursor keys to control, Esc to stop");

/* Variables setup */
image=0;
xloc=150;
yloc=75;

/* Loop */
loop:
if (kbhit())
key=getxch(); /* Key available */
else
key=0; /* No key */

/* ESC aborts */
if (key==0x011B)
{
set80x25();
farfree(heli1); farfree(heli2);
farfree(heli3); farfree(heli4);
set80x25();
exit(0);
}

/* Test for directions */
switch (key)
{
case 0x4800 : /* UP */
yloc--; yloc--;
if (yloc<10)
yloc=10;
break;
case 0x4900 : /* UP-RIGHT */
yloc--; yloc--;
if (yloc<10)
yloc=10;
xloc++; xloc++;
if (xloc>272)
xloc=272;
break;






-- Page 163 --




Light Speed
High Speed Graphics Programming


case 0x4700 : /* UP-LEFT */
yloc--; yloc--;
if (yloc<10)
yloc=10;
xloc--; xloc--;
if (xloc<0)
xloc=0;
break;
case 0x5000 : /* DOWN */
yloc++; yloc++;
if (yloc>161)
yloc=161;
break;
case 0x5100 : /* DOWN-RIGHT */
yloc++; yloc++;
if (yloc>161)
yloc=161;
xloc++; xloc++;
if (xloc>272)
xloc=272;
break;
case 0x4F00 : /* DOWN-LEFT */
yloc++; yloc++;
if (yloc>161)
yloc=161;
xloc--; xloc--;
if (xloc<0)
xloc=0;
break;
case 0x4D00 : /* RIGHT */
xloc++; xloc++;
if (xloc>272)
xloc=272;
break;
case 0x4B00 : /* LEFT */
xloc--; xloc--;
if (xloc<0)
xloc=0;
break;
}

/* Update image */
image++;

/* Draw correct image */
if (image<7)
ega_putimage(heli1, xloc, yloc);
else if (image<14)
ega_putimage(heli2, xloc, yloc);
else if (image<21)
ega_putimage(heli3, xloc, yloc);
else if (image<28)
ega_putimage(heli4, xloc, yloc);
else
image=0; /* Out of range - reset */


-- Page 164 --




Light Speed
High Speed Graphics Programming


/* Repeat cycle */
goto loop;
}

There will not be any demonstration programs for the routines that are
similar in operation to those featured in the above program. However, for
routines that need explaining, they will receive an appropriate example.
The image functions:

















































-- Page 165 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_andimage

Purpose:

AND image onto the screen.

Calling Protocol:

void ega_andimage(image, xloc, yloc)

far char *xloc; /* Previosly stored image buffer */
int xloc, yloc; /* (x,y) location of top left of image */

Description:

This routine will place the image on the screen, AND'ing each value in
the image with the pixels underneath. The logic for the and operation, only
operating on 1 bit of information:

Background Buffer Screen Result
-----------------------------------------------
blank blank blank
blank set blank
set blank blank
set set set

The only major use for this function is when you are trying to compare
the values in the image buffer with those on the screen. The result will
show which pixels were set in both buffers.

Example:

See demonstration program, as for ega_putimage

See Also:

ega_putimage, ega_getimage, ega_xorimage, ega_orimage


















-- Page 166 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_extractsize

Purpose:

Find size of already stored image.

Calling Protocol:

int ega_extractsize(image)

char far *image; /* Buffer to extract size from */

Description:

Each of the images is pre-faced with a five byte header, as well as
having a packed data format. This function allows you to calculate exactly
how much storage space you need for the image, if it was to be duplicated,
or something similar.

This function only works on a previously stored image. See the
ega_imagesize function for details of calculating storage requirements
before an image is saved.

The value returned is the number of byte required to store the image.

Example:

/* Light Speed Reference Example Program */
/* Extract size from image after storage */
#include "lspeed.h"
#include

main()
{
/* Image storage */
char far *image;

/* Set graphics */
set640x350();

/* Allocate buffer */
image=farmalloc(imagesize(10, 10, 20, 20));
if (image==NULL)
{
set80x25();
printf("Allocation error!\n");
exit(1);
}







-- Page 167 --




Light Speed
High Speed Graphics Programming


set80x25();
printf("To save an image that went from (10,10) to (20,20)\n");
printf("took %d bytes!\n", ega_extractsize(image));
farfree(image);
}

See Also:

ega_imagesize
















































-- Page 168 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_getimage

Purpose:

Store and image in memory.

Calling Protocol:

void ega_getimage(topx, topy, bottomx, bottomy, image)

int topx, topy; /* Top (x,y) of image to store */
int bottomx, bottomy; /* Bottom (x,y) of image to store */
char far *image; /* Pointer to image buffer */

Description:

This function will save the image from the screen, int a specified
image buffer. The buffer must have been previously allocated by a call to
farmalloc or a similar function in the C standard library. The pointer
passed as the storage area must be declared as FAR. This allows for images
of any size to be stored, even up to screen dimensions (though this is
impracticle because it is very hard to manipulate and reduces program
memory).

The co-ordinates passed as arguments specify the locations of the top
left and bottom right corners of the image. They must be specified in that
order, otherwise unpredictable results will occur (especially over-writing
of your program or other data).

Example:

See demonstration program























-- Page 169 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_imagesize

Purpose:

Find the memory required for an image.

Calling Protocol:

int ega_imagesize(topx, topy, bottomx, bottomy)

int topx, topy; /* Top (x,y) of image */
int bottomx, bottomy; /* Bottom (x,y) of image */


Description:

You can use the ega_imagesize function with exactly the same set of
co-ordinates to determine how much memory you should allocate. A flow chart
of this process:

1) Set far pointer char far *image;
2) Use ega_imagesize int memory=ega_imagesize(0,0,10,10);
3) Allocate memory image=farmalloc(memory);
4) Save image ega_getimage(0,0,10,10,image);
5) Manipulate...

The value returned is the amount of memory required to store the
image, in bytes.

Example:

See demonstration program

See also:

ega_extractsize



















-- Page 170 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_orimage

Purpose:

OR image onto the screen.

Calling Protocol:

void ega_orimage(image, xloc, yloc)

far char *xloc; /* Previosly stored image buffer */
int xloc, yloc; /* (x,y) location of top left of image */

Description:

This routine will place the image on the screen, OR'ing each value in
the image with the pixels underneath. The logic for the or operation, only
operating on 1 bit of information:

Background Buffer Screen Result
-----------------------------------------------
blank blank blank
blank set set
set blank set
set set set

Example:

See demonstration program, as for ega_putimage

See Also:

ega_putimage, ega_getimage, ega_xorimage, ega_andimage






















-- Page 171 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_putimage

Purpose:

Put an image onto the screen.

Calling Protocol:

void ega_putimage(image, xloc, yloc)

far char *xloc; /* Previosly stored image buffer */
int xloc, yloc; /* (x,y) location of top left of image */

Description:

This routine will place the image on the screen, copying eahc value
from the image buffer _directly_ to the screen, without regard for the
pixels underneath. As all images save are square in shape, any image placed
on the screen will also have the rectangular shape.

Example:

See demonstration program

See Also:

ega_andimage, ega_getimage, ega_xorimage, ega_orimage




























-- Page 172 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_xorimage

Purpose:

XOR image onto the screen.

Calling Protocol:

void ega_xorimage(image, xloc, yloc)

far char *xloc; /* Previosly stored image buffer */
int xloc, yloc; /* (x,y) location of top left of image */

Description:

This routine will place the image on the screen, XOR'ing each value in
the image with the pixels underneath. The logic for the xor operation, only
operating on 1 bit of information:

Background Buffer Screen Result
-----------------------------------------------
blank blank blank
blank set set
set blank set
set set blank

The major benefit to the XOR operation is that you can use xor to
place the image on the screen, then another xor in exactly the same spot to
remove it.

Example:

See demonstration program, as for ega_putimage

See Also:

ega_putimage, ega_getimage, ega_orimage, ega_andimage


















-- Page 173 --




Light Speed
High Speed Graphics Programming


Miscellaneous Functions
-----------------------

The following set of functions are from different areas that do not
quite tie in with any of the major groups. There are image/screen saving
and restoring functions, keyboard functions, and screen enable and disable
routines.


















































-- Page 174 --




Light Speed
High Speed Graphics Programming


Function Name:

disable_screen

Purpose:

Disable the video display.

Calling Protocol:

void disable_screen(void)

Description:

This routine will completely disable the graphics adapter from
the monitor. The cut off is completely transparant to an
application - it is only in the hardware controllers that the effect
is noticed.

The major advantage however, is that the computer does not
waste any of the processor cycles reading data from the display
memory. Therefore, if you have a routine that does not need any kind
of graphics or textual output, then a call to this routine first will
improve the routines' performance.

The screen can be updated as per normal, however, and once the
screen is restored using a call to enable_screen, the new changes
will have effect.

Example:

/* Light Speed Reference Example Program */
/* Screen disable/enable */
#include "lspeed.h"

main()
{
/* Disable the screen */
printf("Press any key to disable the screen...\n");
printf("And another one a few seconds later to re-enable it!\n");
getch();
disable_screen();

/* Print a message, that will not be seen */
printf("This text is not seen until after the screen is enabled.\n");
printf("The slow routine could be called from here...\n");
getch(); /* Wait for next keypress */

/* Re-enable screen */
enable_screen();
}

See Also:

enable_screen


-- Page 175 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_capture_area_byte

Purpose:

Store a screen area.

Calling Protocol:

int ega_capture_area_byte(filename, topx, topy, bottomx, bottomy)

char *filename; /* Filename to save to */
int topx, topy; /* Top left corner of area */
int bottomx, bottomy; /* Bottom left corner of area */

Description:

This function will save the specified screen area to the filename. If
the function worked properly, then a return of 0 will result. There are
two possible error conditions:

Error Return
-------------------------------
Could not create -2
the file
Not in a graphics -1
mode

You must make a note of the co-ordinates used to save the area, as
they are used later when you re-load the area. This function will work in
all of the graphics modes, and can also be used to transfer a graphics area
between modes of different resolution.

Example:

/* Light Speed Reference Example Program */
/* Saving/loading areas */
#include "lspeed.h"

main()
{
/* Set graphics, register font */
set640x350();
registernicefont();

/* Draw some lines */
ega_putline(0, 0, 100, 50, LS_WHITE);
ega_putline(100, 0, 0, 50, LS_YELLOW);

/* Tell the user what is happening */
ega_writetext(10, 100, LS_WHITE, LS_YELLOW, NICE_FONT,
"Saving data...");




-- Page 176 --




Light Speed
High Speed Graphics Programming


/* Save the file */
switch(ega_capture_area_byte("areatest.img", 0, 0, 100, 50, 0, 0))
{
/* Test return */
case 0 : /* All ok */
break;
case -1 : /* Impossible! */
printf("Not in graphics - system error!\n");
exit(1);
case -2 : /* Could not use file */
set80x25();
printf("Error - could not create AREATEST.IMG!\n");
exit(1);
}

/* Clear screen */
ega_clearpage();

/* Write loading message */
ega_writetext(10, 10, LS_YELLOW, LS_BLACK, NICE_FONT,
"Screen cleared - press a key to load data!");

/* Get a key, load data */
getxch();
ega_clearpage(); /* Clear off message too */
switch(ega_restore_area_byte("areatest.img", 0, 0, 100, 50, 0, 0))
{
/* Test return */
case 0 : /* All ok */
break;
case -1 : /* Impossible! */
printf("Not in graphics - system error!\n");
exit(1);
case -2 : /* Could not use file */
set80x25();
printf("Error - could not load AREATEST.IMG!\n");
exit(1);
}

/* Wait for key, exit */
ega_writetext(10, 100, LS_WHITE, LS_BLACK, NICE_FONT,
"Image loaded - press a key...");
getxch();
set80x25();
}

See Also:

ega_restore_screen_byte, ega_save_area_byte, ega_save_screen_byte

Notes:

The format of the saved file is one colour per byte, unlike the video
memory which stores the data in a packed format. This means that it takes
much more area to save a file to disk, than it would if exactly the video


-- Page 177 --




Light Speed
High Speed Graphics Programming


buffer was saved. Therefore, in the next release, there will be routines
for saving direct from the buffer, and loading directly into the video
buffer. There should also be routines for loading and saving images with
various compression algorithms - GIF/PCX/TIFF.





















































-- Page 178 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_capture_screen_byte

Purpose:

Store a screen.

Calling Protocol:

int ega_capture_screen_byte(filename)

char *filename; /* Filename to save to */

Description:

This function will save the whole screen to a file, as if a screen
dump had been performed. A return of zero means that everything worked
properly. There are two possible error conditions:

Error Return
-------------------------------
Could not create -2
the file
Not in a graphics -1
mode

This function will work in all of the graphics modes, with the
following table showing file size and approximate time to save the screen.

Mode File length Approx. time
--------------------------------------------
640x350 224000 bytes 20 sec.
640x200 128000 bytes 12 sec.
320x200 64000 bytes 7 sec.

Note: The timing tests were performed on a 16Mhz standard AT.

Example:

/* Light Speed Reference Example Program */
/* Saving/loading screens */
#include "lspeed.h"

main()
{
/* Set graphics, register font */
set320x200();
registernicefont();

/* Draw some lines */
ega_putline(0, 0, 100, 50, LS_WHITE);
ega_putline(100, 0, 0, 50, LS_YELLOW);
ega_putline(150, 10, 25, 150, LS_RED);



-- Page 179 --




Light Speed
High Speed Graphics Programming


/* Save the file */
switch(ega_capture_screen_byte("scrntest.img"))
{
/* Test return */
case 0 : /* All ok */
break;
case -1 : /* Impossible! */
printf("Not in graphics - system error!\n");
exit(1);
case -2 : /* Could not use file */
set80x25();
printf("Error - could not create SCRNTEST.IMG!\n");
exit(1);
}

/* Clear screen */
ega_clearpage();

/* Write loading message */
ega_writetext(10, 10, LS_YELLOW, LS_BLACK, NICE_FONT,
"Screen cleared - press a key to load data!");

/* Get a key, load data */
getxch();
ega_clearpage(); /* Clear off message too */
switch(ega_restore_screen_byte("scrntest.img"))
{
/* Test return */
case 0 : /* All ok */
break;
case -1 : /* Impossible! */
printf("Not in graphics - system error!\n");
exit(1);
case -2 : /* Could not use file */
set80x25();
printf("Error - could not load AREATEST.IMG!\n");
exit(1);
}

/* Wait for key, exit */
ega_writetext(10, 180, LS_WHITE, LS_BLACK, NICE_FONT,
"Screen loaded - press a key...");
getxch();
set80x25();
}

See Also:

ega_restore_screen_byte, ega_save_area_byte, ega_save_screen_byte

Notes:

The format of the saved file is one colour per byte, unlike the video
memory which stores the data in a packed format. This means that it takes
much more area to save a file to disk, than it would if exactly the video


-- Page 180 --




Light Speed
High Speed Graphics Programming


buffer was saved. Therefore, in the next release, there will be routines
for saving direct from the buffer, and loading directly into the video
buffer. There should also be routines for loading and saving images with
various compression algorithms - GIF/PCX/TIFF.





















































-- Page 181 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_restore_area_byte

Purpose:

Restore a screen area.

Calling Protocol:

int ega_restore_area_byte(filename, topx, topy, bottomx, bottomy,
xloc, yloc)

char *filename; /* Filename to save to */
int topx, topy; /* Top left corner of area */
int bottomx, bottomy; /* Bottom left corner of area */
int xloc, yloc; /* (x,y) location to place upper left */

Description:

This function will restore the specified screen area from the
filename. If the function worked properly, then a return of 0 will result.
There are two possible error conditions:

Error Return
-------------------------------
Could not load -2
the file
Not in a graphics -1
mode

This is where the co-ordinates you used when saving the area are
used. They are specified as the top and bottom corners, with the last two
variables passed as arguments used to position the image on the screen.
This means you can move the image to any location, regardless of where it
was saved from. This function will work in all graphics modes, and can also
be used to transfer a graphics area between modes of different resolution.

Example:

See ega_restore_area_byte

See Also:

ega_restore_screen_byte, ega_restore_area_byte, ega_save_screen_byte

Notes:

The format of the saved file is one colour per byte, unlike the video
memory which stores the data in a packed format. This means that it takes
much more area to save a file to disk, than it would if exactly the video
buffer was saved. Therefore, in the next release, there will be routines
for saving direct from the buffer, and loading directly into the video
buffer. There should also be routines for loading and saving images with
various compression algorithms - GIF/PCX/TIFF.


-- Page 182 --




Light Speed
High Speed Graphics Programming


Function Name:

ega_restore_screen_byte

Purpose:

Restore a screen.

Calling Protocol:

int ega_restore_screen_byte(filename)

char *filename; /* Filename to save to */

Description:

This function will restore the whole screen from a file, after it has
been save with the ega_save_screen_byte function. A return of zero means
that everything worked properly. There are two possible error conditions:

Error Return
-------------------------------
Could not load -2
the file
Not in a graphics -1
mode

This function uses the current graphics mode to determine the size
of the file. The actual file size is not taken into consideration - it all
depends on the screen mode.

Example:

See ega_reatore_screen_byte
See Also:

ega_restore_screen_byte, ega_save_area_byte, ega_restore_area_byte

Notes:

The format of the saved file is one colour per byte, unlike the video
memory which stores the data in a packed format. This means that it takes
much more area to save a file to disk, than it would if exactly the video
buffer was saved. Therefore, in the next release, there will be routines
for saving direct from the buffer, and loading directly into the video
buffer. There should also be routines for loading and saving images with
various compression algorithms - GIF/PCX/TIFF.










-- Page 183 --




Light Speed
High Speed Graphics Programming


Function Name:

enable_screen

Purpose:

Enable the screen after disabling.

Calling Protocol:

void enable_screen(void);

Description:

This function can be used to re-enable the screen after it has been
disabled by a call to disable_screen. See the disable_screen function for a
more complete explanation of why these two functions can be handy in
speeding up a program.

Example:

See disable_screen

See Also:

disable_screen































-- Page 184 --




Light Speed
High Speed Graphics Programming


Function Name:

getxch

Purpose:

Read key from keyboard.

Calling Protocol:

unsigned int getxch(void)

Description:

This function can be used instead of the standard getch() calls to the
C library read key function. The value returned contains both the keycode
and the scan code value of the key pressed, with the values for every
available key listed in the following table. The computer will halt program
processing until a key is pressed, or read the next available key if there
are already keys in the buffer.

Keycode table:
--------------

Key Normal Shift Ctrl Alt
-------------------------------------------------------------
1 0x0231 0x0221 -- 0x7800
2 0x0332 0x0340 0x0300 0x7900
3 0x0433 0x0423 -- 0x7A00
4 0x0534 0x0524 -- 0x7B00
5 0x0635 0x0625 -- 0x7C00
6 0x0736 0x075E 0x071E 0x7D00
7 0x0837 0x0826 -- 0x7E00
8 0x0938 0x092A -- 0x7F00
9 0x0A39 0x0A28 -- 0x8000
0 0x0B30 0x0B29 -- 0x8100
A 0x1E61 0x1E41 0x1E01 0x1E00
B 0x3062 0x3042 0x3002 0x3000
C 0x2E63 0x2E42 0x2E03 0x2E00
D 0x2064 0x2044 0x2004 0x2000
E 0x1265 0x1245 0x1205 0x1200
F 0x2166 0x2146 0x2106 0x2100
G 0x2267 0x2247 0x2207 0x2200
H 0x2368 0x2348 0x2308 0x2300
I 0x1769 0x1749 0x1709 0x1700
J 0x246A 0x244A 0x240A 0x2400
K 0x256B 0x254B 0x250B 0x2500
L 0x266C 0x264C 0x260C 0x2600
M 0x326D 0x324D 0x320D 0x3200
N 0x316E 0x314E 0x310E 0x3100
O 0x186F 0x184F 0x180F 0x1800
P 0x1970 0x1950 0x1910 0x1900
Q 0x1071 0x1051 0x1011 0x1000
R 0x1372 0x1352 0x1312 0x1300
S 0x1F73 0x1F53 0x1F13 0x1F00


-- Page 185 --




Light Speed
High Speed Graphics Programming


Key Normal Shift Ctrl Alt
-------------------------------------------------------------
T 0x1474 0x1454 0x1414 0x1400
U 0x1675 0x1655 0x1615 0x1600
V 0x2F76 0x2F56 0x2F16 0x2F00
W 0x1177 0x1157 0x1117 0x1100
X 0x2D78 0x2D58 0x2D18 0x2D00
Y 0x1579 0x1559 0x1519 0x1500
Z 0x2C7A 0x2C5A 0x2C1A 0x2C00
, 0x332C 0x333C -- --
. 0x342E 0x343E -- --
/ 0x352F 0x353F -- --
; 0x273B 0x273A -- --
' 0x2827 0x2822 -- --
[ 0x1A5B 0x1A7B 0x1A1B --
] 0x1B5D 0x1B7D 0x1B1D --
` 0x2960 0x297E -- --
- 0x0C2D 0x0C5F 0x0C1F 0x8200
= 0x0D3D 0x0D2B -- 0x8300
\ 0x2B5C 0x2B7C 0x2B1C --
F1 0x3B00 0x5400 0x5E00 0x6800
F2 0x3C00 0x5500 0x5F00 0x6900
F3 0x3D00 0x5600 0x6000 0x6A00
F4 0x3E00 0x5700 0x6100 0x6B00
F5 0x3F00 0x5800 0x6200 0x6C00
F6 0x4000 0x5900 0x6300 0x6D00
F7 0x4100 0x5A00 0x6400 0x6E00
F8 0x4200 0x5B00 0x6500 0x6F00
F9 0x4300 0x5C00 0x6600 0x7000
F10 0x4400 0x5D00 0x6700 0x7100
0x1C0D 0x1C0D 0x1C0A --
0x5200 0x5230 -- --
0x5300 0x532E -- --
0x011B 0x011B 0x011B --
0x4700 0x4737 0x7700 --
0x4F00 0x4F31 0x7500 --
0x4900 0x4939 0x8400 --
0x5100 0x5133 0x7600 --
0x0F09 0x0F00 -- --
0x0E08 0x0E08 0x0E7F --
0x4B00 0x4B34 0x7300 --
0x4D00 0x4D36 0x7400 --
0x4800 0x4838 -- --
0x5000 0x5032 -- --
-- 0x4C35 -- --
0x372A -- 0x7200 --
0x4A2D 0x4A2D -- --
0x4E2B 0x4E2B -- --
0x3F2F 0x3F2F -- --

Note: '--' signifies that the key can not be read

Example:

None provided, as use is self explanatory.


-- Page 186 --




Light Speed
High Speed Graphics Programming


Function Name:

reset_keyboard

Purpose:

Reset the keyboard.

Calling Protocol:

void reset_keyboard(void)

Description:

This function can be used to reset the keyboard, if it becomes locked
under any circumstances. This could be called once in every program, so
that at the start of the program the keyboard is garaunteed to be in a
stable state.

Example:

No example provided



































-- Page 187 --




Light Speed
High Speed Graphics Programming


Appendix A - Registering your own user fonts
--------------------------------------------

The structure of the font file is simple:

The first byte contains the height of the font
The rest of the file contains the font data, for characters
32 to 127.

As of this release, only fonts that are eight pixels wide (byte
sized) are supported. This is inbuilt in the printing routine, and also
means that your font file data must be eight bytes wide.

To set up your font file, use whatever means necessary to draw all
of the chracters, and generate some form of text output. The program I
used to collect the font data returned the output in binary, and
because of this, the font conversion program also expects binary input.

To be more clear, the font file took the following form (the
computer font is being used as an example):

00000000
00000000
00000000
00000000
00000000
00000000
00000000
00000000
00000000
00000000
00000000
00000000
00000000
00000000 _______
00000000
00000000
00001000
00001000
00001000
00001000
00001100
00001100
00000000
00001100
00001100
00000000
00000000
00000000 _______
00000000
00000000
00110011
00110011
00100010
00100010


-- Page 188 --




Light Speed
High Speed Graphics Programming


00000000
00000000
00000000
00000000
00000000
00000000
00000000
00000000 _______

The underline marks were not part of the file, they are there to
show the seperation between the characters. Each character was 14
pixels high (the height can be varied). Only the first three characters
of the font are shown (the values 32, 33 and 34), whereas the actual
font file has all of the characters from 32 to 127.

After the font file is set up, you must run it through the font
formatting program, FONTCONV. The conversion program will prompt you
for several details:

Input filename: the name of the binary font data
Output filename: filename for C font output
Font name: name for the font
Font identifier: C font identifier, see below
Character height: height of the characters

Most of the prompts are self explanatory, however you must be
careful when specifying the font identifier. This is the C variable
that will be used to access the font data. For example, the identifier
used for the computer font, was ls_computerfontdata. You should select
an identifer that is similarly structured. This lessens the chance that
the font identifer might cancel out a program variable.

After the conversion, you will have a C file structured similar to
this (for computer font):

/* Light Speed Graphics Library Font Driver File
Font: Computer_Text */

unsigned char ls_computerfontdata[] = {
0x0E, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x08, 0x08, 0x08, 0x08, 0x0C,
: : : : : : : : : : : : : : : :
0x04, 0x08, 0x08, 0x08, 0x30, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x30, 0x49, 0x06, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 };

The first value is the font height, the rest of the file is the
converted font data.

Once you have set produced the correct font file, you can compile
it as any standard C module. You should do this, and either add the
file to the library (not suggested), or add the file to your project
file (or make file).





-- Page 189 --




Light Speed
High Speed Graphics Programming


To actually link the font into your program, you need to follow
these steps:

(1) In the data section of your program, you must set up an
identifier that will be used to reference the font information. The
form is (computer font, again): char far *ls_computerfont;
(2) Set the pointer equal to the data structer:
ls_computerfont=ls_computerfontdata; This operation is exactly
the same as a call to the registerXXXfont functions.
(3) You can write your own character and/or string print
functions, using the reference to the far pointer. This far pointer can
be passed straight through to the generic character output
function, ega_writechar (see that function for more details).
This is essentially what has been done for the ega_XXXch
functions.


One final note:
---------------

Registering your own user fonts is quite simple, if you follow the
steps above (they are the exact steps I took when coding the functions
in the first place, except most of it was in Assembly language).

However - the concept of user fonts is not fully supported in this
release. That is why you must write your own text output routines to
support the new font. I aplopgize for any problems this may cause - but
as of the next release, there will be support for registering in your
own iuser fonts in a much simpler form, and NO re-writing of the output
functions.

If you do have a font that you are trying to add to the library,
and have taken the steps above and cannot get the functions to work
properly, the please contact me - I will be glad to help. I am also
looking for a lot more fonts for the library, so please let me know of
any fonts that you have drawn, and/or successfully converted into the
Light Speed format (if your font is used in a Light Speed release, full
credit will be given).



















-- Page 190 --




Light Speed
High Speed Graphics Programming


Appendix B - Light Speed Colours
--------------------------------

The following colour declarations are drawn straight from the
Light Speed header file, "lspeed.h":

Colour Declaration Value
--------------------------------------------
Black LS_BLACK 0
Blue LS_BLUE 1
Green LS_GREEN 2
Cyan LS_CYAN 3
Red LS_RED 4
Magenta LS_MAGENTA 5
Brown LS_BROWN 6
Light Grey LS_LGREY 7
Light Gray LS_LGRAY 7
Dark Grey LS_DGREY 8
Dark Gray LS_DGRAY 8
Light Blue LS_LBLUE 9
Light Green LS_LGREEN 10
Light Cyan LS_LCYAN 11
Light Red LS_LRED 12
Light Magenta LS_LMAGENTA 13
Yellow LS_YELLOW 14
White LS_WHITE 15

Note the two spellings of the grey/gray fonts, and the generic use
of the word colour: Australian spelling uses grey and colour, American
spelling is gray and color. Fortunately, there are no specific
references to the word colour in the header file (other than as
arguments), so usage was kept uniform.

However, grey/gray has been catered for in both spellings, so that
use of the textual descriptions is easier in any country.






















-- Page 191 --




Light Speed
High Speed Graphics Programming


Appendix C - External Programs
------------------------------

Apart from the Light Speed demo programs, there are some extra
executables that form part of the package.

(1) Font conversion program: FONTCONV

See description in Appendix A. This program is only used if you
are linking in your own user fonts.

(2) Mouse pointer design: PTRDES

The mouse pointer design program is included to help you in
designing your own mouse pointers, for calls to set_mouse_pointer.
This is similar to the program I used in designing the pointers
already included in the library.

Usage of the program is simple: Use the arrow keys to move around
the editing field. To set a pixel, the keys 1 to 4 can be used:

1 - set picel to background
2 - set pixel to XOR mode
3 - set pixel to black
4 - set pixel to white

The square box up in the top right corner shows the new pointer as
you are drawing it, with the number you set corresponding to the
colour shown here:

1 - Black
2 - Magenta
3 - Green
4 - White

To save the data to a file, press the key. The file
created is called "pointer.mou", and contains the following
structure:

--------------------------------------------------------------------

Screen mask codes:

0x0000 0x3FFC 0x5FFA 0x6FF6 0x77EE 0x7BDE 0x7DBE 0x7E7E
0x7E7E 0x7DBE 0x7BDE 0x77EE 0x6FF6 0x5FFA 0x3FFC 0x0000

Cursor mask codes:

0xFFFF 0xC003 0xA005 0x9009 0x8811 0x8421 0x8241 0x8181
0x8181 0x8241 0x8421 0x8811 0x9009 0xA005 0xC003 0xFFFF

--------------------------------------------------------------------





-- Page 192 --




Light Speed
High Speed Graphics Programming


The format can then be converted to C data via a simple macro in
any text editor. There is no provision for hotspots in the save
file - you can include them when you call the set_mouse_pointer
function.

The last keyboard commands available are 'C' and . Pressing
'C' will clear the screen, and you can start drawing the pointer
from scratch. Pressing will exit you back to DOS.

You can use any of the keypad direction keys to move the cursor,
and the cursor will wrap around at the edges of the display. The
only errors the program will generate are when there is a problem
creating the pointer output file.

This program will be revised for the next release - the pointer
system is being re-designed to allow for colours in the pointer,
and therefore you will be able to design in full colour.

(3) Screen grabbing program: EGAGRAB

The screen grabbing program can be used to capture screen shots
from almost any graphics program, and save them for inclusion into
your own programs, or for later area editing with EGAPROC.

To install the screen grabber, type 'EGAPROC ' at the
command line. Do not repeatedly install the program, as the TSR
logic does check for re-installation. Once installed, the program
will return you to DOS with the message that the program has been
installed.

If there are any problems with installtion, the errors will be
reported back and the program will not install. There are two
possible errors - DOS version before v2.0 or a a failure to hook
the keyboard interrupt. If any other unusual event occurs, then
the program will report that there was an untracable error.

To use the program, load up your graphics program (whether it is a
game, CAD program, or just a drawing program) that you need to
capture the screen from. Once the correct screen is set, press one
of the keys, and the key, and the screen will
be saved to disk.

The routine in the screen grabber does not use any of the Light
Speed save routines, but uses the BIOS instead. this is for safety
reasons, as any non-standard calls will probably crash the
computer. Therefore, the time taken to save a screen is longer
than the Light Speed routines use.

The grabber is mode independent - therefore, the correct screen
size parameters will be used for each of the three supported
modes. The modes are 320x200x26, 640x200x26, and 640x350x16. The
approximate time taken to save the file, and the size of the file
produced are in the following chart.




-- Page 193 --




Light Speed
High Speed Graphics Programming


Mode File Size Time Taken

320x200 64,000 bytes 18 seconds
640x200 128,000 bytes 34 seconds
640x350 224,000 bytes 47 seconds

The format of the save file is directly compatible with the full
screen loading function, ega_restore_screen_byte. See tahat
function for a more complete description of the file format.

The files are saved under the name GRABXXXX.SCR, with the XXXX
representing a four digit number, padded with 0's. Therefore, the
first picture you save will by GRAB0001.SCR, the second will be
GRAB0002.SCR, and so on.

You only need to install the screen grabber once, and if you
change mode during the operation of saveing several screens, the
change will be transparent to the grabber, and the correct
file size used on each save..

(4) Full screen to area screen processor: EGAPROC

This program shows how easy it use to program using the Light
Speed library, as it was created in just under 25 minutes.

The purpose of this program is to enable you to edit your full
screen save files into smaller portions, for use by the
ega_restore_area_byte function. This saves the need for loading in
a full screen image if you only need a small portion for the
program.

To use EGAPROC, you must specify the file names you are going to
use on the command line. First, you must specify the name of the
file that contains the full screen image, and the secnond
parameter is the name of the output file. There is no feature to
change this when the program is running, unfortunately.

An example command line: 'EGAPROC grab003.scr small.img '
would start the program with the file 'grab003.scr' being use for
the full screen, and the file 'small.img' used as the save file
for the newly edited portion.

The program will check the size of the full screen file, and set
the mode accordingly. If the file size is an unkwown number, the
program will return to DOS with an appropriate message.

The program is controlled mostly via the mouse - there are only
two keys used: the key which will return you to DOS, and
to save the image.








-- Page 194 --




Light Speed
High Speed Graphics Programming


To select your new area, wait for the screen to be loaded, and
then you will be presented with the mouse pointer. You can then
press the left button to start the marking area. Move to the end
of the area you wish to select, and press the left button again to
form a box around the area. For fine tuning, you can edit the box
by holding down the button and moving the mouse around the screen.

Once the area is correct, you can press the key to save
it. The save file is the second argument on the command line. The
screen will flip to the blank page, and report to you the
dimensions of the screen. You must make a note of these numbers
when wish to load the screen using the ega_restore_area_byte
function.

Once the save has finished, and you have written down the correct
variables, you can press a key to return to the full screen
picture. You can do one of two things now - return to DOS by
pressing , or re-save a new area over the top of the last one
if it was incorrect.

This program is written to use the Light Speed screen and area
save/load functions, so operatess much faster than the TSR screen
grabber.


































-- Page 195 --




  3 Responses to “Category : C Source Code
Archive   : LSPD05-2.ZIP
Filename : LSPEED.REF

  1. Very nice! Thank you for this wonderful archive. I wonder why I found it only now. Long live the BBS file archives!

  2. This is so awesome! 😀 I’d be cool if you could download an entire archive of this at once, though.

  3. But one thing that puzzles me is the “mtswslnkmcjklsdlsbdmMICROSOFT” string. There is an article about it here. It is definitely worth a read: http://www.os2museum.com/wp/mtswslnk/