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
  FreeBSD(98) 4.11

  NetBSD teokure 9.0

  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, canna, wnn, skk, m17nlib, uim, iBus
    and fcitx. If you use uim, don't forget to set LANG environmental variable
    correctly.
    (iBus is not tested on FreeBSD)
  o Set LANG environmental variable in advance in order for uim to select an
    appropriate conversion engine.
  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
