man/Xevi.man

   1 .\" Copyright (c) 1997  Silicon Graphics, Inc.
   2 .\"
   3 .\" Permission is hereby granted, free of charge, to any person obtaining a
   4 .\" copy of this software and associated documentation files (the "Software"),
   5 .\" to deal in the Software without restriction, including without limitation
   6 .\" the rights to use, copy, modify, merge, publish, distribute, sublicense,
   7 .\" and/or sell copies of the Software, and to permit persons to whom the
   8 .\" Software furnished to do so, subject to the following conditions:
   9 .\"
  10 .\" The above copyright notice and this permission notice shall be included in
  11 .\" all copies or substantial portions of the Software.
  12 .\"
  13 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  14 .\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  15 .\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
  16 .\" SILICON GRAPHICS, INC. BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  17 .\" WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
  18 .\" OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  19 .\" SOFTWARE.
  20 .\"
  21 .\" Except as contained in this notice, the name of Silicon Graphics, Inc. shall not
  22 .\" be used in advertising or otherwise to promote the sale, use or other
  23 .\" dealing in this Software without prior written authorization from
  24 .\" Silicon Graphics, Inc.
  25 .\"
  26 .TH XEVI __libmansuffix__ __xorgversion__ "X FUNCTIONS"
  27 .SH NAME
  28 XeviQueryExtension, XeviQueryVersion, XeviGetVisualInfo - X Extended Visual Information functions
  29 .SH SYNOPSIS
  30 \&#include <X11/extensions/XEVI.h>
  31
  32 Bool
  33 XeviQueryExtension (Display *dpy);
  34 .LP
  35 Bool
  36 XeviQueryVersion (Display *dpy,
  37     int *major_version_return,
  38     int *minor_version_return);
  39 .LP
  40 int
  41 XeviGetVisualInfo (Display *dpy, VisualID *visual,
  42     int n_visual, ExtendedVisualInfo ** evi_return,
  43     int * n_info_return);
  44 .fi
  45 .SH DESCRIPTION
  46 The
  47 X11 Extended Visual Information extension (EVI) allows a client to determine
  48 information about core X visuals beyond what the core protocol provides.
  49
  50 The EVI application programming library contains the interfaces described below.
  51 With the exception of
  52 .BR XeviQueryExtension,
  53 if any of these routines are
  54 called with a display that does not support the extension, the
  55 ExtensionErrorHandler (which can be set with
  56 .BR XSetExtensionErrorHandler
  57 and functions the same way as
  58 .BR XSetErrorHandler )
  59 will be called and the function will then return.
  60 .PP
  61 .BR XeviQueryExtension
  62 returns
  63 .BR True
  64 if the Extended Visual Information extension is available on the given display.
  65 A client must call
  66 .BR XeviQueryExtension
  67 before calling any other EVI
  68 function in order to negotiate a compatible protocol version; otherwise
  69 the client will get undefined behavior (EVI may or may not work).
  70 .PP
  71 .BR XeviQueryVersion
  72 returns
  73 .BR True
  74 if the request succeeded; the values of the major and minor protocol
  75 version supported by the server are returned in
  76 .I major_version_return
  77 and
  78 .I minor_version_return.
  79 .PP
  80 .BR XeviGetVisualInfo
  81 returns a list of ExtendedVisualInfo structures that describe
  82 visual information beyond that supported by the core protocol. This includes
  83 layer information relevant for systems supporting overlays and/or underlay
  84 planes, and information that allows applications better to determine the level
  85 of hardware support for multiple colormaps. XeviGetVisualInfo returns
  86 .BR Success
  87 if successful, or an X error otherwise.
  88 If the argument
  89 .I visual
  90 is NULL, then information for all visuals of all
  91 screens is returned. Otherwise, it's a pointer to a list of visuals for which
  92 extended visual information is desired.
  93 .I n_visual
  94 is the number of elements in the array visual.
  95 .I evi_return
  96 returns a pointer to a list of ExtendedVisualInfo. When done, the client
  97 should free the list using XFree\.
  98 .I n_info_return
  99 returns the number of elements in the array evi_return.
 100 .LP
 101 The
 102 .BR ExtendedVisualInfo
 103 structure has the following fields:
 104 .in +.5i
 105 .nf
 106 .ta 1.6i
 107 VisualID        \fIcore_visual_id\fR
 108 int     \fIscreen\fR
 109 int     \fIlevel\fR
 110 unsigned int    \fItransparency_type\fR
 111 unsigned int    \fItransparency_value\fR
 112 unsigned int    \fImin_hw_colormaps\fR
 113 unsigned int    \fImax_hw_colormaps\fR
 114 unsigned int    \fInum_colormap_conflicts\fR
 115 VisualID *      \fIcolormap_conflicts\fR
 116 .fi
 117 .LP
 118 The combination of
 119 .I core_visual_id
 120 and
 121 .I screen
 122 number uniquely specify the visual being described.
 123 .LP
 124 .I level
 125 returns the level number for the visual, 0 for normal planes, > 0 for
 126 overlays, < 0 for underlays.
 127 .LP
 128 .I
 129 transparency_type
 130 returns the type of transparency supported by the visual. XEVI_TRANSPARENCY_NONE if
 131 there are no transparent pixels, XEVI_TRANSPARENCY_PIXEL if the visual supports
 132 a transparent pixel, XEVI_TRANSPARENCY_MASK if the visual supports transparent
 133 plane(s).
 134 .LP
 135 .I transparency_value
 136 returns the pixel/plane value to set for transparency if transparency_type isn't
 137 XEVI_TRANSPARENCY_NONE.
 138 .LP
 139 .I min_hw_colormaps
 140 and
 141 .I max_hw_colormaps
 142 return the minimum and maximum number of hardware colormaps backing up the
 143 visual.
 144 .LP
 145 .I num_colormap_conflicts
 146 returns the number of elements in
 147 .I colormap_conflicts.
 148 This array returns a list of visuals that may cause conflicts in the use of the
 149 hardware colormap. For example, if a 12-bit hardware colormap is overloaded to
 150 support 8-bit colormaps, the corresponding 8-bit visuals would conflict with the
 151 12-bit visuals.
 152
 153 .SH ERRORS
 154 .BR XeviGetVisualInfo
 155 will return
 156 .I BadValue
 157 if passed an illegal visual ID,
 158 .I BadAccess
 159 if the X server does not respond,
 160 .I BadAlloc
 161 if there is a memory allocation failure.