WSDISPLAY(4)              OpenBSD Programmer's Manual             WSDISPLAY(4)

NAME
     wsdisplay - generic display device support in wscons

SYNOPSIS
     wsdisplay* at ...
     option WSDISPLAY_DEFAULTSCREENS=N

DESCRIPTION
     The wsdisplay driver is an abstraction layer for display devices within
     the wscons(4) framework.  It attaches to the hardware specific display
     device driver and makes it available as text terminal or graphics inter-
     face.

     Display devices have the ability to display characters on them (without
     help of an X server), either directly by hardware or through software
     drawing pixel data into the display memory.  The wsdisplay driver will
     connect a terminal emulation module and provide a tty-like software in-
     terface.

     The console locator in the configuration line refers to the device's use
     as output part of the operating system console.  A device specification
     containing a positive value here will only match if the device is in use
     as system console.  (The console device selection in early system startup
     is not influenced.)  This way, the console device can be connected to a
     known wsdisplay device instance.

     The mux locator in the configuration line refers to the wsmux(4) that
     will be used to get keyboard events.  If this locator is -1 no mux will
     be used.

     The logical unit of an independent contents displayed on a display (some-
     times referred to as ``virtual terminal'') is called a ``screen'' here.
     If the underlying device driver supports it, multiple screens can be used
     on one display.  (As of this writing, only the lcd(4) and vga(4) display
     drivers provide this ability.)  Screens have different minor device num-
     bers and separate tty instances.  One screen possesses the ``focus'',
     this means it is displayed on the display and its tty device will get the
     keyboard input.  (In some cases, if no screen is set up or if a screen
     was just deleted, it is possible that no focus is present at all.)  The
     focus can be switched by either special keyboard input (typically CTL-
     ALT-Fn) or an ioctl command issued by a user program.  Screens are set up
     or deleted through the /dev/ttyCcfg control device (preferably using the
     wsconscfg(8) utility).  Alternatively, the compile-time option
     WSDISPLAY_DEFAULTSCREENS=N will set up N screens of the display driver's
     default type and using the system's default terminal emulator at autocon-
     figuration time.

     In addition and with help from backend drivers the following features are
     also provided:

     o   Loading, deleting and listing the loaded fonts.

     o   Browsing backwards in the screen output, the size of the buffer for
         saved text is defined by the particular hardware driver.

     o   Blanking the screen by timing out on inactivity in the screen holding
         the input focus.  Awakening activities consist of:

         o   pressing any keys on the keyboard;
         o   moving or clicking the mouse;
         o   any output to the screen.

         Blanking the screen is usually done by disabling the horizontal sync
         signal on video output, but may also include blanking the vertical
         sync in which case most monitors go into power saving mode.  See
         wsconsctl(8) for controlling variables.

     Consult the back-end drivers' documentation for which features are sup-
     ported for each particular hardware type.

   IOCTL INTERFACE
     The following ioctl(2) calls are provided by the wsdisplay driver or by
     devices which use it.  Their definition are found in
     <dev/wscons/wsconsio.h>.

     WSDISPLAYIO_GTYPE (u_int)
           Retrieve the type of the display.  The list of types is in
           <dev/wscons/wsconsio.h>.

     WSDISPLAYIO_GINFO (struct wsdisplay_fbinfo)
           Retrieve basic information about a framebuffer display.  The re-
           turned structure is as follows:

                 struct wsdisplay_fbinfo {
                         u_int   height;
                         u_int   width;
                         u_int   depth;
                         u_int   cmsize;
                 };

           The height and width members are counted in pixels.  The depth mem-
           ber indicates the number of bits per pixel, and cmsize indicates
           the number of color map entries accessible through
           WSDISPLAYIO_GETCMAP and WSDISPLAYIO_PUTCMAP.  This call is likely
           to be unavailable on text-only displays.

     WSDISPLAYIO_GETCMAP (struct wsdisplay_cmap)
           Retrieve the current color map from the display.  This call needs
           the following structure set up beforehand:

                 struct wsdisplay_cmap {
                         u_int   index;
                         u_int   count;
                         u_char  *red;
                         u_char  *green;
                         u_char  *blue;
                 };

           The index and count members specify the range of color map entries
           to retrieve.  The red, green, and blue members should each point to
           an array of count u_chars.  On return, these will be filled in with
           the appropriate entries from the color map.  On all displays that
           support this call, values range from 0 for minimum intensity to 255
           for maximum intensity, even if the display does not use eight bits
           internally to represent intensity.

     WSDISPLAYIO_PUTCMAP (struct wsdisplay_cmap)
           Change the display's color map.  The argument structure is the same
           as for WSDISPLAYIO_GETCMAP, but red, green, and blue are taken as
           pointers to the values to use to set the color map.  This call is
           not available on displays with fixed color maps.

     WSDISPLAYIO_GVIDEO (u_int)
           Get the current state of the display's video output.  Possible val-
           ues are:

           WSDISPLAYIO_VIDEO_OFF  The display is blanked.

           WSDISPLAYIO_VIDEO_ON   The display is enabled.

     WSDISPLAYIO_SVIDEO (u_int)
           Set the state of the display's video output.  See
           WSDISPLAYIO_GVIDEO above for possible values.

     WSDISPLAYIO_GCURPOS (struct wsdisplay_curpos)
           Retrieve the current position of the hardware cursor.  The returned
           structure is as follows:

                 struct wsdisplay_curpos {
                         u_int x, y;
                 };

           The x and y members count the number of pixels right and down, re-
           spectively, from the top-left corner of the display to the hot spot
           of the cursor.  This call is not available on displays without a
           hardware cursor.

     WSDISPLAYIO_SCURPOS (struct wsdisplay_curpos)
           Set the current cursor position.  The argument structure, and its
           semantics, are the same as for WSDISPLAYIO_GCURPOS.  This call is
           not available on displays without a hardware cursor.

     WSDISPLAYIO_GCURMAX (struct wsdisplay_curpos)
           Retrieve the maximum size of cursor supported by the display.  The
           x and y members of the returned structure indicate the maximum num-
           ber of pixel rows and columns, respectively, in a hardware cursor
           on this display.  This call is not available on displays without a
           hardware cursor.

     WSDISPLAYIO_GCURSOR (struct wsdisplay_cursor)
           Retrieve some or all of the hardware cursor's attributes.  The ar-
           gument structure is as follows:

                 struct wsdisplay_cursor {
                         u_int   which;
                         u_int   enable;
                         struct wsdisplay_curpos pos;
                         struct wsdisplay_curpos hot;
                         struct wsdisplay_cmap cmap;
                         struct wsdisplay_curpos size;
                         u_char *image;
                         u_char *mask;
                 };

           The which member indicates which of the values the application re-
           quires to be returned.  It should contain the logical OR of the
           following flags:

           WSDISPLAYIO_CURSOR_DOCUR
                 Get enable, which indicates whether the cursor is currently
                 displayed (non-zero) or not (zero).

           WSDISPLAYIO_CURSOR_DOPOS
                 Get pos, which indicates the current position of the cursor
                 on the display, as would be returned by WSDISPLAYIO_GCURPOS.

           WSDISPLAYIO_CURSOR_DOHOT
                 Get hot, which indicates the location of the ``hot spot''
                 within the cursor.  This is the point on the cursor whose po-
                 sition on the display is treated as being the position of the
                 cursor by other calls.  Its location is counted in pixels
                 from the top-left corner of the cursor.

           WSDISPLAYIO_CURSOR_DOCMAP
                 Get cmap, which indicates the current cursor color map.  Un-
                 like in a call to WSDISPLAYIO_GETCMAP, cmap here need not
                 have its index and count members initialized.  They will be
                 set to 0 and 2 respectively by the call.  This means that
                 cmap.red, cmap.green, and cmap.blue must each point to at
                 least enough space to hold two u_chars.

           WSDISPLAYIO_CURSOR_DOSHAPE
                 Get size, image, and mask.  These are, respectively, the di-
                 mensions of the cursor in pixels, the bitmap of set pixels in
                 the cursor and the bitmap of opaque pixels in the cursor.
                 The format in which these bitmaps are returned, and hence the
                 amount of space that must be provided by the application, are
                 device-dependent.

           WSDISPLAYIO_CURSOR_DOALL
                 Get all of the above.

           The device may elect to return information that was not requested
           by the user, so those elements of struct wsdisplay_cursor which are
           pointers should be initialized to NULL if not otherwise used.  This
           call is not available on displays without a hardware cursor.

     WSDISPLAYIO_SCURSOR (struct wsdisplay_cursor)
           Set some or all of the hardware cursor's attributes.  The argument
           structure is the same as for WSDISPLAYIO_GCURSOR.  The which member
           specifies which attributes of the cursor are to be changed.  It
           should contain the logical OR of the following flags:

           WSDISPLAYIO_CURSOR_DOCUR
                 If enable is zero, hide the cursor.  Otherwise, display it.

           WSDISPLAYIO_CURSOR_DOPOS
                 Set the cursor's position on the display to pos, the same as
                 WSDISPLAYIO_SCURPOS.

           WSDISPLAYIO_CURSOR_DOHOT
                 Set the ``hot spot'' of the cursor, as defined above, to hot.

           WSDISPLAYIO_CURSOR_DOCMAP
                 Set some or all of the cursor color map based on cmap.  The
                 index and count elements of cmap indicate which color map en-
                 tries to set, and the entries themselves come from cmap.red,
                 cmap.green, and cmap.blue.

           WSDISPLAYIO_CURSOR_DOSHAPE
                 Set the cursor shape from size, image, mask.  See above for
                 their meanings.

           WSDISPLAYIO_CURSOR_DOALL
                 Do all of the above.

           This call is not available on displays without a hardware cursor.

     WSDISPLAYIO_GMODE (u_int)
           Get the current mode of the display.  Possible results include:

           WSDISPLAYIO_MODE_EMUL
                 The display is in emulating (text) mode.

           WSDISPLAYIO_MODE_MAPPED
                 The display is in mapped (graphics) mode.

           WSDISPLAYIO_MODE_DUMBFB
                 The display is in mapped (frame buffer) mode.

     WSDISPLAYIO_SMODE (u_int)
           Set the current mode of the display.  For possible arguments, see
           WSDISPLAYIO_GMODE.

     WSDISPLAYIO_GBURNER (struct wsdisplay_burner)
           Retrieves the state of the screen burner.  The returned structure
           is as follows:

                 struct wsdisplay_burner {
                         u_int   off;
                         u_int   on;
                         u_int   flags;
                 };

           The off member contains the inactivity time before the screen is
           turned off, in milliseconds.  The on member contains the time be-
           fore the screen is turned back on, in milliseconds.  The flags mem-
           ber contains a logical OR of the following flags:

           WSDISPLAY_BURN_VBLANK
                 When turning the display off, disable the vertical synchro-
                 nization signal.

           WSDISPLAY_BURN_KBD
                 Monitor keyboard activity.

           WSDISPLAY_BURN_MOUSE
                 Monitor mouse activity (this only works for mice using the
                 wsmouse(4) driver).

           WSDISPLAY_BURN_OUTPUT
                 Monitor display output activity.

           If none of the activity source flags are set, the screen burner is
           disabled.

     WSDISPLAYIO_SBURNER (struct wsdisplay_burner)
           Sets the state of the screen burner.  The argument structure, and
           its semantics, are the same as for WSDISPLAYIO_GBURNER.

     WSDISPLAYIO_WSMOUSED (struct wscons_event)
           This call is used by the wsmoused(8) daemon to inject mouse events
           gathered from serial mice, as well as various control events.

     WSDISPLAYIO_GETPARAM (struct wsdisplay_param)
           Retrieves the state of a display parameter.  This call needs the
           following structure set up beforehand:

                 struct wsdisplay_param {
                         int param;
                         int min, max, curval;
                         int reserved[4];
                 };

           The param member should be set with the parameter to be returned.
           The following parameters are supported:

           WSDISPLAYIO_PARAM_BACKLIGHT
                 The intensity of the display backlight (usually on laptop
                 computers).

           WSDISPLAYIO_PARAM_BRIGHTNESS
                 The brightness level.

           WSDISPLAYIO_PARAM_CONTRAST
                 The contrast level.

           On return, min and max specify the allowed range for the value,
           while curval specifies the current setting.  Not all parameters are
           supported by all display drivers.

     WSDISPLAYIO_SETPARAM (struct wsdisplay_param)
           Sets a display parameter.  The argument structure is the same as
           for WSDISPLAYIO_GETPARAM, with the param and curval members filled
           in.  Not all parameters are supported by all display drivers.

     WSDISPLAYIO_LINEBYTES (u_int)
           Get the number of bytes per row when the device is in
           WSDISPLAYIO_MODE_DUMBFB mode.

FILES
     /dev/tty[C-F]*                      terminal devices (per screen)
     /dev/tty[C-F]cfg                    control device (per screen)
     /usr/include/dev/wscons/wsconsio.h

SEE ALSO
     intro(4), tty(4), wscons(4), wsmux(4), wsconscfg(8), wsconsctl(8),
     wsfontload(8)

BUGS
     The wsdisplay code currently limits the number of screens on one display
     to 8.

     The terms ``wscons'' and ``wsdisplay'' are not cleanly distinguished in
     the code and in manual pages.

OpenBSD 4.7                     April 26, 2009                               6
