netsurf/docs/using-framebuffer.md

--------------------------------------------------------------------------------
  Usage Instructions for Framebuffer NetSurf                  2nd October 2010
--------------------------------------------------------------------------------

  This document provides usage instructions for the Framebuffer version of 
  NetSurf.

  Framebuffer NetSurf has been tested on Ubuntu and Debian.

Overview
========

  What it is
  ----------

  The NetSurf framebuffer front end is primarily intended for kiosk
   and embedded applications where there is insufficient Operating
   System support for a full graphical windowing environment.

  The framebuffer frontend features:

  * A trivial occluded rectangle window management toolkit

  * Font handling system using either:
    - A trivial internal monochrome bitmap glyph set.
    - An interface to fully anti-aliased glyphs using libfreetype 2

  * Uses libnsfb to provide transparent support for:
    - Numerous surface providers allowing usage on Linux, X, SDL, VNC
      and any mapped linear memory region.
    - Surface depths of 8, 16, 24 and 32bpp 
    - Optimised software plotters for lines, rectangles, polygons,
      arbitrary ellipses (including circles), cubic and quadratic
      splines, font glyphs and 32bpp RGBA bitmaps.
    - Abstracted input handling.
 
  What it is not
  --------------
  
  The framebuffer frontend is not a replacement for full native
   ports. It lacks functionality and flexibility compared to such
   implementations. 

  Limitations include:
    - Single window interface.
    - No tabbed interface.
    - Expects to control the entire plotting surface.
    - No ability to re-size a surface after initialisation.
    - Inflexible input character mapping.
    - Limited history view.

  In addition it should be noted support for some libnsfb surfaces has
   been implemented purely for debugging functionality (SDL
   especially) and is not intended to replace native surface
   handlers.

  If a high level windowing system is available then a native NetSurf
   frontend is almost certainly a better choice than attempting to use
   the framebuffer frontend.

  If there is a graphical environment which supports GTK then using
   the GTK frontend is a vastly superior choice. The framebuffer
   frontend will appear exceptionally limited on such capable systems.

Running
=======

  The framebuffer frontend is executed with the nsfb command. This
   command takes parameters to control the operation of the
   browser. The 'Configuring' section describes the available options
   in detail.

  The selection of the display surface is controlled with the -f
   switch, the available display surfaces can be shown by passing '?'
   as the parameter.

    $ ./nsfb -f ?
    ./nsfb: Valid surface names are:
    ./nsfb: ram
    ./nsfb: sdl
    ./nsfb: x
    ./nsfb: vnc
    ./nsfb: wld

  The avilable surfaces are dependant on what was compiled into the
   nsfb library.

  Common issues
  -------------

  - The browser appears to "hang" with no output

    This is often cause by the unintentianal selection of the debug
     "ram" surface. In this case the browser is in fact operating but
     the output is being rendered to a memory buffer. the solution is
     to explictly select the intended surface using the -f switch

  - The displayed browser interface has no visible icons

    This is generally because the necessary resources are not availale
     on the resource search path.

  - There is no displayed text.

    The font configuration is incorrect either it has been compiled
      wrongly or the configured freetype font is not available

  - The browser messages are "bad"

    If the browser messages are being emited as unrecognisable short
     text symbols or in the wrong language it is likely the Messages
     file could not be located. This can be confirmed by looking for
     the text "Message translations failed to load" in the verbose log
     output (run the browser with the -v switch)

