<sect1 id="glcd-howto">
<sect1info>
  <author>
    <firstname>Markus</firstname>
    <surname>Dolze</surname>
  </author>
</sect1info>
<title>The glcd Driver</title>

<para>
The glcd driver (graphic lcd) driver is a "meta driver" that renders text for
display on graphic displays. It uses either a built-in 5x8 font (the same as
used in elsewhere in LCDproc) or Freetype 2 to draw the characters and icons
into an internal frame buffer. That frame buffer is then copied to the display
by a small sub-driver called connection type driver (CT-driver).
</para>

<note><para>
LCDproc is compiled with FreeType support by default if it is installed on your
system. It is enabled by default, too. However a font is not configured by
default. Thus the driver will not start unless a font is configured!
</para></note>

<sect2 id="glcd-connections">
<title>Connections</title>

<sect3 id="glcd-ct-t6963">
<title>Connection type t6963</title>
<para>
Support for displays using a Toshiba T6863 controller connected to the
parallel port. Wiring is the same as for the t6963 driver. Refer to
<xref linkend="t6963-connections" /> for details.
</para>
<para>
If used without FreeType this connection type uses the same font as the
t6963 driver but draws the characters into the graphic memory of the T6963.
</para>
<important><para>
You must configure the display for 8x8 font to make this connection type work!
</para></important>
</sect3>

<sect3 id="glcd-ct-png">
<title>Connection type png</title>
<para>
This connection type writes out the frame buffer into files in <filename>/tmp</filename>.
The files are named <filename>lcdproc######.png</filename> where <replaceable>######</replaceable>
is a number starting at 0.
</para>
<tip><para>
As a new file is written on any change to the screen it is best to turn off the
heartbeat.
</para></tip>
</sect3>

<sect3 id="glcd-ct-serdisplib">
<title>Connection type serdisplib</title>
<para>
Use the serdisplib library (<ulink url="http://serdisplib.sourceforge.net/" />)
for output. This enables use of a number of graphical displays connected to a
parallel, serial, or USB port. See the serdisplib web page for details,
especially for available options for your display.
</para>
</sect3>

