* Head Up Display Filter - Version 2.5
* Intel Plugin for Lightwave 3D 5.0 and 5.5
* Code and Design (C) Copyright 1998 by Kevin Phillips,
                                        T42 Creative Designs

Introduction:
-------------
This plugin allows the user to create and overlay a head-up display style image, complete with artificial horizon, and plenty of new animated features!


Updates :
---------
The latest update to the HUD plugin now allows you to save and load HUD file independant of Lightwave...  What this means is that users now have a way to store HUD designs rather then saving them with the scene file!  Nows the chance to build your own library of designs!

Also added is the ability to force the HUD to save to the Alpha channel - This makes building HUDS for compositing easy!

An extra feature to autoscale the HUD to your render size is also included!  This way, even resolution-dependant designs will rescale to new resolutions!

There's a lot of work involved here - Lots of experimenting and spare time have been thrown into this plugin - I'm simply releasing this plugin for people to play with - If you find it useful, let me know! ;-)


Installing the Plugin:
----------------------
Installing the plugin is a piece of cake!  Simply select the OPTIONS button at the top of the screen, and click on the button ADD PLUGIN.

Find and select the file VHUD25.P and click OK.  Lightwave should tell you that 2 plugins were successfully installed.

Load up your animation scene.

Select the EFFECTS button, then the IMAGE PROCESSING Tab.  In the Image Filter selection list, look for the filter name T42_HUDBETA and select it.  (Note that the plugin button will display "T42 HUD v2.5")



Setting up the Plugin:
----------------------
Click on the OPTIONS button next to the plugin to set up the parameters for the plugin.  This plugin just displays a user-designed image built from a set of primitive items.  Note that most these items are based on a Absolute coordinate system (ie. 0,0 is the top left pixel) so all HUD design must take into consideration the size of the final render...

The Panel that is first displayed contains all the settings and buttons.  Each function operates as follows:

Pixel Expand:	A single pixel (1x1) may not appear large enough on screen for high
		resolutions.  Instead you may select an 'expansion' setting...
		This simply draws a larger border *around* the pixel. Note that the
		coordinates will still draw as normal - Just the pixels will appear
		'thicker'

		This setting only applies to:
		Lines, Boxes, Circles, Crosses and Horizons.

Digit Size:	For future use, but works in conjunction with the 'coords' animated item.
		There is one basic font - This allows it to be displayed in 3 sizes.



Static Items:
-------------

These are the basic drawing items for your HUD design.  You can set up to 4 of each by simply clicking on the item button.  This will display another	panel containing all the details you need to set:

		RGB:		Only 1 colour for all 4 items, though each item group can
				be different if you wish.

		Item #:		This button activates/deactivates the item.

		Parameters:	Each item has a set of parameters:

				Lines:		Draw from SX,SY to EX,EY
				Boxes:		Top-left X,Y, height and width
				Circles:	Centre X,Y and Radius
				Crosses:	Centre X,Y, Height and Width
				Tboxes:		As for box, but with a Transparency setting
						(Produces a 'seethru' rectangular area)


Animated Items:	
----------------

There are now 4 animatable effects available in the HUD.  They are somewhat more complex looking then the 5 static items, and operate as follows:


Blinkers:
---------
A blinker is simply a coloured square that 'blinks' at a set rate.  The parameters on the panel are as follows:

		Blink		Activate/deactivate the blinker
		X,Y 		Top left corner of blinker
		S		Size of the sides of the square.
		Blink Rate	indicates how many frames on and off...


Meters:
-------
A Meter is a bar that moves by being controlled by an object in the scene.  There are 3 of these available, and all work on the scale of the controlling object.

		Meter		Activate/Deactivate the Meter
		X,Y		Coordinates of a corner of the bar... Explained shortly!
		M		Max length of the bar in pixels
		T		Thickness (width) of the bar in pixels
		D		Direction of bar - H(orizontal) or V(ertical)

				If H, then x&y are top-left coordinates, and the bar
				is drawn to the right...

				If V, then x&y are the bottom-left coordinates, and the bar
				is drawn up...

		RGB		The colour of the Meter bar

		Control		Control object
		Axis		The axis that will control the bar...
		Divide		If you are using scales larger then 1.0, use this to
				scale the value down (ie. using scale of 10.0, divide = 10!)


Radar:
------
A swirling line with trail is animated to fake a 'radar' sweep effect.  Also available is the ability to 'scan' for 8 objects in the scene, just to add some 'functionaliy' to the whole thing!

For now, the parameters are:

		Activate	Activate/deactivate Radar effect
		CX, CY		Centre of the radar display
		R		Radius of the radar
		SA		Step Angle - Each frame, rotate the radar by this many
				degrees
		TL		Tail length... Leaves a nice tail behind the sweep line.
				(in degrees = 90 = quarter of a circle)
		RGB		Colour of the Radar sweep/detected dots
		Scan Axis	What pair of Axis relate to the X/Y in the radar sweep.
				These are the coordinate axis of the scannable objects
		Scan Range	Divide the objects coordinates by this value to extend the
				'scannable' range of the radar
		Scan Objects	Up to 8 objects can be scanned and displayed as dots in the
				circular radar area.  Select them here...
		Dot Size	How large (in pixels) to draw the detected objects 'dot'