Configuring
===========

  Several resources are set at *compile* time and are not changeable at
   run time such as the icon bitmaps, the font system to use and what
   default surface to use. Refer to the BUILDING-Framebuffer document
   for details.

  As with any NetSurf frontend run-time configuration is read from a
   "Choices" file. This file is a simple key:value list and by default
   is located in "${HOME}/.netsurf/Choices".

  The standard [core user options](docs/netsurf-options.md) are
   available. In addition to the core options there are a number of
   values to control specific aspects of the framebuffer version.

  Toolkit Options
  ---------------

  The trivial toolkit has some configuration parameters allowing the
   user to alter specific aspects of the UI. All the sizes are in
   surface pixels however that is mapped.

  fb_furniture_size 
    This is the size allowed for the scroll bar elements.

  fb_toolbar_size
    The height of the toolbar.

  fb_toolbar_layout
    The layout of the toolbar, layout uses a string to define buttons
    type and position each character adds an element to the toolbar:

    b - Move back in history
    l - Display the local history
    f - Move forward in history
    s - stop fetching content
    r - refresh content
    u - url bar expands to fit remaining space
    t - throbber/activity indicator
    c - close the current window
    q - Disable The toolbar altogether

    If the option contains only the q specifier the toolbar is
    disabled altogether (this was previously the empty string but that
    was difficult to configure correctly).

    The default layout is "blfsrutc" there should be no more than a
    single url bar entry.

  fb_osk
    Whether the on screen keyboard should be enabled for input.


  Framebuffer Surface
  -------------------

  There are four command line switches which override compiled in
   defaults these are:

  -f <handler>   
     Selects a surface handler to pass to libnsfb instead of the
     default. (e.g. x, sdl, mem, linux)

  -b <depth>
     Selects the pixel depth to pass to libnsfb instead of the
     compiled in default. (one of 8, 16, 24, 32)

  -w <width>
     Selects the surface width to pass to libnsfb instead of the
     compiled in default.

  -h <height>
     Selects the surface height to pass to libnsfb instead of the
     compiled in default.

  The libnsfb surface parameters are controlled with:

    fb_refresh - The refresh rate (for physical displays)
    fb_depth - The depth (in bits per pixel) of the surface
    fb_device - The path to the device (for physical displays)
    fb_input_devpath - The path to the input devices (for linux input layer)
    fb_input_glob - The input device selection glob  (for linux input layer)
    window_width - The width of the framebuffer
    window_height - The height of the framebuffer

  The defaults are for 800 by 600 pixels at 16bpp and 70Hz refresh rate.

  The documentation of libnsfb should be consulted for further
   information about supported surfaces and their configuration.

  Fonts
  -----

  If the compile time option is set to use the freetype font system
   then several configuration options are available. If the simple
   bitmap glyphs are used none of these options apply.

  Font faces are provided for the css default styles of sans serif,
   serif, monospace, cursive and fantasy. Only the sans serif
   non-italic normal weight font is required to exist, If any of the
   other faces are missing the sans serif font will be used instead.

  The compiled in default font file paths are specified within the
  build time Makefile.config. The default faces is the truetype DejaVu
  font set in the directory /usr/share/fonts/truetype/ttf-dejavu/

  The font glyphs are, by default, rendered as 256 level transparency
   which gives excellent visual results even on small font sizes.

  The font selection may be changed by placing truetype font files
   in the resources path. The resource files will be the generic names
   sans_serif.ttf, sans_serif_bold.ttf etc. 

  The font system is configured at run-time by several options: 

  fb_font_monochrome 
    This option causes the renderer to use monochrome glyph
    rendering. This method of rendering is much less visually
    appealing and while faster to plot it is slower to render.

  fb_font_cachesize
    This option sets the number of kilobytes of memory set aside for
    caching the rendered glyphs. This caching significantly improves
    the performance of using the freetype rendering system. It is set
    to 2048 by default (2 Megabytes of memory) which impiracle testing
    shows to be a suitable value for the seven default faces.

  The remaining options control the files to be used for font faces. The
   font file name options will override both the compiled in paths and
   files found in the resource path.

  fb_face_sans_serif - The sans serif face
  fb_face_sans_serif_bold - The bold sans serif face
  fb_face_sans_serif_italic - The italic sans serif face
  fb_face_sans_serif_italic_bold - The bold italic sans serif face.
  fb_face_serif - The serif font
  fb_face_serif_bold - The bold serif font
  fb_face_monospace - The monospaced font
  fb_face_monospace_bold - The bold monospaced font
  fb_face_cursive - The cursive font
  fb_face_fantasy - The fantasy font