setxdmbg
========
:revdate: June 26, 2019
:encoding: utf-8
:lang: fr
:author: Sébastien Ballet
:email: slacker6896 at gmail dot com
:doctype: book
:toc:
:toclevel: 4

// There's two way to rebuild the html version of this asciidoc source file :
//
//  1. In the directory of this asciidoc source file:
//
//    $ asciidoc --out-file=../setxdmbg.html \
//		./setxdmbg.txt
//
//  2. In the parent directory of this asciidoc source file:
//
//    $ asciidoc --out-file=./setxdmbg.html \
//		./adoc/setxdmbg.txt
//
//
// Note:
//   By default, the output html file has no table of content. To add one, the
//   attribute ":toc:", and eventually "::toclevels:" must be added in the
//   attributes list at start of this source file.
//
// -----------------------------------------------------------------------------
//
// By default, the document is left justified, and fills the page width. To limit
// the document width to 75% of the page, and to center it :
//
//   1. Edit, if required, the configuration file /etc/asciidoc/xhtml11.conf
//   and :
//
//     a. Look for the line :
//         <body class=....>
//
//     b. After max-width:{max-width}, add :
//          ;margin-left:auto;margin-right:auto;
//
//   2. Rebuild the html output file with the attribute max-width set to 75% :
//
//      a. Rebuild from the source file directory :
//
//        $ asciidoc -a max-width=75% \
//		--out-file=../setxdmbg.html \
//		./setxdmbg.txt
//
//         or
//
//      b. Rebuild from the source file parent directory :
//
//        $ asciidoc -a max-width=75% \
//		--out-file=./setxdmbg.html \
//		./adoc/setxdmbg.txt
//
// -----------------------------------------------------------------------------

[underline]#*SYNOPSIS*#

  setxdmbg --help
  setxdmbg --image <path> [OPTION]...

[underline]#*DESCRIPTION*#

*setxdmbg* is a command line tool to generate and set XDM display 
manager background image.


[underline]#*OPTION*#

*+-h+*|*+--help+*

 ::
+
Prints this help page.

*+-i+*|*+--image+* +<path>+

 ::
+
Full path to the source image used to generate the XDM background image.

*+-l+*|*+--log+* +[<path>]+

 ::
+
Full path to the file in which *setxdmbg* must log its activity. Default
to +/dev/stdout+ when *<path>* is not specified.

*+-p+*|*+--physical-screen+* +<screen>+

 ::
+
Displays the XDM background image on a given physical screen only.
+
*<screen>* can be any existing output supported by +xrandr+ (ex. +VGA-1+, 
+HDMI-0+, +DVI-D-0+,...) or the keyword *primary* to select the primary 
screen.

*+-T+*|*+--top-border+* +<height>[:<color>]+

 ::
+
Defines the height, and optionally the color, of the border at the top 
of the XDM background image.
+
+<color>+ can be any color supported by the imagemagick primitive
[underline]#+-fill+#  (ex: +red+, +#ddddff+, +rgb(255,255,255)+,+none+,...). When
+<color>+ is not specified, default to +black+.

*+-B+*|*+--bottom-border+* +<height>[:<color>]+

 ::
+
Defines the height, and optionally the color, of the border at the bottom 
of the XDM background image.
+
+<color>+ can be any color supported by the imagemagick primitive
[underline]#+-fill+#  (ex: +red+, +#ddddff+, +rgb(255,255,255)+,+none+,...). When
+<color>+ is not specified, default to +black+.
  
*+-x+*|*+--extra-image-op+* +<image-op>+

 ::
+
Adds *<op>* to the list of extra image operator to apply to the source
image to generate the XDM background image. The following +imagemagick+
operators are supported :
+
* link:https://imagemagick.org/script/command-line-options.php#adaptive-blur[-adaptive-blur <radius[xSigma\]>]
* link:https://imagemagick.org/script/command-line-options.php#adaptive-sharpen[-adaptive-sharpen <radius[xSigma\]>]
* link:https://imagemagick.org/script/command-line-options.php#auto-gamma[-auto-gamma]

