NAME

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

SYNTAX



#include

Bool XF86VidModeQueryExtension( Display *_d_i_s_p_l_a_y, int *_e_v_e_n_t___b_a_s_e___r_e_t_u_r_n, int *_e_r_r_o_r___b_a_s_e___r_e_t_u_r_n);

Bool XF86VidModeQueryVersion( Display *_d_i_s_p_l_a_y, int *_m_a_j_o_r___v_e_r_s_i_o_n___r_e_t_u_r_n, int *_m_i_n_o_r___v_e_r_s_i_o_n___r_e_t_u_r_n);

Bool XF86VidModeSetClientVersion( Display *_d_i_s_p_l_a_y);

Bool XF86VidModeGetModeLine( Display *_d_i_s_p_l_a_y, int _s_c_r_e_e_n, int *_d_o_t_c_l_o_c_k___r_e_t_u_r_n, XF86VidModeModeLine *_m_o_d_e_l_i_n_e);

Bool XF86VidModeGetAllModeLines( Display *_d_i_s_p_l_a_y, int _s_c_r_e_e_n, int *_m_o_d_e_c_o_u_n_t___r_e_t_u_r_n, XF86VidModeModeInfo ***_m_o_d_e_s_i_n_f_o);

Bool XF86VidModeDeleteModeLine( Display *_d_i_s_p_l_a_y, int _s_c_r_e_e_n, XF86VidModeModeInfo *_m_o_d_e_l_i_n_e);

Bool XF86VidModeModModeLine( Display *_d_i_s_p_l_a_y, int _s_c_r_e_e_n, XF86VidModeModeLine *_m_o_d_e_l_i_n_e);

Status XF86VidModeValidateModeLine( Display *_d_i_s_p_l_a_y, int _s_c_r_e_e_n, XF86VidModeModeLine *_m_o_d_e_l_i_n_e);

Bool XF86VidModeSwitchMode( Display *_d_i_s_p_l_a_y, int _s_c_r_e_e_n, int _z_o_o_m);

Bool XF86VidModeSwitchToMode( Display *_d_i_s_p_l_a_y, int _s_c_r_e_e_n, XF86VidModeModeInfo *_m_o_d_e_l_i_n_e);

Bool XF86VidModeLockModeSwitch( Display *_d_i_s_p_l_a_y, int _s_c_r_e_e_n, int _l_o_c_k);

Bool XF86VidModeGetMonitor( Display *_d_i_s_p_l_a_y, int _s_c_r_e_e_n, XF86VidModeMonitor *_m_o_n_i_t_o_r);

Bool XF86VidModeGetViewPort( Display *_d_i_s_p_l_a_y, int _s_c_r_e_e_n, int *_x___r_e_t_u_r_n, int *_y___r_e_t_u_r_n);

Bool XF86VidModeSetViewPort( Display *_d_i_s_p_l_a_y, int _s_c_r_e_e_n, int _x, int _y);

XF86VidModeGetDotClocks( Display *_d_i_s_p_l_a_y, int _s_c_r_e_e_n, int *_f_l_a_g_s _r_e_t_u_r_n, int *_n_u_m_b_e_r _o_f _c_l_o_c_k_s _r_e_t_u_r_n, int *_m_a_x _d_o_t _c_l_o_c_k _r_e_t_u_r_n, int **_c_l_o_c_k_s _r_e_t_u_r_n);

XF86VidModeGetGamma( Display *_d_i_s_p_l_a_y, int _s_c_r_e_e_n, XF86VidModeGamma *_G_a_m_m_a);

XF86VidModeSetGamma( Display *_d_i_s_p_l_a_y, int _s_c_r_e_e_n, XF86VidModeGamma *_G_a_m_m_a);

XF86VidModeGetGammaRamp( Display *_d_i_s_p_l_a_y, int _s_c_r_e_e_n, int _s_i_z_e, unsigned short *_r_e_d _a_r_r_a_y, unsigned short *_g_r_e_e_n _a_r_r_a_y, unsigned short *_b_l_u_e _a_r_r_a_y);

XF86VidModeSetGammaRamp( Display *_d_i_s_p_l_a_y, int _s_c_r_e_e_n, int _s_i_z_e, unsigned short *_r_e_d _a_r_r_a_y, unsigned short *_g_r_e_e_n _a_r_r_a_y, unsigned short *_b_l_u_e _a_r_r_a_y);

XF86VidModeGetGammaRampSize( Display *_d_i_s_p_l_a_y, int _s_c_r_e_e_n, int *_s_i_z_e);

ARGUMENTS

