comment -*- mode: text; tab-width:2; indent-tabs-mode:nil -*-

Framebuffer support

* Tested environment
  Arch Linux
  CentOS 5
  (Linux kernel 2.6 or later)

  FreeBSD 9.0

  NetBSD teokure 6.1.4

  OpenBSD 5.3

* Build
  ./configure --with-gui=fb ...
  make
  sudo make install
  (Framebuffer version and X11 version can coexist in the same directory.
   So you can install main/mlterm-fb and inputmethod/*/*-fb.so alone by
   'make install-fb' to the directory where mlterm (X11 version) has been
   already installed instead of installing all files by 'make install'.)

* Configuration
  Configuration of framebuffer version is the same as that of X11 version
  except font settings as follows.
  Be sure to configure fonts before starting mlterm-fb.

  o Font
    Add pcf or true type fonts you want to show to ~/.mlterm/font-fb.
    The format of ~/.mlterm/font-fb is almost the same as that of ~/.mlterm/font,
    but specify their file paths, not XLFD. (See etc/font-fb.)

    It requires freetype library to show true type fonts.
    If you don't want to use true type fonts, do ./configure with
    --disable-anti-alias option which requires freetype library.

    If mlterm-fb starts with --aafont option, mlterm-fb reads ~/.mlterm/*aafont
    files and searches fonts with the use of fontconfig.
    ./configure with --disable-fontconfig option disables this feature.

* Start
  mlterm-fb (-fg white -bg black -sb=false)

* Note
  (for Linux)
  o If mlterm can't open /dev/input/event<num> of the keyboard, shortcut keys
    are disabled.
    If the string in /sys/class/input/input<num>/name contains "key",
    /dev/input/event<num> is regarded as the keyboard.
    You can specify <num> by "KBD_INPUT_NUM" environmental variable.
    ("KBD_INPUT_NUM" accepts multiple <num> separated by comma (<num>,<num>).)
  o If you want to change keyboard layout, execute "loadkeys xxx" command.
    (e.g. loadkeys jp106)
  o You can input accented characters with the use of 'dead' keys, but
    mlterm-fb reads kernel accent table in startup once.
    If you execute loadkeys after mlterm-fb has started, mlterm-fb doesn't
    read it again.
  o If mlterm can't open /dev/input/event<num> of the mouse, mouse operation is
    disabled.
    If the string in /sys/class/input/input<num>/name contains "mouse",
    /dev/input/event<num> is regarded as the mouse.
    You can specify <num> by "MOUSE_INPUT_NUM" environmental variable.
    ("MOUSE_INPUT_NUM" accepts multiple <num> separated by comma (<num>,<num>).)
  o If you want to use mouse, disable gpm in advance. (/etc/init.d/gpm stop)

  (for FreeBSD)
  o Start FreeBSD kernel with SC_PIXEL_MODE and VESA option and set display mode
    by vidcontrol as follows.
    $ vidcontrol MODE_XXX
  o If you want to change key repeat or enable write-combine, execute
    kbdcontrol -r [delay.repeat] or
    memcontrol set -b 0x.... -l 0x.... write-combine
    in advance.
  o If you want to change keyboard layout, execute "kbdcontrol -l xxx" command.
    (e.g. kbdcontrol -l cz.iso2)
  o Start moused in advance as follows if you want to use mouse (/dev/sysmouse)
    on FreeBSD 5.0 or later.
    $ /etc/rc.d/moused onestart
  o mlterm-fb works with 4 bpp alone on FreeBSD(98).

  (for NetBSD)
  o See https://gist.github.com/tsutsui/5689730
    (Thanks to @tsutsuii san)
  o ./configure automatically determines whether to build mlterm-fb for
    NetBSD/x68k or for wscons.
    It is possible to force it by --with-gui=x68kgrf or --with-gui=wscons option.
  o Boot kernel with vesa.
    [Example of /boot.cfg]
    menu=Boot ... vesa 0x13e;boot
                  ^^^^^^^^^^ -> 0x13e = 640x400x32 ('vesa list' on boot prompt)
  o You can change auto key repeat settings (ms) by the following options of
    ~/.mlterm/main. (The values of these options should be in units of 25ms)
    kbd_repeat_1=400
    kbd_repeat_N=50
  o The keyboard input data is read from /dev/wskbd by default. If you want to
    use another device, set it to the value of WSKBD environmental variable.
    (e.g. export WSKBD=/dev/wskbd0)
  o If you want to change keyboard layout, execute "wsconsctl -w -k encoding=xxx"
    command.
    (e.g. wsconsctl -w -k encoding=cz)
  o 8 bpp is not supported.
  o If you want to use ibus input method plugin (./configure --enable-ibus),
    add "-lpthread" to LIBS2_fb of mlterm-x.x.x/main/Makefile.in before building
    mlterm-fb.
  o The wall picture is shown by ANSI colors on 1, 2 or 4 bpp, but if you
    specify --colors=false (use_ansi_colors=false) and set sixel which contains
    16 or less colors to the wall picture on 4 bpp, it is shown by its palette.
  o You can specify --depth=1 (1bpp) or --depth=4 (4bpp) on NetBSD/luna68k.
  o You can change the screen resolution and depth by fb_resolution option in
    ~/.mlterm/main on NetBSD/x68k. Supported resolutions are 512x512x15
    512x512x8 768x512x4 768x512x1 1024x768x4 1024x768x1 640x480x4.
    fb_resolution=512x512x15
  o Unless you specify --multivram=false or separate_wall_picture=false option
    in fb_resolution=768x512x4, 1024x768x4 or 640x480x4, the wall picture is
    drawn on Text VRAM instead of Graphic VRAM and scrolling performance will
    be improved.

  (for OpenBSD)
  o Enable following options and rebuild kernel.
    (Apply http://mlterm.sourceforge.net/openbsd-5.3-fixvesa.patch for OpenBSD
     4.9 or later at the same time.)
    vesabios0 at mainbus?
    option VESAFB
  o You can change the screen resolution and depth by fb_resolution option in
    ~/.mlterm/main.
    fb_resolution=800x600x32
  o You can change auto key repeat settings (ms) by /etc/wsconsctl.conf or
    wsconsctl command.
    $ wsconsctl keyboard.repeat.del1=400
    $ wsconsctl keyboard.repeat.deln=50
  o The keyboard input data is read from /dev/wskbd by default. If you want to
    use another device, set it to the value of WSKBD environmental variable.
    (e.g. export WSKBD=/dev/wskbd0)

  (Common)
  o You can use a software keyboard if you double-click the left mouse button
    (Button1) at the right bottom corner of the screen. (Not supported on 1, 2
    and 4 bpp)
  o If you want to change fonts dynamically by mlcc, execute mlcc with "font"
    (not "font-fb") argument.
  o To redraw the screen completely, execute a following command.
    $ mlcc exec update_all
  o Available scrollbars are "simple" alone.
    It is not recommended to use them on 1 bpp.
  o Available input method plugins are kbd, m17nlib, uim, iBus and fcitx.
    (iBus is not tested on FreeBSD)
  o You can rotate display (>= 16bpp) by --rotate=right or --rotate=left option.
    ("rotate_display = right" or "rotate_display = left" in ~/.mlterm/main is
     also available.)
    Following command rotates display dynamically.
    $ mlcc rotate_display right
    or $ mlcc rotate_display left
    (To fall back to the default, $ mlcc rotate_display none)

* Unsupported features
  o Daemon mode
  o mlclient (mlclientx is avaialble, though)
  o OPEN_SCREEN shortcut of ~/.mlterm/key.
  o geometry option
