.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 \fIxvforms\fP and \fIxvutils\fP libraries.
.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 
\fIvexpr\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.  
.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 "xvforms.h"
.PP
The most basic purpose of the \fIxvdisplay\fP library is to aid the application
in displaying an image on the screen.  There are two ways of displaying an
image on the screen;  depending on how you wish to display the image, you
will make calls to different routines in the \fIxvdisplay\fP library.  To
clarify, these methods are detailed below.
.IP "(1)" 
The first method is to display an image independantly, and without a graphical 
user interface, as is the case with \fBputimage\fP.  The image will pop up
automatically; you will have to provide some method to exit the 
program, such as typing 'Q' or clicking in the image, since there is no
graphical user interface with which to control the program.  Note that the
application using this method will be a \fIhybrid graphical routine\fP,
as opposed to a \fIvroutine\fP or an \fIxvroutine\fP  (for more details,
see the first section of Chapter 1).  When using this method, your code
should have the following calls, in the order shown (\fInote that arguments
are omitted!\fP):
.sp
/* initialize xvdisplay library */
.br
xvd_initialize();  
.br
/* allocate & initialize the display structure,
.br
create an image window, display it on the screen */ 
.br
xvd_create_xvdisplay();  
.sp 2
.IP "(2)"
The more common method is to display an image within a workspace that is
part of the application's graphical user interface.  This is the method used
in \fBeditimage\fP, \fBviewimage\fP, and \fBwarpimage\fP.  The workspace
in which the image will be displayed will exist for the duration of the program;
the image displayed can be controlled with a variety of routines
available in the \fIxvdisplay\fP library.  When using this method, your code
should have the following calls, in the order shown (\fInote that arguments
are omitted!\fP):
.sp
/* initialize xvdisplay library */
.br
xvd_initialize();   
.br
/* allocs & inits the DisplayStructure */  
.br
xvd_init_xvdisplay();  
.br
/* builds all associated X Resources */
.br
xvd_build_xvdisplay(); 
.br
/* creates an XImage widget within the parent, 
.br
and displays the image in it */
.br
xvd_create_raster();   
.sp
.PP
The instructions above should give you a general feel for the steps involved
in displaying an image with the \fIxvdisplay\fP library, in spite of the fact
that arguments to routines have been omitted.  In many of the routines found
in the \fIxvdisplay\fP library, there are several arguments that re-occur often.
As these arguments take some explanation, let us describe 
them here in detail.  Later in this section, then, it will only be necessary
to give a brief description of these arguments, thus saving space and 
repetition;  the following paragraphs can be used as reference when necessary. 
.IP "\fBThe Display:\fP" 
This is the X Windows Display on which the image will be displayed; 
a complete explanation of the Display can be found in Chapter 2 of the 
\fIXlib - C Library\fP documentation, by James Gettys, Robert W. Sheifler,
and Ron Newman, distributed with X11R4 by MIT.  If you don't want to
think about it, it is wise to remember that a call to the 
\fIxvf_initialize()\fP routine initializes and returns the Display; all 
you need to do is pass it to the \fIxvdisplay\fP library when necessary.
If you are writing an xvroutine, this call is automatically generated for you 
by \fBconductor\fP. 
.IP "\fBThe DisplayStructure:\fP"
Many of the \fIxvdisplay\fP routines have as their first argument a pointer
to the DisplayStructure; this is the structure that holds all the information
about your application, as discussed in the second paragraph of the 
Introduction.  When the documentation in this section refers to "a pointer
to the active DisplayStructure", this means that it is expected that the
DisplayStructure passed in has been allocated and properly initialized with
either a single call to \fIxvd_create_xvdisplay()\fP (in the case of a pop-up
image), or to a pair of calls to \fIxvd_init_xvdisplay() and 
xvd_build_xvdisplay()\fP (in the case of an image displayed in the GUI).
.IP "\fBThe Shape Mask:\fP"   
When 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 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.
.IP
The shape mask should be a Khoros VIFF data structure of data type bit.
NOTE: if the VIFF data structure passed to the \fIxvdisplay\fP library
is NOT of type bit, it will be automatically converted to type bit, without 
prompting or warning. 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), your application
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 X11R4!
.IP "\fBThe Clip Mask:\fP" 
When 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. 
.IP
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.
AGAIN:  Only very simple bit images should be used as clip masks; the
"ball.bit" image mentioned above is a good clip mask.
.IP "\fBThe Overlay\fP:"
When 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: if the VIFF data structure passed in is a multiband image, 
the first band will be taken as the overlay.
.IP "\fBPrivate Colormap\fP:"
This boolean variable indicates whether or not you want the \fIxvdisplay\fP
library to create a private colormap for your application.  If 
\fIprivate_cmap\fP is TRUE (1), the \fIxvdisplay\fP library will first attempt
to allocate all the colors for your application out of the default colormap.
The number of colors available to your application from the default colormap
will be dependant on how many other applications are running simultaneously 
with your application, and how many colors those other applications have 
already allocated.  If your application has too many colors to fit in the 
default colormap, then the \fIxvdisplay\fP library will go ahead and create
a private colormap for your application.  The advantage of using a private
colormap is that your image will be guaranteed to have use of the colors
available on a particular screen, minus those used by your application's
user interface. The disadvantage of using a private colormap is that when 
a "techo-flashing" phenomenon of varying severity may occur as the mouse 
is moved about the screen; this is a result of your private colormap being 
installed and de-installed as the mouse is moved into and out of the image 
being displayed by your application.  
.IP
If \fIprivate_cmap\fP is FALSE (0), the \fIxvdisplay\fP library will use only
the default colormap for your application.  If your application uses more
colors than are available in the default colormap, they will be re-mapped
to other, already-allocated colors from the default colormap.  The advantage
of NOT having a private colormap is that the "techno-flashing" phenomenon
is eliminated.  The disadvantage of not having a private colormap is that
your application is limited to the colors available in the default colormap;
if your image uses more colors than are available, some colors will be re-mapped
to other colors that do exist in the default colormap -- this may result in
"incorrect" or "unexpected" display of some colors in some images.
.IP "\fBRead Only\fP:"
Specifies whether or not your application will be dynamically changing the 
color cells in the colormap. For example, \fBeditimage\fP allows the user
to change the colors displayed in the image via the "Pseudo Color" or "LUT"
mechanisms;  thus, \fBeditimage\fP would have \fIread_only\fP set to FALSE (0).
\fIPutimage\fP, on the other hand, simply displays an image;  it never changes
the colormap of the image.  Therefore, \fBputimage\fP would have \fIread_only\fP
set to TRUE (1).  NOTE: it is usually best to set \fIread_only\fP to TRUE
(1), unless you know for a fact that your application will be changing the
colormap;  having a Read-Only colormap will allow your application to share 
colors with other applications that are being executed simultaneously, and
will not force them to use a private colormap.  For a more detailed discussion
of allocating, modifying, and freeing color cells, see section 5.1.2
(pp. 55 - 60) of the \fIXlib - C Library\fP documentation, by James Gettys, 
Robert W. Sheifler, and Ron Newman, distributed with X11R4 by MIT.  
.PP
Now you should have an idea of the minimum number of calls that you will have
to make in order to display an image with the \fIxvdisplay\fP library.  Some
of the most common arguments to routines in the \fIxvdisplay\fP library 
have been explained.  Now, complete descriptions of all \fIxvdisplay\fP 
library routines are presented in the following pages.  See Chapter 7 
for two short examples of programs using the \fIxvdisplay\fP library.
.bp
.sp 3
.NH 2 " xvd_initialize()"
.XS
      \*(SN   xvd_initialize()
.XE
.sp
.LP
This routine initializes global variables that will be used during future 
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 X Windows Display on which your application will appear.
.sp
.LP
=====================================================================
.sp 3
.NH 2 " xvd_init_xvdisplay()"
.XS
      \*(SN   xvd_init_xvdisplay()
.XE
.sp
.LP
This routine creates and initializes the xvdisplay structure.  It doesn't
create any X resources associated with the image, shape mask, clip mask,
overlay, or colormap, and it does not display the image.
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_xvdisplay(display, image, shape, clip, overlay, 
.br
			private_cmap, read_only, shape_parent, colormap)
.sp
Display *display;  
.br
struct xvimage  *image; 
.br
struct xvimage  *shape; 
.br
struct xvimage  *clip; 
.br
struct xvimage  *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 X Windows Display on which your application will appear.
.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. 
If NO shape mask is desired, pass in NULL.
.IP clip:
If desired, a bit image may be input and used as a clip mask.
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.  If NO overlay is desired, pass in NULL.  
.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 shape_parent:
This argument is only valid if a shape mask is provided.  TRUE (1) if the 
parent (and ancestors) of the raster widget containing the image are also 
to be removed, in order to let the background windows show through the 
application;  FALSE (0) otherwise.  If you are using method 1 to display
the image (pop-up window), provide TRUE;  if you are using method 2 to
display your image (GUI), provide FALSE.
.IP colormap:
Pass in the colormap to be used with the image.  If you want to use the
default colormap, pass NULL.
.LP
=====================================================================
.sp 3
.NH 2 " xvd_build_xvdisplay()"
.XS
      \*(SN   xvd_build_xvdisplay()
.XE
.sp
.LP
This routine builds up the xvdisplay structure with all X resources associated
with the image, shape mask, clip mask, and so on. It does not, however,
create a window in which to display the image.  It is required that the
DisplayStructure be already allocated and initialized with a prior call to
\fIxvd_init_xvdisplay()\fP. 
.B
.sp
xvd_build_xvdisplay(xvdisplay)
.sp
DisplayStructure *xvdisplay;  
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -
- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP xvdisplay: 10
A pointer to the DisplayStructure that has been initialized and allocated 
with a call to \fIxvd_init_xvdisplay()\fP.
.sp
.LP
=====================================================================
.sp 3
.NH 2 " xvd_init_image()"
.XS
      \*(SN   xvd_init_image()
.XE
.sp
.LP
\fIIMPORTANT NOTE\fP: Due to enhancements that have been made to the
xvdisplay library, this routine has been outdated as of Patch2. It still 
exists for backwards compatibility with those existing applications that 
call it;  however, programmers that have existing programs calling this
routine should migrate as soon as possible.  Old calls to this routine should
be replaced with a pair of calls to \fIxvd_init_xvdisplay()\fP and 
\fIxvd_build_xvdisplay()\fP, described above.
.LP
This routine creates and initializes the xvdisplay structure and all associated 
X resources.  Takes a Khoros VIFF data structure, and prepares the image
contained within it to be displayed as an XImage under X Windows, version 11
release 4.  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;
.br
struct xvimage  *shape;
.br
struct xvimage  *clip;
.br
struct xvimage  *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 X Windows Display on which your application will appear.
.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. 
If NO shape mask is desired, pass in NULL.
.IP clip:
If desired, a bit image may be input and used as a clip mask.
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.  If NO overlay is desired, pass in NULL.  
.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 shape_parent:
This argument is only valid if a shape mask is provided.  TRUE (1) if the 
parent (and ancestors) of the raster widget containing the image are also 
to be removed, in order to let the background windows show through the 
application;  FALSE (0) otherwise.  If you are using method 1 to display
the image (pop-up window), provide TRUE;  if you are using method 2 to
display your image (GUI), provide FALSE.
.IP colormap:
Pass in the colormap to be used with the image.  If you want to use the
default colormap, pass NULL.
.LP
=====================================================================
.sp 3
.NH 2 " xvd_create_xvdisplay()"
.XS
      \*(SN   xvd_create_xvdisplay()
.XE
.sp
.LP
Creates and initializes the xvdisplay structure and all associated 
X resources.  Creates and automatically pops up the window with the 
specified image displayed in it.  NOTE: do not use this routine in conjunction 
with \fIxvd_init_xvdisplay(), xvd_build_xvdisplay(),\fP or 
\fIxvd_create_raster()\fP.
.B
.sp
DisplayStructure *xvd_create_xvdisplay(display, image, shape, clip, overlay,
.br
		private_cmap, read_only, name, xpos, ypos, position_widget)

.sp
Display *display;  
.br
struct xvimage  *image;
.br
struct xvimage  *shape;
.br
struct xvimage  *clip;
.br
struct xvimage  *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 X Windows Display on which your application will appear.
.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. 
If NO shape mask is desired, pass in NULL.
.IP clip:
If desired, a bit image may be input and used as a clip mask.
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.  If NO overlay is desired, pass in NULL.  
.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:
If desired, you may specify the name for the toplevel Application Shell
widget here.
.IP xpos, ypos:
You may specify the location for window placement here;
if the user has a window manager that will automatically place the window,
the window will mapped at this position.  If you wish the user to place the
window then pass xpos & ypos equal to -1.
.IP position_widget:
A position widget appears underneath the image window;  when the user moves
the mouse over the image, the position widget will constantly update its
display of (X x Y = Z), where X and Y specify the location of the mouse in
the image, and Z indicates the pixel value at that location.  Provide TRUE (1)
if you want a position widget;  FALSE (0) otherwise. 
.LP
=====================================================================
.sp 3
.NH 2 " xvd_create_image()"
.XS
      \*(SN   xvd_create_image()
.XE
.sp
.LP
\fIIMPORTANT NOTE\fP: Due to enhancements that have been made to the
xvdisplay library, this routine has been outdated as of Patch2. It still 
exists for backwards compatibility with those existing applications that 
call it;  however, programmers that have existing programs calling this
routine should migrate as soon as possible.  Old calls to this routine should
be replaced with a call to \fIxvd_create_xvdisplay(), described above\fP. 
.LP
This routine creates and initializes the xvdisplay structure and all associated 
resources.  Creates and pops up the window with the image displayed in it.
.LP
.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;
.br
struct xvimage  *shape;
.br
struct xvimage  *clip;
.br
struct xvimage  *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 X Windows Display on which your application will appear.
.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. 
If NO shape mask is desired, pass in NULL.
.IP clip:
If desired, a bit image may be input and used as a clip mask.
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.  If NO overlay is desired, pass in NULL.  
.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:
If desired, you may specify the name for the toplevel Application Shell
widget here.
.IP xpos, ypos:
You may specify the location for window placement here;
if the user has a window manager that will automatically place the window,
the window will mapped at this position.  If you wish the user to place the
window then pass xpos & ypos equal to -1.
.IP position_widget:
A position widget appears underneath the image window;  when the user moves
the mouse over the image, the position widget will constantly update its
display of (X x Y = Z), where X and Y specify the location of the mouse in
the image, and Z indicates the pixel value at that location.  Provide TRUE (1)
if you want a position widget;  FALSE (0) otherwise. 
.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 prior call to 
\fIxvd_init_xvdisplay()\fP).  All X resources must be already created (with 
a prior call to \fIxvd_build_xvdisplay()\fP).  The parent must already have 
been created (in graphical user interfaces, with a call to the 
\fIxvf_init_XXX()\fP routine, automatically generated by \fBconductor\fP.
.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 X Windows Display on which your application will appear.
.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:
A pointer to the DisplayStructure that has already been initialized with a 
call to \fIxvd_init_xvdisplay()\fP, and with X resources created with a call to
\fIxvd_build_xvdisplay()\fP.
.IP position_widget:
A position widget appears underneath the image window;  when the user moves
the mouse over the image, the position widget will constantly update its
display of (X x Y = Z), where X and Y specify the location of the mouse in
the image, and Z indicates the pixel value at that location.  Provide TRUE (1)
if you want a position widget;  FALSE (0) otherwise. 
.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 with a call to \fIxvd_init_xvdisplay()\fP.  It does \fInot\fP 
initialize the xvdisplay structure for you, 
like \fIxvd_create_xvdisplay()\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 X Windows Display on which your application will appear.
.sp
.IP xvdisplay:
A pointer to the DisplayStructure that has already been initialized with 
a call to \fIxvd_init_xvdisplay()\fP.
.sp
.IP "desired_width, desired_height:"
The desired width and height of the iconified image. 
.LP
=====================================================================
.sp 3
.NH 2 " xvd_delete_xvdisplay()"
.XS
      \*(SN   xvd_delete_xvdisplay()
.XE
.sp
.LP
Deletes the DisplayStructure and frees all associated resources.  
Should be called after a particular DisplayStructure will no longer be used.
.sp 
.B
.sp
xvd_delete_xvdisplay(xvdisplay)
.sp
DisplayStructure *xvdisplay;  
.sp
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP xvdisplay: 10
A pointer to the active DisplayStructure to be freed & deleted.
.sp
.LP
=====================================================================
.sp 3
.NH 2 " xvd_delete_image()"
.XS
      \*(SN   xvd_delete_image()
.XE
.sp
.LP
\fIIMPORTANT NOTE\fP: Due to enhancements that have been made to the
xvdisplay library, this routine has been outdated as of Patch2. It still 
exists for backwards compatibility with those existing applications that 
call it;  however, programmers that have existing programs calling this
routine should migrate as soon as possible.  Old calls to this routine should
be replaced with a call to \fIxvd_delete_xvdisplay(), described above\fP. 
.LP
Deletes the DisplayStructure 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
A pointer to the active 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 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:
A pointer to the active DisplayStructure.
.IP type: 10
The type of automatic coloring desired. Available types include:
.br
RGB_CUBE, RGB_TRIANGLE, RGB_SPIRAL, HLS_SPIRAL, HSV_RINGS, 
HLS_RINGS, RGB_DISTANCE, CIE_DIAGRAM, DENSITY_SLICE,
GREYSCALE, SA_PSEUDO, ORIGINAL, RAINBOW, INVERT, INVERT_ORIG, 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
A pointer to the active DisplayStructure. 
.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
A pointer to the active DisplayStructure. 
.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 initially displayed at
the location from which it was originally extracted; the user will then be
allowed
to move the bounding box 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. 
Note that there must be an image \fIalready displayed\fP when you call
this routine.  There are several possible cases for situations in which 
you might want to call this routine.  Please see the explanations below 
for the usage that fits your particular case.
.sp 
.B
.sp
xvd_update_image(xvdisplay, image)
.br
DisplayStructure *xvdisplay;
.br
struct xvimage   *image;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.PP 
.sp
.IP xvdisplay: 10
A pointer to the active DisplayStructure. 
.sp
.IP image:
There are a few different cases for the \fIimage\fP variable, depending on
the particular circumstances of your image display algorithm.
.IP "case 1"
If you want to update the currently displayed image because the contents 
of the currently displayed image have changed, 
call \fIxvd_update_image()\fP with \fIimage = NULL\fP; ie, 
\fIxvd_update_image(xvdisplay, NULL)\fP.
.IP "case 2"
If you want to replace the currently displayed image with a new image,
call \fIxvd_update_image()\fP with the new image; ie, 
\fIxvd_update_image(xvdisplay, new_image)\fP.  Be aware that when you do
this, the old image will be freed automatically by the xvdisplay library.
You will no longer be able to reference the old image.
.IP "case 3"
If you want to update the currently displayed image with a new
image, but do not want the old image to be freed by xvdisplay library,
then you must set \fIxvdisplay->image\fP to NULL before calling 
\fIxvd_update_image()\fP;  ie: 
.br
xvdisplay->image = NULL;
.br
xvd_update_image(xvdisplay, new_image);
.sp
.IP "case 4"
If you want to clear (blank out) the currently displayed image,
see the documentation on \fIxvd_clear_image()\fP
.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.
Note that there must be an shape mask \fIalready shaping\fP the window
when you call this routine.  There are several possible cases for situations 
in which you might want to call this routine.  Please see the explanations 
below for the usage that fits your particular case.
.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
A pointer to the active DisplayStructure. 
.IP shape:
The Khoros VIFF data structure containing the image to be used to shape 
the image window.  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.  
.IP
There are a few different cases for the \fIshape\fP variable, depending on
the particular circumstances of your image display algorithm.
.IP "case 1"
If you want to update the current shape mask because the contents
of the current shape mask have changed, call \fIxvd_update_shape()\fP with
\fIshape = NULL\fP; ie, \fIxvd_update_shape(xvdisplay, NULL)\fP.
.IP "case 2"
If you want to replace the current shape mask with a new shape mask,
call \fIxvd_update_shape()\fP with the new shape mask; ie,
\fIxvd_update_shape(xvdisplay, new_shape)\fP.  Be aware that when you do
this, the old shape mask will be freed automatically by the xvdisplay library.
You will no longer be able to reference the old shape mask.
.IP "case 3"
If you want to update the current shape mask with a new shape mask,
but do not want the old shape mask to be freed by xvdisplay library,
then you must set \fIxvdisplay->shape\fP to NULL before calling
\fIxvd_update_shape()\fP.  For example:
.br
xvdisplay->shape = NULL;
.br
xvd_update_shape(xvdisplay, new_shape);
.sp
.IP "case 4"
If you want to clear (get rid of) the shape mask, 
see the documentation on \fIxvd_clear_shape()\fP.
.sp
.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.
Note that there must be an clip mask \fIalready overlaid\fP on the image
when you call this routine.  There are several possible cases for situations 
in which you might want to call this routine.  Please see the explanations 
below for the usage that fits your particular case.
.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
A pointer to the active DisplayStructure. 
.IP clip:
This is the Khoros VIFF data structure containing the 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. 
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
There are a few different cases for the \fIclip\fP variable, depending on
the particular circumstances of your image display algorithm.
.IP "case 1"
If you want to update the current clip mask because the contents
of the current clip mask have changed, call \fIxvd_update_clip()\fP with
\fIclip = NULL\fP; ie, \fIxvd_update_clip(xvdisplay, NULL)\fP.
.IP "case 2"
If you want to replace the current clip mask with a new clip mask,
call \fIxvd_update_clip()\fP with the new clip mask; ie,
\fIxvd_update_clip(xvdisplay, new_clip)\fP.  Be aware that when you do
this, the old clip mask will be freed automatically by the xvdisplay library.
You will no longer be able to reference the old clip mask.
.IP "case 3"
If you want to update the current clip mask with a new clip mask,
but do not want the old clip mask to be freed by xvdisplay library,
then you must set \fIxvdisplay->clip\fP to NULL before calling
\fIxvd_update_clip()\fP.  For example:
.br
xvdisplay->clip = NULL;
.br
xvd_update_clip(xvdisplay, new_clip);
.sp
.IP "case 4"
If you want to clear (get rid of) the clip mask, 
see the documentation on xvd_clear_clip().
.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.
Note that there must be an overlay \fIalready on\fP the image when you call 
this routine.  There are several possible cases for situations in which you 
might want to call this routine.  Please see the explanations below for the 
usage that fits your particular case.
.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
A pointer to the active DisplayStructure. 
.IP overlay:
This is the Khoros VIFF data structure containing the new image to be used 
as the overlay.  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.
.IP
There are a few different cases for the \fIoverlay\fP variable, depending on
the particular circumstances of your image display algorithm.
.IP "case 1"
If you want to update the current overlay because the contents
of the current overlay have changed, call \fIxvd_update_overlay()\fP with
\fIoverlay = NULL\fP; ie, \fIxvd_update_overlay(xvdisplay, NULL)\fP.
.IP "case 2"
If you want to replace the current overlay with a new overlay ,
call \fIxvd_update_overlay()\fP with the new overlay; ie,
\fIxvd_update_overlay(xvdisplay, new_overlay)\fP.  Be aware that when you do
this, the old overlay will be freed automatically by the xvdisplay library.
You will no longer be able to reference the old overlay.
.IP "case 3"
If you want to update the current overlay with a new overlay,
but do not want the old overlay to be freed by xvdisplay library,
then you must set \fIxvdisplay->overlay\fP to NULL before calling
\fIxvd_update_overlay()\fP.  For example:
.br
xvdisplay->overlay = NULL;
.br
xvd_update_overlay(xvdisplay, new_overlay);
.sp
.IP "case 4"
If you want to clear (get rid of) the current overlay, 
see the documentation on \fIxvd_clear_overlay()\fP.
.LP
=====================================================================
.sp 3
.NH 2 " xvd_update_xvdisplay()"
.XS
      \*(SN   xvd_update_xvdisplay()
.XE
.sp
.LP
Updates the currently displayed image, the shape mask, the clip mask, and
the overlay image.
.sp 
.B
.sp
xvd_update_xvdisplay(xvdisplay, image, shape, clip, overlay)
.br
DisplayStructure *xvdisplay;
.br
struct xvimage   *image;
.br
struct xvimage  *shape;
.br
struct xvimage  *clip;
.br
struct xvimage  *overlay;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP xvdisplay: 10
A pointer to the active DisplayStructure. 
.IP image:
The Khoros VIFF data structure containing the image to be displayed.
See the documentation on \fIxvd_update_image()\fP for the four cases
that apply.
.IP shape:
The Khoros VIFF data structure containing the shape mask.
See the documentation on \fIxvd_update_image()\fP for the four cases
that apply.
.IP clip:
The Khoros VIFF data structure containing the clip mask.
See the documentation on \fIxvd_update_clip()\fP for the four cases
that apply.
.IP overlay:
The Khoros VIFF data structure containing the overlay.
See the documentation on \fIxvd_update_overlay()\fP for the four cases
that apply.
.LP
 ====================================================================
.sp 3
.NH 2 " xvd_update_all()"
.XS
      \*(SN   xvd_update_all()
.XE
.sp
.LP
\fIIMPORTANT NOTE\fP: Due to enhancements that have been made to the
xvdisplay library, this routine has been outdated as of Patch2. It still 
exists for backwards compatibility with those existing applications that 
call it;  however, programmers that have existing programs calling this
routine should migrate as soon as possible.  Old calls to this routine should
be replaced with a call to \fIxvd_update_xvdisplay(), described above\fP. 
.LP
Updates the currently displayed image, the shape mask, the clip mask, and
the overlay image.
.sp 
.B
.sp
xvd_update_all(xvdisplay, image, shape, clip, overlay)
.br
DisplayStructure *xvdisplay;
.br
struct xvimage   *image;
.br
struct xvimage  *shape;
.br
struct xvimage  *clip;
.br
struct xvimage  *overlay;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP xvdisplay: 10
A pointer to the active DisplayStructure. 
.IP image:
The Khoros VIFF data structure containing the image to be displayed.
See the documentation on \fIxvd_update_image()\fP for the four cases
that apply.
.IP shape:
The Khoros VIFF data structure containing the shape mask.
See the documentation on \fIxvd_update_image()\fP for the four cases
that apply.
.IP clip:
The Khoros VIFF data structure containing the clip mask.
See the documentation on \fIxvd_update_clip()\fP for the four cases
that apply.
.IP overlay:
The Khoros VIFF data structure containing the overlay.
See the documentation on \fIxvd_update_overlay()\fP for the four cases
that apply.
.LP
 ====================================================================
.sp 3
.NH 2 " xvd_update_xcolors()"
.XS
      \*(SN   xvd_update_xcolors()
.XE
.sp
.LP
Updates the colors displayed in the image;  this is a very specialized
routine for use when you elect to make changes directly to the XColor
structures stored in the \fIxvdisplay->xcolors\fP array.  The colors
in the \fIxvdisplay->xcolors\fP can only be dynamically changed if the
xvdisplay \fIread_only\fP parameter has been set
to \fIFALSE (0)\fP when calling \fIxvd_create_xvdisplay\fP or
\fIxvd_init_xvdisplay\fP.  Note:  be aware 
that you make changes to the \fIxvdisplay->xcolors\fP array at your own risk!
.sp 
.B
.sp
xvd_update_xcolors(xvdisplay)
.br
DisplayStructure *xvdisplay;
.sp
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP xvdisplay: 10
A pointer to the active DisplayStructure. 
.LP
 ====================================================================
.sp 3
.NH 2 " xvd_update_region()"
.XS
      \*(SN   xvd_update_region()
.XE
.sp
.LP
Updates a specified region of the currently displayed image, rather
than the entire image.  Only applicable when a specific portion of the
currently displayed image has had a change made to its contents.
Warning - this routine does not free pixels when they are no longer used.
.sp 
.B
.sp
xvd_update_region(xvdisplay, x, y, w, h)
.br
DisplayStructure *xvdisplay;
.br
int x, y;
.br
int w, h;
.sp
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP xvdisplay: 10
A pointer to the active DisplayStructure. 
.IP "x, y":
The (x, y) location of the upper left hand corner of the region in the
image to be updated.
.IP "w, h":
The width and height of the region in the image to be updated.
.LP
 ====================================================================
.sp 3
.NH 2 " xvd_update_pixel()"
.XS
      \*(SN   xvd_update_pixel()
.XE
.sp
.LP
Updates a specific pixel of the currently displayed image.
Only applicable when a specific pixel of the currently displayed image 
has changed.
.sp 
.B
.sp
xvd_update_pixel(xvdisplay, x, y)
.br
DisplayStructure *xvdisplay;
.br
int x, y;
.sp
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP xvdisplay: 10
A pointer to the active DisplayStructure. 
.IP "x, y":
The (x, y) location of the pixel to be changed.
.LP
 ====================================================================
.sp 3
.NH 2 " xvd_query_position()"
.XS
      \*(SN   xvd_query_position()
.XE
.sp
.LP
Finds the position of the cursor 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
int 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 widget: 10
The widget on which you want the (x,y) location of the cursor.  If you are
displaying an image using, for example, \fIxvd_create_raster()\fP, you will
want to pass the \fIraster\fP widget on which the image is displayed;  that
is, \fIxvdisplay->raster\fP.
.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
int 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). 
\fIxvd_query_value()\fP will also return the index into the image map.
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.  
.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 xvdisplay: 10
A pointer to the active DisplayStructure. 
.IP "x, y:"
The (x, y) location of the pixel for which you want the value.  If, for example,
you are printing the value of the pixel under the cursor as it moves across
the image, you may pass in the (x,y) values which were returned by 
\fIxvd_query_position()\fP;  alternatively, you may have other information 
which specifies the (x,y) location in the image for which you need the pixel
value.
.IP value:
Returns the double value of the pixel at the (x, y) location specified.
Pass in NULL if you don't need to know the value.
.IP index:
Returns the integer index for that pixel into the image map.
Pass in NULL if you don't need to know the index.
.IP allocated:
Returns an integer flag indicating whether the currently displayed
pixel color is actually allocated (1), or is the closest available color to
another allocated color (0).  Pass in NULL if you don't need to know
whether the pixel color is allocated.
.LP
=====================================================================
.sp 3
.NH 2 " xvd_clear_image()"
.XS
      \*(SN   xvd_clear_image()
.XE
.sp
.LP
Clears (blanks out) the currently displayed image.
.sp 
.B
.sp
int xvd_clear_image(xvdisplay, free_image)
.br
DisplayStructure *xvdisplay;
.br
int     free_image;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP xvdisplay: 10
A pointer to the active DisplayStructure. 
.IP free_image:
Should the memory associated with the current display image be freed
before the display widget is cleared?  This is done by calling freeimage()
with the display image.  Pass TRUE (1) if so, FALSE (0) if not. 
.LP
=====================================================================
.sp 3
.NH 2 " xvd_clear_shape()"
.XS
      \*(SN   xvd_clear_shape()
.XE
.sp
.LP
Clears (gets rid of) the current shape mask.
.sp 
.B
.sp
int xvd_clear_shape(xvdisplay, free_shape)
.br
DisplayStructure *xvdisplay;
.br
int  free_shape;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP xvdisplay: 10
A pointer to the active DisplayStructure. 
.IP free_shape:
Should the memory associated with the current shape mask image be freed
before the display widget is cleared?  This is done by calling freeimage()
with the shape mask image.  Pass TRUE (1) if so, FALSE (0) if not. 
.LP
=====================================================================
.sp 3
.NH 2 " xvd_clear_clip()"
.XS
      \*(SN   xvd_clear_clip()
.XE
.sp
.LP
Clears (gets rid of) the current clip mask.
.sp 
.B
.sp
int xvd_clear_clip(xvdisplay, free_clip)
.br
DisplayStructure *xvdisplay;
.br
int  free_clip;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP xvdisplay: 10
A pointer to the active DisplayStructure. 
.IP free_clip:
Should the memory associated with the current clip mask image be freed
before the display widget is cleared?  This is done by calling freeimage()
with the clip mask image.  Pass TRUE (1) if so, FALSE (0) if not. 
.LP
=====================================================================
.sp 3
.NH 2 " xvd_clear_overlay()"
.XS
      \*(SN   xvd_clear_overlay()
.XE
.sp
.LP
Clears (gets rid of) the current overlay.
.sp 
.B
.sp
int xvd_clear_overlay(xvdisplay, free_overlay)
.br
DisplayStructure *xvdisplay;
.br
int  free_overlay;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP xvdisplay: 10
A pointer to the active DisplayStructure. 
.IP free_shape:
Should the memory associated with the current overlay image be freed
before the display widget is cleared?  This is done by calling freeimage()
with the overlay image.  Pass TRUE (1) if so, FALSE (0) if not. 
.LP
=====================================================================
.sp 3
.NH 2 " xvd_clear_xvdisplay()"
.XS
      \*(SN   xvd_clear_xvdisplay()
.XE
.sp
.LP
Clears and frees all internal resources associated with the xvdisplay 
structure.  All ximages and pixmaps are cleared, but the input images 
supplied by the user are cleared only if free_images is TRUE (1), otherwise
their fields are simply cleared from the DisplayStructure.
.sp 
.B
.sp
int xvd_clear_xvdisplay(xvdisplay, free_images)
.br
DisplayStructure *xvdisplay;
.br
int free_images;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP xvdisplay: 10
A pointer to the active DisplayStructure. 
.IP free_images:
Should the memory associated with all input images be freed before
clearing the display widget?  The possible images are the display image,
shape mask image, clip mask image, and overlay image.  Pass TRUE (1) if so,
FALSE (0) if not.
.LP
=====================================================================
.sp 3
.NH 2 " xvd_shrink_ximage()"
.XS
      \*(SN   xvd_shrink_ximage()
.XE
.sp
.B
.LP
Takes an ximage, and returns a shrunken ximage of the desired width and
height.  This is commonly used when creating an icon or image to zoom in.
.B
.sp
xvd_shrink_ximage(display, ximage, desired_width, desired_height, subximage)
.br
DisplayStructure *display;
.br
XImage *ximage;
.br
int desired_width, desired_height;
.br
XImage *subximage;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP display: 10
The X Windows Display on which your application will appear.
.IP ximage:
The XImage to be shrunken.
.IP "desired_width, desired_height:" 
The width and height of the desired image. 
.IP subximage:
If you have previously created the subsampled ximage to be used in the
shrinking process, provide it here;  pass NULL if you want the subsampled
ximage created for you.  Note:  if the desired_width or desired_height are
not the same as the current subximage, then a new subximage will be created
and the old one destroyed.
.LP
====================================================================