_d_i_s_p_l_a_y Specifies the connection to the X server.
_s_c_r_e_e_n Specifies which screen number the setting apply to.
_e_v_e_n_t___b_a_s_e___r_e_t_u_r_n Returns the base event number for the extension.
_e_r_r_o_r___b_a_s_e___r_e_t_u_r_n Returns the base error number for the extension.
_m_a_j_o_r___v_e_r_s_i_o_n___r_e_t_u_r_n Returns the major version number of the extension.
_m_i_n_o_r___v_e_r_s_i_o_n___r_e_t_u_r_n Returns the minor version number of the extension.
_d_o_t_c_l_o_c_k___r_e_t_u_r_n Returns the clock for the mode line.
_m_o_d_e_c_o_u_n_t___r_e_t_u_r_n Returns the number of video modes available in the server.
_z_o_o_m If greater than zero, indicates that the server should switch to
the next mode, otherwise switch to the previous mode.
_l_o_c_k Indicates that mode switching should be locked, if non-zero.
_m_o_d_e_l_i_n_e Specifies or returns the timing values for a video mode.
_m_o_d_e_s_i_n_f_o Returns the timing values and dotclocks for all of the available
video modes.
_m_o_n_i_t_o_r Returns information about the monitor.
_x Specifies the desired X location for the viewport.
_x___r_e_t_u_r_n Returns the current X location of the viewport.
_y Specifies the desired Y location for the viewport.
_y___r_e_t_u_r_n Returns the current Y location of the viewport.

STRUCTURES


_V_i_d_e_o _M_o_d_e _S_e_t_t_i_n_g_s_:
typedef struct {
    unsigned short    hdisplay;    /* Number of display pixels horizontally */
    unsigned short    hsyncstart;  /* Horizontal sync start */
    unsigned short    hsyncend;    /* Horizontal sync end */
    unsigned short    htotal;      /* Total horizontal pixels */
    unsigned short    vdisplay;    /* Number of display pixels vertically */
    unsigned short    vsyncstart;  /* Vertical sync start */
    unsigned short    vsyncend;    /* Vertical sync start */
    unsigned short    vtotal;      /* Total vertical pixels */
    unsigned int      flags;       /* Mode flags */
    int               privsize;    /* Size of private */
    INT32             *private;    /* Server privates */
} XF86VidModeModeLine;


typedef struct { unsigned int dotclock; /* Pixel clock */ unsigned short hdisplay; /* Number of display pixels horizontally */ unsigned short hsyncstart; /* Horizontal sync start */ unsigned short hsyncend; /* Horizontal sync end */ unsigned short htotal; /* Total horizontal pixels */ unsigned short vdisplay; /* Number of display pixels vertically */ unsigned short vsyncstart; /* Vertical sync start */ unsigned short vsyncend; /* Vertical sync start */ unsigned short vtotal; /* Total vertical pixels */ unsigned int flags; /* Mode flags */ int privsize; /* Size of private */ INT32 *private; /* Server privates */ } XF86VidModeModeInfo;

_M_o_n_i_t_o_r _i_n_f_o_r_m_a_t_i_o_n_: typedef struct { char* vendor; /* Name of manufacturer */ char* model; /* Model name */ float EMPTY; /* unused, for backward compatibility */ unsigned char nhsync; /* Number of horiz sync ranges */ XF86VidModeSyncRange* hsync;/* Horizontal sync ranges */ unsigned char nvsync; /* Number of vert sync ranges */ XF86VidModeSyncRange* vsync;/* Vertical sync ranges */ } XF86VidModeMonitor;

typedef struct { float hi; /* Top of range */ float lo; /* Bottom of range */ } XF86VidModeSyncRange;

typedef struct { int type; /* of event */ unsigned long serial; /* # of last request processed by server */ Bool send_event; /* true if this came from a SendEvent req */ Display *display; /* Display the event was read from */ Window root; /* root window of event screen */ int state; /* What happened */ int kind; /* What happened */ Bool forced; /* extents of new region */ Time time; /* event timestamp */ } XF86VidModeNotifyEvent;

typedef struct { float red; /* Red Gamma value */ float green; /* Green Gamma value */ float blue; /* Blue Gamma value */ } XF86VidModeGamma;

DESCRIPTION

These functions provide an interface to the server extension _X_F_r_e_e_8_6_-_V_i_d_M_o_d_e_E_x_t_e_n_s_i_o_n which allows the video modes to be queried and adjusted dynamically and mode switching to be controlled. Applications that use these functions must be linked with _-_l_X_x_f_8_6_v_m

MODELINE FUNCTIONS

The _X_F_8_6_V_i_d_M_o_d_e_G_e_t_M_o_d_e_L_i_n_e function is used to query the settings for the currently selected video mode. The calling program should pass a pointer to a _X_F_8_6_V_i_d_M_o_d_e_M_o_d_e_L_i_n_e structure that it has already allocated. The function fills in the fields of the structure.

If there are any server private values (currently only applicable to the S3 server) the function will allocate storage for them. Therefore, if the _p_r_i_v_s_i_z_e field is non-zero, the calling program should call _X_f_r_e_e_(_p_r_i_v_a_t_e_) to free the storage.

