Adds DLI samples and documentation.

Makefile

@@ -70,6 +70,7 @@ SAMPLE_FP_BAS=\
 
 SAMPLE_INT_BAS=\
     int/carrera3d.bas \
+    int/dli.bas \
     int/iospeed.bas \
     int/joyas.bas \
     int/pi.bas \

manual.md

@@ -1587,3 +1587,204 @@ modify memory. Use with care!
   the memory location at _address_.
 
 
+Display List Interrupts
+-----------------------
+
+*Note: This is an advanced topic.*
+
+Display list interrupts (normally called
+`DLI`) are a way to modify display
+registers at certain vertical positions
+on the screen.
+
+You can use them to:
+
+- Display more colors in the image, by
+  changing color registers - registers
+  from $D012 to $D01A.
+
+- Split one Player/Missile graphics to
+  different horizontal positions -
+  registers from $D000 to D007.
+
+- Change scrolling position, screen
+  width, P/M width, etc.
+
+FastBasic allows you to specify one or
+more DLI routines, activate one or
+deactivate all DLI by using the `DLI`
+statement:
+
+
+**Define a new DLI**  
+**DLI SET _name_ = _op1_, _op2_, ... / DLIS.**
+
+  Setups a new DLI with the given name
+  and performing the _op_ operations.
+
+  Each operation is of the form:
+  _data_ `INTO` _address_. `INTO` can be
+  abbreviated to `I.`.
+
+  _data_ is one constant byte or the
+  name of a `DATA BYTE` array, and
+  _address_ is a memory location to
+  modify.
+
+  If _data_ is a DATA array, the first
+  element (at index 0) will be used at
+  the first line with DLI active in the
+  screen, the second element at the
+  second active line, etc.
+
+  You can specify any number of
+  operations, but as each one takes some
+  time you could see display artifacts
+  if you use too many.
+
+  Note that by defining a DLI you are
+  simply giving it a name, you need to
+  activate the DLI afterwards.
+
+  You can split a DLI definition over
+  multiple lines, just like DATA by
+  ending a line with a comma and
+  starting the next line with `DLI =`
+
+
+**Enable a DLI**
+**DLI _name_ / DL.**
+
+  This statement enables the DLI with
+  the given name, the DLI must be
+  defined before in the program.
+
+  This setups the OS DLI pointer to the
+  named DLI and activates the interrupt
+  bit in the display processor (the
+  ANTIC chip), but does not activates on
+  which lines the DLI must be called.
+
+  To define on which lines the DLI is
+  active you must modify the _Display
+  List_, see the example at the end of
+  the section.
+
+  You can also pass the name of a DATA
+  BYTE array with a custom machine
+  language routine to the `DLI`
+  statement, the routine must begin with
+  a _PHA_ and end with _PLA_ and _RTI_.
+
+
+**Disable a DLI**
+**DLI / DL.**
+
+  This statement simply disables the
+  DLI, returning the display to the
+  original
+
+
+**DLI Examples**
+
+  This is the most basic example of a
+  DLI that simply changes the background
+  color at the middle of the screen:
+
+      ' Define the DLI: set background
+      ' color to $24 = dark red.
+      DLI SET d1 = $24 INTO $D01A
+      ' Setups screen
+      GRAPHICS 0
+      ' Alter the Display List, adds
+      ' a DLI at line 11 on the screen
+      POKE DPEEK(560) + 16, 130
+      ' Activate DLI
+      DLI d1
+      ' Wait for any keyu
+      ? "Press a Key" : GET K
+      ' Disable the DLI
+      DLI
+
+  The next example shows how you can use
+  a DLI to change multiple values in the
+  screen:
+
+      ' An array with color values
+      DATA Colors() BYTE = $24,$46,$68
+      ' Define the DLI: set background
+      ' color from the Color() array
+      ' and text color with value $80
+      DLI SET d2 = Colors INTO $D01A, $80 INTO $D018
+      ' Setups screen
+      GRAPHICS 0
+      ' Adds DLI at three lines:
+      POKE DPEEK(560) + 13, 130
+      POKE DPEEK(560) + 16, 130
+      POKE DPEEK(560) + 19, 130
+      ' Activate DLI
+      DLI d2
+      ' Wait for any keyu
+      ? "Press a Key" : GET K
+      ' Disable the DLI
+      DLI
+
+  The final example shows how you can
+  move multiple P/M using one DLI
+
+      ' Player shapes, positions and colors
+      DATA p1() BYTE = $E7,$81,$81,$E7
+      DATA p2() BYTE = $18,$3C,$3C,$18
+      DATA pos() BYTE = $40,$60,$80,$A0
+      DATA c1() BYTE = $28,$88,$C8,$08
+      DATA c2() BYTE = $2E,$80,$CE,$06
+      ' Our DLI writes the position and
+      ' colors to Player 1 and Player 2
+      DLI SET d3 = pos INTO $D000, pos INTO $D001,
+      DLI        = c1 INTO $D012, c2 INTO $D013
+      GRAPHICS 0 : PMGRAPHICS 2
+      ' Setup our 4 DLI and Players
+      FOR I = 8 TO 20 STEP 4
+        POKE DPEEK(560) + I, 130
+        MOVE ADR(p1), PMADR(0)+I*4+5,4
+        MOVE ADR(p2), PMADR(1)+I*4+5,4
+      NEXT
+      ' Activate DLI
+      DLI d3
+      ? "Press a Key"
+      REPEAT
+        PAUSE 0
+        pos(0) = pos(0) + 2
+        pos(1) = pos(1) + 1
+        pos(2) = pos(2) - 1
+        pos(3) = pos(3) - 2
+      UNTIL KEY()
+      DLI
+
+
+**Some usefull registers**
+
+  This is a table of some useful
+  registers to change during a DLI:
+
+|Address| Register                  |
+| ----- | ------------------------- |
+| $D000 | Player 0 horizontal pos.  |
+| $D001 | Player 1 horizontal pos.  |
+| $D002 | Player 2 horizontal pos.  |
+| $D003 | Player 3 horizontal pos.  |
+| $D004 | Missile 0 horizontal pos. |
+| $D005 | Missile 0 horizontal pos. |
+| $D006 | Missile 0 horizontal pos. |
+| $D007 | Missile 0 horizontal pos. |
+| $D012 | Color of Player 0         |
+| $D013 | Color of Player 0         |
+| $D014 | Color of Player 0         |
+| $D015 | Color of Player 0         |
+| $D016 | Color register 0          |
+| $D017 | Color register 1          |
+| $D018 | Color register 2          |
+| $D019 | Color register 3          |
+| $D01A | Color of Background       |
+
+

