1XF86VIDMODE(3)             Library Functions Manual             XF86VIDMODE(3)
2
3
4

NAME

6       XF86VidModeQueryExtension,   XF86VidModeQueryVersion,   XF86VidModeSet‐
7       ClientVersion,   XF86VidModeGetModeLine,    XF86VidModeGetAllModeLines,
8       XF86VidModeAddModeLine,  XF86VidModeDeleteModeLine, XF86VidModeModMode‐
9       Line, XF86VidModeValidateModeLine,  XF86VidModeSwitchMode,  XF86VidMod‐
10       eSwitchToMode,     XF86VidModeLockModeSwitch,    XF86VidModeGetMonitor,
11       XF86VidModeGetViewPort,   XF86VidModeSetViewPort,    XF86VidModeGetDot‐
12       Clocks,  XF86VidModeGetGamma,  XF86VidModeSetGamma,  XF86VidModeGetGam‐
13       maRamp, XF86VidModeSetGammaRamp, XF86VidModeGetGammaRampSize,  XF86Vid‐
14       ModeGetPermissions - Extension library for the XFree86-VidMode X exten‐
15       sion
16

SYNOPSIS

18       #include <X11/extensions/xf86vmode.h>
19
20       Bool XF86VidModeQueryExtension(
21           Display *display,
22           int *event_base_return,
23           int *error_base_return);
24
25       Bool XF86VidModeQueryVersion(
26           Display *display,
27           int *major_version_return,
28           int *minor_version_return);
29
30       Bool XF86VidModeSetClientVersion(
31           Display *display);
32
33       Bool XF86VidModeGetModeLine(
34           Display *display,
35           int screen,
36           int *dotclock_return,
37           XF86VidModeModeLine *modeline);
38
39       Bool XF86VidModeGetAllModeLines(
40           Display *display,
41           int screen,
42           int *modecount_return,
43           XF86VidModeModeInfo ***modesinfo);
44
45       Bool XF86VidModeAddModeLine(
46           Display *display,
47           int screen,
48           XF86VidModeModeInfo *modeline
49           XF86VidModeModeInfo *aftermode);
50
51       Bool XF86VidModeDeleteModeLine(
52           Display *display,
53           int screen,
54           XF86VidModeModeInfo *modeline);
55
56       Bool XF86VidModeModModeLine(
57           Display *display,
58           int screen,
59           XF86VidModeModeLine *modeline);
60
61       Status XF86VidModeValidateModeLine(
62           Display *display,
63           int screen,
64           XF86VidModeModeLine *modeline);
65
66       Bool XF86VidModeSwitchMode(
67           Display *display,
68           int screen,
69           int zoom);
70
71       Bool XF86VidModeSwitchToMode(
72           Display *display,
73           int screen,
74           XF86VidModeModeInfo *modeline);
75
76       Bool XF86VidModeLockModeSwitch(
77           Display *display,
78           int screen,
79           int lock);
80
81       Bool XF86VidModeGetMonitor(
82           Display *display,
83           int screen,
84           XF86VidModeMonitor *monitor);
85
86       Bool XF86VidModeGetViewPort(
87           Display *display,
88           int screen,
89           int *x_return,
90           int *y_return);
91
92       Bool XF86VidModeSetViewPort(
93           Display *display,
94           int screen,
95           int x,
96           int y);
97
98       XF86VidModeGetDotClocks(
99           Display *display,
100           int screen,
101           int *flags return,
102           int *number of clocks return,
103           int *max dot clock return,
104           int **clocks return);
105
106       XF86VidModeGetGamma(
107           Display *display,
108           int screen,
109           XF86VidModeGamma *Gamma);
110
111       XF86VidModeSetGamma(
112           Display *display,
113           int screen,
114           XF86VidModeGamma *Gamma);
115
116       XF86VidModeGetGammaRamp(
117           Display *display,
118           int screen,
119           int size,
120           unsigned short *red array,
121           unsigned short *green array,
122           unsigned short *blue array);
123
124       XF86VidModeSetGammaRamp(
125           Display *display,
126           int screen,
127           int size,
128           unsigned short *red array,
129           unsigned short *green array,
130           unsigned short *blue array);
131
132       XF86VidModeGetGammaRampSize(
133           Display *display,
134           int screen,
135           int *size);
136

ARGUMENTS