Note that all scanning is in Units (ie. Metres) and the range is the radius, using the camera's position as the centre of the radar area... If you want to extend the range to a larger area (ie. Such as double the radius value), simple enter 2.0 into the scan range.  To halve the range, use 0.5!


Coordinates:
------------
Allow the X,Y & Z coordinates to be displayed for a control object.  The coordinates are based on the Unit value (ie. if metres, then will display the values in meters)

		Control 	The object that the coordinates will track
		Divide 		If the counters are too fast or too slow, you can use
				this value to scale the values...
		Decimal Places	Format the Coordinates as 4,6 or 8 characters
		RGB		Colour of the coordinates

		Activate,x,y	Allow each axis to be displayed at a differing location...

		


Horizon Control:
----------------
A rocking-horizon effect can be created by selecting a control object.

Control Object:		If there is (none) control object selected, there will be no Horizon 
			drawn.	Note that the angle of the horizon works on the bank angle of the 
			control	object - It also rotates opposite direction (if looking from 
			behind) sorta like the real thing!

			The horizon in this release of the plugin is always drawn around the 
			centre of the screen and always in solid white.

Horizon Type:		You can select the shape of the horizon. There are 5 avaliable:

			* Line		Horizontal Line
			* Cross		Solid Cross Shape
			* Hairs		Cross-hairs
			* Diamond	Diamond Shape
			* Halfbox	Box with lines missing at the top and bottom...
					Sorta like an F16 type display. (I did say 'sorta'!) ;-)

Horizon Size:		You can set the height and width of the horizon.



Save & Load HUD buttons:
------------------------
You can now save and load HUD files to disk from Lightwave.  This means that the ability to build a library of favourite designs is closer to hand!

(Note that the HUD data **is** still saved in the scene file)


***************
*MEGA-WARNING!*
***************

Saving HUDs will work, but *will* need 'massaging' when reloaded, especially if control objects were utilised for Horizons, Meters and other animated items...  These will *not* map back to a new scene file - You *will* need to assign new items to the controls.

If you try to render a scene using a HUD loaded from disk, you are asking for a crash!  My advice is to save the HUD with the scene file... This ensures that all control objects align with the HUD settings!



HUD to Alpha button:
--------------------
This button forces the HUD display to be added to the Alpha channel for compositing later on.  The Alpha is always 100% - So transparent boxes won't be 'transparent' if used in compositing.



Resize Setting:
---------------
This control allows you to select a base size for the HUD you have defined... This setting will be used to scale the HUD for different render sizes - You no longer need to define the HUD based on a render size...

Note that base render sizes are based on the default sizes provided by Lightwave.


There are some *exceptions* to scaling:
---------------------------------------

* Text - The font size is not altered.
* Circles are always circular - They don't become elliptical if resolution changes.
* Meters are altered, but not the Max value that the Meter may have.
* Pixel Size is NOT altered, neither is the DOT size of the Radar 'objects'.


Bugs & Future Enhancements:
---------------------------
This section simply overviews a few minor bugs in the plugin.  Most are easily fixable, but for now just be aware that they are there:

* Rescaling has not been 100% tested so *may* (will?) have bugs.
* There are NO range checks - Never use a 0 value in height/width/radius settings...
  Lightwave *WILL* crash if you use a 0!
* Pixel Expand draws a border around the pixels. If you use it then be aware that there
  will be an edge added to your lines/circles/boxes/horizon/crosses... If they
  were drawn on the edge of the screen, they will appear to go outside it.
  Horizon corners may look strange at time because the pixels are square and not rotated.
* Items are drawn *over* each other.  Unless you use the same colour for your HUD, you may
  get some wierd effects... The order of drawing is as follows:

	Tboxes
	Horizon
	Circle
	Box
	Line
	Cross
	Blinker
	Radar(Sweep then dots)
	Meters
	Coordinates


Future Enhancements I've been looking at include:

	* Global Transparency value (To allow 'see through' HUD's):
	  This was already there, but unfortunately, lines that cross caused an
	  Additive effect and got solid corners, etc!  I've made it Solid for now!
	  Also had an idea to allow a user to control the transparency with an object.

	* Enhanced Horizon:
		* Ability to set centre coordinates for Horizon, rather then screen centre
		* Pitch/heading items as well as the banking effect
		* More Horizon Shapes (Maybe allow to design using 8 lines?)

	* Lock-on objects:
		* Select 4 control items to 'lock on' to...
		* 4 different 'Lock on' shapes, with time setting before lockon
		
	* More animated items (4 of each):
		* Pulsers - Items like pulsing squares/circles (Grow/shrink with trails)
		* Bouncers- Lines that bounce back/forth/up/down with a trail behind...
				(Like the light on the front of the KITT car in Knight Rider!)
		* SineWave- With/without a box around it!
		* Random  - Random Binary/Ascii/Z80 opcodes scrolling box display!
		* Typer   - Read a text file and 'type' it onto the screen.


Disclaimer:
-----------
vhud25.p is a freeware plugin.  Freeware implies that you may use this plugin freely for personal use, but ownership and copyright of the plugin remains that of the Author.  You are granted unlimited use for personal work by the Author.  If you plan to use this plugin for Commercial work, please ensure that you credit the Author somewhere in the work for which the plugin is being used.

This plugin has been fully tested with Lightwave 3D 5.5 and should work with Version 5.0 as well, though please be aware that you may not hold the Author responsible for any error, damage or monetary loss caused by the use of this software.

                         *** You use this plugin at your own risk ***