samples/int/dli.bas

@@ -0,0 +1,72 @@
+' Define the DLI: set background
+' color to $24 = dark red.
+DLI SET d1 = $24 INTO $D01A
+' Setups screen
+GRAPHICS 0
+' Alter the Display List, adds
+' a DLI at line 11 on the screen
+POKE DPEEK(560) + 16, 130
+' Activate DLI
+DLI d1
+' Wait for any keyu
+? "Press a Key" : GET K
+' Disable the DLI
+DLI
+
+? "Again..."
+GET K
+
+' An array with color values
+DATA Colors() BYTE = $24,$46,$68
+' Define the DLI: set background
+' color from the Color() array
+' and text color with value $80
+DLI SET d2 = Colors INTO $D01A, $80 INTO $D018
+' Setups screen
+GRAPHICS 0
+' Adds DLI at three lines:
+POKE DPEEK(560) + 13, 130
+POKE DPEEK(560) + 16, 130
+POKE DPEEK(560) + 19, 130
+' Activate DLI
+DLI d2
+' Wait for any keyu
+? "Press a Key" : GET K
+' Disable the DLI
+DLI
+
+? "Again..."
+GET K
+
+' Player shapes, positions and colors
+DATA p1() BYTE = $E7,$81,$81,$E7
+DATA p2() BYTE = $18,$3C,$3C,$18
+DATA pos() BYTE = $40,$60,$80,$A0
+DATA c1() BYTE = $28,$88,$C8,$08
+DATA c2() BYTE = $2E,$80,$CE,$06
+' Our DLI writes the position and
+' colors to Player 1 and Player 2
+DLI SET d3 = pos INTO $D000, pos INTO $D001,
+DLI        = c1 INTO $D012, c2 INTO $D013
+GRAPHICS 0 : PMGRAPHICS 2
+' Setup our 4 DLI and Players
+FOR I = 8 TO 20 STEP 4
+  POKE DPEEK(560) + I, 130
+  MOVE ADR(p1), PMADR(0)+I*4+5,4
+  MOVE ADR(p2), PMADR(1)+I*4+5,4
+NEXT
+' Activate DLI
+DLI d3
+? "Press a Key"
+REPEAT
+  PAUSE 0
+  pos(0) = pos(0) + 2
+  pos(1) = pos(1) + 1
+  pos(2) = pos(2) - 1
+  pos(3) = pos(3) - 2
+UNTIL KEY()
+DLI
+
+? "Key to end..."
+GET K
+