IO Requests
Enable
Creating images
Showing images
References and slots
Layers (Sprites)
Multiple Sprites
More on images
In this page, the color codes of the standard palette are used throughout. As a quick reminder, here is a subset of them (see ioref for the complete list):
STD PALETTE --+-------- 0|BLACK 1|WHITE 2|RED 3|CYAN 4|PURPLE 5|GREEN 6|BLUE 7|YELLOW
The IO Chip (MIDP1/MIDP2) is able to execute some sort of instructions called "requests". For example, this is a request:
17 0
and it means "set the background color to BLACK".
This is another one:
17 0 0 255
and it means "set the background color to pure blue (i.e. RGB 0,0,255)".
While this one:
17 0 0
is an invalid request.
The first byte of a request (17 in the examples above) tells you what the request is all about ("set the background color", or SETBGCOL in the examples above).
Unlike CPU instructions, requests are "sent" to the IO Chip. Also, unlike CPU instructions you cannot tell how long is a request by looking at its first byte.
Suppose you want to send the request 17 5 to the IO Chip to set the background color to GREEN. First you send one byte after the other by writing into REQPUT (2:1):
LDA #17 STA 2:1 LDA #5 STA 2:1
Then you signal the end of the request by writing any value you like into REQEND (2:2):
STA 2:2
Now, suppose you want to send the request 17 20 100 255. Using 2:1 and 2:2, that would take 9 (i.e. 4*2 + 1) assembly instructions. There is another way. You can store a sequence of bytes like this (note the first two bytes stating how long the request is; in this case 4 bytes):
4 0 17 20 100 255
starting from, for example, 7:50 and then send the request writing the address (including the 2-bytes length) into the registers REQPTRHI (2:5) and REQPTRLO (2:4):
LDA #7 STA 2:5 LDA #50 STA 2:4
The order is important! The sending starts when you write into 2:4. When sending multiple requests, you don't need to rewrite into 2:5 if it doesn't change.
This way of sending a request by telling the IO chip where it starts in memory is called DMA (for Direct Memory Access).
When you write into FRMDRAW (2:18), the CPU is blocked until the next frame is due and the following elements are drawn:
1) A rectangle covering the whole frame using the color set by the request SETBGCOL (default: WHITE)
2) The image configured by the request SETBGIMG (default: no image)
3) The matrix of characters set by CONVIDEO, CONCCHR, CONCFG, etc..., a.k.a. the Console
4) Sprites and Tiled Layers configured by the requests LSPRITE/LTILED, a.k.a. the Layers
You can configure which of the steps above are actually carried out by adding together a combination of the following:
ENABLE -+------- 1|BGCOL 2|BGIMG 4|CONSOLE 8|LAYERS
and writing the result into ENABLE (2:16).
For example, by default, the value stored in 2:16 is 5. 5 is 1+4. So, by default, the background and the console are drawn.
As a last example, this program:
LDA #17 STA 2:1 LDA #5 STA 2:1 STA 2:2
results in a green screen with a white rectangle in the middle (i.e. the console), while this program:
LDA #1 STA 2:16 LDA #17 STA 2:1 LDA #5 STA 2:1 STA 2:2
results in just a green screen, because the console has been disabled.
The main request to create an image (IPNGGEN) is fairly complex and is usually generated by the Paint module. However, studying how that request is composed can help you to demystify the whole concept of images. Here is a 20 bytes request to create a small image.
(20 0) 25 1 8 0 8 0 1 3 3 1 2 7 126 255 219 255 195 231 255 126
I prefixed the request with a 2-bytes length (20 0) because it is common to send images to the IO chip using DMA.
First there is IPNGGEN (25), followed by the ImageId (1). The ImageId is discussed later. As long as you are consistent within your program, 1 is usually fine.
Then there are 4 bytes for the width (8 0) and the height (8 0) of the image, followed by the Depth (1) of the image. For Depth you can choose one of the following:
D|Col -+--- 1| 2 2| 4 4| 16 8|256
So, a Depth of 1 means 2 colors.
The next byte (ColorType) is usually 3, meaning that a color palette is included in the image. The next byte (Flags) is a combination of the following:
FLAGS --+---------- 1|IDX0TRANSP 2|PALREF 4|ZOOM0 8|ZOOM1 16|ZOOM2
On the example above, Flags is 3, meaning that the first color of the image is unused / transparent (IDX0TRANSP) and colors are described by the color codes of the current palette (PALREF). ZOOM0, ZOOM1 and ZOOM2 are discussed later.
Now the description of how the image looks like begins.
First there is the palette of the image:
1 2 7
The first byte (1) is the number of entries minus 1. So, the first 1 means that the palette has 2 entries (same as the number of colors; but it could be lower). The next 2 bytes are the color codes.
So, the first entry is RED and the second entry is YELLOW. However, since IDX0TRANSP above, RED pixels appear transparent.
If Flags did no contain PALREF, each entry would take 3 bytes instead of 1, for the red, green and blue components of the color.
Finally, there is group of bytes (Data) describing each pixel of the image.
126 255 219 255 195 231 255 126
Here is where these 8 bytes come from. If you draw a picture using X for YELLOW and . for RED:
.XXXXXX. XXXXXXXX XX.XX.XX XXXXXXXX XX....XX XXX..XXX XXXXXXXX .XXXXXX.
And then turn them into 0s and 1s:
01111110 11111111 11011011 11111111 11000011 11100111 11111111 01111110
You can use the following table:
LO| % |$| HI --+----+-+--- 0|0000|0| 0 1|0001|1| 16 2|0010|2| 32 3|0011|3| 48 4|0100|4| 64 5|0101|5| 80 6|0110|6| 96 7|0111|7|112 8|1000|8|128 9|1001|9|144 10|1010|A|160 11|1011|B|176 12|1100|C|192 13|1101|D|208 14|1110|E|224 15|1111|F|240
Here is how it works:
1) Take the first row of the image (01111110)
2) Split it in two halves (also called "nibbles"): 0111 and 1110.
3) Find the first half (0111) in the table, and note the number on the right (112).
4) Find the second half (1110) in the table, and note the number on the left (14).
5) Add the two numbers together: 112 + 14 = 126.
If you check, you will see that 126 is the first of the 8 Data bytes. Use the second row for the second byte, and so on.
Once you create an image, to show it you can send a SETBGIMG (19) request. Remember to use ENABLE (2:16) to disable the console and enable the background image.
First create a program of 2 pages (1 page of code and 1 page of data).
At 4:0, create a IPNGGEN request (see above for the explanation):
20 0 25 1 8 0 8 0 1 3 3 1 2 7 126 255 219 255 195 231 255 126
At 4:22, create a SETBGIMG request:
2 0 19 1
The byte following 19 is the ImageId. As stated above, use 1 and you will be fine.
Now for the code (starting from 3:0).
First, use ENABLE to enable the background image and to disable the console:
LDA #3 STA 2:16
All the requests are on page 4, so setup the DMA to use page 4:
LDA #4 STA 2:5
Now create the image (send the IPNGGEN request):
LDA #0 STA 2:4
And show it (send the SETBGIMG request):
LDA #22 STA 2:4
If you try the program, you should see a yellow image centered on the screen. Keep this program; it will be modified below to explore other aspects of the IO chip.
Images (and layers, to be discussed later) are "objects" managed by the IO chip.
You can keep references to images using slots. By default, there are 4 (image) slots (from 0 to 3) available.
When you create an image, ImageId is the slot you use. The slot will hold a reference to the image. If the slot already referenced another image, that reference is removed.
The example above used ImageId 1 and looked liked this:
IPNGGEN 1 (image A) SETBGIMG 1
After these requests, the IO chip looks like this:
ID Slots Images Users +---+ 0 | . | +---+ +-+ 1 | -------> |A| <------ BGIMG +---+ +-+ 2 | . | +---+ 3 | . | +---+
The request IDESTROY (20) removes a reference from a slot to an image. It is followed by the ImageId of the slot.
Note that in the example above you could send a IDESTROY with ImageId 1 and the image would not be destroyed (BGIMG "keeps it alive"). A better name for IDESTROY might have been something like IUNLINK.
Here is a more complex example. After the following requests:
IPNGGEN 3 (image A) IDESTROY 3 IPNGGEN 0 (image B) SETBGIMG 0 IPNGGEN 0 (image C)
The IO chip looks like this:
ID Slots Images Users +---+ +-+ 0 | -----> |C| +---+ +-+ 1 | . | +-+ +---+ |B| <-- BGIMG 2 | . | +-+ +-+ +---+ |A| 3 | . | +-+ +---+
Image A is not used by anyone and the IO chip might destroy it if it needs more memory (a process called "garbage collection"). Image B is used by the IO chip (even if you have disabled the drawing of the background image with ENABLE). Image C is kept alive by the programmer, who is holding a reference to it in slot 0.
You can increase (or decrease) the number of image slots by sending a IDIM (21) request, but this is usually not necessary.
Layers are objects that you can easily move around the display. The name comes from the fact that when they overlap is as if they were stacked on top of each other.
You manage layers using slots. It is just like images, but it is a different set of slots. By default, there are 16 (layer) slots (from 0 to 15) available. If you need to increase the number of layers you can use the request LDIM (35). It is followed by the last layer id (i.e. 31 if you need 32 layers).
There are two kind of layers: sprites and tiled layers. Sprites are described first, as they are a bit easier to use. To create a sprite, you can use the LSPRITE (37) request. It is followed by the LayerId and by the ImageId. If you only use one sprite, you should use slot 0 for LayerId. How to handle multiple sprites is discussed later.
Starting from the program from the "Creating images" section above, you can replace the SETBGCOL request with a LSPRITE request. So, starting from 4:22, you will have:
3 0 37 0 1
The value written into ENABLE should also be changed. You want to enable the drawing of the layers instead of the background image. So, starting from 3:0, you will have:
LDA #9 STA 2:16
If you try the program now, nothing happens. This is because layers are created hidden. To show them, you have to write 128 into LCTL (2:81). So, at the end of the program (it should be at 3:20), add:
LDA #128 STA 2:81
If you try the program now, you should see the sprite. Unlike the background image, the sprite is positioned at the top left corner of the display. But unlike background images, you can move sprites! Use LX (2:82) and LY (2:83). You can of course do so in a loop. For example, at the end of the program (it should be at 3:25), add:
LDA #50 STA 2:83 INC 2:82 STA 2:18 JMP 3:30
As you can see, after the position of the sprite has been updated, the program writes to FRMDRAW (2:18).
To create more than one sprite, just send more LSPRITE requests. Make sure to give each sprite a different LayerId. You can use the same image several times or give each sprite a separate image.
You can only control one layer (remember that sprites are just a type of layer) at a time. To tell the IO chip which one you want to control, write its LayerId into LID (2:80). The layer registers (i.e.: LCTL, LX, LY, etc...) will then refer to that particular layer. Initially, LID is set to 0; this is the reason why you don't need to worry about it if you only have one layer and its LayerId is 0.
Here is how to modify the previous example to handle multiple sprites.
Leave the data page as it is. You should have a IPNGGEN request at 4:0 and a LSPRITE request at 4:22.
The beginning of the code is left unchanged:
LDA #9 STA 2:16 LDA #4 STA 2:5
Then (starting at 3:10), the following loop creates 3 sprites:
LDX #0 LDA #0 STA 2:4 STX 4:25 LDA #22 STA 2:4 STX 2:80 LDA #128 STA 2:81 DEC 4:13 INX CPX #3 BNE 3:12
Note how the requests are changed before they are sent to the IO chip: at each iteration, the color code of the image to be created (4:13) is decremented, and the LayerId (4:25) of the sprite to be created is incremented. Also note that LID (2:80) is updated with the LayerId of the newly created sprite, before enabling it by writing 128 into LCTL (2:81).
After the code above, the IO chip looks like this:
IMAGES LAYERS
ID Slots Images Slots ID
+---+ +-+ +---+
0 | . | |Y| <------ | 0
+---+ +-+ +-+ +---+
1 | ----+ |B| <------------ | 1
+---+ | +-+ +-+ +---+
2 | . | +------> |G| <-------| 2
+---+ +-+ +---+
3 | . | .
+---+ .
+---+
| . | 15
+---+
If you try the program now, you will see only one sprite. The other two sprites are really there; they are simply below the one you see.
Add this loop at the end of the program (it should be at 3:41), to move them:
LDA #0 STA 2:80 INC 2:82 INC 2:80 INC 2:83 INC 2:80 INC 2:82 INC 2:83 STA 2:18 JMP 3:41
Note how at each frame LID (2:80) is first reset to select sprite 0 and then it is incremented twice to select the other two sprites. For each sprite, LX (2:82) and LY (2:83) are changed differently.
If you run the program now, the three sprites should move in a loop.
When converting an image to bytes, turning X/.s into 1/0s was a trivial, but important step. X/.s are pixels. 1/0s are bits. The distinction will become relevant shortly, when multicolor images are discussed, but first, let's see how images of sizes other than 8x8 are converted.
If the image is shorter or taller, it is not really a problem: a 8x2 image would just have 2 rows and a 8x100 image would just have 100 rows.
If the image is narrower, you fill each row until you reach 8 bits. For example, the following 3x3 image:
010 111 010
should be treated like this:
01000000 11100000 01000000
Note that the width to use in the IPNGGEN request is still 3.
If the image is wider, you need more bytes for each row; just group the bits in groups of 8 when you convert them. You still need to fill each row until you reach a multiple of 8 bits. For example, the following 10x3 image:
1111111111 1000000001 1111111111
should be treated like this:
11111111 11000000 10000000 01000000 11111111 11000000
Every byte of each row is sent starting from the first on the left, to the last on the right. To clarify, the Data of last image is 6 bytes long, and the order of the bytes is the following:
1 2 3 4 5 6
If the image has more than 2 colors, Depth means how many bits each pixel takes. Here is an example with Depth 2:
#| %|Color -+--+------ 0|00|WHITE 1|01|RED 2|10|YELLOW 3|11|GREEN
The following image:
RR..GG ..YY..
can be turned into the following bits:
01 01 00 00 11 11 00 00 10 10 00 00
The bits can then be regrouped and each row can be extended to reach the first multiple of 8:
01010000 11110000 00001010 00000000
Here is the resulting request:
(18 0) 25 1 6 0 2 0 2 3 3 3 1 2 7 5 80 240 10 0
If Depth is 4, the order of the bit patterns matching the image palette can be found on the table you used to convert bits to bytes.
When you start using lots of images, available data pages can run out quickly. This is especially a problem with phones with a high resolution display. The IPNGGEN request for a 16 colors, 16x16 image takes up more than half a page... and 16x16 might be quite small on a tiny 320x240 display!
You can add one of the following values (ZOOM0/ZOOM1/ZOOM2) to Flags:
ZOOM --+-- 0|x1 4|x2 8|x3 12|x4 16|x5 20|x6 24|x7 28|x8
If, for example, you create a 8x8 image with a zoom factor of x3 (+8), the actual image is going to be a 24x24 image. Note that, while this helps you to keep your program small, inside the IO chip the image still consumes as much memory as a regular 24x24 image. On the other hand, phones with high resolution displays usually have lots of memory, so this might be an acceptable trade off.
For the ZOOM flags to work, the width of the original image must be a multiple of 8.
Another use of the ZOOM flags is to create a background tileset. If you create a 8x1 RGB image with a zoom factor of x8 (+28), the resulting image will be a 64x8 images that can be used for a 8x8 LTILED (discussed later). Here is an example request:
(42 0) 25 1 8 0 1 0 8 3 28 7 0 0 0 ; BLACK 255 255 255 ; WHITE 255 0 0 ; RED 0 255 0 ; GREEN 0 0 255 ; BLUE 255 255 0 ; YELLOW 0 255 255 ; CYAN 255 0 255 ; MAGENTA 0 1 2 3 4 5 6 7
This is one of the few cases where a Depth of 8 is useful: you don't need to use binary numbers for Data, as every pixel is exactly 1 byte (i.e. 8 bits), and the Data section is still small as the original image is small (i.e. only 8x1 pixels).