Input device

This is the specification for the input device of the Bedrock computer system.

This document is aimed at people who are implementing the Bedrock system from scratch. For people who are learning about or writing program for the Bedrock system, the input device manual will generally be more useful.

Concepts

Pointer position

The pointer position is a pair of signed 16 bit coordinates representing the position of the screen pixel underneath the pointer, sharing a coordinate space with the screen device. The horizontal coordinate increases rightwards, and the vertical coordinate increases downwards. The origin is the top-left pixel of the Bedrock screen.

Scroll delta

Each scroll delta is a signed 16 bit value representing the distance scrolled along an axis since the value was last read. The distance is measured in lines, and saturates at bounds. The distance scrolled by each increment of a smooth scrolling device is determined by the implementation. The initial value of each delta is zero.

The horizontal scroll delta increases when scrolling rightwards (the action that would slide content leftwards) and decreases when scrolling leftwards, and the vertical scroll delta increases when scrolling downwards (the action that would slide content upwards) and decreases when scrolling upwards.

Button list

A button list is an 8 bit value representing a set of held buttons. Each bit in the value represents a button on an input device, with a bit being set only if the corresponding button is being held.

Character queue

The character queue is a first-in first-out byte queue that buffers received characters.

When a character is received from a keyboard device, that character is converted to a UTF-8 encoded byte sequence and then, if there is sufficient capacity, pushed byte-by-byte to the back of the queue. The enter or return key is represented by the newline character 0x0A. The maximum length of the queue is determined by the implementation.

Ports

Horizontal coordinate

Reading from this port group will perform an atomic read, returning the horizontal coordinate of the pointer position.

Vertical coordinate

Reading from this port group will perform an atomic read, returning the vertical coordinate of the pointer position.

Horizontal scroll

Reading from this port will return the horizontal scroll delta, and then will set the horizontal scroll delta to zero.

Vertical scroll

Reading from this port will return the vertical scroll delta, and then will set the vertical scroll delta to zero.

Pointer active

The pointer is active only while the pointer position is within the screen bounds, or while a pointer button that was pressed while within screen bounds is still being held. A touchscreen pointer is only active while touched.

Reading from this port will return 0xFF if the pointer is active, or 0x00 otherwise.

Pointer button

Reading from this port will return a button list representing the list of pointer buttons that are held down, mapped as per the following table:

If the pointer device is a right-handed mouse, primary is the left-mouse button, secondary is the right-mouse button, and tertiary is the middle-mouse button. For a left-handed mouse, primary and secondary will be reversed. If the pointer device is a touchscreen, primary is the touchscreen surface.

Keyboard input

Reading from this port will remove and return a byte from the front of the character queue. Reading while the character queue is empty will return a zero byte.

Writing any value to this port will clear the character queue. If a non-zero byte was written and the system uses an onscreen keyboard for text entry, the onscreen keyboard will be made available. If a zero byte was written, the onscreen keyboard will be hidden.

Keyboard modifier

Reading from this port will return a button list representing the list of keyboard modifiers that are held down, mapped as per the following table:

Controller

Each controller port is associated with a gamepad device, in order from the least-recently to most-recently connected.

Reading from one of these ports will return a button list representing the list of buttons that are held down on the associated gamepad, mapped as per the following table:

An analog stick or directional pad on the gamepad will map to the up, down, left, and right buttons.

The affirmative face button maps to confirm, the negative face button maps to cancel, the primary action face button maps to primary, and the secondary action face button maps to secondary. The face buttons used by popular game consoles map to controller buttons as follows:

Implementation notes

Emulated gamepad

On systems with a hardware keyboard, the first gamepad should also be emulated from keyboard input. The up, down, left, and right arrow keys should map to the corresponding gamepad buttons, the enter key to confirm, and the escape key to cancel.

Cursor icon

The system cursor icon should be hidden while the pointer device is within the screen bounds, so that each program can render their own cursor.

Wake behaviour

This device will send a wake request to the system device when any of the following events occur:

• A pointer button is pressed or released
• A keyboard modifier is pressed or released
• A controller button is pressed or released
• A character is received from the keyboard device
• The pointer active state changes
• The pointer position changes
• The horizontal or vertical scroll delta changes