421 lines
13 KiB
HTML
421 lines
13 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of XRANDR</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>XRANDR</H1>
|
|
Section: C Library Functions (3)<BR>Updated: libXrandr 1.5.2<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<P>
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
<BR> Xrandr - X Resize, Rotate and Reflection extension.
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNTAX</H2>
|
|
|
|
#include <<A HREF="file:///usr/include/X11/extensions/Xrandr.h">X11/extensions/Xrandr.h</A>>
|
|
<PRE>
|
|
|
|
Bool XRRQueryExtension (Display *<I>dpy</I>,
|
|
int *<I>event_base_return</I>, int *<I>error_base_return</I>);
|
|
|
|
Status XRRQueryVersion (Display *<I>dpy</I>,
|
|
int *<I>major_version_return</I>,
|
|
int *<I>minor_version_return</I>);
|
|
|
|
XRRScreenConfiguration *XRRGetScreenInfo (Display *dpy,
|
|
Drawable <I>draw</I>);
|
|
|
|
void XRRFreeScreenConfigInfo (
|
|
<I>XRRScreenConfiguration *config</I>);
|
|
|
|
Status XRRSetScreenConfig (Display *<I>dpy</I>,
|
|
XRRScreenConfiguration *<I>config</I>,
|
|
Drawable <I>draw</I>,
|
|
int <I>size_index</I>,
|
|
Rotation <I>rotation</I>,
|
|
Time <I>timestamp</I>);
|
|
|
|
Status XRRSetScreenConfigAndRate (Display *<I>dpy</I>,
|
|
XRRScreenConfiguration *<I>config</I>,
|
|
Drawable <I>draw</I>,
|
|
int <I>size_index</I>,
|
|
Rotation <I>rotation</I>,
|
|
short <I>rate</I>,
|
|
Time <I>timestamp</I>);
|
|
|
|
Rotation XRRConfigRotations(
|
|
XRRScreenConfiguration *<I>config</I>,
|
|
Rotation *<I>current_rotation</I>);
|
|
|
|
Time XRRConfigTimes (
|
|
XRRScreenConfiguration *<I>config</I>,
|
|
Time *<I>config_timestamp</I>);
|
|
|
|
XRRScreenSize *XRRConfigSizes(
|
|
XRRScreenConfiguration *<I>config</I>,
|
|
int *<I>nsizes</I>);
|
|
|
|
short *XRRConfigRates (
|
|
XRRScreenConfiguration *<I>config</I>,
|
|
int <I>size_index</I>,
|
|
int *<I>nrates</I>);
|
|
|
|
SizeID XRRConfigCurrentConfiguration (
|
|
XRRScreenConfiguration *<I>config</I>,
|
|
Rotation *<I>rotation</I>);
|
|
|
|
short XRRConfigCurrentRate (
|
|
XRRScreenConfiguration *<I>config</I>);
|
|
|
|
int XRRRootToScreen(
|
|
Display *<I>dpy</I>,
|
|
Window <I>root</I>);
|
|
|
|
void XRRSelectInput(Display *<I>dpy</I>, Window <I>window</I>, int <I>mask</I>);
|
|
|
|
/*
|
|
* intended to take RRScreenChangeNotify, or
|
|
* ConfigureNotify (<I>on the root window</I>)
|
|
* returns 1 if it is an event type it understands, 0 if not
|
|
*/
|
|
int XRRUpdateConfiguration(XEvent *<I>event</I>);
|
|
|
|
/*
|
|
* the following are always safe to call, even if RandR is
|
|
* not implemented on a screen
|
|
*/
|
|
<BR>
|
|
Rotation XRRRotations(
|
|
Display *<I>dpy</I>, int <I>screen</I>,
|
|
Rotation *<I>current_rotation</I>);
|
|
|
|
XRRScreenSize *XRRSizes(Display *<I>dpy</I>,
|
|
int <I>screen</I>, int *<I>nsizes</I>);
|
|
|
|
short *XRRRates (Display *<I>dpy</I>, int <I>screen</I>,
|
|
int <I>size_index</I>, int *<I>nrates</I>);
|
|
|
|
Time XRRTimes (Display *<I>dpy</I>, int <I>screen</I>, Time *<I>config_timestamp</I>);
|
|
</PRE>
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>ARGUMENTS</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="1"><I>display</I><DD>
|
|
Specifies the connection to the X server.
|
|
<DT id="2"><I>screen</I><DD>
|
|
Specifies which screen.
|
|
<DT id="3"><I>draw</I><DD>
|
|
Specifies the screen.
|
|
<DT id="4"><I>rotation</I><DD>
|
|
Specifies the possible rotations or reflections of the screen.
|
|
<DT id="5"><I>current_rotation</I><DD>
|
|
Specifies the current rotations and reflection of the screen.
|
|
<DT id="6"><I>timestamp</I><DD>
|
|
Specifies the server timestamp.
|
|
<DT id="7"><I>config_timestamp</I><DD>
|
|
Specifies the timestamp when the screen was last (re)configured.
|
|
<DT id="8"><I>config</I><DD>
|
|
Specifies the screen configuration being used.
|
|
<DT id="9"><I>sizes</I><DD>
|
|
Specifies the array of supported sizes.
|
|
<DT id="10"><I>rate</I><DD>
|
|
Specifies the refresh rate in Hz.
|
|
<P>
|
|
</DL>
|
|
<A NAME="lbAE"> </A>
|
|
<H2>DATATYPES</H2>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<B>Rotations/Reflections</B>
|
|
|
|
<P>
|
|
|
|
Can be any of:
|
|
<PRE>
|
|
#define RR_Rotate_0 1
|
|
#define RR_Rotate_90 2
|
|
#define RR_Rotate_180 4
|
|
#define RR_Rotate_270 8
|
|
|
|
/* new in 1.0 protocol, to allow reflection of screen */
|
|
/* reflection is applied after rotation */
|
|
|
|
#define RR_Reflect_X 16
|
|
#define RR_Reflect_Y 32
|
|
|
|
|
|
typedef struct {
|
|
int width, height;
|
|
int mwidth, mheight;
|
|
} XRRScreenSize;
|
|
|
|
typedef struct {
|
|
int type; /* event base */
|
|
unsigned long serial; /* # of last request processed by server */
|
|
Bool send_event; /* true if this came from a SendEvent request */
|
|
Display *display; /* Display the event was read from */
|
|
Window window; /* window which selected for this event */
|
|
Window root; /* Root window for changed screen */
|
|
Time timestamp; /* when the screen change occurred */
|
|
Time config_timestamp; /* when the last configuration change */
|
|
SizeID size_index;
|
|
SubpixelOrder subpixel_order;
|
|
Rotation rotation;
|
|
int width;
|
|
int height;
|
|
int mwidth;
|
|
int mheight;
|
|
} XRRScreenChangeNotifyEvent;
|
|
|
|
</PRE>
|
|
|
|
The
|
|
<B>XRRScreenSize</B>
|
|
|
|
structure contains a possible root size in pixels and in millimeters.
|
|
<P>
|
|
A
|
|
<B>XRRScreenChangeNotifyEvent</B>
|
|
|
|
is sent to a client that has requested notification whenever the screen
|
|
configuration is changed. A client can perform this request by calling
|
|
<B>XRRSelectInput</B>, passing the display, the root window, and the
|
|
<B>RRScreenChangeNotifyMask</B> mask.
|
|
<P>
|
|
<B>XRRScreenConfiguration</B>
|
|
|
|
is an opaque data type containing the configuration information
|
|
for a screen.
|
|
<P>
|
|
<B>Timestamps</B>
|
|
|
|
<P>
|
|
|
|
Time stamps are included and must be used to ensure the client is playing
|
|
with a full deck: the screen may change properties
|
|
on the fly and this ensures its knowledge of the configuration is up to date.
|
|
This is to help issues when screens may become hot-pluggable in the future.
|
|
<P>
|
|
<A NAME="lbAF"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
<B>Xrandr</B>
|
|
|
|
is a simple library designed to interface the X Resize and Rotate
|
|
Extension. This allows clients to change the size and rotation of the
|
|
root window of a screen, along with the ability to reflect the screen
|
|
about either axis (if supported by the implementation). Rotation and
|
|
reflection may be implemented by software and may result in slower
|
|
performance if rotation and reflection are implemented in this fashion
|
|
(as are all implementations as of October 2002).
|
|
<P>
|
|
|
|
The Xrandr library does some minimal caching to avoid roundtrips to
|
|
provide clients frequently used information. See "The X Resize and
|
|
Rotate Extension" for a detailed description; also note that depth
|
|
switching, as described in the document is not implemented, and may
|
|
(or may not) ever be implemented, as display memory is growing rapidly,
|
|
and toolkits are already beginning to support migration, mitigating the
|
|
need for depth switching. If it is implemented in the future, we
|
|
expect to do so via an upward compatible extension to the
|
|
current library/protocol; functionality described here should continue
|
|
to work.
|
|
<P>
|
|
|
|
Rotation and reflection and how they interact can be confusing. In
|
|
Randr, the coordinate system is rotated in a counter-clockwise
|
|
direction relative to the normal orientation. Reflection is along the
|
|
window system coordinate system, not the physical screen X and Y axis,
|
|
so that rotation and reflection do not interact. The other way to
|
|
consider reflection is to treat it as specified in the "normal"
|
|
orientation, before rotation.
|
|
<P>
|
|
|
|
The
|
|
<B>XRRScreenChangeNotify</B>
|
|
|
|
event is sent to clients that ask to be informed whenever the root window
|
|
configuration changes. Configuration changes may include resolution,
|
|
physical size, subpixel order (see <A HREF="/cgi-bin/man/man2html?3+XRender">XRender</A>(3)), and rotation. Note
|
|
that changes to any or all of these could occur due to external events
|
|
(user control in the X server, a different monitor/flat panel display
|
|
being hot-plugged) and is not only the result of a protocol/library
|
|
request to the X server.
|
|
<P>
|
|
|
|
Additionally, to eliminate a potential race condition,
|
|
this event may be generated
|
|
immediately upon selecting for notification if the screen has changed
|
|
since the client of Xrandr connected to the X server, to enable
|
|
reliable screen resolution changing when a user may log in and
|
|
change the configuration while one or many clients are starting up.
|
|
<P>
|
|
|
|
<B>Xlib notification</B>
|
|
|
|
<P>
|
|
|
|
Clients must call back into Xlib using
|
|
<B>XRRUpdateConfiguration</B>
|
|
|
|
when screen configuration change notify events are generated
|
|
(or root window configuration changes occur, to update Xlib's
|
|
view of the resolution, size, rotation, reflection or subpixel order.
|
|
Generally, toolkits will perform this operation on behalf of applications;
|
|
we did not want to change display structure data behind the back of toolkits,
|
|
as in multithreaded clients, various race conditions might occur.
|
|
Toolkits should provide clients some mechanism for notification of
|
|
screen change, of course.
|
|
<P>
|
|
<A NAME="lbAG"> </A>
|
|
<H2>FUNCTIONS</H2>
|
|
|
|
There are two classes of interfaces: those which can be safely called
|
|
even if RandR is not implemented on a screen (to make common idioms not
|
|
dependent on the server having support), and those which will return
|
|
errors if the extension is not present.
|
|
<P>
|
|
|
|
<B>XRRRotations</B>
|
|
|
|
returns both the possible set of rotations/reflections supported
|
|
(as a bitmask) as the value of the function, along with the current
|
|
rotation/reflection of the screen.
|
|
<P>
|
|
|
|
<B>XRRSizes</B>
|
|
|
|
returns the size and a pointer to the current sizes supported by
|
|
the specified screen. The first size specified is the default size
|
|
of the server. If RandR is not supported, it returns 0 for
|
|
the number of sizes.
|
|
<P>
|
|
|
|
<B>XRRRates</B>
|
|
|
|
returns a pointer to the rates supported by the specified size.
|
|
If RandR is not supported, it returns 0 for the number of rates.
|
|
<P>
|
|
|
|
<B>XRRTimes</B>
|
|
|
|
returns the time last reported by the server along with the
|
|
timestamp the last configuration changed.
|
|
If the configuration has changed since the client last updated
|
|
its view of the server time, requests to change the configuration
|
|
will fail until the client has an up to date timestamp.
|
|
<P>
|
|
|
|
<B>XRRRootToScreen</B>
|
|
|
|
returns the screen number given a root window (for example, from
|
|
an <B>XRRScreenChangeNotifyEvent</B>).
|
|
<P>
|
|
|
|
The rest of the functions will fail if applied to screens not
|
|
implementing the RandR extension.
|
|
<B>XRRSetScreenConfig</B>
|
|
|
|
sets the screen size and rotation and reflection to the desired
|
|
values on the screen specified by <I>draw</I>, or returns a
|
|
<B>BadValue</B>
|
|
|
|
error.
|
|
<I>size_index</I> specifies which size configuration is to be used,
|
|
<I>rotation</I> specifies which rotation or reflection is to
|
|
be used (or a
|
|
<B>BadValue</B>
|
|
|
|
error is returned).
|
|
The <I>timestamp</I> is used by the server to make sure the client
|
|
has up to date configuration information. Status is returned
|
|
to indicate success or failure; a client must refresh its configuration
|
|
information if it fails and try the call again (by calling
|
|
<B>XRRGetScreenInfo</B>).
|
|
<P>
|
|
|
|
<B>XRRSetScreenConfigAndRate</B>
|
|
|
|
is like
|
|
<B>XRRSetScreenConfig</B>
|
|
|
|
but also sets the refresh rate. If specified rate is not supported a
|
|
<B>BadValue</B>
|
|
|
|
error is returned.
|
|
<P>
|
|
|
|
<B>XRRConfigRotations,</B>
|
|
|
|
<B>XRRConfigSizes,</B>
|
|
|
|
<B>XRRConfigCurrentConfiguration,</B>
|
|
|
|
<B>XRRConfigTimes,</B>
|
|
|
|
<B>XRRConfigRates,</B>
|
|
|
|
and
|
|
<B>XRRConfigCurrentRate</B>
|
|
|
|
are used to get specific configuration information out of a screen
|
|
configuration.
|
|
<P>
|
|
|
|
<B>XRRGetScreenInfo</B>
|
|
|
|
returns a screen configuration for later use; the information is
|
|
private to the library.
|
|
Call
|
|
<B>XRRFreeScreenConfigInfo</B>
|
|
|
|
to free this information when you are finished with it.
|
|
It forces a round trip to the server.
|
|
<P>
|
|
Other functions include:
|
|
<B>XRRQueryExtension</B>
|
|
|
|
which returns the event and error base codes,
|
|
<B>XRRQueryVersion</B>
|
|
|
|
, which returns the current version of the extension (this information
|
|
is cached by the library).
|
|
<A NAME="lbAH"> </A>
|
|
<H2>RESTRICTIONS</H2>
|
|
|
|
<B>Xrandr</B>
|
|
|
|
will remain upward compatible after the current 1.0 release.
|
|
<A NAME="lbAI"> </A>
|
|
<H2>AUTHOR</H2>
|
|
|
|
Jim Gettys, and Keith Packard, HP.
|
|
<P>
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="11"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="12"><A HREF="#lbAC">SYNTAX</A><DD>
|
|
<DT id="13"><A HREF="#lbAD">ARGUMENTS</A><DD>
|
|
<DT id="14"><A HREF="#lbAE">DATATYPES</A><DD>
|
|
<DT id="15"><A HREF="#lbAF">DESCRIPTION</A><DD>
|
|
<DT id="16"><A HREF="#lbAG">FUNCTIONS</A><DD>
|
|
<DT id="17"><A HREF="#lbAH">RESTRICTIONS</A><DD>
|
|
<DT id="18"><A HREF="#lbAI">AUTHOR</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:06:01 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|