Skip to content
php-baremetal REGISTRY
Publish a package

php-baremetal/ext-input

bm-ext MIT

Touch input for php-baremetal: the Touch interface, the Pressed/Moved/Released/Gesture events and a C API for touch drivers. Platform-neutral.

ext-input · Reference

C API for touch drivers

What a touch driver calls to raise events: bm_input.h.

A driver implements Baremetal\Input\Touch and uses include/bm_input.h to raise the events. ext-input has no platform code, so the same driver runs wherever ext-events does. The package that carries the driver requires php-baremetal/ext-input.

Start order. The extension of a driver package must start after ext-input (and ext-input after ext-events): a PHP class that implements Baremetal\Input\Touch must be registered once the interface exists. ext-input's priority is 50, so a driver package whose extension runs in the 100s starts after it.

typedef enum { BM_INPUT_PRESSED = 1, BM_INPUT_MOVED, BM_INPUT_RELEASED, BM_INPUT_GESTURE } bm_input_kind_t;
typedef enum { BM_INPUT_SWIPE_UP = 1, BM_INPUT_SWIPE_DOWN, BM_INPUT_SWIPE_LEFT, BM_INPUT_SWIPE_RIGHT,
               BM_INPUT_TAP, BM_INPUT_DOUBLE_TAP, BM_INPUT_LONG_PRESS } bm_input_gesture_t;

struct _zend_class_entry *bm_input_touch_ce(void);
struct _zend_object *bm_input_gesture_case(bm_input_gesture_t g);
struct _zend_object *bm_input_touch_events(struct _zend_object *dev, void **rec);
void bm_input_touch_emit(void *rec, bm_input_kind_t kind, int x, int y, bm_input_gesture_t gesture);
Function Use
bm_input_touch_ce() The Baremetal\Input\Touch interface, to implement it with zend_class_implements() in the driver's class setup.
bm_input_gesture_case() The GestureType case of a gesture, for the driver's own gesture() method; NULL for an unknown value. The case is borrowed. PHP task only.
bm_input_touch_events() Call it from events(), on the PHP task, passing the driver's object. It registers the event classes the first time, creates the record of that object and returns the Baremetal\Source handle to return to PHP. *rec receives the record to give to bm_input_touch_emit(). It returns NULL with an exception when the event table is full.
bm_input_touch_emit() Raises an event.

Rules

  • One record per device object. A second bm_input_touch_events() call for the same object returns a new handle on the same record, and the record is kept until the module shuts down. It keeps the object alive, because every event carries it as $device.
  • bm_input_touch_emit() can be called from any task, such as a task that reads the chip while PHP runs on another core, but not from an interrupt handler. It takes no PHP memory and touches no PHP value: it copies kind, x, y (clamped to 16 bits) and, for BM_INPUT_GESTURE, gesture into the event slot, and the properties are filled later on the PHP task.
  • While the source is stopped, or before events() was called, nothing is raised. The driver may call bm_input_touch_emit() regardless. An event is also dropped, and counted by the bus, when no event slot is free.
  • x and y are screen coordinates: apply the panel's orientation before calling. gesture matters only for BM_INPUT_GESTURE; pass 0 for the other kinds.
  • An event is dropped, with no error, when kind is not a bm_input_kind_t value, or when kind is BM_INPUT_GESTURE and gesture is not a bm_input_gesture_t value. Map the codes of the chip to the enum before calling.
  • Hand rec to the task that emits through a synchronising primitive (queue, semaphore, task notification), so the record is visible there.

Sketch

static void *s_rec;

PHP_METHOD(MyTouch, events)
{
    ZEND_PARSE_PARAMETERS_NONE();
    zend_object *h = bm_input_touch_events(Z_OBJ_P(ZEND_THIS), &s_rec);
    if (h == NULL) {
        RETURN_THROWS();
    }
    RETURN_OBJ(h);
}

/* on the task that reads the chip */
bm_input_touch_emit(s_rec, BM_INPUT_MOVED, x, y, 0);   /* gesture: ignored for non-gesture kinds */

(In a real driver the record belongs to the device, not to a static.)

Related