
	Writing a Video Window Program.

A file "Xvid.c" has been written to serve as an extension to Xlib.  This
file should be compiled in with any programs which expect to control video.

A Video Window is defined as a window within X that allows video to exist
within it.  Video windows have restrictions and rules beyond those for
normal X windows.  Only one video window may exist at a time.

A Video Region is a subset of a video window, this pertains to the
area within a Video Window which contains Video data.

On the Parallax 1280, video is encoded and bypasses the color lookup-tables.
Thus the full lookup table is available for graphics.  Graphics within
a Video Region uses part of the color table which must be reserved for\
use within Video Windows only.  It is necessary to always support Graphics
within Video Regions so cursors will work in those regions.  Thus this
implementation reserves colors 0-0xbf for graphics,  0xc0 and the odd
values between 0xc1-0xff for Video Windows, and reserves all other
color values for internal use.

Live Video requires full use of 7 of the Parallax 1280's eight bit planes
for the video being digitized.  Only the LSB (zmask = 1) is available
for graphics.  When this bit is 1, a graphics color is displayed, when it is
0, the underlying video is displayed.  Which graphics color is used depends
on the underlying video.  color value 0xc1 will be used if the video pixel
underlying is very dark.  color value 0xff will be used against very bright
video pixels.  The color map for these colors can be established to either
all display the same color, or to contrast against the video.  The default
is that graphics will be bright against dark video and visa-versa.

Still Video allows the LSB 6 bits of the display pixels to be used for
graphics, as the video is not constantly digitizing into the MSB 7 bits
like it would be for live video.  Thus over still video you can have
32 independent colors (The LSBit must be 1 to flag that this is a graphics
pixel).  The zmask must be set to 0x3f and the color values must be between
0xc1 and 0xff and must be odd.  

Color values 0xc1-0xff are not allocated by X.  It is assumed there will
be only one video window, and that all 32 of these colors are available
to the video window.  The standard X call for changing color table
entries is used to change these colors.

It is not always possible to fill every pixel within a video window with
video.  For example the 1280 restricts video to modulus 16 X coordinates.
Partially obscured video windows may make the shape of the video region
too complicated for the hardware.  Thus areas that should contain video
but can not, are set to color 0xc0.  This color is settable by the
video window program, but should be set to a dark color if contrasting
colors are going to be used for graphics over video.  This allows
programs following the color rules outlined above to not have to worry
about what parts of the Video Window are actually video regions and which
aren't.  

Graphics drawn within a video region should always contain a zmask less
than or equal to 0x3f.  It is only by seeing this plane mask that the
server can distinguish between operations involving video and those that
do not.  Graphics drawn with a larger mask in a video region will cause the 
video region to shrink out of the way.  This may be a desirable effect, but 
has limitations.  1) The next XStartVideo will obliterate this graphics, 
2) usually a fill type graphics operation should be used first, to guarantee
that what was previosly a video region now is entirely not.

Graphics drawn within live video must have zmask=1.  Other zmasks will
freeze the video.  Graphics drawn within still video should have zmask
of 0x3f or less.  Color values passed through the X greater than 0xbf
will be flagged by X as illegal.  Since the color values are always
used in video regions with zmasks of 0x3f or less, the upper two bits
of color value is ignored.  Thus use color values 1..3f to represent
color values c1..ff.


The following routines exist to support video, and exist in the
file Xvid.c:

XStartVideo(w,srcpix,sx,sy);

	This routine establishes the current X window "w" as a video
	window.  All parts of the window may be used as a video region.
	Those areas which are not video regions will be cleared to "srcpix"
	srcpix should almost always be set to 0xc0 to allow grapics within
	the video window to work properly.  "sx" and "sy" define what
	part of the video source to use.  Values of 0 and 0x1e1 map the
	upper left corner of the video source to the upper left corner
	of the video window.  Larger sx's and smaller sy's map progressively
	further right and further down points in the video source to the
	upper left corner of the video window.  sx must be between 0 and
	639 and sy must be between 0 and 481.

	The device server will maintain the video window to the best of its
	abilities, As graphics intrude on the video, the video will shrink away.
	Furthermore, movement of the video window is supported at the
	server level.  However the video window program must watch for
	certain window events, specifically: ExposeWindow, ExposeRegion,
	and ExposeCopy.  The events cannot be detected by the server, and
	it is therefore the responsibility of the video window program
	to detect these conditions and simply reissue the XStartVideo.
	Any overlay graphics may also need to be regenerated as with any
	X program.

	It is also a good idea to periodically reissue XStartVideo.  It
	is not necessary, but there are two good reasons: 1) X will
	turn on the screen saver after a couple of minutes if it
	sees no screen activity.  X cannot see live video happenning,
	but will see issueance of XStartVideo.  2) The server will
	have video shrink away from intruding graphics.  This is
	not always the best approach.  Resissuance of XStartVideo will
	optimally replace the Video regions if intrusions have occurred
	since the last XStartVideo.  5 Seconds seems a good interval to
	reissue this request.