<sect3 id="glcd-ct-glcd2usb">
<title>Connection type glcd2usb</title>
<para>
Support for the glcd2usb device (<ulink url="http://www.harbaum.org/till/glcd2usb/index.shtml" />,
a graphic LCD to USB converter based on Atmel ATmega16 and the V-USB stack.
This device features an adjustable backlight and 4 keys. Right now only displays
with the KS0108 controller are supported.
</para>
<para>
The device has 4 keys which may be configured using the <literal>KeyMap_A</literal>
(leftmost key) to <literal>KeyMap_D</literal> (rightmost key) settings.
</para>
<para>
Note that any size setting configured in <filename>LCDd.conf</filename> is
ignored as the size reported by the device is used.
</para>
</sect3>

<sect3 id="glcd-ct-x11">
<title>Connection type x11</title>
<para>
This connection type draws the frame buffer to a X window. It features
adjustable LCD pixel size, pixel color, backlight color and simulates
contrast and brightness. PC keyboard is used to simulate buttons.
</para>
</sect3>

<sect3 id="glcd-ct-picolcdgfx">
<title>Connection type picolcdgfx</title>
<para>
Support for the picoLCD Graphics 256x64 display from mini-box.com.
</para>
</sect3>

<!--
<sect3 id="glcd-ct-xyz">
<title>Connection type xyz</title>
<para>
</para>
</sect3>
-->

</sect2>

<!-- ## glcdlib meta driver for graphical LCDs ## -->
<sect2 id="glcd-config">
<title>Configuration in LCDd.conf</title>

<sect3 id="glcd-config-global">
<title>[glcd]</title>

<variablelist>
<title>Settings affecting all connection type drivers</title>
<varlistentry>
  <term>
    <property>ConnectionType</property> =
    {
    <emphasis><parameter><literal>t6963</literal></parameter></emphasis> |
    <parameter><literal>glcd2usb</literal></parameter> |
    <parameter><literal>png</literal></parameter> |
    <parameter><literal>picolcdgfx</literal></parameter> |
    <parameter><literal>serdisplib</literal></parameter> |
    <parameter><literal>x11</literal></parameter>
    }
  </term>
  <listitem><para>
    Specify which connection type to use. See <link linkend="glcd-connections">
    above</link> for details.
  </para></listitem>
</varlistentry>

<varlistentry>
  <term>
    <property>Size</property> = &parameters.size;
  </term>
  <listitem><para>
    Specifies the size of the LCD in pixels.
    Default: <literal>128x64</literal>.
    Maximum value supported: <literal>640x480</literal>.
  </para><para>
    The size in characters is automatically calculated from this value and the
    CellSize value (see below) and cannot be configured.
  </para></listitem>
</varlistentry>

<varlistentry>
  <term>
    <property>Contrast</property> =
    <parameter><replaceable>CONTRAST</replaceable></parameter>
  </term>
  <listitem><para>
    Set the initial contrast (if supported by the connection type driver).
    Legal values for <replaceable>CONTRAST</replaceable> are
    <literal>0</literal> - <literal>1000</literal>.
    If not given, it defaults to <literal>600</literal>.
  </para></listitem>
</varlistentry>

<varlistentry>
  <term>
    <property>Brightness</property> =
    <parameter><replaceable>BRIGHTNESS</replaceable></parameter>
  </term>
  <listitem><para>
    Set the initial brightness when the backlight is "on" (if supported by the
    connection type driver).
    Legal values are <literal>0</literal> - <literal>1000</literal>.
    If not given, it defaults to <literal>800</literal>.
  </para></listitem>
</varlistentry>

<varlistentry>
  <term>
    <property>OffBrightness</property> =
    <parameter><replaceable>BRIGHTNESS</replaceable></parameter>
  </term>
  <listitem><para>
    Set the initial brightness when the backlight is set "off" (if supported by
    the connection type driver).
    Legal values are <literal>0</literal> - <literal>1000</literal>.
    If not given, it defaults to <literal>100</literal>.
  </para></listitem>
</varlistentry>
</variablelist>

<variablelist>
<title>Available parameters if compiled with FreeType support</title>
<varlistentry>
  <term>
    <property>useFT2</property> = &parameters.yesdefno;
  </term>
  <listitem><para>
    Tell whether to use FreeType2 or not. It is set to <literal>yes</literal> by
    default. If turned off (set to <literal>no</literal>), the fixed internal
    5x8 font is used to draw characters and icons.
  </para></listitem>
</varlistentry>

<varlistentry>
  <term>
    <property>normal_font</property> =
    <parameter><replaceable>FONTFILE</replaceable></parameter>
  </term>
  <listitem><para>
    Set path to the font file to use, e.g. <filename>/usr/local/lib/X11/fonts/TTF/andalemo.ttf</filename>.
    This option is required if FreeType 2 support is enabled, but it is not set
    to any default value. A font with a fixed character width (monotype) is
    strongly recommended.
  </para></listitem>
</varlistentry>

<varlistentry>
  <term>
    <property>fontHasIcons</property> = &parameters.yesdefno;
  </term>
  <listitem><para>
    Many fonts to not include the Unicode glyphs used for drawing icons. If this
    option is set to <literal>no</literal> then the internal 5x8 font is used
    even if FreeType is enabled. This option is on (<literal>yes</literal>) by
    default.
  </para></listitem>
</varlistentry>

<varlistentry>
  <term>
    <property>CellSize</property> = &parameters.size;
  </term>
  <listitem><para>
    Specifies the size of the character cell in pixels. Characters will be
    drawn within this cell.
    Default: <literal>6x8</literal>; minimum value <literal>4x6</literal>;
    maximum value: <literal>24x32</literal>.
  </para></listitem>
</varlistentry>

<!--
<varlistentry>
  <term>
    <property>CharEncoding</property> =
    <parameter><replaceable>CHARSET</replaceable></parameter>
  </term>
  <listitem><para>
    Specify character encoding to use, e.g. <literal>iso8859-2</literal>.
    If not given, use the default <literal>ISO8859-1</literal>.
  </para></listitem>
</varlistentry>
-->
</variablelist>

<variablelist>
<title>Keypad settings</title>
<varlistentry>
  <term>
    <property>KeyRepeatDelay</property> =
    <parameter><replaceable>DELAY</replaceable></parameter>
  </term>
  <listitem><para>
    <replaceable>DELAY</replaceable>is the time in milliseconds from first key
    report to first repeat. Set to <literal>0</literal> to disable repeated key
    reports. Allowed values are between <literal>0</literal> and <literal>3000</literal>,
    the default is <literal>500</literal>.
  </para></listitem>
</varlistentry>

<varlistentry>
  <term>
    <property>KeyRepeatInterval</property> =
    <parameter><replaceable>DELAY</replaceable></parameter>
  </term>
  <listitem><para>
    <replaceable>DELAY</replaceable>is the time in milliseconds between repeated
    key strokes. Allowed values are between <literal>0</literal> and <literal>3000</literal>,
    the default is <literal>300</literal>. This setting is ignored, if KeyRepeatDelay
    is disabled (set to zero).
  </para></listitem>
</varlistentry>

<varlistentry>
  <term>
    <property>KeyMap_A</property> =
    <parameter><replaceable>KEY</replaceable></parameter>
  </term>
  <term>
    <property>KeyMap_B</property> =
    <parameter><replaceable>KEY</replaceable></parameter>
  </term>
  <term>
    <property>KeyMap_C</property> =
    <parameter><replaceable>KEY</replaceable></parameter>
  </term>
  <term>
    <property>KeyMap_D</property> =
    <parameter><replaceable>KEY</replaceable></parameter>
  </term>
  <term>
    <property>KeyMap_E</property> =
    <parameter><replaceable>KEY</replaceable></parameter>
  </term>
  <term>
    <property>KeyMap_F</property> =
    <parameter><replaceable>KEY</replaceable></parameter>
  </term>
  <listitem><para>
    These settings allow to assign arbitrary key strings to key strokes. Up to
    26 keys may be configured ('<literal>A</literal>' to '<literal>Z</literal>').
    </para>
    <para>
    The following is the built-in default mapping hard-coded in the driver. Only
    keys '<literal>A</literal>' to '<literal>F</literal>' are used by default.
    </para>
    <informaltable>
    <tgroup cols="2">
      <tbody>
        <row>
          <entry>KeyMap_A</entry>
          <entry><literal>Up</literal></entry>
        </row>
        <row>
          <entry>KeyMap_B</entry>
          <entry><literal>Down</literal></entry>
        </row>
        <row>
          <entry>KeyMap_C</entry>
          <entry><literal>Left</literal></entry>
        </row>
        <row>
          <entry>KeyMap_D</entry>
          <entry><literal>Right</literal></entry>
        </row>
        <row>
          <entry>KeyMap_E</entry>
          <entry><literal>Enter</literal></entry>
        </row>
        <row>
          <entry>KeyMap_F</entry>
          <entry><literal>Escape</literal></entry>
        </row>
      </tbody>
    </tgroup>
    </informaltable>
  </listitem>
</varlistentry>
</variablelist>

<variablelist>
<title>Settings for the t6963 connection type</title>
<varlistentry>
  <term>
    <property>Port</property> =
    <parameter><replaceable>PORT</replaceable></parameter>
  </term>
  <listitem><para>
    Specify the address of the parallel port the LCD is connected to.
    Common values for <replaceable>PORT</replaceable> are <literal>0x278</literal>,
    <literal>0x378</literal> and <literal>0x3BC</literal>.
    If not given, the default is <literal>0x378</literal>.
  </para></listitem>
</varlistentry>

<varlistentry>
  <term>
    <property>bidirectional</property> = &parameters.yesdefno;
  </term>
  <listitem>
  <para>
    Use parallel port in bi-directional mode. [default: <literal>yes</literal>;
    legal: <literal>yes</literal>, <literal>no</literal>]
  </para>
  <para>
    Most LPT ports can be used in bi-directional mode. It is required for
    proper timing of the display.
  </para>
  </listitem>
</varlistentry>

<varlistentry>
  <term>
    <property>delayBus</property> = &parameters.yesnodef;
  </term>
  <listitem>
  <para>
     Use additional delay in read / write operations. [default: <literal>no</literal>;
     legal: <literal>yes</literal>, <literal>no</literal>]. As the driver
     implements busy checking usually no additional delays are required.
  </para>
  </listitem>
</varlistentry>
</variablelist>

<variablelist>
<title>Settings for the serdisplib connection type</title>
<varlistentry>
  <term>
    <property>serdisp_name</property> =
    <parameter><replaceable>NAME</replaceable></parameter>
  </term>
  <listitem><para>
    This is the name or alias to select a display driver in the serdisplib
    library. As there is not default value setting this option is mandatory.
  </para></listitem>
</varlistentry>

<varlistentry>
  <term>
    <property>serdisp_device</property> =
    <parameter><replaceable>DEVICE</replaceable></parameter>
  </term>
  <listitem><para>
    Set the device to use. Unlike elsewhere in <filename>LCDd.conf</filename>
    this is a device description understood by serdisplib. As there is not
    default value setting this option is mandatory.
  </para></listitem>
</varlistentry>

<varlistentry>
  <term>
    <property>serdisp_options</property> =
    <parameter><replaceable>OPTIONS</replaceable></parameter>
  </term>
  <listitem><para>
    <replaceable>OPTIONS</replaceable> is a serdisplib option string, which is
    a list of semicolon separated key / value pairs. Use this to pass any
    additional options to serdisplib, e.g. wiring or rotation settings.
  </para>
  <note>
    <para>As the value will contain equal signs the whole <replaceable>OPTIONS</replaceable>
    value must be enclosed in double quotes.</para>
    <para>The display width and height are always set using the values from the
    glcd driver (see above). Any width / height values set in the option string
    will be ignored.</para>
  </note>
  </listitem>
</varlistentry>
</variablelist>

<variablelist>
<title>Settings for the x11 connection type</title>
<varlistentry>
  <term>
    <property>x11_PixelSize</property> =
    <parameter>
      <replaceable>PIXELS</replaceable>
      <literal>+</literal>
      <replaceable>GAP</replaceable>
    </parameter>
  </term>
  <listitem><para>
    Each LCD dot is drawn in the X window as a filled rectangle of this size
    plus a gap between each filled rectangle. A PixelSize of <literal>3+1</literal>
    would draw a 3x3 filled rectangle with a gap of 1 pixel to the right and
    bottom, effectively using a 4x4 area of the window. Default is <literal>3+1</literal>.
  </para></listitem>
</varlistentry>
<varlistentry>
  <term>
    <property>x11_PixelColor</property> =
    <parameter><literal>0x</literal><replaceable>RRGGBB</replaceable></parameter>
  </term>
  <listitem><para>
    The color used to draw each LCD dot at full contrast and full brightness.
    Default is <literal>0x000000</literal>.
  </para></listitem>
</varlistentry>
<varlistentry>
  <term>
    <property>x11_BacklightColor</property> =
    <parameter><literal>0x</literal><replaceable>RRGGBB</replaceable></parameter>
  </term>
  <listitem><para>
    The color used for the backlight at full brightness.
    Default is <literal>0x80FF80</literal>.
  </para></listitem>
</varlistentry>
<varlistentry>
  <term>
    <property>x11_Border</property> =
    <parameter><replaceable>PIXELS</replaceable></parameter>
  </term>
  <listitem><para>
    Extra space in pixels around the LCD portion of the X window.
    Default is <literal>20</literal>.
  </para></listitem>
</varlistentry>
<varlistentry>
  <term>
    <property>x11_Inverted</property> = &parameters.yesnodef;
  </term>
  <listitem><para>
    Swap the colors for the pixel and backlight within the LCD portion of the
    X window. This results in an inverted display.
  </para></listitem>
</varlistentry>
</variablelist>

<variablelist>
<title>Settings for the picolcdgfx connection type</title>
<varlistentry>
  <term>
    <property>picolcdgfx_KeyTimeout</property> =
    <parameter><replaceable>TIMEOUT</replaceable></parameter>
  </term>
  <listitem><para>
    The time in milliseconds to wait for a key press before assuming no key was
    pressed. This settings is the usb_read timeout. Default 125.
  </para></listitem>
</varlistentry>
<varlistentry>
  <term>
    <property>picolcdgfx_Inverted</property> = &parameters.yesnodef;
  </term>
  <listitem><para>
    When set to yes, the pixel will be inverted. Default no.
  </para></listitem>
</varlistentry>
</variablelist>

</sect3>
</sect2>
</sect1>