Input device

This is the user manual for the input device of the Bedrock computer system.

This document is aimed at people who are learning about or writing programs for the Bedrock system. For people who are implementing the system from scratch, the input device specification will provide more relevant information.

Overview

The input device provides inputs from a keyboard, a mouse or other pointing device, and four 8-button gamepads.

Concepts

The mouse cursor position is represented as a pair of pixel coordinates, using the same coordinate space as the screen device. Each coordinate value is signed, where the values 0000 to 7FFF represent 0 to +32767, and the values FFFF to 8000 represent -1 to -32768. The pixel in the top-left corner of the screen has coordinates zero-zero.

The horizontal scroll and vertical scroll ports each use pixel deltas to represent the distance scrolled, with a delta being the number of pixels scrolled since that port was last read. Each delta is a signed byte, where the values 00 to 7F represent 0 to +127, and the values FF to 80 represent -1 to -128.

The mouse button, modifier, navigation, and gamepad ports each use byte values to represent button states. Each bit of a byte represents a different button, with the bit being set only if the button is currently being held down.

Ports

Horizontal coordinate

Reading a double from this port will return the horizontal coordinate of the mouse cursor. The value is measured in pixels and increases rightwards. The pixel in the top-left corner of the program window has a coordinate of zero.

See the reading the mouse cursor example.

Vertical coordinate

Reading a double from this port will return the vertical coordinate of the mouse cursor. The value is measured in pixels and increases downwards. The pixel in the top-left corner of the program window has a coordinate of zero.

See the reading the mouse cursor example.

Horizontal scroll

Reading a byte from this port will return the distance scrolled horizontally since the port was last read, as a signed byte. The value is measured in pixels and increases rightwards.

See the reading scroll deltas example.

Vertical scroll

Reading a byte from this port will return the distance scrolled vertically since the port was last read, as a signed byte. The value is measured in pixels and increases downwards.

See the reading scroll deltas example.

Mouse active

Reading a byte from this port will return FF if the mouse cursor is within screen bounds or being dragging, or 00 otherwise.

Mouse button

Reading a byte from this port will return a byte representing the held states of the mouse buttons. Each bit represents a mouse button, and is set if the button is held.

See the detecting button events example.

Keyboard active

Reading a byte from this port will return FF if a keyboard is available, or 00 otherwise.

Writing a non-zero byte to this port will reveal an on-screen keyboard on a touchscreen device, and writing a zero byte will hide the on-screen keyboard.

Character

Characters typed on the keyboard are UTF-8 encoded and buffered in a queue. Reading a byte from this port will remove and return the oldest byte from the queue, or 00 if the queue is empty.

See the reading from the keyboard example.

Modifier

Reading a byte from this port will return a byte representing the held states of the keyboard modifier keys. Each bit represents a modifier key, and is set if the key is held.

See the detecting button events example.

Navigation

Reading a byte from this port will return a byte representing the held states of the navigation keys. Each bit represents a navigation key, and is set if the key is held.

See the detecting button events example.

Gamepad

Reading from each of the four gamepad ports will return a byte representing the held state of the buttons on that gamepad. Each bit represents a button, and is set if the button is held. The directional buttons represent analog sticks or a directional pad.

See the detecting button events example.

Wake behaviour

This device will wake the system from sleep when it receives any mouse, keyboard, or gamepad input.

Examples

Reading the mouse cursor

The position of the mouse cursor can be found by reading the horizontal coordinate and vertical coordinate ports. This example reads the cursor position each frame and prints it to the terminal:

@start
  LDD*:40 JMS:print-double  ( print horizontal position )
  :' ' STD:86               ( print a space character   )
  LDD*:42 JMS:print-double  ( print horizontal position )
  :00 STD:83                ( end the transmission      )
  *:0800 STD*:00 JMP:start  ( wait for an input event   )

@print-double  ( n* -- )
  r:04 &loop                ( n*     | i )
    ROL*:04 DUP AND:0F      ( n* d   | i )
    DUP GTH:09 AND:07       ( n* d l | i )
    ADD ADD:30 STD:86       ( n*     | i )
    DECr DUPr JCNr:~loop    ( n*     | i )
  POPr POP* JMPr            (        |   )

Reading scroll deltas

The scroll delta values can be found by reading the horizontal scroll and vertical scroll ports. This example reads the scroll deltas each frame, printing cumulative distances to the terminal:

DUP*:0000                     ( x* y*      )

@start
  SWP* LDD*:44 ADD*           ( y* x*      )
  DUP* JMS:print-double       ( y* x*      )
  :' ' STD:86                 ( y* x*      )
  SWP* LDD*:46 ADD*           ( x* y*      )
  DUP* JMS:print-double       ( x* y*      )
  :00 STD:83                  ( x* y*      )
  *:0800 STD*:00 JMP:start    ( x* y*      )

@print-double  ( n* -- )
  r:04 &loop                  ( n*     | i )
    ROL*:04 DUP AND:0F        ( n* d   | i )
    DUP GTH:09 AND:07         ( n* d l | i )
    ADD ADD:30 STD:86         ( n*     | i )
    DECr DUPr JCNr:~loop      ( n*     | i )
  POPr POP* JMPr              (        |   )

Reading from the keyboard

To read character input from the keyboard, read bytes from the character port until a zero byte is returned. The bytes read are UTF-8 encoded characters:

@start
  JMS:read-chars
  *:0800 STD*:00
  JMP:start

@read-chars  ( -- )
  JMP:~start &loop
    STD:86 &start
    LDD:4A DUP JCN:~loop
  POP JMPr

Detecting button events

To detect press and release events for a mouse, keyboard, or controller button, compare the current state of the button bit to the previous state. This example will print to the terminal whenever the left mouse button is pressed or released:

%λ: JMSr: ;

@start
  PSH:[&prev 00] LDD:49            ( old new )
  AND:80 DUP STA:~prev             ( old new )
  DUP* NOT AND JCS:print-released  ( old new )
  SWP  NOT AND JCS:print-pressed   (         )
  *:0800 STD*:00 JMP:start         (         )

@print-released  ( -- )
  λ:{"RELEASED "} JMP:print-string
@print-pressed  ( -- )
  λ:{"PRESSED "} JMP:print-string

@print-string  ( string* -- )
  JMP:~start &loop
    STD:86 INC* &start
    DUP* LDA DUP JCN:~loop
  POP POP* :00 STD:83 JMPr