internal.txt

This is part of the flight simulator 'fly8'.
Author: Eyal Lebedinsky (eyal@ise.canberra.edu.au).


Modules
=======


portable
--------

ALTITUDE.C	display HUD altitude
AUTOP.C		Auto pilot simulator
BODY.C		bodies mgmt
COCKPIT.C	draw instruments
COLORS.C	color mgmt
COMMAND.C	process user commands
DEBUG.C		debug support functions
DEVICE.C	graphics devices mgmt
FLY8.C		main program
GETSTR.C	accept user input with editing and history
HEADING.C	display HUD heading
HUD.C		head-up-display painter: graphics
HUDMENU.C	hud setup menus
IFUNCS.C	integer trig functions
ILS.C		display and manage the ILS system
INFO.C		screen text display
INIT.C		program initialization
ITABS.C         integer trig tables (generated by ifuncs.c)
KEYBOARD.C      keyboard devices mgmt
KEYPAD.C
LAND.C          algorithmic landscape
LOG.C		print to log
LOOP.C		the main busy-loop of the simulation and display
MACROS.C        handle keyboard macros
MAT.C		3D matrix handling
MEMORY.C	memory mgmt
MENU.C		menu interaction support
MENUS.C		menus used by the system
MESSAGE.C	handle display messages queue.
NETPORT.C	network access mgr (mid level)
OBASIC.C	object: plane - cross between Classic and F16.
OBJECT.C	'object' data structure mgmt
OBJECTS.C	3D objects mgmt
OBOX.C		object: box
OBROKEN.C	object: fragment
OCHUTE.C	object: ejecting pilot
OCLASSIC.C	object: plane - a wild spaceship.
OCRATER.C	object: bomb crater
OGROUND.C	object: ground (land)
OGTARGET.C	object: ground target
OHOUSE.C	object: house (land)
OLOW.C		object: low level ground (crash alert)
OM61.C		object: M61 bullet.
OMK82.C		object: MK82 bomb
OPADDOC.C	object: paddoc (land)
OPLANE.C	object: plane
ORUNWAY.C	object: runway (land)
OSMOKE.C	object: smoke particle
OTARGET.C	object: target
OTOWER.C	object: control tower
OVIEWER.C	object: viewer
OXPLANE.C	object: experimental plane
PID.C		automatic control logic
PIPER.C		display HUD radar piper
PITCH.C		display HUD pitch ladder
PLAYER.C	remote players maintenance
POINTER.C	pointing devices mgmt
RADAR.C		display HUD radar info
RANDOM.C	random pointing device emulator
REMOTE.C	remote comms interface (high level)
SHOW.C		3D graphics wire-frame routines
SKY.C		algorithmic sky painting
SOUND.C		sound devices mgmt
SPEED.C		display HUD speed
STFONT1.C	stroke font (square, fast, cold)
STFONT2.C	stroke font (round, slow, nice)
STROKE.C	stroke character generator used in HUD
SYSTEM.C	system-wide functions
TERM.C		program termination
TUNES.C		tunes used for sound
UTIL.C		misc functions
VIEWS.C		render ann views (cockpit, HUD and all HDD)
VMODES.C	read in the fly.vmd file
WINDOW.C	windows and screen sizing functions


Headers
-------

COLORS.H	color definitions
FLY.H		the main header
HUD.H		header for HUD modules
NOTES.H		used to define sounds (notes and tunes)
KEYOFD.H	--"--
KEYOFC.H	--"--
KEYDEF.H	key definitions (internal to fly8)
KEYMAP.H	key mapping to fly8 functions
		in the future this may be replaced with externaly defined
		key mapping.
PLANE.H		plane related stuff


MSDOS
-----

CONFIG.H	non portable definitions

DRIVERS.C	lists all drivers, but otherwise portable.
KEYPAD.C	the keyboard as a pointing device (portable code except you
		may re-assign keys).
CONSOLE.C	low level PC keyboard access
GRQC.C		graphics device driver (using QuickC graphics)
GRT4K.C		graphics device driver (using low-level tseng4k access)
MOUSE.C		the mouse as a pointing device
PACKET.C	low level packet net driver (ethernet packet level)
PCDOS.C		miscelanious system functions (pcdos)
PCSERIAL.C	low level serial net driver
SLIP.C		low level packet net driver (SLIP protocol)
SPEAKER.C	PC speaker sound ouput driver
STICK.C		the joystick as a pointing device
TIMER.C		timer functions
GETTIMER.C	stanalone pgm to read the timer chip channel 0
SETTIMER.C	stanalone pgm to set the timer chip channel 0 to mode 3

MSUBS.ASM	fast fixed point math, replaces some C functions.

MAKQC.TOP	makefile for portable files (QuickC)
MAKQC		makefile for msdos files (QuickC)
MAKC7.TOP	makefile for portable files (C7)
MAKC7		makefile for msdos files (C7)

FLY.INI		configuration file
FLY.BAT		short batch file for running fly8
GRQC.VMD	graphics modes for grqc.c
GRT4K.VMD	graphics modes for grt4k.c