_X_F_8_6_V_i_d_M_o_d_e_G_e_t_A_l_l_M_o_d_e_L_i_n_e_s returns the settings for all video modes. The calling program supplies the address of a pointer which will be set by the function to point to an array of _X_F_8_6_V_i_d_M_o_d_e_M_o_d_e_I_n_f_o structures. The memory occupied by the array is dynamically allocated by the _X_F_8_6_V_i_d_M_o_d_e_G_e_t_A_l_l_M_o_d_e_L_i_n_e_s function and should be freed by the caller. The first element of the array corresponds to the current video mode.

The _X_F_8_6_V_i_d_M_o_d_e_M_o_d_M_o_d_e_L_i_n_e function can be used to change the settings of the current video mode provided the requested settings are valid (e.g. they don't exceed the capabilities of the monitor).

Modes can be deleted with the _X_F_8_6_V_i_d_M_o_d_e_D_e_l_e_t_e_M_o_d_e_L_i_n_e function. The specified mode must match an existing mode. To be considered a match, all of the fields of the given _X_F_8_6_V_i_d_M_o_d_e_M_o_d_e_I_n_f_o structure must match, except the _p_r_i_v_s_i_z_e and _p_r_i_v_a_t_e fields. If the mode to be deleted is the current mode, a mode switch to the next mode will occur first. The last remaining mode can not be deleted.

The validity of a mode can be checked with the _X_F_8_6_V_i_d_M_o_d_e_V_a_l_i_d_a_t_e_M_o_d_e_L_i_n_e function. If the specified mode can be used by the server (i.e. meets all the constraints placed upon a mode by the combination of the server, card, and monitor) the function returns _M_O_D_E___O_K, otherwise it returns a value indicating the reason why the mode is invalid (as defined in _x_f_8_6_._h)

MODE SWITCH FUNCTIONS

When the function _X_F_8_6_V_i_d_M_o_d_e_S_w_i_t_c_h_M_o_d_e is called, the server will change the video mode to next (or previous) video mode. The _X_F_8_6_V_i_d_M_o_d_e_S_w_i_t_c_h_T_o_M_o_d_e function can be used to switch directly to the specified mode. Matching is as specified in the description of the _X_F_8_6_V_i_d_M_o_d_e_A_d_d_M_o_d_e_L_i_n_e function above. The _X_F_8_6_V_i_d_M_o_d_e_L_o_c_k_M_o_d_e_S_w_i_t_c_h function can be used to allow or disallow mode switching whether the request to switch modes comes from a call to the _X_F_8_6_V_i_d_M_o_d_e_S_w_i_t_c_h_M_o_d_e or _X_F_8_6_V_i_d_M_o_d_e_S_w_i_t_c_h_T_o_M_o_d_e functions or from one of the mode switch key sequences.

Because of the asynchronous nature of the X protocol, a call to _X_F_l_u_s_h is needed if the application wants to see the mode change immediately. To be informed of the execution status of the request, a custom error handler should be installed using _X_S_e_t_E_r_r_o_r_H_a_n_d_l_e_r before calling the mode switching function.

MONITOR FUNCTIONS

Information known to the server about the monitor is returned by the _X_F_8_6_V_i_d_M_o_d_e_G_e_t_M_o_n_i_t_o_r function. The _h_s_y_n_c and _v_s_y_n_c fields each point to an array of _X_F_8_6_V_i_d_M_o_d_e_S_y_n_c_R_a_n_g_e structures. The arrays contain _n_h_s_y_n_c and _n_v_s_y_n_c elements, respectively. The _h_i and _l_o_w values will be equal if a discreate value was given in the _X_F_8_6_C_o_n_f_i_g file.

The _v_e_n_d_o_r, _m_o_d_e_l, _h_s_y_n_c, and _v_s_y_n_c fields point to dynamically allocated storage that should be freed by the caller.

VIEWPORT FUNCTIONS

The _X_F_8_6_V_i_d_M_o_d_e_G_e_t_V_i_e_w_P_o_r_t and _X_F_8_6_V_i_d_M_o_d_e_S_e_t_V_i_e_w_P_o_r_t functions can be used to, respectively, query and change the location of the upper left corner of the viewport into the virtual screen.

OTHER FUNCTIONS

The _X_F_8_6_V_i_d_M_o_d_e_Q_u_e_r_y_V_e_r_s_i_o_n function can be used to determine the version of the extension built into the server.

The function _X_F_8_6_V_i_d_M_o_d_e_Q_u_e_r_y_E_x_t_e_n_s_i_o_n returns the lowest numbered error and event values assigned to the extension.

BUGS

The XF86VidModeSetClientVersion, XF86VidModeGetDotClocks, XF86VidModeGetGamma, XF86VidModeSetGamma, XF86VidModeSetGammaRamp, XF86VidModeGetGammaRamp, XF86VidModeGetGammaRampSize, and XF86VidModeGetPermissions functions need to be documented. In the meantime, check the source code for information about how to use them.

SEE ALSO

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

AUTHORS

Kaleb Keithley, Jon Tombs, David Dawes, and Joe Moss