Differences

This shows you the differences between two versions of the page.

--- human_interface [2016/05/31 19:27]
ex_writer [DOIT]
+++ — (current)
@@ Line 1: / Line 1: @@
-====== Human Interface ======
-The Human Interface system routines handle input from the [[keypad]] and control handles, scoring, system pausing and blackout, and menu display.
-===== Human Interface System Routines =====
-Undocumented routines are marked with an asterisk (*)
-^ Name ^ Description ^
-| [[human interface#doit|DOIT]] | Responds to input transition (and branches to transition handler) |
-| [[human interface#doitb|DOITB]]* | Like DOIT, but uses B instead of A |
-| [[human interface#getnum|GETNUM]] | Get a number from the user |
-| [[human interface#getpar|GETPAR]] | Get game parameter from user ("Enter <prompt string>") |
-| [[human interface#incscr|INCSCR]] | Increment 3-byte score and compare to end score (ENDSCR) |
-| [[human interface#kctasc|KCTASC]] | Converts Bally keypad code to ASCII |
-| [[human interface#menu|MENU]] | Display menu and branch on choice |
-| [[human interface#msktd|MSKTD]] | Mask joystick in B to Deltas |
-| [[human interface#paws|PAWS]] | Pause for specified number of interrupts |
-| [[human interface#pizbrk|PIZBRK]] | Black out screen and wait for key/trigger/joystick input |
-| [[human interface#sentry|SENTRY]] | Wait for change of program status in ports/timers/counters |
-===== Human Interface System Routine Descriptions =====
-==== DOIT ====
-RESPOND TO INPUT TRANSITION
-| Calling Sequence: | <code z80>SYSTEM    DOIT</code> or <code z80>SYSSUK    DOIT
-DW        (DOIT table)
-</code>|
-| Arguments: | A = Return code from SENTRY routine\\ B = Extended return code\\ HL = DOIT table address |
-| Description: | This routine is used with [[#sentry|SENTRY]] for dispatching to a state transition routine. The return code from SENTRY is used to search the DOIT table. If a match is found, control is transferred to the associated handling routine. If no match is found, the routine repeats.\\ \\ The handling routine may be macro or machine instructions. The routine receives registers as they are on DOIT entry. If no transition is found, execution continues at the first instruction following call. |
-The DOIT table is a linear list composed of 3-byte entries, with one entry per SENTRY return code.
-{{doit_table.png}}
-//Transfer type// (byte 0, bits 6–7) designates how the handler address is to be transferred to. The codes are:
-  * 00 = JMP to machine language routine and pop context
-  * 01 = [[user program interface#rcall|RCALL]] machine language routine in current context
-  * 10 = [[user program interface#mcall|MCALL]] interpreter routine in current context
-Mode 01 and 10 expect the returned-to point to be interpretive; mode 00 expect it to be machine instructions.
-//Return code// (byte 0, bit 0–5) [from SENTRY?]
-//Handler address// (bytes 1 and 2) contains the address of the handling routine.
-End of list is indicated by a terminator byte that is greater than or equal to $C0.
-See [[human interface#keyboard input example|Keyboard Input Example]] below for example SENTRY and DOIT usage.
-==== DOITB ====
-RESPOND TO INPUT TRANSITION (USING B)
-| Calling Sequence: | <code z80>SYSTEM    DOITB</code> or <code z80>SYSSUK    DOITB
-DW        (DOIT table)
-</code>|
-| Notes: | Identical to DOIT, but uses B instead of A |
-==== GETNUM ====
-GET NUMBER
-| Calling Sequence: | <code z80>SYSTEM    GETNUM</code> or <code z80>SYSSUK    GETNUM
-DB        (x-coordinate)
-DB        (y-coordinate)
-DB        (CHRDIS options)
-DB        (DISNUM options)
-DW        (number address)</code>|
-| Arguments: | B = [[screen handler#disnum|]]DISNUM display options\\ C = [[screen handler#chrdis|CHRDIS]] display options\\ D = Y-coordinate for feedback display\\ X-coordinate for feedback display\\ HL = Address to store entered number |
-| Description: | This routine captures number input from either the keypad or the player one control handle pot. Keypad entry has priority. The routine exits when the specified number of digits are entered or = is pressed on the keypad.\\ \\ Pot entry is enabled by pressing the trigger. The current pot value is then shown. Twist the pot until the number you want is shown. Then press the trigger again to complete entry. |
-| Restrictions: | The pot can only enter 1 or 2 digits. If a group of numbers is being entered, the user must enable entry for each new number. |
-==== GETPAR ====
-GET GAME PARAMETER
-| Calling Sequence: | <code z80>SYSTEM    GETPAR</code> or <code z80>SYSSUK    GETPAR
-DW        (prompt)
-DB        (digits)
-DW        (parameter)</code>|
-| Arguments: | A = number of digits to get\\ BC = address of prompt string\\ DE = title string address (not loaded)\\ HL = address of parameter to get |
-| Description: | A menu frame is created displaying the title passed in DE. The message "ENTER" is displayed in the center of the screen, followed by the prompt string. [[human interface#getnum|GETNUM]] is entered with feedback specified in 2X enlarged characters. After entry is complete, GETPAR pauses for ¼ second to allow the user to see their entry, then returns.  |
-| Notes: | See entry conditions and resource requirements for menu.\\ \\ Prompt string example: "# OF PLAYERS"\\ \\ The title string address (DE) is usually the title returned from [[human interface#menu|MENU]].\\ \\ The parameter address (HL) points at the [[glossary#l|low-order]] byte of the BCD number in RAM. |
-| Restrictions: | None |
-==== INCSCR ====
-INCREMENT SCORE AND COMPARE TO END SCORE
-| Calling Sequence: | <code z80>SYSTEM    INCSCR</code> or <code z80>SYSSUK    INCSCR
-DW        (address of score)</code>|
-| Arguments: | HL = Address of score (must be 3 bytes long) |
-| Output: | Score incremented and optionally game over bit set |
-| Description: | The 3-byte score pointed at by HL (BCD with low-order byte at lowest address) is incremented by 1 and compared to the end score (ENDSCR). If the end score bit (GSBSCR) was set in the game status byte (GAMSTB) and end score has been reached, then the game over bit (GSBEND) is set in the game status byte. |
-==== KCTASC ====
-KEY CODE TO ASCII
-| Calling Sequence: | <code z80>SYSTEM    KCTASC</code>|
-| Arguments: | B = key code (not loaded) |
-| Output: | A = ASCII equivalent of key code |
-| Notes: | None |
-| Description: | This routine does a table lookup (listed below) |
-| Restrictions: | None |
-^ Key Code ^ Name ^ Graphic ^ Hex Value ^
-| 1 | Clear | C | 43 |
-| 2 | Up Arrow | ↑ | 5E |
-| 3 | Down Arrow | ↓ | 5C |
-| 4 | Percent | % | 25 |
-| 5 | Recall | MR | 52 |
-| 6 | Store | MS | 53 |
-| 7 | Change Sign | CH | 3B |
-| 8 | Divide | ÷ | 2F |
-| 9 | 7 | 7 | 37 |
-| 10 | 8 | 8 | 38 |
-| 11 | 9 | 9 | 39 |
-| 12 | Multiply | × | 2A |
-| 13 | 4 | 4 | 34 |
-| 14 | 5 | 5 | 35 |
-| 15 | 6 | 6 | 36 |
-| 16 | Minus | − | 2D |
-| 17 | 1 | 1 | 31 |
-| 18 | 2 | 2 | 32 |
-| 19 | 3 | 3 | 33 |
-| 20 | Plus | + | 2B |
-| 21 | Clear Entry | CE | 26 |
-| 22 | 0 | 0 | 30 |
-| 23 | Decimal Point | . | 2E |
-| 24 | Equals | = | 3D |
-==== MENU ====
-DISPLAY MENU AND BRANCH ON SELECTION
-| Calling Sequence: | <code z80>SYSTEM    MENU</code> or <code z80>SYSSUK    MENU
-DW        (menu title string address)
-DW        (menu list address</code>|
-| Arguments: | DE = Address of menu title string\\ HL = Address of menu list |
-| Output: | DE = String address of selection mode |
-| Description: | The title is displayed at the top of the screen. Each entry in the menu list is then displayed with a preceding number supplied by MENU. [[human interface#getnum|GETNUM]] is called to get the selection number. The menu list is searched for the selected node and it is jumped to. |
-| Notes: | A maximum of eight entries may appear.\\ \\ On entry, MENU expects interrupts to be enabled and colors and boundaries to be initialized. MENU uses 96 lines of screen, creams the alternate set, and requires three levels of context. MENU calls [[human interface#sentry|SENTRY]] and thus 'eats' all irrelevant transitions. |
-Menu List Layout:
-{{menu_list.png}}
-==== MSKTD ====
-JOYSTICK MASK TO DELTAS
-| Calling Sequence: | <code z80>SYSTEM    MSKTD</code> or <code z80>LD        B,(joystick mask)
-SYSSUK    MSKTD
-DW        (x-delta)
-DB        (flop flag)
-DW        (y-delta)
-</code>|
-| Arguments: | B = Joystick mask (not loaded)\\ C = Flop flag\\ DE = X positive delta\\ HL = Y positive delta |
-| Output: | DE = X-Delta\\ HL = Y-Delta |
-| Description: | This routine uses the joystick mask and flop flag to conditionally modify the passed deltas. If negative direction is indicated, the delta is 2's complemented; if no direction is indicated, 0 is returned.\\ \\ MSKTD uses the value returned by a joystick and returns positive, negative, or zero values depending on the delta values provided. Delta values entered are what we would like to use if the joystick is held right (left if flopped) or down. Negative values will be returned if the joystick is left (right if flopped) or up.\\ \\ If we give it an x-delta of 1.0 for single pixel motion, we will get -1.0 for left, 0.0 for middle, and 1.0 for right. Dropping these values directly into the x-delta bytes of the vector block, then calling VECT and VWRITR, will move the pattern appropriately for direct motion control. Passing a delta of 0.25 and adding the resulting values to the vector block deltas would simulate, for example, the inertial motion of a spaceship.  |
-| Note: | B is not loaded by SYSSUK. |
-The joystick mask (B) is the byte value returned by the joystick port. That is, reading the appropriate port for a joystick ($10 for joystick 0) and placing the value here works. Alternatively, you can call the SENTRY command, pick up the joystick changes through DOIT, and the value will already be in the B register.
-==== PAWS ====
-PAUSE
-| Calling Sequence: | <code z80>SYSTEM    PAWS</code> or <code z80>SYSSUK    PAWS
-DB        (number of interrupts)</code>|
-| Arguments: | B = number of interrupts to wait |
-| Notes: | None |
-| Description: | This routine pauses for a specified number of interrupts. If used with [[interrupt scheduler#actint|ACTINT]], a value of 60 = 1 second. This routine does an EI upon entry and assumes interrupts will occur.  |
-| Restrictions: | None |
-==== PIZBRK ====
-BLACK OUT SCREEN AND WAIT FOR KEY
-| Calling Sequence: | <code z80>SYSTEM    PIZBRK</code> or <code z80>SYSSUK    PIZBRK
-DB        (number of interrupts)</code>|
-| Arguments: | none |
-| Output: | none |
-| Description: | This routine blacks out the screen and waits for either a key press, trigger, or joystick change. This function should be called whenever a "hold until further notice" is needed.\\ \\ All keys on the keypad are enabled. Interrupts are disabled on entry and enabled on exit. It is recommended to reset any 60th of a second timers on exiting PIZBRK. |
-==== SENTRY ====
-SENSE TRANSITION
-| Calling Sequence: | <code z80>SYSTEM    SENTRY</code> or <code z80>SYSSUK    SENTRY
-DW        (Key mask address)</code>|
-| Arguments: | DE = Keypad mask table |
-| Output: | A = Return code\\ B = Extended code (see output chart below) |
-| Description: | SENTRY checks for changes in the potentiometers (pots), control handles, triggers, keypad, [[glossary#s|semaphores]], and counters/timers. It also takes care of blackout, the automatic blacking-out of the screen after 255 seconds without a change. If SENTRY isn't called, then the game will not black out.\\ \\ SENTRY checks if TIMOUT equals zero on entry, and if zero, it goes to PIZBRK. If a key has gone down or a control handle changed, then TIMOUT is set to $FF.\\ \\ HL should point at a keypad mask. The keypad consists of 6 rows by 4 columns.\\ \\ Example mask of 0–9 only:\\ <code z80>
-DB      011100B
-DB      111100B
-DB      011100B
-DB      000000B</code> |
-| Restrictions: | None |
-The keypad mask is arranged as follows:
-{{keypad_mask.png}}
-Sentry output chart:
-^ Priority ^ A = ^ Meaning ^ B = ^
-| | SNUL | Nothing changed | |
-| 1 | SCT//n// | Counter/timer //n// decremented to 0 (n=0–7) | |
-| 2 | SF//n// | SEMI4S bit //n// was 1 (//n//=0–7) | |
-| 3 | SP//n// | Pot //n// changed (//n//=0–3) | new value |
-| 4 | SSEC | 1 second has elapsed since the last SSEC | |
-| 5 | SKYU | Keypad went from down to up | 0 |
-| 5 | SKYD | Key is down | key number |
-| 6 | SJ//n// | Joystick //n// changed (//n//=0–3) | new value |
-| 6 | ST//n// | Trigger //n// changed (//n//=0–3) | new value |
-**Notes:**
-  * The potentiometers (pots) are [[glossary#d|debounced]].
-  * New trigger value = trigger off ($0) or trigger on ($10).
-  * When switches are actuated simultaneously, the order of return is: SCT7 to SCT0, SF7 to SF0, SP0 to SP3, SSEC, SKYU, SKYD, SJ0, ST0, SJ1, ST1, SJ2, ST2, SJ3, ST3.
-===== Keyboard Input Example =====
-This routine echoes number keys and takes a coffee break on trigger 0 being pulled. Assumes SP is set and screen erases.
-<code z80>
-          SYSTEM     INTPC
-LOOP:     DO         SENTRY
-          DW         NUMBAS
-          DO         DOIT
-          DW         DTAB
-          DO         MJUMP
-          DW         LOOP
-NUMBAS:   DB         011100B          ;NUMBER KEYS ONLY
-          DB         111100B
-          DB         011100B
-          DB         0
-DTAB:     MC         SKYD,SHOW        ;ON KEY DOWN MACRO CALL
-          MC         ST0,PBREAK+END   ;ON TO MACRO CALL
-SHOW:     DO         KCTASC           ;CONVERT TO ASCII
-          DO         SUCK
-          DB         00000111B        ;X,Y=0=DE
-          DB         11001100B        ;OPTIONS=C
-          DONT       CHRDIS           ;DISPLAY CHAR
-          MRET                        ;BACK TO LOOP
-PBREAK:   DO         PIZBRK           ;COFFEE BREAK
-          DO         MRET             ;BACK TO LOOP
-</code>
-----
-[NM:55]