====== Pattern Writing ======

Virtually every videogame involves the manipulation of animated figures. These figures are composed of patterns that are arbitrary pixel arrays. The Bally Arcade's write routines are used to transfer such patterns to the screen.

Five hierarchical levels of write routine calls are supported. The levels differ in the amount of preprocessing required by the user before calling. The highest level assumes that most of the parameters reside in a standard data structure, while the lowest level presumes that all arguments are in registers with all attendant transformations (such as relative-to-absolute conversion) already accomplished. The five levels are:

^ Level ^ System Routine ^ Function ^
| 1 | [[system routines:screen handler#vwritr|VWRITR]] | Write Relative from a Vector |
| 2 | [[system routines:screen handler#writr|WRITR]] | Write Relative |
| 3 | [[system routines:screen handler#writp|WRITP]] | Write with Size from Pattern Block |
| 4 | [[system routines:screen handler#writ|WRIT]] | Write Pattern |
| 5 | [[system routines:screen handler#writa|WRITA]] | Write Pattern to Absolute (i.e., Screen RAM) Address |

===== Pattern Transformations =====

Two pattern transformations may be performed prior to writing: FLOP and EXPAND. FLOP mirrors the pattern on the x-axis. EXPAND translates a 1-bit per pixel pattern into a 2-bit per pixel pattern. Since many patterns are only two-color, this allows for more efficient pattern storage. FLOP and EXPAND may be used simultaneously.

===== Writing Modes =====

Three Writing Modes may be used: PLOP, OR, and XOR. PLOP is a conventional store into RAM. The OR option ORs the data bit-by-bit with the data that was already present. Similarly, if XOR is set, the pattern is XORed with the data 'beneath' it. Use of OR or XOR takes slightly longer, since a read before write is necessary.

Note that ROTATE is not supported in software due to space considerations.

===== Standard Calling Sequence =====

Every write routine uses a subset of the following register/argument assignments:

^ Register ^ Argument ^ Note ^
| A | [[hardware:magic system|Magic Register]] | |
| B | Y Pattern Size | # Vertical Bytes (i.e., 8 vertical pixels = 8 bytes) |
| C | X Pattern Size | # Horizontal Bytes (i.e., 8 horizontal pixels = 1 byte) |
| D | Y-Coordinate | 0–101 |
| E | X-Coordinate | 0–159 |
| HL | Pattern Address | |
| IX | Vector Address | |

===== The Pattern Block =====

The higher the level of the write routine, the more ancillary information is stored with the pattern. The following diagram shows what each level expects. Any bytes of a lower address than the pointer for a given level need not be specified.

**Use Restrictions:** None of the write routines are [[:glossary#r|reentrant]] due to [[hardware:magic system#magic register|Magic Register]] / [[hardware:magic system#expander|Expander]] clobber.

{{:pattern_representation.png}}

==== X/Y Displacement ====

This value allows you to set the "control point" for the pattern. The default point is at the upper lefthand corner of the pattern. Positive x displacements move the control point right, and positive y displacements move the control point down. Moving the control point allows the user to dictate how calculations relate to the pattern. For instance, displacing the control point to the center of a ball pattern can make limit checks consistent from any direction.
==== X/Y Size ====

X-size defines the pattern's width in //bytes// and is dependent upon whether the pattern is full-color or monochrome (expanded). Full-color patterns are stored two-bits-per-pixel (2bpp), so a pattern that is eight pixels wide would have an x-size of two bytes. Monochrome images are stored one-bit-per-pixel (1bpp), so eight pixels would equal one byte.

Y-size defines the pattern's height in bytes.