138       display             Specifies the connection to the X server.
139
140       screen              Specifies which screen number the setting apply to.
141
142       event_base_return   Returns the base event number for the extension.
143
144       error_base_return   Returns the base error number for the extension.
145
146       major_version_return
147                           Returns the major version number of the extension.
148
149       minor_version_return
150                           Returns the minor version number of the extension.
151
152       dotclock_return     Returns the clock for the mode line.
153
154       modecount_return    Returns the number of video modes available in  the
155                           server.
156
157       zoom                If  greater  than  zero,  indicates that the server
158                           should switch to the next mode, otherwise switch to
159                           the previous mode.
160
161       lock                Indicates  that mode switching should be locked, if
162                           non-zero.
163
164       modeline            Specifies or returns the timing values for a  video
165                           mode.
166
167       aftermode           Specifies  the  timing  values  for  the video mode
168                           after which the new mode will added.
169
170       modesinfo           Returns the timing values and dotclocks for all  of
171                           the available video modes.
172
173       monitor             Returns information about the monitor.
174
175       x                   Specifies the desired X location for the viewport.
176
177       x_return            Returns the current X location of the viewport.
178
179       y                   Specifies the desired Y location for the viewport.
180
181       y_return            Returns the current Y location of the viewport.
182

STRUCTURES

184       Video Mode Settings:
185       typedef struct {
186           unsigned short      hdisplay;       /∗ Number of display pixels horizontally */
187           unsigned short      hsyncstart;     /∗ Horizontal sync start */
188           unsigned short      hsyncend;       /∗ Horizontal sync end */
189           unsigned short      htotal;         /∗ Total horizontal pixels */
190           unsigned short      vdisplay;       /∗ Number of display pixels vertically */
191           unsigned short      vsyncstart;     /∗ Vertical sync start */
192           unsigned short      vsyncend;       /∗ Vertical sync start */
193           unsigned short      vtotal;         /∗ Total vertical pixels */
194           unsigned int        flags;          /∗ Mode flags */
195           int privsize;                       /∗ Size of private */
196           INT32       *private;               /∗ Server privates */
197       } XF86VidModeModeLine;
198
199       typedef struct {
200           unsigned int        dotclock;       /∗ Pixel clock */
201           unsigned short      hdisplay;       /∗ Number of display pixels horizontally */
202           unsigned short      hsyncstart;     /∗ Horizontal sync start */
203           unsigned short      hsyncend;       /∗ Horizontal sync end */
204           unsigned short      htotal;         /∗ Total horizontal pixels */
205           unsigned short      vdisplay;       /∗ Number of display pixels vertically */
206           unsigned short      vsyncstart;     /∗ Vertical sync start */
207           unsigned short      vsyncend;       /∗ Vertical sync start */
208           unsigned short      vtotal;         /∗ Total vertical pixels */
209           unsigned int        flags;          /∗ Mode flags */
210           int privsize;                       /∗ Size of private */
211           INT32       *private;               /∗ Server privates */
212       } XF86VidModeModeInfo;
213
214       Monitor information:
215       typedef struct {
216           char*       vendor;                /∗ Name of manufacturer */
217           char*       model;                 /∗ Model name */
218           float       EMPTY;                 /∗ unused, for backward compatibility */
219           unsigned char nhsync;              /∗ Number of horiz sync ranges */
220           XF86VidModeSyncRange* hsync;       /∗ Horizontal sync ranges */
221           unsigned char nvsync;              /∗ Number of vert sync ranges */
222           XF86VidModeSyncRange* vsync;       /∗ Vertical sync ranges */
223       } XF86VidModeMonitor;
224
225       typedef struct {
226           float       hi;     /∗ Top of range */
227           float       lo;     /∗ Bottom of range */
228       } XF86VidModeSyncRange;
229
230       typedef struct {
231           int type;                   /∗ of event */
232           unsigned long serial;       /∗ # of last request processed by server */
233           Bool send_event;            /∗ true if this came from a SendEvent req */
234           Display *display;           /∗ Display the event was read from */
235           Window root;                /∗ root window of event screen */
236           int state;                  /∗ What happened */
237           int kind;                   /∗ What happened */
238           Bool forced;                /∗ extents of new region */
239           Time time;                  /∗ event timestamp */
240       } XF86VidModeNotifyEvent;
241
242       typedef struct {
243           float red;                  /∗ Red Gamma value */
244           float green;                /∗ Green Gamma value */
245           float blue;                 /∗ Blue Gamma value */
246       } XF86VidModeGamma;
247

DESCRIPTION

