Skip to content

Commit

Permalink
Add more caveats and limitations.
Browse files Browse the repository at this point in the history
  • Loading branch information
@digitaltrails
digitaltrails committed Feb 27, 2024
1 parent 88b1e20 commit 66c2859
Show file tree
Hide file tree
Showing 2 changed files with 60 additions and 46 deletions.
52 changes: 29 additions & 23 deletions docs/_build/man/vdu_controls.1
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "VDU_CONTROLS" "1" "Dec 27, 2023" "" "vdu_controls"
.TH "VDU_CONTROLS" "1" "Feb 28, 2024" "" "vdu_controls"
.SH NAME
vdu_controls \- vdu_controls 1.11.0
.SH VDU_CONTROLS - A DDC CONTROL PANEL FOR MONITORS
Expand All @@ -50,8 +50,8 @@ A control panel for DisplayPort, DVI, HDMI, or USB connected VDUs (\fIVisual Dis
[\-\-hide\-on\-focus\-out|\-\-no\-hide\-on\-focus\-out] [\-\-smart\-window|\-\-no\-smart\-window]
[\-\-syslog|\-\-no\-syslog] [\-\-debug|\-\-no\-debug] [\-\-warnings|\-\-no\-warnings]
[\-\-sleep\-multiplier multiplier] [\-\-ddcutil\-extra\-args \(aqextra args\(aq]
[\-\-dbus\-client\-enabled|\-\-no\-dbus\-client\-enabled]
[\-\-dbus\-listen|\-\-no\-dbus\-listen]
[\-\-dbus\-client|\-\-no\-dbus\-client]
[\-\-dbus\-signals|\-\-no\-dbus\-signals]
[\-\-create\-config\-files] [\-\-install] [\-\-uninstall]
.UNINDENT
.UNINDENT
Expand Down Expand Up @@ -130,11 +130,11 @@ minimise the main window automatically on focus out
show the splash screen. \fB\-\-splash\fP is the default.
.TP
.B \-\-monochrome\-tray|\-\-no\-monochrome\-tray
monochrome themed system\-tray.
monochrome dark themed system\-tray.
\fB\-\-no\-monochrome\-tray\fP is the default.
.TP
.B \-\-mono\-light\-tray|\-\-no\-mono\-light\-tray
alter monochrome\-tray for a light themed system\-tray.
monochrome themed system\-tray.
\fB\-\-no\-mono\-light\-tray\fP is the default.
.TP
.B \-\-smart\-window|\-\-no\-smart\-window
Expand All @@ -153,13 +153,13 @@ extra arguments to pass to ddcutil (enclosed in single quotes)
.UNINDENT
.INDENT 0.0
.TP
.B \-\-dbus\-client\-enabled|\-\-no\-dbus\-client\-enabled
use the ddcutil\-dbus\-server instead of the ddcutil command
\fB\-\-no\-dbus\-client\-enabled\fP is the default
.B \-\-dbus\-client|\-\-no\-dbus\-client
use the D\-Bus ddcutil\-service instead of the ddcutil command
\fB\-\-dbus\-client\fP is the default
.TP
.B \-\-dbus\-listener|\-\-no\-dbus\-listener
listen for VDU status change signals
\fB\-\-no\-dbus\-listener\fP is the default
.B \-\-dbus\-signals|\-\-no\-dbus\-signals
enable D\-Bus ddcutil\-service VDU\-connectivity\-change signals
\fB\-\-dbus\-signals\fP is the default
.UNINDENT
.INDENT 0.0
.TP
Expand Down Expand Up @@ -189,15 +189,15 @@ controls. Additional controls can be enabled via the \fBSettings\fP dialog.
implementations.
.sp
From \fBvdu_controls 2.0\fP onward, \fBvdu_controls\fP defaults to using the \fBD\-Bus ddcutil\-service\fP\&.
Should the \fBddcutil\-service\fP be unavailable, \fBvdu_controls\fP will fall back to running \fBddcutil\fP
separately for each VCP\-command.
Should the \fBddcutil\-service\fP be unavailable, \fBvdu_controls\fP will fall back to running the
\fBddcutil\fP command to perform each request.
.sp
The UI\(aqs look\-and\-feel adjusts itself for dark and light desktop themes. The application may
optionally run in the system tray of KDE, Deepin, GNOME, and Xfce (and possibly others).
.sp
The UI provides an optional \fBambient\-light slider\fP for simultaneously adjusting
all VDUs according to custom per\-VDU ambient lux/brightness profiles. Options are included for
accessing a hardware ambient light\-meter, or a webcam, for fully automatic brightness adjustment.
all VDUs according to custom per\-VDU ambient lux/brightness profiles. Options are included
for automated adjustment by accessing a hardware light\-meters, webcams, or other devices.
.sp
Named \fBPreset\fP configurations can be saved and recalled. For example, presets may be created
for night, day, photography, movies, and so forth. Presets can be triggered by specific ambient
Expand Down Expand Up @@ -682,11 +682,13 @@ interpolation\-sensitivity\-percent=10
.sp
If you are using \fBddcutil\fP version 2.0 or greater, \fBvdu_controls\fP will default to using the
\fBddcutil\fP \fIdynamic sleep optimiser\fP\&. The optimiser automatically tunes and caches VDU specific
timings when ever \fBddcutil\fP is run. Any reliability\-issues or reported errors may be
automatically resolved as the optimiser refines it\(aqs cached timings. Should problems persist, the
timings when ever \fBddcutil\fP is run. Any reliability\-issues or errors may be automatically
resolved as the optimiser refines it\(aqs cached timings. Should problems persist, the
optimiser can be disabled by adding \fI\-\-disable\-dynamic\-sleep\fP to the \fBddcutil extra arguments\fP in
the \fBSettings Dialog\fP (either globally on the \fBvdu_controls tab\fP or selectively under each VDU\(aqs
tab).
tab). If dynamic sleep is disabled, multipliers can then be manually assigned. The optimiser\(aqs
heuristics continue to be refined, it may be that some issues may be resolved by moving to a more
recent version of \fBlibddcutil/ddcutil\fP\&.
.sp
For versions of \fBddcutil\fP prior to 2.0, you can manually set the \fBvdu_control\fP
\fBsleep\-multiplier\fP passed to \fBddcutil\fP\&. A sleep multiplier less than one will speed up the i2c
Expand All @@ -696,9 +698,9 @@ with multiplier values may greatly speed up responsiveness. In a multi\-VDU setu
multipliers can be configured (see previous section).
.SS Improving Response Time and Reliability: Connections and Controls
.sp
\fBDDC/I2C\fP is not the most reliable form of communication. VDUs may vary in their
responsiveness and compliance. GPUs, GPU drivers, and types of connection may affect the
reliability.
\fBDDC/I2C\fP is not a totally reliable form of communication. VDUs may vary in their responsiveness
and compliance. GPUs, GPU drivers, and types of connection may affect the reliability. Both ddcutil
and vdu_controls attempt to manage the reliability by using repetition and by adjusting timings.
.sp
If you have the choice, a \fBDisplayPort\fP to \fBDisplayPort\fP connection may be more reliable than
\fBDVI\fP or \fBHDMI\fP\&.
Expand All @@ -720,9 +722,13 @@ specific picture\-profile might result in the contrast\-control being disabled,
will not be aware of the restriction resulting in its contrast\-control erring or appearing to do
nothing.
.sp
The \fBddcutil\-service\fP has some ability to signal hot\-plug events, such as connecting
a new VDU or powering one down. Not all GPU\-drivers support an efficient means of event detection,
as a result there may be a delay of many seconds before \fBddcutil\-service\fP passes these events
to \fBvdu_controls\fP\&.
.sp
Builtin laptop displays normally don\(aqt implement DDC and those displays are not supported, but a
laptop\(aqs externally connected VDUs are likely to be controllable. (For some laptops it might be
possible to write a custom script\-wrapper for \fIddcutil\fP which emulates DDC for the laptop display.)
laptop\(aqs externally connected VDUs are likely to be controllable.
.SH EXAMPLES
.INDENT 0.0
.INDENT 3.5
Expand Down
54 changes: 31 additions & 23 deletions docs/_build/man/vdu_controls.1.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,8 @@ <h1 id="synopsis">Synopsis:</h1>
[--hide-on-focus-out|--no-hide-on-focus-out] [--smart-window|--no-smart-window]
[--syslog|--no-syslog] [--debug|--no-debug] [--warnings|--no-warnings]
[--sleep-multiplier multiplier] [--ddcutil-extra-args &#39;extra args&#39;]
[--dbus-client-enabled|--no-dbus-client-enabled]
[--dbus-listen|--no-dbus-listen]
[--dbus-client|--no-dbus-client]
[--dbus-signals|--no-dbus-signals]
[--create-config-files] [--install] [--uninstall]</code></pre>
<h2 id="optional-arguments">Optional arguments:</h2>
<p>Arguments supplied on the command line override config file
Expand Down Expand Up @@ -62,10 +62,10 @@ <h2 id="optional-arguments">Optional arguments:</h2>
--splash|--no-splash
show the splash screen. ``--splash`` is the default.
--monochrome-tray|--no-monochrome-tray
monochrome themed system-tray.
monochrome dark themed system-tray.
``--no-monochrome-tray`` is the default.
--mono-light-tray|--no-mono-light-tray
alter monochrome-tray for a light themed system-tray.
monochrome themed system-tray.
``--no-mono-light-tray`` is the default.
--smart-window|--no-smart-window
smart main window placement and geometry.
Expand All @@ -74,12 +74,12 @@ <h2 id="optional-arguments">Optional arguments:</h2>
protocol reliability multiplier for ddcutil (typically
0.1 .. 2.0, default is 1.0)
--ddcutil-extra-args extra arguments to pass to ddcutil (enclosed in single quotes)
--dbus-client-enabled|--no-dbus-client-enabled
use the ddcutil-dbus-server instead of the ddcutil command
``--no-dbus-client-enabled`` is the default
--dbus-listener|--no-dbus-listener
listen for VDU status change signals
``--no-dbus-listener`` is the default
--dbus-client|--no-dbus-client
use the D-Bus ddcutil-service instead of the ddcutil command
``--dbus-client`` is the default
--dbus-signals|--no-dbus-signals
enable D-Bus ddcutil-service VDU-connectivity-change signals
``--dbus-signals`` is the default
--create-config-files
if they do not exist, create template config INI files
in $HOME/.config/vdu_controls/
Expand All @@ -102,16 +102,15 @@ <h1 id="description">Description</h1>
<p>From <code>vdu_controls 2.0</code> onward, <code>vdu_controls</code>
defaults to using the <code>D-Bus ddcutil-service</code>. Should the
<code>ddcutil-service</code> be unavailable, <code>vdu_controls</code>
will fall back to running <code>ddcutil</code> separately for each
VCP-command.</p>
will fall back to running the <code>ddcutil</code> command to perform
each request.</p>
<p>The UI’s look-and-feel adjusts itself for dark and light desktop
themes. The application may optionally run in the system tray of KDE,
Deepin, GNOME, and Xfce (and possibly others).</p>
<p>The UI provides an optional <code>ambient-light slider</code> for
simultaneously adjusting all VDUs according to custom per-VDU ambient
lux/brightness profiles. Options are included for accessing a hardware
ambient light-meter, or a webcam, for fully automatic brightness
adjustment.</p>
lux/brightness profiles. Options are included for automated adjustment
by accessing a hardware light-meters, webcams, or other devices.</p>
<p>Named <code>Preset</code> configurations can be saved and recalled.
For example, presets may be created for night, day, photography, movies,
and so forth. Presets can be triggered by specific ambient light levels,
Expand Down Expand Up @@ -507,12 +506,16 @@ <h2 id="lux-metering-internal-parameters">Lux Metering Internal
<code>vdu_controls</code> will default to using the <code>ddcutil</code>
<em>dynamic sleep optimiser</em>. The optimiser automatically tunes and
caches VDU specific timings when ever <code>ddcutil</code> is run. Any
reliability-issues or reported errors may be automatically resolved as
the optimiser refines it’s cached timings. Should problems persist, the
reliability-issues or errors may be automatically resolved as the
optimiser refines it’s cached timings. Should problems persist, the
optimiser can be disabled by adding <code>--disable-dynamic-sleep</code>
to the <strong>ddcutil extra arguments</strong> in the <strong>Settings
Dialog</strong> (either globally on the <strong>vdu_controls
tab</strong> or selectively under each VDU’s tab).</p>
tab</strong> or selectively under each VDU’s tab). If dynamic sleep is
disabled, multipliers can then be manually assigned. The optimiser’s
heuristics continue to be refined, it may be that some issues may be
resolved by moving to a more recent version of
<code>libddcutil/ddcutil</code>.</p>
<p>For versions of <code>ddcutil</code> prior to 2.0, you can manually
set the <code>vdu_control</code> <code>sleep-multiplier</code> passed to
<code>ddcutil</code>. A sleep multiplier less than one will speed up the
Expand All @@ -525,9 +528,11 @@ <h2 id="lux-metering-internal-parameters">Lux Metering Internal
<h2
id="improving-response-time-and-reliability-connections-and-controls">Improving
Response Time and Reliability: Connections and Controls</h2>
<p><code>DDC/I2C</code> is not the most reliable form of communication.
<p><code>DDC/I2C</code> is not a totally reliable form of communication.
VDUs may vary in their responsiveness and compliance. GPUs, GPU drivers,
and types of connection may affect the reliability.</p>
and types of connection may affect the reliability. Both ddcutil and
vdu_controls attempt to manage the reliability by using repetition and
by adjusting timings.</p>
<p>If you have the choice, a <code>DisplayPort</code> to
<code>DisplayPort</code> connection may be more reliable than
<code>DVI</code> or <code>HDMI</code>.</p>
Expand All @@ -550,11 +555,14 @@ <h1 id="limitations">Limitations</h1>
the contrast-control being disabled, but <code>vdu_controls</code> will
not be aware of the restriction resulting in its contrast-control erring
or appearing to do nothing.</p>
<p>The <code>ddcutil-service</code> has some ability to signal hot-plug
events, such as connecting a new VDU or powering one down. Not all
GPU-drivers support an efficient means of event detection, as a result
there may be a delay of many seconds before <code>ddcutil-service</code>
passes these events to <code>vdu_controls</code>.</p>
<p>Builtin laptop displays normally don’t implement DDC and those
displays are not supported, but a laptop’s externally connected VDUs are
likely to be controllable. (For some laptops it might be possible to
write a custom script-wrapper for <code>ddcutil</code> which emulates
DDC for the laptop display.)</p>
likely to be controllable.</p>
<h1 id="examples">Examples</h1>
<pre><code>vdu_controls
All default controls.
Expand Down

0 comments on commit 66c2859

Please sign in to comment.