.ds f. xvdisplay.sec
.NH 1 "XVDISPLAY LIBRARY"
.XS
\s12\*(SN  XVDISPLAY LIBRARY\s0
.XE
.sp 2
.NH 2 "INTRODUCTION TO THE XVDISPLAY LIBRARY"
.XS
      \*(SN  INTRODUCTION
.XE
.sp 2
.PP
\fIxvdisplay\fP is the Khoros Library which contains utilities to aid
in displaying Khoros images on workstations under X Windows, Release 11,
Version 4.  The \fIxvdisplay\fP library must be used in conjunction with 
the \fIxvutils\fP library, as messages are popped up by routines in 
the \fIxvdisplay\fP library using utilities in the \fIxvutils\fP library.  
.PP
As a general rule, the Khoros libraries used by xvroutines each must 
have some way of storing information about and later identifying the 
current environment of the application that is using them.  The 
\fIxvexpr\fP and \fIxvgraphics\fP libraries use an integer \fIid\fP for this
purpose, while the \fIxvforms\fP library uses a pointer to 
a \fIxvf_form\fP structure for the same reason.  The \fIxvdisplay\fP 
library uses a \fIDisplayStructure\fP in which to store and 
reference the various necessary necessary information about the calling
xvroutine's current environment.  When using the \fIxvdisplay\fP library, 
the \fIDisplayStructure\fP may be initialized by a call to either 
\fIxvd_create_image()\fP or \fIxvd_init_image()\fP;  therefore, after the
required call to \fIxvd_initialize()\fP, one of these two routines must
be called before any other calls to the \fIxvdisplay\fP library are made.  
.sp 2
ALL programs that utilize these routines MUST link against: 
.sp
-lXaw -lXmu -lXt -lXext -lX11
.sp 2
ALL programs that utilize these routines MUST include the statement:
.sp
#include "xvdisplay.h"
.br
#include "xvutils.h"
.sp 3
.NH 2 " xvd_initialize()"
.XS
      \*(SN   xvd_initialize(display)
.XE
.sp
.LP
This routine sets up the environment necessary for other calls to
the \fIxvdisplay\fP library.  It initializes the screen, the root window, and
the default screen.  A graphics context for drawing is created, and foreground
and background pixels are given default values.  The number of colors available
on the screen is determined, as well as the type of visual being dealt with.
In addition, a cursor is created for use with the raster widget.
This routine MUST be called before ANY other calls to the \fIxvdisplay\fP 
library are made.  
.B
.sp
xvd_initialize(display)
.sp
Display *display;  
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -
- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP display: 10
The X11R4 Display on which to create the raster widget in which the image will
appear.  Note that if the application uses the \fIxvforms\fP library to create
a graphical user interface, the display will be returned by the required call
to xvf_initialize().
.sp
.LP
=====================================================================
.sp 3
.NH 2 " xvd_create_image()"
.XS
      \*(SN   xvd_create_image()
.XE
.sp
.LP
Creates and initializes the xvdisplay structure and all associated 
resources.  Creates and maps the window with the image displayed in it.
NOTE: this routine is a combination of xvd_init_image() and xvd_create_raster().
.sp 
.B
.sp
DisplayStructure *xvd_create_image(display, image, shape, clip, overlay,
.br
			private_cmap, read_only, name, xpos, ypos, position_widget)

.sp
Display *display;  
.br
struct xvimage  *image, *shape, *clip, *overlay;
.br
int              private_cmap;
.br
int		 read_only;
.br
char            *name;
.br
int              xpos, ypos;
.br
int              position_widget;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP display: 10
The X11R4 Display on which to create the raster widget in which the image will 
appear.  Note that if the application uses the \fIxvforms\fP library to create
a graphical user interface, the display will be returned by the required call
to xvf_initialize().
.sp
.IP image:
The Khoros viff data structure containing the image to be displayed.  Note
that if this is a multi-band image, the first band will be the image to
be displayed.
.IP shape:
If desired, a bit image may be provided to act as a shape mask. When an image
is used as a shape mask for the currently displayed image, the only part of the
currently displayed image that will be visible is that part defined by the
pixels in the shape mask image that have a value of (1).  All other parts of
the currently displayed image will "disappear", and the background (the part
of the screen behind the image raster widget) will show through.
The shape mask should be a Khoros viff data structure of data type bit.  
NOTE: if the viff data structure passed in is NOT of type bit, it will be 
automatically converted to type bit, without prompting or warning.  
ALSO NOTE: if NO shape mask is desired, pass in NULL.
.IP
WARNING: Only very simple bit images should be used as shape masks.  
For example, the bit
image "ball.bit" KHOROS_HOME/data/images is a good shape mask. As more
complicated images are used (images with many "holes" in them), editimage
will become incredibly slow as the X server  has to do much additional
work in order to map the image to the window.  WARNING: THIS FEATURE WILL ONLY
WORK ON X SERVERS THAT SUPPORT X11 R4!
.IP clip:
If desired, a bit image may be input and used as a clip mask.
When an image is used as a clip mask for the currently displayed image,
the only part of the current image that will appear normally
is that part defined by the pixels in the clip mask image that have a value
of (1). All other parts of the current image will appear in the background
color of the image window. The clip mask should be a Khoros viff data 
structure of data type bit.
NOTE: if the viff data structure passed in is NOT of type bit, it will be
automatically converted to type bit, without prompting or warning.
ALSO NOTE: if NO clip mask is desired, pass in NULL.
.IP overlay:
If desired, a bit image may be specified to be overlayed onto the currently
displayed image.  The overlay should be a Khoros viff data structure 
of data type bit.  NOTE: if the viff data structure passed in is NOT of 
type bit, it will be automatically converted to type bit, without prompting 
or warning.  ALSO NOTE: if NO overlay is desired, pass in NULL.  AND: if
the viff data structure passed in is a multiband image, the first band will
be taken as the overlay.
.IP private_cmap:
When \fIprivate_cmap\fP is passed as TRUE,  the \fIxvdisplay\fP library will 
create a private colormap for the application if not enough colors are available 
in the default colormap.  
.IP read_only:
Specify TRUE (1) if you will NOT be changing pixel values in the image.
Specify FALSE (0) if you WILL be changing pixel values in the image.
.IP name:
The name for the raster widget in which the image will be displayed.  This
name will appear as the title of the raster widget.
.IP "xpos and ypos":
The (x,y) position on screen (in device coordinates) at which to place the
raster widget. If the raster widget is to be placed manually, pass in 
(-1, -1). 
.IP "position widget": 
This flag indicates whether or not to put a position widget underneath the
widget in which the image is displayed.  If used, this position widget will
display the (x,y) location of the mouse in the raster widget, and the 
pixel value at that location.
.LP
=====================================================================
.sp 3
.NH 2 " xvd_init_image()"
.XS
      \*(SN   xvd_init_image()
.XE
.sp
.LP
Takes a Khoros viff data structure, and prepares the image contained within
it to be displayed as an XImage under X Windows, version 11 R4.  Returns a
pointer to the completed DisplayStructure which will be needed for subsequent
calls to the \fIxvdisplay\fP library.
.sp 
.B
.sp
DisplayStructure *xvd_init_image(display, image, shape, clip, overlay, 
.br
			private_cmap, read_only, shape_parent, colormap)
.sp
Display *display;  
.br
struct xvimage  *image, *shape, *clip, *overlay;
.br
int              private_cmap;
.br
int		 read_only;
.br
int		 shape_parent;
.br
Colormap	 colormap;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP display: 10
The X11R4 Display on which to create the raster widget in which the image will 
appear.  Note that if the application uses the \fIxvforms\fP library to create
a graphical user interface, the display will be returned by the required call
to xvf_initialize().
.sp
.IP image:
The Khoros viff data structure containing the image to be displayed.  Note
that if this is a multi-band image, the first band will be the image to
be displayed.
.IP shape:
If desired, a bit image may be provided to act as a shape mask. When an image
is used as a shape mask for the currently displayed image, the only part of the
currently displayed image that will be visible is that part defined by the
pixels in the shape mask image that have a value of (1).  All other parts of
the currently displayed image will "disappear", and the background (the part
of the screen behind the image raster widget) will show through.
The shape mask should be a Khoros viff data structure of data type bit.  
NOTE: if the viff data structure passed in is NOT of type bit, it will be 
automatically converted to type bit, without prompting or warning.  
ALSO NOTE: if NO shape mask is desired, pass in NULL.
.IP
WARNING:
Only very simple bit images should be used as shape masks.  For example, the bit
image "ball.bit" KHOROS_HOME/data/images is a good shape mask. As more
complicated images are used (images with many "holes" in them), editimage
will become incredibly slow as the X server  has to do much additional
work in order to map the image to the window.  WARNING: THIS FEATURE WILL ONLY
WORK ON X SERVERS THAT SUPPORT THE X11 R4!
.IP clip:
If desired, a bit image may be input and used as a clip mask.
When an image is used as a clip mask for the currently displayed image,
the only part of the current image that will appear normally
is that part defined by the pixels in the clip mask image that have a value
of (1). All other parts of the current image will appear in the background
color of the image window. The clip mask should be a Khoros viff data 
structure of data type bit.
NOTE: if the viff data structure passed in is NOT of type bit, it will be
automatically converted to type bit, without prompting or warning.
ALSO NOTE: if NO clip mask is desired, pass in NULL.
.IP overlay:
If desired, a bit image may be specified to be overlayed onto the currently
displayed image.  The overlay should be a Khoros viff data structure 
of data type bit.  NOTE: if the viff data structure passed in is NOT of 
type bit, it will be automatically converted to type bit, without prompting 
or warning.  ALSO NOTE: if NO overlay is desired, pass in NULL.  AND: if
the viff data structure passed in is a multiband image, the first band will
be taken as the overlay.
.IP private_cmap:
When \fIprivate_cmap\fP is
passed as TRUE,  the \fIxvdisplay\fP library will create a private colormap
if not enough colors are available in the default colormap.
.IP read_only:
This argument determines whether color
cells allocated for the image are Read Only or Read/Write.  The \fIread_only\fP
argument should be passed in as TRUE (1) if the image will NOT have pixel
values modified, FALSE (0) if it will have pixel values modified.
.IP shape_parent:
The \fIshape_parent\fP integer argument should be passed in
as TRUE (1) if the \fIshape\fP argument is to be used to shape the parent
window, FALSE (0) if the \fIshape\fP argument is shape only the image window.
Note that this argument is ignored if the \fIshape\fP argument is passed in
as NULL.
.IP colormap:
The \fIcolormap\fP argument is so that the caller \fIxvd_init_image()\fP
may force the \fIxvdisplay\fP library to use a predefined colormap when
desired.  This can be used for the purpose of conserving color cells and
decreasing the "techno-flash" phenomenon that occurs when all color cells
are used for a particular image.  If desired, you may pass in a previously
created colormap, and the \fIxvdisplay\fP library will as many colors
from this colormap as possible.  For example, in an
application such as \fBwarpimage\fP, which displays two images side by side,
it is a good idea to pass the colormap of the first image to
\fIxvd_init_image()\fP for the second image.  Thus, the second image will
share as many colors from the first image that it can.  For applications
that have only one image, or that should not share colors for some reason,
pass NULL for this argument.  If NULL is passed in for this argument then
the \fIxvdisplay\fP library will first try allocating colors out of the default
colormap, before allocating a new colormap (a private colormap).  The exception
to this rule is when \fIprivate_cmap\fP is FALSE.  When \fIprivate_cmap\fP is
passed as TRUE,  the \fIxvdisplay\fP library will create a private colormap
if not enough colors are available in the default colormap.
.LP
=====================================================================
.sp 3
.NH 2 " xvd_create_raster()"
.XS
      \*(SN   xvd_create_raster()
.XE
.sp
.LP
Creates & initializes a raster widget for the xvdisplay structure.  
The DisplayStructure must already be initialized (with a call to 
xvd_init_image()) and all X resources already created (ie, the toplevel widget
and the backplane must already have been created).
.sp 
.B
.sp
xvd_create_raster(display, parent, xvdisplay, position_widget)
.br
Display *display;
.br
Widget  parent;
.br
DisplayStructure *xvdisplay;
.br
int     position_widget;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP display: 10
The X11R4 Display on which to create the raster widget in which the image will 
appear.  Note that if the application uses the \fIxvforms\fP library to create
a graphical user interface, the display will be returned by the required call
to xvf_initialize().
.sp
.IP parent:
The Widget on which to create the raster widget on which
the image will be created.  This widget should be of type formWidgetClass.
.IP xvdisplay:
The DisplayStructure that has already been initialized with a call to
xvd_init_image().
.IP "position widget": 
This flag indicates whether or not to put a position widget underneath the
widget in which the image is displayed.  If used, this position widget will
display the (x,y) location of the mouse in the raster widget, and the 
pixel value at that location.
.LP
=====================================================================
.sp 3
.NH 2 " xvd_create_icon()"
.XS
      \*(SN   xvd_create_icon()
.XE
.sp
.LP
Creates and initializes an icon widget in which the image is displayed in
miniature.  Creates and maps the icon with the image displayed in it.
Note: this routine should be called \fIafter\fP the xvdisplay structure
is initialized.  It does \fInot\fP initialize the xvdisplay structure for
you, like \fIxvd_create_image()\fP does.
.sp 
.B
.sp
xvd_create_icon(display, xvdisplay, desired_width, desired_height);
.sp
Display *display;  
.br
DisplayStructure *xvdisplay;
.br
int desired_width;
.br
int desired_height;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP display: 10
The X11R4 Display on which to create the raster widget in which the image will 
appear.  Note that if the application uses the \fIxvforms\fP library to create
a graphical user interface, the display will be returned by the required call
to xvf_initialize().
.sp
.IP xvdisplay:
The DisplayStructure that has already been initialized with a call to
xvd_init_image().
.sp
.IP "desired_width, desired_height:"
The desired width and height of the iconified image. 
.LP
=====================================================================
.sp 3
.NH 2 " xvd_delete_image()"
.XS
      \*(SN   xvd_delete_image()
.XE
.sp
.LP
Deletes the xvdisplay structure and frees all associated resources.  
Should be called after a particular DisplayStructure will no longer be used.
.sp 
.B
.sp
xvd_delete_image(xvdisplay)
.sp
DisplayStructure *xvdisplay;  
.sp
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP xvdisplay: 10
The DisplayStructure to be freed & deleted.
.sp
.LP
=====================================================================
.sp 3
.NH 2 " xvd_error_handler()"
.XS
      \*(SN   xvd_error_handler()
.XE
.sp
.LP
This very specialized routine is used to handle X Protocol errors.  
When an error from Xlib, the X Toolkit, or the Athena Widget set is 
encountered, it is often difficult to establish what portion of the 
application's code is causing the X Protocol error.  The \fIxvdisplay\fP 
library's use of \fIxvd_error_handler()\fP makes it possible to trace 
the location of code causing X Errors via the \fBdbx\fP or 
other debugging program.
.LP
The \fIxvd_error_handler()\fP routine is AUTOMATICALLY INSTALLED
with the use of the \fIxvdisplay\fP library - YOU NEED NOT EXPLICITLY
INSTRUCT YOUR PROGRAM TO CALL THIS ROUTINE.  The definition of this routine
is provided simply for your information, and NOT because you should make
a call to \fIxvd_error_handler()\fP in your program! 
.LP
If X Protocol errors are 
encountered in your application that uses the \fIxvdisplay\fP library,
you can instruct the \fBdbx\fP program to stop in the \fIxvd_error_handler()\fP 
routine.  Then, by using the \fBdbx\fP "where" command, the faulty code 
can be easily located.  The \fIxvd_error_handler\fP routine will return 
FALSE (0) if it is possible for the application to recover from the X Protocol 
error.  If the error cannot be recovered from, it will print out the error 
message produced by X, it will exit the program.
.sp 
.B
.sp
xvd_error_handler(display, xerror)
.br
Display *display;
.br
XErrorEvent *error;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP display:
The X11R4 Display on which the application program is displayed.
.IP error: 10
Pointer to the XErrorEvent structure that contains the information about the
error that occurred.
.LP
=====================================================================
.LP
.sp 3
.NH 2 " xvd_autocolor()"
.XS
      \*(SN   xvd_autocolor()
.XE
.sp
.LP
Performs one of several predefined types of automatic
coloring on a Khoros image.  The image to be autocolored must be contained
in the DisplayStructure, as is the case after a call to xvd_init_image(),
or xvd_create_image().
.sp 
.B
.sp
xvd_autocolor(xvdisplay, type)
.br
DisplayStructure *xvdisplay;
.br
int              type;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP xvdisplay:
The DisplayStructure that has already been initialized with a call to
xvd_init_image().
.IP type: 10
The type of automatic coloring desired. Available types include:
.br
RGB_CUBE, RGB_TRIANGLE, RGB_SPIRAL, RGB_DISTANCE, CIE_DIAGRAM, DENSITY_SLICE,
GREYSCALE, ORIGINAL, RAINBOW, INVERT, or RANDOM.
.LP
=====================================================================
.sp 3
.NH 2 " xvd_set_colormap()"
.XS
      \*(SN   xvd_set_colormap()
.XE
.sp
.LP
Sets the colormap for the widget passed in.
.sp 2
.B
.sp
xvd_set_colormap(widget, colormap)
.br
Widget   widget;
.br
Colormap colormap;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP widget: 10
The widget to have its colormap set. 
.br
.IP colormap:
The colormap for the widget.
.LP
=====================================================================
.sp 2
.NH 2 " xvd_extract_roi()"
.XS
      \*(SN   xvd_extract_roi()
.XE
.sp
.LP
Extracts a region of interest from the displayed image into a new
Khoros viff data structure. 
.sp 
.B
.sp
struct xvimage *xvd_extract_roi(xvdisplay, mouse, x1, y1, x2, y2)
.br
DisplayStructure *xvdisplay;
.br
int     mouse; 
.br
int	x1, y1, x2, y2;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP xvdisplay: 10
The DisplayStructure that has already been initialized with a call to
xvd_init_image() or xvd_create_image().
.br
.IP mouse:
If the mouse is to be used to extract the image, pass in TRUE (1).  In this
case, crosshairs will appear on the displayed image; the user will be allowed
to move the crosshairs to define the region of interest.  Note that when
\fImouse\fP is passed in as TRUE, the \fIx1, y1, x2,\fP and \fIy2\fP arguments
are ignored.  If the region of interest is to be defined by the device 
coordinates specified in the \fIx1, y1, x2,\fP and \fIy2\fP arguments, pass in
FALSE (0).
.IP " x1, y1, x2, y2"
The device coordinates defining the region of interest. These arguments will
only be used when the \fImouse\fP flag is FALSE.  When this method of extraction
is used, (x1, y1) defines one corner of the region of interest; (x2, y2) 
defines the diagonal corner of the region of interest.
.LP
=====================================================================
.sp 3
.NH 2 " xvd_insert_roi()"
.XS
      \*(SN   xvd_insert_roi()
.XE
.sp
.LP
Inserts a region of interest contained in a Khoros viff data structure into 
the displayed image.
.sp 
.B
.sp
xvd_insert_roi(xvdisplay, subimage, mouse, x, y, saveimage)
.br
DisplayStructure *xvdisplay;
.br
struct xvimage *subimage;
.br
int     mouse; 
.br
int	x, y;
.br
struct xvimage **saveimage;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP xvdisplay: 10
The DisplayStructure that has already been initialized with a call to
xvd_init_image() or xvd_create_image().
.br
.IP subimage:
The Khoros viff data structure containing the region of interest to be
inserted into the currently displayed image.
.IP mouse:
If the mouse is to be used to insert the image, pass in TRUE (1).  In this
case, the region of interest will be inserted into the displayed image at
the location from which it was originally extracted; the user will be allowed
to move the bounding box around the region of interest to a new position if
desired.  Note that when \fImouse\fP is passed in as TRUE, the \fIx\fP and 
\fIy\fP arguments are ignored.  If the insert position for the region of 
interest is to be defined by the device coordinates specified in the \fIx\fP 
and \fIy\fP arguments, pass in FALSE (0).
.IP "x, y"
The device coordinates defining the upper left hand corner of the position 
where the region of interest is to be inserted. These arguments will
only be used when the \fImouse\fP flag is FALSE. 
.IP saveimage:
If desired, pass in the address of a pointer to the struct xvimage structure,
in which the original image (before the region of interest is inserted)
will be saved.  Pass in NULL if it is not important to save the original
image.
.LP
=====================================================================
.sp 2
.NH 2 " xvd_update_image()"
.XS
      \*(SN   xvd_update_image()
.XE
.sp
.LP
Updates the currently displayed image, or displays a new image.
.sp 
.B
.sp
xvd_update_image(xvdisplay, image)
.br
DisplayStructure *xvdisplay;
.br
struct xvimage   *image;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP xvdisplay: 10
The DisplayStructure that has already been initialized with a call to
xvd_init_image() or xvd_create_image().
.br
.IP image:
The Khoros viff data structure containing the new image to be displayed.
If \fIimage\fP is passed in as NULL, the currently displayed image will
be updated.
.LP
=====================================================================
.sp 3
.NH 2 " xvd_update_shape()"
.XS
      \*(SN   xvd_update_shape()
.XE
.sp
.LP
Updates the shape mask, or displays the current image with a new shape mask.
.sp 
.B
.sp
xvd_update_shape(xvdisplay, shape)
.br
DisplayStructure *xvdisplay;
.br
struct xvimage   *shape;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP xvdisplay: 10
The DisplayStructure that has already been initialized with a call to
xvd_init_image() or xvd_create_image().
.br
.IP shape:
The Khoros viff data structure containing the new image to be used as the 
shape mask.  The only part of the
currently displayed image that will be visible is that part defined by the
pixels in the shape mask image that have a value of (1).  All other parts of
the currently displayed image will "disappear", and the background (the part
of the screen behind the image raster widget) will show through.
The shape mask should be a Khoros viff data structure of data type bit.  
If \fIshape\fP is passed in as NULL, the current shape mask will
be updated.  NOTE: if the viff data structure passed in is NOT of type bit, 
it will be automatically converted to type bit, without prompting or warning.  
.LP
=====================================================================
.sp 2
.NH 2 " xvd_update_clip()"
.XS
      \*(SN   xvd_update_clip()
.XE
.sp
.LP
Updates the clip mask, or displays the current image with a new clip mask.
.sp 
.B
.sp
xvd_update_clip(xvdisplay, clip)
.br
DisplayStructure *xvdisplay;
.br
struct xvimage   *clip;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP xvdisplay: 10
The DisplayStructure that has already been initialized with a call to
xvd_init_image() or xvd_create_image().
.IP clip:
The Khoros viff data structure containing the new image to be used as the 
clip mask.  The only part of the current image that will appear normally
is that part defined by the pixels in the clip mask image that have a value
of (1). All other parts of the current image will appear in the background
color of the image window. The clip mask should be a Khoros viff data 
structure of data type bit. If \fIclip\fP is passed in as NULL, the current 
clip mask will be updated.
NOTE: if the viff data structure passed in is NOT of type bit, it will be
automatically converted to type bit, without prompting or warning.
.LP
=====================================================================
.sp 3
.NH 2 " xvd_update_overlay()"
.XS
      \*(SN   xvd_update_overlay()
.XE
.sp
.LP
Updates the overlay image, or displays the current image with a new overlay.
.sp 
.B
.sp
xvd_update_overlay(xvdisplay, overlay)
.br
DisplayStructure *xvdisplay;
.br
struct xvimage   *overlay;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP xvdisplay: 10
The DisplayStructure that has already been initialized with a call to
xvd_init_image() or xvd_create_image().
.IP overlay:
The Khoros viff data structure containing the new image to be used as the 
overlay.  If \fIoverlay\fP is passed in as NULL, the current overlay will be 
updated.  The overlay should be a Khoros viff data structure of data type bit. 
NOTE: if the viff data structure passed in is NOT of type bit, it will be 
automatically converted to type bit, without prompting or warning.  
ALSO: if the viff data structure passed in is a multiband image, the first 
band will be taken as the overlay.
.LP
=====================================================================
.sp 3
.NH 2 " xvd_update_all()"
.XS
      \*(SN   xvd_update_all()
.XE
.sp
.LP
Updates the currently displayed image, the shape mask, the clip mask, and
the overlay image.
.sp 
.B
.sp
xvd_update_overlay(xvdisplay, image, shape, clip, overlay)
.br
DisplayStructure *xvdisplay;
.br
struct xvimage   *image, *shape, *clip, *overlay;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP xvdisplay: 10
The DisplayStructure that has already been initialized with a call to
xvd_init_image().
.IP image:
The Khoros viff data structure containing the new image to be displayed.
If \fIimage\fP is passed in as NULL, the currently displayed image will
be updated.
.IP shape:
The Khoros viff data structure containing the new image to be used as the 
shape mask.  The only part of the
currently displayed image that will be visible is that part defined by the
pixels in the shape mask image that have a value of (1).  All other parts of
the currently displayed image will "disappear", and the background (the part
of the screen behind the image raster widget) will show through.
The shape mask should be a Khoros viff data structure of data type bit.  
If \fIshape\fP is passed in as NULL, the current shape mask will
be updated.  NOTE: if the viff data structure passed in is NOT of type bit, 
it will be automatically converted to type bit, without prompting or warning.  
.IP clip:
The Khoros viff data structure containing the new image to be used as the 
clip mask.  The only part of the current image that will appear normally
is that part defined by the pixels in the clip mask image that have a value
of (1). All other parts of the current image will appear in the background
color of the image window. The clip mask should be a Khoros viff data 
structure of data type bit. If \fIclip\fP is passed in as NULL, the current 
clip mask will be updated.
NOTE: if the viff data structure passed in is NOT of type bit, it will be
automatically converted to type bit, without prompting or warning.
.IP overlay:
The Khoros viff data structure containing the new image to be used as the 
overlay.  If \fIoverlay\fP is passed in as NULL, the current overlay will be 
updated.  The overlay should be a Khoros viff data structure of data type bit. 
NOTE: if the viff data structure passed in is NOT of type bit, it will be 
automatically converted to type bit, without prompting or warning.  
ALSO: if the viff data structure passed in is a multiband image, the first 
band will be taken as the overlay.
.LP
 ====================================================================
.sp 3
.NH 2 " xvd_query_position()"
.XS
      \*(SN   xvd_query_position()
.XE
.sp
.LP
Finds the position of the mouse in the window. Returns TRUE (1) if the
next event is a Motion Notify event, so that application may do motion
compression if applicable.  Returns FALSE (0) otherwise.
.sp 
.B
.sp
xvd_query_position(widget, x, y, clip)
.br
Widget widget;
.br
int     *x, *y;
.br
int     clip;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP xvdisplay: 10
The DisplayStructure that has already been initialized with a call to
xvd_init_image().
.IP "x, y":
Returns the (x,y) position of the mouse in the widget.
.IP clip:
Indicates whether or not to clip to the widget specified.  Note that if 
xvd_query_position() is called when the mouse is \fIoutside\fP the widget
specified, x and/or y may be either negative or larger than the actual size of 
the widget.  If \fIclip\fP is specified as TRUE(1), and the mouse is outside 
the widget specified, the (x,y) location at which the mouse left the widget 
is returned, instead of possibly negative or very large values.
.LP
=====================================================================
.sp 3
.NH 2 " xvd_check_visibility()"
.XS
      \*(SN   xvd_check_visibility()
.XE
.sp
.LP
Determines whether or not a widget is currently visible.  Returns TRUE (1)
if the widget is visible, FALSE (0) otherwise.
.sp 
.B
.sp
xvd_check_visibility(widget)
.br
Widget widget;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP widget:
The widget in which we are interested.
.LP
=====================================================================
.sp 3
.NH 2 " xvd_query_value()"
.XS
      \*(SN   xvd_query_value()
.XE
.sp
.LP
Returns the value of the image at the desired x & y position (the pixel).  u
xvd_query_value() will also return the index into both the  image map and the X 
color array stored in the DisplayStructure.  This routine also returns a flag
indicating whether the currently displayed pixel color is actually allocated
or is the closest available color to another allocated color.  You may pass
in NULL for the value, index, or allocated parameters, in which case the
field will be ignored.
.sp 
.B
.sp
int xvd_query_value(xvdisplay, x, y, value, index, allocated)
.br
DisplayStructure *xvdisplay;
.br
int     x, y;
double  *value;
int     *index, *allocated;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP widget:
The widget in which we are interested.
.LP
=====================================================================
