man/XF86VM.man

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