UNIX/X11
--------

CONFIG.H	as above

CONSOLE.C	as above
DRIVERS.C	as above
MISC.C		as above
MOUSE.C		as above
UNIX.C		system services for UNIX
NOSOUND.C	dummy sound driver.
TIMER.C		as above
GRX.C		graphics driver using X11

MAKEFILE.TOP	as above
MAKEFILE	as above

FLY.INI		as above
FLY		short script for running fly8
GRX.VMD		graphics modes


External support
----------------

Interrupt driven, buffered serial line support library (com.lib).

Standard graphics (microsoft C library).
Fast 256 color VGA graphics (gr.lib).

Packet driver C interface (pktdrvr.lib).

Input line editing routine (util.lib).
High resolution timer support (util.lib).


Other files
-----------

FLY.INI		parameters file (read)
FLY.LOG		log file (write)
FLY.MAC		keyboard macros save file (read/write)


Porting
=======

A minimal set of drivers will include:

DRIVERS.C	adjusted lists

CONSOLE.C	low level non-blocking keyboard access
GRxxx.C		graphics device driver
KEYPAD.C	the keyboard as a pointing device
OpSys.C		miscelanious system functions
NoSound.C	dummy sound driver
TIMER.C		timer functions


Program structure
=================

main() is in fly8.c. After setting everything up (mainly initialize()) it
calls user_command() [in command.c] which talks to the user. Whenever
the program is in a busy wait it calls Sys->Poll() which calls idle_loop().
This last one [in fly8.c] decides if it is time to show another frame and
does so. It also drives the simulation program.

The program should have NO HARD WAITS!!!! The keyboard driver MUST do the poll
when waiting for a keystroke.

Sys->Poll(int mode) has two modes:
	0 poll all low level devices but do not call idle_loop()
	1 do everything.
This is to allow the main body of the simulation/rendering to call Sys->Poll()
to enable sound etc. that needs constant polling.


 An important issue is the separation of function between the different
program layers. All objects have a 'native' world which is termed here a
'player'. There is the one 'native' player and many remote players. A
player is identified by the pair (int netport, char address[]) which are
treated as a black box. The remote player handler (remote.c) exchanges
messages with remote users through a netport which is managed separately
(netport.c). The messages are moved as packets. The same packets are
then handed over to the network drivers (each enviroment had different
ones) which does NOT have any understanding of the contents. A netport
is directly related to a network access point (usually some hardware
device) and the program can handle nore than one of these concurrently.
While the low level programs (netport.c and net drivers) know nothing
about fly8, remote.c knows a lot about it and knows how to talk to the
netports but cannot control the net directly.

 During the design of the program (i.e when looking back at the blind
at-the-keyboard programming sessions) various functions had to be placed
at the prefered level - not always clear were that is. For example, the
program can collect multiple logical packets and hande then to the
network as one large real packet. The mechanizm for that ended up at the
netport level. It could as easily have been left to each driver to do it
when appropriate, or it could have been pushed up to the remote handler
(who originally build all packets) to take care of that.

 One day the large header (fly8.h) will be split to reflect this
layering and enforce more structure on the whole system. One day.


e_plane.misc[20] allocation
---------------------------

  0	LIFETIME(p)	autopilot: millisecs to next randomization
  1	SPEED(p)	autopilot: desired speed
  2	HEADING(p)	autopilot: desired heading
  3	ALTITUDE(p)	autopilot: desired altitude
  4	NEWTGT(p)	time left for new target notice
  5			Cm
  6			high res R[Z] when on-ground
  7			...
  8			pull up time
  9			millisec life of water-line marker
 10			autop: command speed.
 11			bombs in flight counter.
 12			autop: command pitch
 13			autop: command roll
 14			ILS glide path deviation
 15			ILS localizer deviation
 16			pullup cue relative angle
 17			pullup cue time

e_plane.opt[10] usage
---------------------

  0 [0-2]	flight model: 0=basic, 1=classic, 2=xplane, 3=yplane.
  1 [1-9]	controls response (damping factor)
  2 [01]	use linear controls (all)
  3 [1-9]	turning speed (classic only)


e_imported.misc[5] allocation
------------------------------


object.misc[5] allocation
--------------------------

 0	bullet count for non ET_PLANE objects (imported planes).
 0	viewer type for O_VIEWER (local).


st.misc[20] allocation
----------------------

  0	last elapsed time
  1	last video_time
  2	last stats[27]
  3	last stats[28]
  4	last stats[29]
  5	last stats[40]
  6	plane dynamics minimum interval
  7	sega glasses port [0 means none]
  8	buttons mode.
  9	flush log rate


st.stats[100] allocation
------------------------

alloc	used	for
-----	----	---
 0- 9	    comms
	 0	bytes sent
	 1	packets sent (physical)
	 2	bytes rcvd
	 3	packets rcvd (physical)
	 4	rcvd bad packet: crc & player OK but not collected by any
		object (player.c) [but player playing].
	 5	rcvd bad packet: driver internal
	 6	rcvd bad packet: bad crc
	 7	rcvd bad packet: player unknown (if short of mem?)
	 8	send packet failed: sync (driver level)
	 9	send packet failed: async (driver level)
