                   hw-visual-lcd (none :: hw-visual-display)

Synopsis:

   Simulates a dot matrix LCD display, using Tcl/Tk to manage the graphics
   window

     ----------------------------------------------------------------------

Functionality:

  Modelling:

   The LCD display model is somewhat abstracted from the physical device:

     * A real display typically has separate row and column pins that are
       cycled to select each pixel in the display. These are replaced by 2
       pins in the model. The FR (frame) pin is driven to 1 to identify that
       a new frame is starting, and driven to 0 when the frame is finished.
       The row-col pin incorporates all of the functionality of the row and
       column drivers on the real chip. This pin is driven once for each "on"
       pixel in the display. The value on the pin is the [X,Y] co-ordinates
       of the pixel, encoded as two adjacent 16-bit values in the 32-bit pin
       value.

       The two pins are used to initiate and terminate a display refresh
       cycle. A display refresh cycle starts when the FR pin is asserted; the
       [X,Y] co-ordinates of all the "on" pixels are then transmitted on the
       row-col pin; and the FR pin is de-asserted to end the refresh cycle.

     * The physical device must be refreshed periodically, but the model
       retains its last written values indefinitely.

   +-------------------------------------------------+
   |                    Behaviors                    |
   |-------------------------------------------------|
   | configuration | The window geometry is          |
   |               | specified in SCREEN pixels via  |
   |               | the width and depth attributes. |
   |               | Each pixel in the simulated     |
   |               | display occupies a box of       |
   |               | bits-per-pixel by               |
   |               | bits-per-pixel screen pixels.   |
   |               | bits-per-pixel is also a        |
   |               | settable attribute, and         |
   |               | defaults to a 4X4 box. Thus,    |
   |               | the number of simulated rows is |
   |               | depth/bits-per-pixel; and the   |
   |               | number of simulated columns is  |
   |               | width/bits-per-pixel.           |
   |               |                                 |
   |               | While "on" pixels are currently |
   |               | always drawn as black, the      |
   |               | background color of the         |
   |               | simulated display can be        |
   |               | specified using the standard    |
   |               | Tcl/Tk color specification      |
   |               | syntax (eg. #6fa700 or white).  |
   |               | This color is specified with    |
   |               | the background-color attribute. |
   |---------------+---------------------------------|
   |       display | See discussion of the FR and    |
   |               | row-col pins in Modeling        |
   |               | section above                   |
   +-------------------------------------------------+

   +-------------------------------------------------+
   |                 SID Conventions                 |
   |-------------------------------------------------|
   |         functional | supported          | -     |
   |--------------------+--------------------+-------|
   |       save/restore | not supported      | -     |
   |--------------------+--------------------+-------|
   |      triggerpoints | not supported      | -     |
   +-------------------------------------------------+

     ----------------------------------------------------------------------

Environment:

   Related components

   The LCD display is typically connected to a controller via the tk-bridge.
   The following configuration file segment shows how the HD44780U LCD
   controller can be connected to the hw-visual-lcd display:

       new hw-lcd-hd44780u-a00 lcd       # Standard Japanese font
       new hw-visual-lcd display         # instantiate the display
      
       # display size is in pixels - ie. font-width*display-height
       set display width 40              # 8 chars X 5 pixels per char
       set display height 8              # single line of 8 pixels

       # connect the LCD to the display
       connect-pin lcd row-col -> display row-col
       connect-pin lcd FR -> display FR

    

     ----------------------------------------------------------------------

Component Reference:

  Component: hw-visual-lcd

   +-------------------------------------------------+
   |                      pins                       |
   |-------------------------------------------------|
   |  name   | direction |  legalvalues  | behaviors |
   |---------+-----------+---------------+-----------|
   | FR      | in        | binary        | display   |
   |---------+-----------+---------------+-----------|
   | row-col | in        | 2 shorts as a | display   |
   |         |           | 32-bit value  |           |
   +-------------------------------------------------+

   +----------------------------------------------------------+
   |                        attributes                        |
   |----------------------------------------------------------|
   |      name      |category|  legal  |default|  behaviors  ||
   |                |        | values  | value |             ||
   |----------------+--------+---------+-------+-------------||
   |                |        |any      |20*8*4 |             ||
   |width           |setting |positive |= 480  |configuration||
   |                |        |value    |       |             ||
   |----------------+--------+---------+-------+-------------||
   |                |        |any      |4*8*4 =|             ||
   |height          |display |positive |128    |configuration||
   |                |        |value    |       |             ||
   |----------------+--------+---------+-------+-------------||
   |                |        |any      |       |             ||
   |bits-per-pixel  |setting |positive |4      |configuration||
   |                |        |value    |       |             ||
   |----------------+--------+---------+-------+-------------||
   |                |        |any legal|       |             ||
   |background-color|setting |tk color |-      |             ||
   |                |        |specifier|       |             ||
   +----------------------------------------------------------+
