12to11/12to11
1
0
Fork 1
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
12to11/12to11.man
hujianwei 151473bfb5 Fully implement tearing control 
* 12to11.man: Document new protocol.
* compositor.h (enum _RenderMode): Add RenderModeVsyncAsync.
* picture_renderer.c (SwapBackBuffers, PresentToWindow)
(NotifyMsc): Handle new render mode.
* sync_source.c (GetWantedSynchronizationType): Use presentation
if the mode is VsyncAsync.
(NoteFrame): Set the vsync presentation mode to
RenderModeVsyncAsync.
2022-11-24 06:12:06 +00:00

326 lines
11 KiB
Groff
Raw Blame History

.TH 12to11
.SH NAME
12to11 - Wayland to X protocol translator
.SH SYNOPSIS
.B 12to11
[\-\fBclass\fP \fIclass\fP] [\-\fBname\fP \fIname\fP] [\-\fBxrm\fP \fIresourcestring\fP...]
.SH DESCRIPTION
.I 12to11
starts a Wayland compositor on the next available socket;
Wayland programs will then be displayed through the X server.
.SH OPTIONS
Some X Toolkit library-style command-line arguments are also accepted,
despite the protocol translator being implemented without using a
toolkit. These options are:
.TP 8
.B \-class \fIclass\fP
This option specifies the resource class under which resources are to
be obtained. When not set, it defaults to the string ``12to11''. The
resource class and name used by the protocol translator are \fInot\fP
set as the
.B WM_CLASS
property on windows created by the protocol translator; instead, those
windows get the classes and names assigned to them by their individual
Wayland clients.
.TP 8
.B \-name \fIname\fP
This option specifies the instance name under which resources are to
be obtained. When not set, it defaults to the executable file name.
.TP
.B \-help\fP
This option causes the protocol translator to print a message
describing options it accepts. The protocol translator will then exit
after printing the message.
.TP
.B \-xrm\fP \fIresourcestring\fP
This option specifies a resource string to be used. This is
especially useful for setting resources that do not have separate
command line options.
.TP
.B \-printsocket\fP
This option makes the protocol translator print the name of the
Wayland socket to standard output.
.SH RESOURCES
\fI12to11\fP understands some resource names and classes that can be
used to specify various settings that affect its behavior. Those
resources are listed below:
.TP 8
.B ximFont\fP (class \fBXimFont\fP)
Specifies the font to be used for displaying the preedit or status
areas of an input method.
.IP
In many input methods, the preedit (a.k.a composition or
preconversion) string and/or a status window is displayed on screen
while typing by the input method server. The client is supposed to
determine the font used by the input method server to display --
however, the Wayland protocol does not allow Wayland clients to
specify that themselves, so the protocol translator has to do that by
itself.
.TP
.B ximStyles\fP (class \fBXimStyles\fP)
Specifies the default input method styles used by the protocol
translator.
.IP
X input methods can support different editing styles, which affect how
preconversion and status text is displayed while typing. These styles
are named:
.TP 16
.B overTheSpot
In ``over the spot'', the preedit string is displayed in a window
created by the input method at a location specified by the Wayland
client, typically the text insertion point.
.TP
.B offTheSpot
In ``off the spot'', the preedit string is displayed in a window
created by the input method at some location away from the text
insertion point. Often, this type of window is placed at the bottom
of the preedit window.
.TP
.B rootWindow
In the ``root window'' editing style, the preedit string is displayed
in a popup window created by the input method.
.TP
.B onTheSpot
In the ``on the spot'' editing style, the preedit string is displayed
inside the text itself by the Wayland client.
.IP "" 8
Not all input methods support all editing styles. In the real world,
most only support one or two of the styles listed above. The protocol
translator will search for a style supported by the input method when
initializing input method support. The \fBximStyles\fP resource is
used to control the order in which the protocol translator searches
for input styles, and should be a comma separated list of input names,
which are searched in left-to-right order. For example,
.IP
.in +4
.EX
\fBoverTheSpot,rootWindow\fP
.EE
.in
.IP
will result in the protocol translator searching for the ``over the
spot'' input style, and if that is not present, the ``root window''
style. Whitespace must not be present inside the comma-separated
list. When \fBximStyles\fP is not specified, it defaults to:
.IP
.in +4
.EX
\fBoverTheSpot,offTheSpot,rootWindow,onTheSpot\fP
.EE
.in
.TP
.B renderer\fP (class \fBRenderer\fP)
Specifies the rendering backend the protocol translator uses to
composite the contents of Wayland surfaces onto X windows. This can
either be \fBpicture\fP (the XRender based compositor) or \fBegl\fP
(the OpenGL ES 2.0 based compositor).
.TP
.B wmProtocols\fP (class \fBWmProtocols\fP)
Comma-separated list of window manager protocols, similar to
\fBinputStyles\fP, that the protocol translator should enable or
disable. The current (and default) list of supported protocols are:
\fBnetWmPing\fP.
.TP
.B idleInhibitCommand\fP (class \fBIdleInhibitCommand\fP)
.TP
.B idleIntervalCommand\fP (class \fBIdleInhibitCommand\fP)
.TP
.B idleDeinhibitCommand\fP (class \fBIdleDeinhibitCommand\fP)
These are commands that run when a focused Wayland client asks to
inhibit the screen saver or screen locker, usually because a video is
being played and does not require user interaction.
\fBidleInhibitCommand\fP specifies a command that is run when one such
client becomes focused or starts inhibiting the screen saver;
\fBidleIntervalCommand\fP is a command that is run every several
seconds (by default 60) while the screen saver is inhibited, and
\fBidleDeinhibitCommand\fP is a command that is run once such a client
stops inhibiting the screen saver or loses the input focus.
.IP
Since there are several different screen saver inhibition protocols
used by different X desktops, the protocol translator refrains from
implementing any of them. Instead, it provides the ability to run any
command necessary to inhibit and de-inhibit the screen saver. For
example, an
.BR XScreenSaver(1)
user may wish to apply the following resources:
.IP
.in +4
.EX
\fB12to11.IdleInhibitCommand: xscreensaver-command -deactivate\fP
.EE
.in
.IP
The commands specified are expected to finish. If the process
corresponding to one command is still running by the time another
command should have been run, the other command will be queued until
the first process exits.
.TP
.B idleCommandInterval\fP (class \fBIdleCommandInterval\fP)
The number of seconds the protocol translator waits between
invocations of the command specified in \fBidleIntervalCommand\fP.
Defaults to 60.
.TP
.B additionalModifiersOfScreen\fP\fINUMBER\fP (class \fBAdditionalModifiers\fP)
A comma-separated list of additional DRM modifiers that can be applied
to each format. These modifiers must be specified by their names
inside the `drm_fourcc.h' system header, and should be used if your X
graphics driver fails to report which modifiers are available.
\fINUMBER\fP should be replaced with the number of the screen on which
the protocol translator is running.
On 9th Generation Intel systems, for example, you may want to set this
to:
.IP
.in +4
.EX
\fB12to11.AdditionalModifiers: I915_FORMAT_MOD_X_TILED,DRM_FORMAT_MOD_LINEAR\fP
.EE
.in
.IP
.SH ENVIRONMENT
Several environment variables exist that modify the behavior of the
protocol translator in one way or another. Most of these are used for
debugging, but some may be relevant to users as well.
.PP
The
.B USE_BUILTIN_RESIZE
environment variable, if set, forces the use of the built-in
drag-to-resize support provided by the protocol translator, even if
the X window manager provides its own.
.PP
The
.B DEBUG_REFRESH_PREDICTION
environment variable, if set, forces the frame clock to predict the
presentation deadline of the X compositing manager. This is used to
debug code that is otherwise not run without subsurfaces being
present.
.PP
The
.B DISABLE_FRAME_SYNCHRONIZATION
environment variable, if set, disables frame synchronization with the
X compositing manager. Setting this variable is probably not a good
idea.
.PP
The
.B SYNCHRONIZE
environment variable, if set, causes the X library to check for errors
immediately after issuing a request. The resulting backtraces from
the error handler then reflect the protocol request that actually
caused the error, instead of some unpredictable request in the future.
.PP
The
.B APPLY_STATE_WORKAROUND
environment variable, if set, causes the protocol translator to handle
toplevel window state changes differently. If Wayland programs do not
make the transition between fullscreen and maximized states correctly,
try setting this variable.
.PP
The
.B GLOBAL_SCALE
environment variable, if set to an integer, overrides the global
program scale factor normally provided by the
.I Gdk/WindowScalingFactor
X setting.
.PP
The
.B OUTPUT_SCALE
environment variable, if set to an integer, overrides the output scale
factor that is otherwise set to the global program scale factor.
Setting this option is only useful to debug Wayland program
downscaling.
.PP
The
.B DIRECT_STATE_CHANGES
variable, if set, forces ConfigureNotify events from the window
manager to be handled directly, without waiting some time for a
corresponding _NET_WM_STATE event to arrive. This is only
useful for debugging the window resizing logic.
.PP
The
.B RENDERER
variable, if set, controls the rendering backend used by the
protocol translator. When set to
.I help
it prints a list of available rendering backends instead. This takes
precedence over the \fBrenderer\fP resource whenever set.
.PP
The
.B RENDER_VISUAL
variable, if set to a number, contains the ID of the visual used
when the EGL rendering backend is in use.
.SH "CONFORMING TO"
The protocol translator aims to comply with the specifications of the
following Wayland interfaces:
.TS H
lb lb
lb n .
Protocol Version
wl_output 4
wl_compositor 5
wl_shm 1
xdg_wm_base 5
wl_subcompositor 1
wl_seat 8
wl_data_device_manager 3
zwp_linux_dmabuf_v1 4
zwp_primary_selection_device_manager_v1 1
wp_viewporter 1
zxdg_decoration_manager_v1 1
zwp_text_input_manager_v3 1
wp_single_pixel_buffer_manager_v1 1
zwp_pointer_constraints_v1 1
zwp_relative_pointer_manager 1
zwp_idle_inhibit_manager_v1 1
xdg_activation_v1 1
wp_tearing_control_manager_v1 1
.TE
.PP
When the protocol translator is built with EGL support, the following
protocol is also supported:
.TS H
lb lb
lb n .
Protocol Version
zwp_linux_explicit_synchronization_v1 2
.TE
.PP
When the X server supports version 1.6 or later of the X Resize,
Rotate and Reflect Extension, the following Wayland protocol is also
supported:
.TS H
lb lb
lb n .
Protocol Version
wp_drm_lease_device_v1 1
.TE
.PP
When the X server supports version 2.4 or later of the X Input
Extension, the following Wayland protocol is also supported:
.TS H
lb lb
lb n .
Protocol Version
zwp_pointer_gestures_v1 3
.TE
.PP
However, Wayland clients are allowed to continue to access data from
the \fBCLIPBOARD\fP and \fBPRIMARY\fP selections even when they do not
have the keyboard focus, against the restrictions put out in the
relevant protocol specifications. It is the opinion of the authors
that such ``security'' does not come with any real benefit.
.SH BUGS
There is a hard to catch bug where Wayland programs leaving the
fullscreen or maximized state may abruptly return to their maximized
size. Setting the
.B APPLY_STATE_WORKAROUND
environment variable may help.
.PP
Using this protocol translator under a window manager that does not at
least support the
.B _NET_WM_SYNC_REQUEST
window manager protocol will result in Wayland programs running badly.
.PP
.SH "SEE ALSO"
X(7), Xorg(1)
.SH AUTHORS
Various contributors.
Reference in a new issue View git blame Copy permalink