Event Broker

Peripherals pose a unique challenge to standard I/O in that interactive peripheral device state is constantly changing. A task working with a peripheral must continually monitor it to know what the user is doing. It can either run a loop that periodically polls the device, which involves considerable CPU overhead, or have the driver respond only to I/O requests that indicate a change-a similarly cumbersome scheme.

The 3DO operating system solves this problem with the event broker, a task that monitors activity exclusively on the control port. Control port activities, or events, include the pressing of any buttons and manipulation of controls on peripherals, as well as connection and disconnection of peripherals in a daisy chain.

The event broker task starts at system bootup and stands as a kind of gatekeeper between user tasks and interactive devices on the control port. To work with interactive peripheral devices, a user task connects to the event broker and registers itself as a listener. A listener, then, is a task connected to the event broker to receive event notification from peripherals, or to pass data to peripherals.

For more information, see Chapter 9 "Understanding Devices and I/O" in 3DO System Programmer's Guide.

Sample Programs

The examples:Eventbroker:joystick folder contains sample programs that enable you to connect and use peripherals. This section describes the basic procedure for working with these programs, including all relevant function calls.

  1. Make a communications connection to the event broker.

    BS_ConnectBroker();

  2. Listen for the devices from which you want events with the following calls:

    BS_WatchPad();
    BS_WatchJoyStick();
    BS_WatchMouse();
    BS_WatchLGun();

  3. To pay attention to certain events at particular times, interleave Ignore and Watch calls with any of the following:

    BS_IgnoreCPad()
    BS_IgnoreLGun()
    BS_IgnoreMouse()
    BS_IgnoreJoyStick()

  4. Wait for event broker events in a CPU-friendly fashion.

    BS_NiceWaitEvent();

    BS_NiceWaitEvent() returns a mask indicating which devices have received data.

    If you receive signals other than event broker message signals, get the signals you received with:

    BS_GetOtherSignals();

    The mask BS_PORT_CHANGE indicates there has been a change on the control port device daisy chain.

  5. Get a tally of devices with:

    BS_GetPeripheralCount();

  6. Manipulate received data with any of the following:

    BS_ProcessJoyStickData();
    BS_ProcessCPadData();
    BS_ProcessMouseData();
    BS_ProcessLGunData();

  7. Shut down the connection to the broker and free up temporary data allocations.

    BS_DisconnectBroker();
For more extensive sample code for programming peripherals using the event broker, see the 3DO:examples:Eventbroker folder provided on the Portfolio 2.5 CD-ROM. In particular, see the 3DO:examples:Eventbroker:Joystick folder.

For sample code that shows how to incorporate a light gun peripheral into a title, see the 3DO:examples:Eventbroker:Lightgun folder that is provided with this release. Sample code for other types of peripherals is also included in the 3DO:examples:Eventbroker folder.

Note: Sample code is provided to illustrate functionality and is not always the best solution to a problem.