Graphics: FillScreen

       Name: FillScreen                                              [Show more]
       Type: Subroutine
   Category: Graphics
    Summary: Fill a rectangular in screen memory or the screen buffer with the
             specified background
    Context: See this subroutine in context in the source code
 References: This subroutine is called as follows:
             * ClearScreen calls FillScreen
             * DrawUpdatedObject calls FillScreen
             * PanLandscapeView calls FillScreen


 Arguments:

   A                    Determines whether we fill screen memory or the screen
                        buffer:

                          * 0 = fill the screen

                          * 25 = fill the screen buffer

   X                    The number of character columns to fill

   Y                    The number of character rows to fill

   screenBackground     The type of background to fill the rectangle with:

                          * 0 = fill with alternating colour 0/1 (blue/black)
                                pixel rows, for the sky during gameplay

                          * 1 = fill with solid colour 0 (blue)

                          * 2 = fill with dithered pixels in colour 0 (blue)
                                and colour 3 (e.g. green in landscape 0000)
                                by alternating colour 3/0/3/0 and 0/3/0/3
                                pixel bytes

                          * 3 = fill with solid colour 1 (black)


.FillScreen

 STA fillRowNumber      \ Set fillRowNumber = A, so we start filling from this
                        \ character row number
                        \
                        \ When we are filling the screen buffer, this value is
                        \ 25 + the row number, so we can use this value as a
                        \ lookup into the screenRowAddrLo and screenRowAddrHi
                        \ tables, and it will return the corresponding address
                        \ from the bufferRowAddrLo or bufferRowAddrHi table, to
                        \ give us the row address in the screen buffer

 STY screenRowCounter   \ Set screenRowCounter = Y, so we will fill this many
                        \ character rows

 TXA                    \ If X < 32 then each character row in the fill will fit
 CMP #32                \ into 256 bytes (as each character block is eight bytes
 BCC fill1              \ and 32 * 8 = 256), so jump to fill1 to set bit 7 of
                        \ moreColumnsToFill to record this fact

                        \ If we get here then each character row in the fill
                        \ needs more than 256 bytes, so we set A to the number
                        \ of columns that we need to fill beyond the 256-byte
                        \ limit, which we get by subtracting 32 from the total
                        \ number of columns we need to fill

 SBC #32                \ Set A = X - 32 to store in moreColumnsToFill below
                        \ (this subtraction works as we just passed through a
                        \ BCC instruction, so we know the C flag is set)

 LDX #32                \ Set X = 32 to set as the value of columnCounter below,
                        \ so we fill 32 columns in the first iteration around
                        \ the fill loop, and then fill moreColumnsToFill columns
                        \ in the second iteration

 BNE fill2              \ Jump to fill2 to skip the following instruction (this
                        \ BNE is effectively a JMP as X is never zero)

.fill1

 LDA #%10000000         \ Set bit 7 of moreColumnsToFill in the next instruction
                        \ to indicate that this fill does not require more than
                        \ 32 columns

.fill2

 STA moreColumnsToFill  \ Set moreColumnsToFill to the value of A that we set
                        \ above

 STX columnCounter      \ Set columnCounter to the updated value of X, so this
                        \ contains the number of columns to fill in the first
                        \ iteration around the fill loop (i.e. the total number
                        \ of columns if it's less than 32, or 32 if we need to
                        \ do the fill in two stages)

 LDX screenBackground   \ Set T to the backgroundEven pixel byte for the screen
 LDA backgroundEven,X   \ background type in screenBackground, to give us the
 STA T                  \ pixel byte we should be clearing the screen to for
                        \ even pixel rows

 LDA backgroundOdd,X    \ Set U to the backgroundOdd pixel byte for the screen
 STA U                  \ background type in screenBackground, to give us the
                        \ pixel byte we should be clearing the screen to for odd
                        \ pixel rows

.fill3

 LDX fillRowNumber      \ Set (Q P) to the entry from the screenRowAddrLo and
 LDA screenRowAddrLo,X  \ screenRowAddrHi tables for the character row whose
 STA P                  \ number is in fillRowNumber
 LDA screenRowAddrHi,X  \
 STA Q                  \ When we are filling the screen buffer, fillRowNumber
                        \ is 25 + the row number, so we can use this value as a
                        \ lookup into the screenRowAddrLo and screenRowAddrHi
                        \ tables, and it will return the corresponding address
                        \ from the bufferRowAddrLo or bufferRowAddrHi table, to
                        \ give us the row address in the screen buffer

 LDX columnCounter      \ Set X to the number of columns that we need to fill

 LDA #1                 \ Set loopCounter = 1 so we only do a maximum of two
 STA loopCounter        \ fill stages, to prevent an incorrectly configured fill
                        \ from filling up more than 64 columns

                        \ We now fill X character blocks from screen address
                        \ (Q P) onwards, alternating each pixel row between the
                        \ pixel bytes in T and U

.fill4

 LDY #&FF               \ Set Y = &FF so we increment Y to zero at the start of
                        \ the following loop, so we can use it as an index into
                        \ the block of screen memory starting at (P Q)

.fill5

 INY                    \ Increment the index in Y to point to the first byte
                        \ in the character block

 LDA T                  \ Set the first byte in the character block to T
 STA (P),Y

 INY                    \ Increment the index in Y to point to the second byte
                        \ in the character block

 LDA U                  \ Set the second byte in the character block to U
 STA (P),Y

 INY                    \ Increment the index in Y to point to the third byte
                        \ in the character block

 LDA T                  \ Set the third byte in the character block to T
 STA (P),Y

 INY                    \ Increment the index in Y to point to the fourth byte
                        \ in the character block

 LDA U                  \ Set the fourth byte in the character block to U
 STA (P),Y

 INY                    \ Increment the index in Y to point to the fifth byte
                        \ in the character block

 LDA T                  \ Set the fifth byte in the character block to T
 STA (P),Y

 INY                    \ Increment the index in Y to point to the sixth byte
                        \ in the character block

 LDA U                  \ Set the sixth byte in the character block to U
 STA (P),Y

 INY                    \ Increment the index in Y to point to the seventh byte
                        \ in the character block

 LDA T                  \ Set the seventh byte in the character block to T
 STA (P),Y

 INY                    \ Increment the index in Y to point to the eighth byte
                        \ in the character block

 LDA U                  \ Set the eighth byte in the character block to U
 STA (P),Y

 DEX                    \ Decrement the column counter in X

 BNE fill5              \ Loop back until we have filled X character blocks

 DEC loopCounter        \ Decrement the loop counter

 BMI fill6              \ If we have already run two fill loops, jump to fill6
                        \ to move on to the next row, so we never do more than
                        \ two fill stages

 LDX moreColumnsToFill  \ Set X to the value of moreColumnsToFill, which either
                        \ has bit 7 set, or contains the number of columns we
                        \ still need to fill on top of the 32 we just filled

 BMI fill6              \ If bit 7 of moreColumnsToFill is set then each row in
                        \ the fill fits into 256 bytes, so we will have already
                        \ filled in the required bytes and can jump to fill6 to
                        \ move on to the next row

 INC Q                  \ Increment the high byte of (Q P) to point to the next
                        \ page in memory

 JMP fill4              \ Loop back to fill4 to continue filling along the
                        \ character row, filling the number of columns in X to
                        \ take us to the correct total number for the row

.fill6

 INC fillRowNumber      \ Increment the row number to move down to the next
                        \ character row

 DEC screenRowCounter   \ Decrement the row counter

 BNE fill3              \ Loop back to fill the next character row until we have
                        \ filled the number of rows in screenRowCounter

 RTS                    \ Return from the subroutine