* link:https://imagemagick.org/script/command-line-options.php#black-threshold[-black-threshold <value[%\]>]
* link:https://imagemagick.org/script/command-line-options.php#blue-shift[-blue-shift <factor>]
* link:https://imagemagick.org/script/command-line-options.php#blur[-blur <radius[xSigma\]>]
* link:https://imagemagick.org/script/command-line-options.php#brightness-contrast[-brightness-contrast <B[xC\][%\]>]
* link:https://imagemagick.org/script/command-line-options.php#charcoal[-charcoal <factor>]
* link:https://imagemagick.org/script/command-line-options.php#colorize[-colorize <percent>]
* link:https://imagemagick.org/script/command-line-options.php#fill[-fill <color>]
* link:https://imagemagick.org/script/command-line-options.php#contrast[-contrast]
* link:https://imagemagick.org/script/command-line-options.php#contrast-stretch[-contrast-stretch <BP[xWP\][%\]>]
* link:https://imagemagick.org/script/command-line-options.php#emboss[-emboss <radius>]
* link:https://imagemagick.org/script/command-line-options.php#enhance[-enhance]
* link:https://imagemagick.org/script/command-line-options.php#fft[-fft]
* link:https://imagemagick.org/script/command-line-options.php#flip[-flip]
* link:https://imagemagick.org/script/command-line-options.php#flop[-flop]
* link:https://imagemagick.org/script/command-line-options.php#gaussian-blur[-gaussian-blur <radius[xSigma\]>]
* link:https://imagemagick.org/script/command-line-options.php#grayscale[-grayscale <method>]
* link:https://imagemagick.org/script/command-line-options.php#monochrome[-monochrome]
* link:https://imagemagick.org/script/command-line-options.php#negate[-negate]
* link:https://imagemagick.org/script/command-line-options.php#noise[+noise <type>]
* link:https://imagemagick.org/script/command-line-options.php#ordered-dither[-ordered-dither <map[,level...\]>]
* link:https://imagemagick.org/script/command-line-options.php#paint[-paint <radius>]
* link:https://imagemagick.org/script/command-line-options.php#posterize[-posterize <levels>]
* link:https://imagemagick.org/script/command-line-options.php#radial-blur[-radial-blur <angle>]
* link:https://imagemagick.org/script/command-line-options.php#raise[-raise <thickness>]
* link:https://imagemagick.org/script/command-line-options.php#raise[+raise <thickness>]
* link:https://imagemagick.org/script/command-line-options.php#sharpen[-sharpen <radius[xSigma\]>]
* link:https://imagemagick.org/script/command-line-options.php#sketch[-sketch <radius[xSigma[+angle\]\]>]
* link:https://imagemagick.org/script/command-line-options.php#solarize[-solarize <percent-threshold>]
* link:https://imagemagick.org/script/command-line-options.php#tint[-tint <value>]

+
****
[underline]#*Attention*#, extra image operators can be time
consuming the first time the XDM background image is generated.

Note that +*-fill*+, which is not an operator, is required 
by operators *+-colorize+* and *+-tint+*, and thus, the use 
of one of these operators requires to pass the argument 
*+--extra-image-op+* twice like in example below :
 
 ::
+
[source,bash]
----
  $ setxdmbg -i /path/to/image.jpg -T 32 -B 32  \
             -x -fill red \
             -x -colorize 20
----
               
For more about image operators supported by *+setxdmbg+*, 
read link:https://imagemagick.org/script/command-line-options.php[this page].

****




[underline]#*DIRECTORIES and FILES*#

[underline]#+/var/cache/setxdmbg+#

 ::
+
Cache directory used to store the latest XDM background image and
its configuration.

[underline]#+~/.setxdmbg+#

 ::
+
Cache directory used to store the latest XDM background image and
its configuration when *+setxdmbg+* is run by a normal user. This is
to allow any user to test *+setxdmbg+* without to have to run XDM.

[underline]#+xdm.<XDISP>.pixmap+#

 ::
+
The latest generated XDM background image . Stored in the setxdmbg's 
cache directory.
+
[underline]#XDISP# is the X server display name, without field 'screennumber', 
and to XDM resource name format, that is, with underscores in place of 
dots and colons.
+
For instance the value of [underline]#XDISP# in case of X server display
name +:0+ is "*+_0+*". it is "*+_1+*" in case of X server display name +:1+,
it is "*+com_foo_bar_0+*" in case of X server display name +com.foo.bar:0+.

[underline]#+xdm.<XDISP>.pixmap.inf+#

 ::
+
Contains information on the latest generated XDM background image.
+
****
These information are internally used to prevent re-generation
of the same image when *+setxdmbg+* is run repeatedly with the
same configuration (ie. same image source, same targeted screen,
same border height, operator-ops,...)
****
+
[underline]#XDISP# is the X server display name, without field 'screennumber', 
and to XDM resource name format, that is, with underscores in place of 
dots and colons.
+
For instance the value of [underline]#XDISP# in case of X server display
name +:0+ is "*+_0+*". it is "*+_1+*" in case of X server display name +:1+,
it is "*+com_foo_bar_0+*" in case of X server display name +com.foo.bar:0+.


[underline]#*EXAMPLES*#

* [underline]#Set image on primary screen only#
+
[source,bash]
----
  $ setxdmbg --image /usr/share/wallpapers/xdm.jpg \
             --physical-screen primary \
             --top-border 16 \
             --bottom-border 32
----

* [underline]#Set image with blur effect#
+
[source,bash]
----
  $ setxdmbg --image /usr/share/wallpapers/xdm.jpg \
             --top-border 16 \
             --extra-image-op blur 16x4
----

* [underline]#Set image with paint effect and gaussian noise#
+
[source,bash]
----
  $ setxdmbg --image /usr/share/wallpapers/xdm.jpg \
             --bottom-border 16 \
             --extra-image-op -paint 4 \
             --extra-image-op +noise Gaussian
----
