man/XF86VM.man

   1 .\"
   2 .\" Copyright (c) 1996  Joe Moss, The XFree86 Project
   3 .\"
   4 .de ZN
   5 .ie t \fB\^\\$1\^\fR\\$2
   6 .el \fI\^\\$1\^\fP\\$2
   7 ..
   8 .TH XF86VIDMODE __libmansuffix__ __vendorversion__
   9 .SH NAME
  10 XF86VidModeQueryExtension, XF86VidModeQueryVersion, XF86VidModeSetClientVersion, XF86VidModeGetModeLine, XF86VidModeGetAllModeLines, XF86VidModeDeleteModeLine, XF86VidModeModModeLine, XF86VidModeValidateModeLine, XF86VidModeSwitchMode, XF86VidModeSwitchToMode, XF86VidModeLockModeSwitch, XF86VidModeGetMonitor, XF86VidModeGetViewPort, XF86VidModeSetViewPort, XF86VidModeGetDotClocks, XF86VidModeGetGamma, XF86VidModeSetGamma, XF86VidModeGetGammaRamp, XF86VidModeSetGammaRamp, XF86VidModeGetGammaRampSize, XF86VidModeGetPermissions \- Extension library for the XFree86-VidMode X extension
  11 .SH SYNTAX
  12 .nf
  13 .LP
  14 \&#include <X11/extensions/xf86vmode.h>
  15 .LP
  16 Bool XF86VidModeQueryExtension(
  17     Display *\fIdisplay\fP\^,
  18     int *\fIevent_base_return\fP\^,
  19     int *\fIerror_base_return\fP\^);
  20 .LP
  21 Bool XF86VidModeQueryVersion(
  22     Display *\fIdisplay\fP\^,
  23     int *\fImajor_version_return\fP\^,
  24     int *\fIminor_version_return\fP\^);
  25 .LP
  26 Bool XF86VidModeSetClientVersion(
  27     Display *\fIdisplay\fP\^);
  28 .LP
  29 Bool XF86VidModeGetModeLine(
  30     Display *\fIdisplay\fP\^,
  31     int \fIscreen\fP\^,
  32     int *\fIdotclock_return\fP\^,
  33     XF86VidModeModeLine *\fImodeline\fP\^);
  34 .LP
  35 Bool XF86VidModeGetAllModeLines(
  36     Display *\fIdisplay\fP\^,
  37     int \fIscreen\fP\^,
  38     int *\fImodecount_return\fP\^,
  39     XF86VidModeModeInfo ***\fImodesinfo\fP\^);
  40 .ig
  41 .LP
  42 Bool XF86VidModeAddModeLine(
  43     Display *\fIdisplay\fP\^,
  44     int \fIscreen\fP\^,
  45     XF86VidModeModeInfo *\fImodeline\fP\,
  46     XF86VidModeModeInfo *\fIaftermode\fP\^);
  47 ..
  48 .LP
  49 Bool XF86VidModeDeleteModeLine(
  50     Display *\fIdisplay\fP\^,
  51     int \fIscreen\fP\^,
  52     XF86VidModeModeInfo *\fImodeline\fP\^);
  53 .LP
  54 Bool XF86VidModeModModeLine(
  55     Display *\fIdisplay\fP\^,
  56     int \fIscreen\fP\^,
  57     XF86VidModeModeLine *\fImodeline\fP\^);
  58 .LP
  59 Status XF86VidModeValidateModeLine(
  60     Display *\fIdisplay\fP\^,
  61     int \fIscreen\fP\^,
  62     XF86VidModeModeLine *\fImodeline\fP\^);
  63 .LP
  64 Bool XF86VidModeSwitchMode(
  65     Display *\fIdisplay\fP\^,
  66     int \fIscreen\fP\^,
  67     int \fIzoom\fP\^);
  68 .LP
  69 Bool XF86VidModeSwitchToMode(
  70     Display *\fIdisplay\fP\^,
  71     int \fIscreen\fP\^,
  72     XF86VidModeModeInfo *\fImodeline\fP\^);
  73 .LP
  74 Bool XF86VidModeLockModeSwitch(
  75     Display *\fIdisplay\fP\^,
  76     int \fIscreen\fP\^,
  77     int \fIlock\fP\^);
  78 .LP
  79 Bool XF86VidModeGetMonitor(
  80     Display *\fIdisplay\fP\^,
  81     int \fIscreen\fP\^,
  82     XF86VidModeMonitor *\fImonitor\fP\^);
  83 .LP
  84 Bool XF86VidModeGetViewPort(
  85     Display *\fIdisplay\fP\^,
  86     int \fIscreen\fP\^,
  87     int *\fIx_return\fP\^,
  88     int *\fIy_return\fP\^);
  89 .LP
  90 Bool XF86VidModeSetViewPort(
  91     Display *\fIdisplay\fP\^,
  92     int \fIscreen\fP\^,
  93     int \fIx\fP\^,
  94     int \fIy\fP\^);
  95 .LP
  96 XF86VidModeGetDotClocks(
  97     Display *\fIdisplay\fP\^,
  98     int \fIscreen\fP\^,
  99     int *\fIflags return\fP\^,
 100     int *\fInumber of clocks return\fP\^,
 101     int *\fImax dot clock return\fP\^,
 102     int **\fIclocks return\fP\^);
 103 .LP
 104 XF86VidModeGetGamma(
 105     Display *\fIdisplay\fP\^,
 106     int \fIscreen\fP\^,
 107     XF86VidModeGamma *\fIGamma\fP\^);
 108 .LP
 109 XF86VidModeSetGamma(
 110     Display *\fIdisplay\fP\^,
 111     int \fIscreen\fP\^,
 112     XF86VidModeGamma *\fIGamma\fP\^);
 113 .LP
 114 XF86VidModeGetGammaRamp(
 115     Display *\fIdisplay\fP\^,
 116     int \fIscreen\fP\^,
 117     int \fIsize\fP\^,
 118     unsigned short *\fIred array\fP\^,
 119     unsigned short *\fIgreen array\fP\^,
 120     unsigned short *\fIblue array\fP\^);
 121 .LP
 122 XF86VidModeSetGammaRamp(
 123     Display *\fIdisplay\fP\^,
 124     int \fIscreen\fP\^,
 125     int \fIsize\fP\^,
 126     unsigned short *\fIred array\fP\^,
 127     unsigned short *\fIgreen array\fP\^,
 128     unsigned short *\fIblue array\fP\^);
 129 .LP
 130 XF86VidModeGetGammaRampSize(
 131     Display *\fIdisplay\fP\^,
 132     int \fIscreen\fP\^,
 133     int *\fIsize\fP\^);
 134 .fi
 135 .SH ARGUMENTS
 136 .IP \fIdisplay\fP 2i
 137 Specifies the connection to the X server.
 138 .IP \fIscreen\fP 2i
 139 Specifies which screen number the setting apply to.
 140 .IP \fIevent_base_return\fP 2i
 141 Returns the base event number for the extension.
 142 .IP \fIerror_base_return\fP 2i
 143 Returns the base error number for the extension.
 144 .IP \fImajor_version_return\fP 2i
 145 Returns the major version number of the extension.
 146 .IP \fIminor_version_return\fP 2i
 147 Returns the minor version number of the extension.
 148 .IP \fIdotclock_return\fP 2i
 149 Returns the clock for the mode line.
 150 .IP \fImodecount_return\fP 2i
 151 Returns the number of video modes available in the server.
 152 .IP \fIzoom\fP 2i
 153 If greater than zero, indicates that the server should switch to
 154 the next mode, otherwise switch to the previous mode.
 155 .IP \fIlock\fP 2i
 156 Indicates that mode switching should be locked, if non-zero.
 157 .IP \fImodeline\fP 2i
 158 Specifies or returns the timing values for a video mode.
 159 .ig
 160 .IP \fIaftermode\fP 2i
 161 Specifies the timing values for the video mode after which the
 162 new mode will added.
 163 ..
 164 .IP \fImodesinfo\fP 2i
 165 Returns the timing values and dotclocks for all of the available
 166 video modes.
 167 .IP \fImonitor\fP 2i
 168 Returns information about the monitor.
 169 .IP \fIx\fP 2i
 170 Specifies the desired X location for the viewport.
 171 .IP \fIx_return\fP 2i
 172 Returns the current X location of the viewport.
 173 .IP \fIy\fP 2i
 174 Specifies the desired Y location for the viewport.
 175 .IP \fIy_return\fP 2i
 176 Returns the current Y location of the viewport.
 177 .SH STRUCTURES
 178 .nf
 179 .ta 2.25i 3.5i
 180 \fIVideo Mode Settings:\fP
 181 typedef struct {
 182     unsigned short      hdisplay;       /\(** Number of display pixels horizontally */
 183     unsigned short      hsyncstart;     /\(** Horizontal sync start */
 184     unsigned short      hsyncend;       /\(** Horizontal sync end */
 185     unsigned short      htotal; /\(** Total horizontal pixels */
 186     unsigned short      vdisplay;       /\(** Number of display pixels vertically */
 187     unsigned short      vsyncstart;     /\(** Vertical sync start */
 188     unsigned short      vsyncend;       /\(** Vertical sync start */
 189     unsigned short      vtotal; /\(** Total vertical pixels */
 190     unsigned int        flags;  /\(** Mode flags */
 191     int privsize;       /\(** Size of private */
 192     INT32       *private;       /\(** Server privates */
 193 } XF86VidModeModeLine;
 194 .sp
 195 typedef struct {
 196     unsigned int        dotclock;       /\(** Pixel clock */
 197     unsigned short      hdisplay;       /\(** Number of display pixels horizontally */
 198     unsigned short      hsyncstart;     /\(** Horizontal sync start */
 199     unsigned short      hsyncend;       /\(** Horizontal sync end */
 200     unsigned short      htotal; /\(** Total horizontal pixels */
 201     unsigned short      vdisplay;       /\(** Number of display pixels vertically */
 202     unsigned short      vsyncstart;     /\(** Vertical sync start */
 203     unsigned short      vsyncend;       /\(** Vertical sync start */
 204     unsigned short      vtotal; /\(** Total vertical pixels */
 205     unsigned int        flags;  /\(** Mode flags */
 206     int privsize;       /\(** Size of private */
 207     INT32       *private;       /\(** Server privates */
 208 } XF86VidModeModeInfo;
 209 .LP
 210 \fIMonitor information:\fP
 211 typedef struct {
 212     char*       vendor; /\(** Name of manufacturer */
 213     char*       model;  /\(** Model name */
 214     float       EMPTY;  /\(** unused, for backward compatibility */
 215     unsigned char       nhsync; /\(** Number of horiz sync ranges */
 216     XF86VidModeSyncRange*       hsync;  /\(** Horizontal sync ranges */
 217     unsigned char       nvsync; /\(** Number of vert sync ranges */
 218     XF86VidModeSyncRange*       vsync;  /\(** Vertical sync ranges */
 219 } XF86VidModeMonitor;
 220 .sp
 221 typedef struct {
 222     float       hi;     /\(** Top of range */
 223     float       lo;     /\(** Bottom of range */
 224 } XF86VidModeSyncRange;
 225 .LP
 226 typedef struct {
 227     int type;                   /\(** of event */
 228     unsigned long serial;       /\(** # of last request processed by server */
 229     Bool send_event;            /\(** true if this came from a SendEvent req */
 230     Display *display;           /\(** Display the event was read from */
 231     Window root;                /\(** root window of event screen */
 232     int state;                  /\(** What happened */
 233     int kind;                   /\(** What happened */
 234     Bool forced;                /\(** extents of new region */
 235     Time time;                  /\(** event timestamp */
 236 } XF86VidModeNotifyEvent;
 237 .LP
 238 typedef struct {
 239     float red;                  /\(** Red Gamma value */
 240     float green;                /\(** Green Gamma value */
 241     float blue;                 /\(** Blue Gamma value */
 242 } XF86VidModeGamma;
 243 .fi
 244 .SH DESCRIPTION
 245 These functions provide an interface to the server extension
 246 \fIXFree86-VidModeExtension\fP
 247 which allows the video modes to be
 248 queried and adjusted dynamically and mode switching to be controlled.
 249 Applications that use these functions must be linked with
 250 .ZN -lXxf86vm
 251 .SS "MODELINE FUNCTIONS"
 252 The
 253 .ZN XF86VidModeGetModeLine
 254 function is used to query the settings for the currently selected
 255 video mode.  The calling program should pass a pointer to a
 256 .ZN XF86VidModeModeLine
 257 structure that it has already allocated.  The function fills in
 258 the fields of the structure.
 259 .PP
 260 If there are any server private values (currently only applicable to
 261 the S3 server) the function will allocate storage for them.
 262 Therefore, if the
 263 .ZN privsize
 264 field is non-zero, the calling program should call
 265 .ZN Xfree(private)
 266 to free the storage.
 267 .PP
 268 .ZN XF86VidModeGetAllModeLines
 269 returns the settings for all video modes.
 270 The calling program supplies the address of a pointer which will be
 271 set by the function to point to an array of
 272 .ZN XF86VidModeModeInfo
 273 structures.  The memory occupied by the array is dynamically allocated
 274 by the
 275 .ZN XF86VidModeGetAllModeLines
 276 function and should be freed by the caller.
 277 The first element of the array corresponds to the current video mode.
 278 .PP
 279 The
 280 .ZN XF86VidModeModModeLine
 281 function can be used to change the settings of the current video mode
 282 provided the requested settings are valid (e.g. they don't exceed the
 283 capabilities of the monitor).
 284 .PP
 285 .ig
 286 To add a mode to the list of available modes, the
 287 .ZN XF86VidModeAddModeLine
 288 function can be used.
 289 Assuming the settings are valid, the video mode will be added after
 290 the existing mode which matches the timings specified by the
 291 .ZN aftermode
 292 parameter.
 293 To be considered a match, all of the fields of the given
 294 .ZN XF86VidModeModeInfo
 295 structure must match, except the
 296 .ZN privsize
 297 and
 298 .ZN private
 299 fields.
 300 If the
 301 .ZN aftermode
 302 parameter is zero, the mode will be added
 303 after the current mode.
 304 .PP
 305 ..
 306 Modes can be deleted with the
 307 .ZN XF86VidModeDeleteModeLine
 308 function.  The specified mode must match an existing mode.
 309 To be considered a match, all of the fields of the given
 310 .ZN XF86VidModeModeInfo
 311 structure must match, except the
 312 .ZN privsize
 313 and
 314 .ZN private
 315 fields.
 316 If the mode to be deleted is the current mode, a mode switch
 317 to the next mode will occur first.  The last remaining mode can not
 318 be deleted.
 319 .PP
 320 The validity of a mode can be checked with the
 321 .ZN XF86VidModeValidateModeLine
 322 function.
 323 If the specified mode can be used by the server (i.e. meets all the
 324 constraints placed upon a mode by the combination of the server, card,
 325 and monitor) the function returns
 326 .ZN MODE_OK ,
 327 otherwise it returns a value indicating the reason why the mode is
 328 invalid (as defined in \fIxf86.h\fP)
 329 .SS "MODE SWITCH FUNCTIONS"
 330 When the function
 331 .ZN XF86VidModeSwitchMode
 332 is called, the server will change the video mode to next (or previous)
 333 video mode. The
 334 .ZN XF86VidModeSwitchToMode
 335 function can be used to switch directly to the specified mode.
 336 Matching is as specified in the description of the
 337 .ZN XF86VidModeAddModeLine
 338 function above.
 339 The
 340 .ZN XF86VidModeLockModeSwitch
 341 function can be used to allow or disallow mode switching whether
 342 the request to switch modes comes from a call to the
 343 .ZN XF86VidModeSwitchMode
 344 or
 345 .ZN XF86VidModeSwitchToMode
 346 functions or from one of the mode switch key sequences.
 347 .PP
 348 .RB Note:
 349 Because of the asynchronous nature of the X protocol, a call to
 350 .ZN XFlush
 351 is needed if the application wants to see the mode change immediately.
 352 To be informed of the execution status of the request, a
 353 custom error handler should be installed using
 354 .ZN XSetErrorHandler
 355 before calling the mode switching function.
 356 .SS "MONITOR FUNCTIONS"
 357 Information known to the server about the monitor is returned by the
 358 .ZN XF86VidModeGetMonitor
 359 function.  The
 360 .ZN hsync
 361 and
 362 .ZN vsync
 363 fields each point to an array of
 364 .ZN XF86VidModeSyncRange
 365 structures.  The arrays contain
 366 .ZN nhsync
 367 and
 368 .ZN nvsync
 369 elements, respectively.
 370 The
 371 .ZN hi
 372 and
 373 .ZN low
 374 values will be equal if a discreate value was given in the
 375 .ZN XF86Config
 376 file.
 377 .PP
 378 The
 379 .ZN vendor ,
 380 .ZN model ,
 381 .ZN hsync ,
 382 and
 383 .ZN vsync
 384 fields point to dynamically allocated storage that should be freed
 385 by the caller.
 386 .SS "VIEWPORT FUNCTIONS"
 387 The
 388 .ZN XF86VidModeGetViewPort
 389 and
 390 .ZN XF86VidModeSetViewPort
 391 functions can be used to, respectively, query and change the location
 392 of the upper left corner of the viewport into the virtual screen.
 393 .SS "OTHER FUNCTIONS"
 394 The
 395 .ZN XF86VidModeQueryVersion
 396 function can be used to determine the version of the extension
 397 built into the server.
 398 .PP
 399 The function
 400 .ZN XF86VidModeQueryExtension
 401 returns the lowest numbered error and event values
 402 assigned to the extension.
 403 .SH BUGS
 404 The
 405 XF86VidModeSetClientVersion,
 406 XF86VidModeGetDotClocks,
 407 XF86VidModeGetGamma,
 408 XF86VidModeSetGamma,
 409 XF86VidModeSetGammaRamp,
 410 XF86VidModeGetGammaRamp,
 411 XF86VidModeGetGammaRampSize,
 412 and
 413 XF86VidModeGetPermissions
 414 functions need to be documented.  In the meantime, check the source
 415 code for information about how to use them.
 416 .SH SEE ALSO
 417 __xservername__(__appmansuffix__), __xconfigfile__(__filemansuffix__), XFlush(__libmansuffix__), XSetErrorHandler(__libmansuffix__), xvidtune(__appmansuffix__)
 418 .SH AUTHORS
 419 Kaleb Keithley, Jon Tombs, David Dawes, and Joe Moss