.\" $Header: apputil,v 1.11 90/04/16 17:35:07 scotthe Exp $
\&
.sp 1
.ce 3
\s+1\fBSection 4\fP\s-1

\s+1\fBApplication Utility Functions\fP\s-1
.sp 2
.nr H1 0
.nr H2 0
.nr H3 0
.nr H4 0
.nr H5 0
.na
.LP
.XS
Section 4: Application Utility Functions
.XE
.NH 1
Screen Information Utilities
.XS
\*(SN Screen Information Utilities
.XE
.IN "XVEXOverlapsOfScreen" "" "@DEF@"
.FD 0
Status XVEXOverlapsOfScreen(\^\fIdisplay\fP, \fIscreen_number\fP, \fIinput_overlap\fP, \fIcapture_overlap\fP, \fIio_overlap\fP\^)
.br
    Display *\fIdisplay\fP\^;
.br
    int \fIscreen_number\fP\^;
.br
    Bool *\fIinput_overlap\fP, *\fIcapture_overlap\fP, *\fIio_overlap\fP\^;
.FN
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.IP \fIscreen_number\fP 1i
Specifies the screen to be examined.
.IP \fIinput_overlap\fP 1i
Returns True if VIRs may overlap, False otherwise.
.IP \fIcapture_overlap\fP 1i
Returns True if VORs may overlap, False otherwise.
.IP \fIio_overlap\fP 1i
Returns True if a VIR and a VOR may overlap, False otherwise.
.LP
Status return is non-zero if VEXlib can be initialized.  Otherwise
the return is zero and the return arguments are not updated.
[See VEX Protocol QueryVideo request description]
.sp 5
.ne 35
.IN "XVEXTimestamps" "" "@DEF@"
.FD 0
Status XVEXTimestamps(\^\fIdisplay\fP, \fIscreen_number\fP, \fIvideo_change_time\fP, \fIvideo_connectivity_time\fP\^)
.br
    Display *\fIdisplay\fP\^;
.br
    int \fIscreen_number\fP\^;
.br
    unsigned long *\fIvideo_change_time\fP\^;
.br
    unsigned long *\fIvideo_connectivity_time\fP\^;
.FN
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.IP \fIscreen_number\fP 1i
Specifies the screen to be examined.
.IP \fIvideo_change_time\fP 1i
Returns the most recent time returned by XVEXQueryVideo (the most recent time the
list of video devices changed).
.IP \fIvideo_connectivity_time\fP 1i
Returns the time of the most recent device network change caused by a 
ChangeConnectivity request (reported by a VideoConnectivityState event).
.LP
Status return is non-zero if VEXlib can be initialized.  Otherwise
the return is zero and the return arguments are not updated.
.LP
During the course of a connection to the X server, the list of devices may
change and the connectivity of devices may change.  This routine will report
the most recent times for these changes.  These times are set within
the VEX library when VideoConnectivity events are received
(video_connectivity_time)
and when the XVEXQueryVideo reply is received (video_change_time).
.sp 5
.ne 35
.IN "XVEXGetVisualInfo" "" "@DEF@"
.FD 0
XVisualInfo *XVEXGetVisualInfo\^(\^\fIdisplay\fP, \fIvinfo_mask\fP, \fIvinfo_template\fP, \fInitems_return\fP, \fIinclude_core_visuals\fP\^)
.br
.br
      Display *\fIdisplay\fP\^;
.br
      long \fIvinfo_mask\fP\^;
.br
      XVisualInfo *\fIvinfo_template\fP\^;
.br
      int *\fInitems_return\fP\^;
.br
      Bool \fIinclude_core_visuals\fP\^;
.FN
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.IP \fIvinfo_mask\fP 1i
Specifies the visual mask value.
.IP \fIvinfo_template\fP 1i
Specifies the visual attributes that are to be used in matching the visual
structures.
.IP \fInitems_return\fP 1i
Returns the number of matching visual structures.
.IP \fIinclude_core_visuals\fP 1i
Specifies which visuals lists should be searched.  If the value is True, then
both the Core and the VEX visuals lists are searched, otherwise, only the
VEX list is searched.
.LP
.LP
.PN XVEXGetVisualInfo
function returns a list of visual structures that match the attributes specified
by vinfo_template.
If \fIinclude_core_visuals\fP is False,
it returns only those visuals that are unique to VEX (not
provided in the Core connection information), otherwise it returns visuals
from either the Core list or the VEX list.
Visuals returned by this routine are not guaranteed to have any video
capability;  association with video is determined by XVEXWindowModel
structures returned by
.PN XVEXGetVins
and
.PN XVEXGetVouts .
If no visual structures match the template using the specified vinfo_mask,
.PN XVEXGetVisualInfo
returns a NULL.
To free the data returned by this function, use
.PN XFree .
The choices for vinfo_mask and the definition for the XVisualInfo data 
structure are given in the Core Xlib specification (see
.PN XGetVisualInfo
in Chapter 10, Application
Utility Functions).
Possible values for the class field of the XVisualInfo structure include
VEXVideoGray and VEXVideoColor in addition to the Core class types.
.bp
.IN "XVEXGetVins" "" "@DEF@"
.FD 0
.sp 5
.ne 20
XVEXVin *XVEXGetVins(\^\fIdisplay\fP, \fIscreen_number\fP, \fInitems_return\fP\^)
.br
    Display *\fIdisplay\fP\^;
.br
    int \fIscreen_number\fP\^;
.br
    int *\fInitems_return\fP\^;
.FN
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.IP \fIscreen_number\fP 1i
Specifies the screen to be examined.
.IP \fInitems_return\fP 1i
Returns number of XVEXVin structures in the returned XVEXVin array.
.LP
Returns an array of XVEXVin structures for the named screen.
The array remains valid for the life of the
connection.
Returns NULL if VEXlib cannot be initialized or
cannot allocate space or if there are no VideoInputs for this screen.
To free the data returned by this function, use
.PN XFree .
.sp 5
.ne 20
.IN "XVEXGetVouts" "" "@DEF@"
.FD 0
XVEXVout *XVEXGetVouts(\^\fIdisplay\fP, \fIscreen_number\fP, \fInitems_return\fP\^)
.br
    Display *\fIdisplay\fP\^;
.br
    int \fIscreen_number\fP\^;
.br
    int *\fInitems_return\fP\^;
.FN
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.IP \fIscreen_number\fP 1i
Specifies the screen to be examined.
.IP \fInitems_return\fP 1i
Returns number of XVEXVout structures in the returned XVEXVout array.
.LP
Returns an array of XVEXVout structures for the named screen.
The array remains valid for the life of the
connection.
Returns NULL if VEXlib cannot be initialized or
cannot allocate space or if there are no VideoOutputs for this screen.
To free the data returned by this function, use
.PN XFree .
.sp 5
.ne 20
.IN "XVEXGetVdevs" "" "@DEF@"
.FD 0
XVEXVdev *XVEXGetVdevs(\^\fIdisplay\fP, \fIscreen_number\fP, \fInitems_return\fP\^)
.br
    Display *\fIdisplay\fP\^;
.br
    int \fIscreen_number\fP\^;
.br
    int *\fInitems_return\fP\^;
.FN
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.IP \fIscreen_number\fP 1i
Specifies the screen to be examined.
.IP \fInitems_return\fP 1i
Returns number of XVEXVdev structures in the returned XVEXVdev array.
.LP
Returns an array of XVEXVdev structures for the named screen.  
The information
contained in the array will be out of date once a VideoChange event is received
(because the device list maintained by the X server has changed).
The client should call
.PN XVEXQueryVideo 
to update device lists and/or connectivity, and then call 
.PN XVEXGetVdevs
to get a new array of XVEXVdev structures.
Returns NULL if VEXlib cannot be initialized or
cannot allocate space or if there are no Video devices for this screen.
To free the data returned by this function, use
.PN XFree .
.sp 5
.ne 25
.IN "XVEXGetConnectLabel" "" "@DEF@"
.FD 0
XVEXConnectLabel *XVEXGetConnectLabel(\^\fIdisplay\fP, \fIscreen_number\fP\^)
.br
    Display *\fIdisplay\fP\^;
.br
    int \fIscreen_number\fP\^;
.FN
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.IP \fIscreen_number\fP 1i
Specifies the screen to be examined.
.LP
Returns a XVEXConnectLabel structure which gives the dimensions and row and 
colum labels of connectivity matrices returned by
.PN XVEXGetConnectMatrices
and
.PN XVEXGetConnectState .
Returns NULL if VEXlib cannot be initialized or
cannot allocate space.
To free the data returned by this function, use
.PN XFree .
[See VEX Protocol QueryVideo request description]
.sp 5
.ne 25
.IN "XVEXGetConnectState" "" "@DEF@"
.FD 0
unsigned char **XVEXGetConnectState(\^\fIdisplay\fP, \fIscreen_number\fP, \fIindex_return\fP\^)
.br
    Display *\fIdisplay\fP\^;
.br
    int \fIscreen_number\fP\^;
.br
    long *\fIindex_return\fP\^;
.FN
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.IP \fIscreen_number\fP 1i
Specifies the screen to be examined.
.IP \fIindex_return\fP 1i
Returns the index of the initial state matrix for
the current state.  The index is for the list of
.PN XVEXConnectMatrix
structures returned by 
.PN XVEXGetConnectMatrices .
.LP
Returns a 2 dimensional array of 
.PN XVEXConnectCell
structures describing the current connectivity
of the named screen.  The data is valid only if the client has selected
VEXConnectivity events on the named screen.
This information is valid until a
new XVEXConnectivityEvent is received. A client should call
.PN XVEXGetConnectState
again to get new state information when a XVEXConnectivityEvent
with count of 0 is received.
.LP
Returns NULL if
VEX could not be initialized or if memory allocation failed.
To free the data returned by this function, use
.PN XFree .
.sp 5
.ne 25
.IN "XVEXGetConnectMatrices" "" "@DEF@"
.FD 0
XVEXConnectMatrix *XVEXGetConnectMatrices(\^\fIdisplay\fP, \fIscreen_number\fP, \fInitems_return\fP\^)
.br
    Display *\fIdisplay\fP\^;
.br
    int \fIscreen_number\fP\^;
.br
    long *\fInitems_return\fP\^;
.FN
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.IP \fIscreen_number\fP 1i
Specifies the screen to be examined.
.IP \fInitems_return\fP 1i
Returns the number of matrices in the array.
.LP
Returns a 3 dimensional array of XVEXConnectCell structures.
This array describes the potential connectivity of all video inputs,
outputs and devices.
Each element
of the returned array is a 2 dimensional array whose row and column labels
are given by the current XVEXConnectLabel structure returned by
.PN XVEXGetConnectLabel .
The value of each member of the XVEXConnectCell structure is one of:
.PN VEXConnected ,
.PN VEXNotConnected,
or the maximum potential connectivity.
[See VEX Protocol QueryVideo request description]
.sp 5
.ne 25
.IN "XVEXGetConnectTransitions" "" "@DEF@"
.FD 0
XVEXConnectTransition *XVEXGetConnectTransitions(\^\fIdisplay\fP, \fIscreen_number\fP, \fInitems_return\fP\^)
.br
    Display *\fIdisplay\fP\^;
.br
    int \fIscreen_number\fP\^;
.br
    long *\fInitems_return\fP\^;
.FN
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.IP \fIscreen_number\fP 1i
Specifies the screen to be examined.
.IP \fInitems_return\fP 1i
Returns the number of transitions in the array.
.LP
Returns an array of XVEXConnectTransition structures which
describe the transitions between matrices in the array returned by
.PN XVEXGetConnectMatrices.
[See VEX Protocol QueryVideo request description]
.sp 5
.ne 25
.NH 1
Setting List Utilities
.XS
\*(SN Setting List Utilities
.XE
.IN "XVEXCreateSettingList" "" "@DEF@"
.FD 0
XVEXSetting *XVEXCreateSettingList(\^\fIvid\fP, \fIcontrol_list\fP, \fIncontrol\fP\^)
.br
    VideoID \fIvid\fP;
.br
    XVEXControl *\fIcontrol_list\fP\^;
.br
    int \fIncontrol\fP\^;
.FN
.IP \fIvid\fP 1i
Specifies the video resource for the settings.
.IP \fIcontrol_list\fP 1i
Specifies the array of XVEXControl structures whose settings are desired
.IP \fIncontrol\fP 1i
Specifies the number of elements in the \fIcontrol_list\fP
.LP
Creates an array of XVEXSettings which correspond one-to-one with
the input array of XVEXControls.  Constant data are copied from the XVEXControls
to the XVEXSettings:  name, format, length.  The setting id's are set to
\fIvid\fP .
Space is allocated for value data for each XVEXSetting structure and the
pointer element points to this data.
.LP
If VEXlib cannot allocate space, the return will be NULL.
To free the data returned by this function, use
.PN XFree .
.sp 5
.ne 30
.NH 1
Range Searching Utilities
.XS
\*(SN Range Searching Utilities
.XE
.IN "XVEXMatchFraction" "" "@DEF@"
.FD 0
Bool XVEXMatchFraction(\^\fIgiven\fP, \fIrange\fP, \fIlower\fP, \fIhigher\fP\^)
.br
    XVEXFraction *\fIgiven\fP\^;
.br
    XVEXFractionRange *\fIrange\fP\^;
.br
    XVEXFraction *\fIlower\fP\^;
.br
    XVEXFraction *\fIhigher\fP\^;
.FN
.IP \fIgiven\fP 1i
Specifies the fraction to be checked.
.IP \fIrange\fP 1i
Specifies the fraction range to be compared against.
.IP \fIlower\fP 1i
Returns the nearest lower fraction in the range.
.IP \fIhigher\fP 1i
Returns the nearest lower higher in the range.
.LP
Returns True if \fIgiven\fP is numerically equal to a fraction in 
\fIrange\fP,
in which case \fIlower\fP and \fIhigher\fP are returned numerically equal to
\fIgiven\fP, with the smallest values for numerator and denominator within
\fIrange\fP.  For example, if \fIgiven\fP is 22/33, \fIlower\fP
and \fIhigher\fP could
be 2/3 even if 22/33 is also in \fIrange\fP.
.LP
Returns False otherwise.  If \fIgiven\fP is between the top and bottom of
\fIrange\fP, then \fIlower\fP is the closest fraction in \fIrange\fP
of less value and
\fIhigher\fP is the closest fraction in \fIrange\fP of greater value.
If \fIgiven\fP
is below \fIrange\fP, both \fIlower\fP and \fIhigher\fP
are the bottom of \fIrange\fP,
while if above both are the top.
.LP
One use of this function is to make sure a src and dest match according to
the x_scale and y_scale ranges, so that the 
.PN XVEXRenderVideo
or
.PN XVEXCaptureGraphics
functions do not get an error.
.sp 5
.ne 30
.IN "XVEXMatchRectangle" "" "@DEF@"
.FD 0
Bool XVEXMatchRectangle(\^\fIgiven\fP, \fIrange\fP, \fIenclosed\fP, \fIenclosing\fP\^)
.br
    XRectangle *\fIgiven\fP\^;
.br
    XVEXRectangleRange *\fIrange\fP\^;
.br
    XRectangle *\fIenclosed\fP\^;
.br
    XRectangle *\fIenclosing\fP\^;
.FN
.IP \fIgiven\fP 1i
Specifies a given rectangle.
.IP \fIrange\fP 1i
Specifies a rectangle range.
.IP \fIenclosed\fP 1i
Returns the largest rectangle in the range that is
enclosed by the given rectangle, if possible.
.IP \fIenclosing\fP 1i
Returns the smallest rectangle in the range that
encloses the given rectangle, if possible.
.LP
Returns True if \fIgiven\fP exactly matches a rectangle in \fIrange\fP.
Then both
\fIenclosed\fP and \fIenclosing\fP are returned equal to \fIgiven\fP.
.LP
Returns false otherwise.  If \fIgiven\fP is within the extents of \fIrange\fP,
then \fIenclosed\fP is the largest rectangle in \fIrange\fP that is completely
enclosed by \fIgiven\fP and \fIenclosing\fP is the smallest rectangle in 
\fIrange\fP
that completely encloses \fIgiven\fP.  But if \fIgiven\fP is partially or
completely outside the extents of \fIrange\fP, then \fIenclosed\fP
and \fIenclosing\fP
are as close as possible to being enclosed/enclosing while still being
rectangles in \fIrange\fP.
.LP
This function can be used to find either the proper enclosing area
around a desired source area or the largest proper destination area
within a given boundary, for rendering video or capturing graphics.
.bp