249       These   functions   provide   an  interface  to  the  server  extension
250       XFree86-VidModeExtension which allows the video modes to be queried and
251       adjusted dynamically and mode switching to be controlled.  Applications
252       that use these functions must be linked with -lXxf86vm
253
254   MODELINE FUNCTIONS
255       The XF86VidModeGetModeLine function is used to query the  settings  for
256       the  currently  selected video mode.  The calling program should pass a
257       pointer to a XF86VidModeModeLine structure that it  has  already  allo‐
258       cated.  The function fills in the fields of the structure.
259
260       If  there  are  any server private values (currently only applicable to
261       the S3 server) the function will allocate storage for them.  Therefore,
262       if  the  privsize  field  is  non-zero, the calling program should call
263       Xfree(private) to free the storage.
264
265       XF86VidModeGetAllModeLines returns the settings for  all  video  modes.
266       The calling program supplies the address of a pointer which will be set
267       by the function to point to an array of XF86VidModeModeInfo structures.
268       The  memory  occupied  by  the  array  is  dynamically allocated by the
269       XF86VidModeGetAllModeLines function and should be freed by the  caller.
270       The first element of the array corresponds to the current video mode.
271
272       The  XF86VidModeModModeLine function can be used to change the settings
273       of the current video mode provided the  requested  settings  are  valid
274       (e.g. they don't exceed the capabilities of the monitor).
275
276       To  add  a mode to the list of available modes, the XF86VidModeAddMode‐
277       Line function can be used.  Assuming the settings are valid, the  video
278       mode  will  be  added after the existing mode which matches the timings
279       specified by the aftermode parameter.  To be considered a match, all of
280       the  fields  of  the  given  XF86VidModeModeInfo  structure must match,
281       except the privsize and private fields.  If the aftermode parameter  is
282       zero, the mode will be added after the current mode.
283
284       Modes  can be deleted with the XF86VidModeDeleteModeLine function.  The
285       specified mode must match an existing mode.  To be considered a  match,
286       all  of  the  fields  of  the  given XF86VidModeModeInfo structure must
287       match, except the privsize and private  fields.   If  the  mode  to  be
288       deleted  is the current mode, a mode switch to the next mode will occur
289       first.  The last remaining mode can not be deleted.
290
291       The validity of a mode can be checked with the XF86VidModeValidateMode‐
292       Line  function.   If the specified mode can be used by the server (i.e.
293       meets all the constraints placed upon a mode by the combination of  the
294       server,  card,  and monitor) the function returns MODE_OK, otherwise it
295       returns a value indicating the reason  why  the  mode  is  invalid  (as
296       defined in xf86.h)
297
298   MODE SWITCH FUNCTIONS
299       When  the  function  XF86VidModeSwitchMode  is  called, the server will
300       change the video mode to next (or previous) video mode. The XF86VidMod‐
301       eSwitchToMode  function can be used to switch directly to the specified
302       mode.  Matching is as specified in the description of  the  XF86VidMod‐
303       eAddModeLine  function  above.   The XF86VidModeLockModeSwitch function
304       can be used to allow or disallow mode switching whether the request  to
305       switch modes comes from a call to the XF86VidModeSwitchMode or XF86Vid‐
306       ModeSwitchToMode  functions  or  from  one  of  the  mode  switch   key
307       sequences.
308
309       Note:  Because  of the asynchronous nature of the X protocol, a call to
310       XFlush is needed if the application wants to see the mode change  imme‐
311       diately.  To be informed of the execution status of the request, a cus‐
312       tom error handler should be  installed  using  XSetErrorHandler  before
313       calling the mode switching function.
314
315   MONITOR FUNCTIONS
316       Information  known  to  the server about the monitor is returned by the
317       XF86VidModeGetMonitor function.  The hsync and vsync fields each  point
318       to  an  array  of  XF86VidModeSyncRange structures.  The arrays contain
319       nhsync and nvsync elements, respectively.  The hi and low  values  will
320       be equal if a discreate value was given in the XF86Config file.
321
322       The  vendor,  model, hsync, and vsync fields point to dynamically allo‐
323       cated storage that should be freed by the caller.
324
325   VIEWPORT FUNCTIONS
326       The XF86VidModeGetViewPort and XF86VidModeSetViewPort functions can  be
327       used  to, respectively, query and change the location of the upper left
328       corner of the viewport into the virtual screen.
329
330   OTHER FUNCTIONS
331       The XF86VidModeQueryVersion function can be used to determine the  ver‐
332       sion of the extension built into the server.
333
334       The  function  XF86VidModeQueryExtension  returns  the  lowest numbered
335       error and event values assigned to the extension.
336

BUGS

338       The XF86VidModeSetClientVersion,  XF86VidModeGetDotClocks,  XF86VidMod‐
339       eGetGamma,  XF86VidModeSetGamma,  XF86VidModeSetGammaRamp,  XF86VidMod‐
340       eGetGammaRamp, XF86VidModeGetGammaRampSize,  and  XF86VidModeGetPermis‐
341       sions  functions  need  to  be  documented.  In the meantime, check the
342       source code for information about how to use them.
343

SEE ALSO

345       Xorg(1), xorg.conf(5), XFlush(3), XSetErrorHandler(3), xvidtune(1)
346

AUTHORS

348       Kaleb Keithley, Jon Tombs, David Dawes, and Joe Moss
349
350
351
352X Version 11                   libXxf86vm 1.1.4                 XF86VIDMODE(3)
Impressum