10-19	    graphics
	10	out->out (clipper)
	11	in->in (clipper)
	12	in->out/out->in (clipper)
	13	hard: out (clipper)
	14	hard: fail (clipper)
	15	hard: in (clipper)
	16	lines processed (per frame)
	17	-
	18	coms: low level soft send failure.
	19	millis to next autoconnect
20-29	    misc
	20	com test count, input [pcserial.c]
	21	com test max
	22	com test total
	23-25	same, for output
	26	elements in display list
	27	time for objects display calcs (NOT video)
	28	time for objects simulation
	29	sync time
30-39	    video totals
	30	bg/fb time (hud, test, sky etc.)
	31	number of frames
	32	total frames time
	33	total video time
	34	total [27] time
	35	total [28] time
	36	total [29] time
	37	total [30] time
	38	-
	39	-

30-39	    memory, misc
	40	debug.c error count
	41	log last write time
	42	-
	43	-
	44	-
	45	memory bytes max used
	46	memory bytes alloced
	47	memory bytes now used
	48	memory shortage (failed)
	49	memory shortage (total)

50-59	    coms
	50	recovered lost objects
	51	objects timed out
	52	bad packages received
	53	rcvd packages
	54	sent packages
	55	rcvd noise packets from non-players
	56	rcvd out of order packet
	57	-
	58	-
	59	-

60-69	    graphics debug
	60	x < 0	(Move)
	61	x > width	(Move)
	62	y < 0	(Move)
	63	y > height	(Move)
	64	x < 0	(Draw)
	65	x > width	(Draw)
	66	y < 0	(Draw)
	67	y > height	(Draw)
	68	line draw bad op
	69	-

70-79	    misc
	70-76	running total of 10-16
	77
	78	total MoveTo executed.
	79	total DrawTo executed.

80-89	    temp counters

90-99	    temp counters


st.flags GP* usage
------------------

DF_GPW		activate model Y instead of F.
DF_GPX		show HUD graph
DF_GPY		model F: fundamental=no-pitch, or linearized=do-pitch.
DF_GPZ		model F: set FUNDAMENTAL mode



pointer.a[4] usage
------------------

Analog functions are:
	 0 right/left turn
	 1 up/down turn


pointer.b[30] usage
-------------------

logical functions are:
	 0   power up
	 1   power down
	 2   level (fly straight north)
	 3   return to origin (x,y,z=0)
	 4   stop (speed=0)
	 5   fire
	 6   rudder left/right
	 7   rudder center
	 8   stable (stop turning)
	 9   ...
	10/a flaps
	11/b spoilers
	12/c reset roll
	13/d air brakes
	14/e wheel brakes
	15/f gear
	16/g power 100
	17/h after burner up
	18/i release lock
	19/j wheel brakes (fine control)
	20/k air brakes (fine control)
	21/l trim right/left
	22/m trim down/up
	23/n trim reset


pointer.opt[10] usage
---------------------

  1  [pn]	set x coord direction
  2  [0-3]	set x coord function
  3  [pn]	set y coord direction
  4  [0-3]	set y coord function
  5  [0-9]	set left button function
  6  [0-3]	set right button function
  7  [0-9]	set x coord sensitivity (mouse only)
  8  [0-9]	set y coord sensitivity (mouse only)
  9  [01]	read twice (joystick only)


Asyncronous events
------------------

The only current such events are network traffic arrival. The two packet
drivers slip.c and packet.c work in this way. pcserial.c expects characters
to be delivered-to/retrieved-from routines in the serial library.

NEW() DEL() [memory.c] and deliver_packet() [netport.c] may be called 
from interrupt routines and are protected by Disable/Enable. The
structures manipulated in this way are:

	memory allocation.
	netport incoming packets queue.

-------------------------------------------------------------------------------
example of a dummy netport driver:
==================================

static int far
com_init (NETPORT *np, char *options)
/* Initialize netport 'np' with user options 'options'. 'options' is the
 * unparsed string that the used supplied and is a list of options separated
 * by colons. Use the get_?arg() functions to retrieve the options.
*/
{
	return (1);	/* always fail */
}

static void far
com_term (NETPORT *np)
/* Terminate netport 'np'.
*/
{
	return;
}

static int far
com_send (NETPORT *np, PACKET *pack)
/* Send packet 'pack' to netport 'np'.
 * If 'pack' is zero then this is an indication that this is the last packet
 * so drivers that send multiple packets in one message will send what they
 * have.
*/
{
	return (1);	/* always fail */
}

static int far
com_receive (NETPORT *np)
/* Receive all packets from netport 'np'. Used only by drivers that do polled
 * receiving.
*/
{
	return (1);	/* always fail */
}

extern struct NetDriver NetDummy = {
	"Dummy",
	0,
	com_init,
	com_term,
	com_send,
	com_receive
};
-------------------------------------------------------------------------------
