z80:Input and Output
Contents
Existing Tutorials
- Sigma's Learn Assembly in 28 Days, Day 11.
- Sigma's Learn Assembly in 28 Days, Day 12.
Introduction
The most important part of any program is the ability to interact with the user. So how can you get the calculator to interact with the user? The answer is through the use of input and output methods. Input (prefix: in) is the feedback the user gives the program. Output (prefix: out) is the result of said inputs the program gives the user. There are many ways of getting user input and giving back useful output. The basics will be discussed below.
Displaying Large Text
Displaying Characters
Displaying text is not as great as it should be. Mostly because it isn't just one instruction like in Ti Basic where you just choose Output(. First you have to set the coordinates of where you want the text to be placed. There are two variables, Rows and Columns. To set the number of rows down, you load A to CurRow. (Current Row) Then you load A to CurCol. (Current Column) Now the calculator knows exactly where to place the text. But before we go any further, you should know that displaying single letters and numbers is different then displaying strings of text.
_PutC is a system call that will display the character on the screen and then move the flashing cursor over to the next place. It "puts" a Character on the screen. Notice that it only displays a character, though. Below is some code that would display text:
Ld A, 2 Ld (CurRow), A Ld A, 6 Ld (CurCol), A Ld A, 'W' b_call(_PutC)
TI's 'ASCII' table of characters
So how does the calculator know that $5A, $38, $30, $20, $52, $4F, $43, $53 means Z80 ROCKS? The answer is the TI 'ASCII' table. It's sort of similar to the ASCII table for computers, except TI changed it slightly. The TI ASCII table is essentially a table of characters that when PutS or any other text displaying routine is called is used to display the correct character. So, when you have a $5A, on the table it equates to the letter 'Z' capitalized, $38 refers to '8', and so on and so forth. But how did we manage to use actual letters earlier and still get the program to work on the calculator? The answer is that the assembler converts each character into the equivalent hex value and stores that in its place. So, you could in theory write a program with nothing but character strings because it to your calculator it is all the same thing (pictures, text, code, data, etc.).
Displaying Strings
Displaying text one character at a time is extremely time consuming. For this, TI has given us ROM calls that can display entire strings. You will load your coordinates the same, but this time you load the location in RAM the string is stored into HL. _PutS is the new system call and it "puts" a String on the screen.
;
Ld HL, string
b_call(_PutS)
;more of your code here
ret
string:
.db "The hello world program is so over rated", 0
As a side note, you'll see that no coordinates have been set. This may sound confusing, but it's perfectly normal. The display character/text ROM calls don't need you to set curRow/curCol every time, but instead take their value as they are when the they are called. It is also important to note that some of the ROM calls will change curRow/curCol.
End Terminating Strings
Why is the string followed by a ,0? The 0 at the end just says that that is the end of the string. If you do not include this, then _PutS will keep displaying characters until it reaches a point in memory that equals 0. Remember, your calculator does not have the ability to distinguish data types, or even code from data.
Length defined Strings
Another way to tell the calculator when to stop displaying text is to have the length of the string be the first byte. Of course, you'll need to use a different ROM call, but sometimes it may be to your advantage to have the string formatted this way as some ROM calls require the length of the string as an input.
Displaying Small Text
It's easy enough to display large text in assembly, so why not small text? There must be some way to display characters and strings in the small font, right? Of course there is! If you have ever programmed TI-BASIC, you'd know that small font is displayed to the "graph screen", and can be displayed anywhere. For small text, though, TI has come up with a different set of coordinate bytes labeled penCol and penRow.
PutMap
Exactly the same thing as PutC, except it displays in small text.
ld A,6 ;set the coordinates ld (penCol),a ld A,12 ld (penRow),a ld A,'A' bcall(_PutMap)
vPutS
Again, vPutS is exactly the same as PutS except it's for small text.
ld A,'A' bcall(_vPutS)
Text Flags
Now comes the fun part. Remember the tutorial on flags? TI has conveniently provided their text ROM calls with checks for many of the text-related system flags. That means you can call the same ROM call and if you modified the system flags it would provide a different output in some manner. Feel free to read through what all the system flags do, but below is a compiled list of the text-specific flags.
| Flag Name | IY offset | Equate description | Explanation |
|---|---|---|---|
| textEraseBelow | textFlags | 0 = Don't erase line below | Only on small text |
| 1 = erase line below | |||
| textInverse | textFlags | 0 = Regular text | Affects both small and large text |
| 1 = write in reverse video | |||
| appTextSave | appFlags | 0 = Don't write to textShadow | Places a copy of the character written to the display into the textShadow buffer. |
| 1 = Save characters written in textShadow | |||
| appAutoScroll | appFlags | 0 = Don't auto scroll | Scrolls text if on last line of large text |
| 1 = auto-scroll text on last line | |||
| textWrite | sGrFlags | 0 = small font writes to display | |
| 1 = small font writes to buffer | |||
| bufferOnly | plotFlag3 | 0 = Draw to display and buffer | |
| 1 = draw to graph buffer only | |||
| fracDrawLFont | fontFlags | 0 = small font with UserPutMap | Affects small text routines |
| 1 = draw large font in UserPutMap | |||
| customFont | fontFlags | 0 = Standard OS fonts | |
| 1 = draw custom characters |
User Input
So now we can tell the user what the calculator is doing. That's part of the way to creating a functional program. Now we need to allow for user input. This can be done through three different ways.
GetKey
This ROM call waits for the user to press a key, and then stores a key code into the accumulator. The specific keycode equates are shown on this list. Note that when you use _GetKey, the calculator will parse for 2nd and alpha keys, meaning that if you want the 2nd/alpha button to do something, it won't work. So, let's show and example of _GetKey in use.
;display the hex value of the key pressed
bcall(_ClrLCDFull) ;clears the screen
bcall(_GetKey)
ld h,0 ;make hl=a and then display it
ld l,a
bcall(_DispHL)
Not a very elegant method, _GetKey is usually used if the programmer wants the ROM call to parse 2nd/alpha for them. It's a very simple command and easy to master its uses.
GetCSC
A variation of _GetKey. Instead of waiting for a key to be pressed, GetCSC will check to see if a key was pressed, and if so, store a keycode to the accumulator. If a key was not pressed, the accumulator equals zero. Note that because GetCSC gets user input this way, you can use GetCSC to create your own parser for 2nd/Alpha key inputs. Note that _GetCSC has different keycodes from _GetKey, listed here.
loop: ;waits for a key to be pressed
bcall(_GetCSC)
or a
jr z,loop
Note that although _GetCSC doesn't wait for a keypress before "returning to program control", it will wait a little bit if you hold down an arrow key before parsing it as multiple keypresses.
Direct Input
The most primitive form of input. It directly polls the hardware what key was pressed. However, it is a complicated process and won't be discussed here. See this page.
Picture Data
So now we have the basics of input and output via text and keypresses, it's time to introduce picture data. Picture data is just the turning on of individual pixels in any pattern defined by the code. There are several ways to do this, but they ultimately boil down to the same process performed in different ways. That process is discussed here. In the mean time, there are two other main methods and two not-so-common (because they sucks and are assembly versions of how to create pictures in basic) methods for manipulating individual pixels.
Pixel ROM calls (bad)
This method is not recommended, but there are a few ROM calls here that can sometimes be useful if you're feeling lazy. TI has provided in the standard ROM calls several commands that allow you to turn pixels on and off, draw lines, circles, and various other shapes. However, since there is a huge list of such ROM calls (undocumented and documented), look at your 83psysroutines.pdf (chapter 5: System Routines — Graphing and Drawing) to see their actual functionality.
Text Sprites (not too good)
If you have ever programmed in TI-Basic, you might have used text sprites. Text sprites are a method developed by TI-Basic programs who realized that they can "overlap" text to form almost any combination of pixels on and off. For more information, see this file.
DisplayImage ROM call (okay)
DisplayImage is a ROM call TI has provided to do as it says: display images. It takes 2 inputs, but you must structure your picture data in a specific way.
Inputs: HL: Points to image data
ld HL,picData
DE: Where to draw on the screen. (0,0) is the top left corner.
ld DE,$0123 ;draw to coordinates (1,35)
Formatting Picture Data
The picture data should be formatted in such a way that the first two bytes determine how large the picture is (number of pixels down, by number of pixels across) Note that each row of data is divided into bytes, so each bit determines whether a pixel is turned on or off. Note that DisplayImage does not xor pixels ("flip" them), the data only dictates if it's turned on or off.
;draw an 8*8 square to top left corner
ld hl,picData
ld de,0
bcall(_DisplayImage)
ret
picData:
.db 8,8 ;an 8*8 box
.db %11111111
.db %10000001
.db %10000001
.db %10000001
.db %10000001
.db %10000001
.db %10000001
.db %11111111
Flags
As with most ROM calls dealing with the display, you can dictate the function of DisplayImage with flags.
| plotLoc | plotFlags | 0 = write to display and buffer |
| 1 = write to display only | ||
| bufferOnly | plotFlag3 | 0 = Draw to display and buffer |
| 1 = draw to graph buffer only |
Writing to a Buffer (Good)
Now, we will introduce the best way to draw pictures. This involves a buffer. A buffer is an array of data. How it's structured and what the data means in the buffer is programmer defined (what the program does with it), but be careful because if you want to allocate (not use for any other purpose) a section of memory for a buffer that's structured 20*20, because z80 doesn't recognize "variables", you can inadvertently use it as a 4*100 buffer. Of course, then, your data would make no sense until you used it as a 20*20 buffer again. Here are some good tips on using buffers:
- Create variables that point to:
# Top of buffer (first byte) # End of buffer (or define the length) # Pointer (where you are looking at in the buffer)
- Define the buffer in a safe location of memory
# In a saferam area (appbackupscreen, etc.) # In the program itself (if you're willing to sacrifice space) # In a location of memory that the calculator already uses for your purposes (plotsscreen for picture buffer)
GrBufCpy
Now that you have a buffer, now what? There's nothing displayed on the screen yet! The answer is to copy the buffer to the screen. TI has provided us with the GrBufCpy ROM call. It simply copies plotsscreen to the display.
bcall(_GrBufCpy)
ionfastcopy
By the looks of it, just using DisplayImage is smaller and faster. It is true that it is smaller; however, DisplayImage has less use, especially when it comes to sprites. So, to make this way faster, a long time ago a fellow z80 programmer named Joe Wingbermuehle developed a new method for quickly drawing to the display, calling it ionfastcopy. It does exactly the same thing as GrBufCpy, but much faster. To use it, you need to do one of two things: port your program for ion, or copy the code for ionfastcopy into your program. The second method is better.
.define gbuf plotsscreen ;what ion.inc defines the screen buffer as
;code for ionfastcopy directly from ionf.z80
fastCopy:
di
ld a,$80 ; 7
out ($10),a ; 11
ld hl,gbuf-12-(-(12*64)+1) ; 10
ld a,$20 ; 7
ld c,a ; 4
inc hl ; 6 waste
dec hl ; 6 waste
fastCopyAgain:
ld b,64 ; 7
inc c ; 4
ld de,-(12*64)+1 ; 10
out ($10),a ; 11
add hl,de ; 11
ld de,10 ; 10
fastCopyLoop:
add hl,de ; 11
inc hl ; 6 waste
inc hl ; 6 waste
inc de ; 6
ld a,(hl) ; 7
out ($11),a ; 11
dec de ; 6
djnz fastCopyLoop ; 13/8
ld a,c ; 4
cp $2B+1 ; 7
jr nz,fastCopyAgain ; 10/1
ret ; 10
Don't worry if you don't understand that code. It involves directly drawing to the screen.
Review
Topic questions
1. What is ASCII and how is it used? 2. What is the difference between GetKey and GetCSC?
Code Fragments
3. Write a short program to display "HELLO WORLD" diagonally 4. Write a program that moves a dot around the screen when the user presses an arrow key. (hint: Use the _IPoint, or see sprites for a better method)
Programming Errors
5. Identify the errors (if any)
;draw an 8*8 square to top left corner
ld hl,picData
ld de,0
bcall(_DisplayImage)
ret
picData:
.db 1,8 ;an 8*8 square
.db %11111111
.db %10000001
.db %10000001
.db %10000001
.db %10000001
.db %10000001
.db %10000001
.db %11111111
6. Identify the errors, if any.
; draw an 8*8 square
; ported for ion
ld de, picdata
ld hl,appbackupscreen
ld bc, 8
ldir
call ionfastcopy
ret
picData: ;an 8*8 square
.db %11111111
.db %10000001
.db %10000001
.db %10000001
.db %10000001
.db %10000001
.db %10000001
.db %11111111
Check your answers here.
Conclusion
That's it for simple input and output. It's suitable for many applications; however, because we are working in assembly, there are advanced topics such as using hardware ports, Sprites, and grayscale that can potentially enhance your program.
