Using EMS in QuickBASIC: Part 3

by Plasma (Jon Ρetrosky)

It’s been a loooooong time

Sorry part 3 took so long to finish...I had a lot of other stuff to do and it sort of got pushed to the side, especially when the QB Chronicles got discontinued. Anyway here it is!

Review

In part one, we set up a basic EMS interface with QuickBasic. We also created a sample program, which did nothing more than test the EMS routines and shuffle some memory around. In part two, we created a simple system to load small wave files and play them back directly from EMS using the Sound Blaster DMA.

Note: If you missed part one, you should read it before continuing. It's available in the tutorials section at Phat Code. It's also published in issue #3 of the QB Chronicles.

Now I’ll show you some other neat things that can be accomplished with EMS: Creating huge arrays and using EMS as a graphics buffer.

First Up: Arrays

If you’ve ever tried to create an array with more than 32767 elements, you know that it doesn’t work. This is one of the many limitations of QuickBasic. Another limitation is that arrays cannot be larger than 64K, unless QuickBasic is started with the /AH switch. However, using the /AH switch slows down array access speed drastically. And you still can’t create an array larger than 64K with integer elements, because this would require more than 32767 elements!

But what if you need to create a huge array? One with a million elements? (This question was recently posted on the board by Qbmaniac.) Well, it can be done with EMS. :)

Array Tracking

There are essentially two pieces of information that are required to keep track of an array:

The first is the element length (how many bytes each is element is). Integer arrays use 2 bytes for each element, while long integer arrays use 4 bytes for each element. String arrays are a bit different; the elements can be different lengths. To keep things simple, we’ll just allow arrays with a fixed element length. (You can create string arrays, but the elements will have to be a fixed length.)

The second is the number of elements. This seems simple, but what about arrays with multiple dimensions? (i.e., Array(32, 64) ) And if an array is dimensioned with 10 elements, those elements can be numbered from 0 to 9, 1 to 10, or even something like -4 to 5. To solve these problems, we’ll just allow single dimension arrays (although multiple dimension arrays can be simulated, more on this later). Also, the element numbering will start at 1. So in this case, if there were 10 elements, they would be numbered from 1 to 10.

Since it would be nice to be able have more than one array in EMS, we’ll create a type called ArrayEMS to hold information about each array. Each array we created will be of this type.

Note: You can find the complete source code for this tutorial in ems3.zip.

Creating the Arrays

To create an array in EMS, you should first define a variable as ArrayEMS type, and then set the element length and the number of elements that you want in the array.

This is just the setup; it won't actually create an array in EMS. We need to make a function to do this ourselves. The easiest way to create an array in EMS is to calculate the needed memory based on the element length and the number of elements, and then allocate this amount to a new handle. The disadvantage of this is that each array requires a free handle. However, this shouldn’t be that big a problem, because I don’t think you’ll be needing 60+ arrays that are larger than 64K.

To calculate the memory needed, just take the number of elements and multiply it by the element length. This will give you the amount in bytes:

The problem here is that EMS allocates memory in 16 KB pages, not by bytes. So we need to convert this to pages, which can be done by simply taking the bytes and dividing by 16384. (16 KB = 16384 bytes)

Now that we have the number of pages needed, we can allocate this memory to an EMS handle. This is all that is needed to set up the array. Below is a function that does all this:

To use this function, just pass your variable of ArrayEMS type:

Now the array is ready to go!

Accessing the Arrays

Now that we have an array set up, it would be nice if we could set and get the values of different elements. After all, that is the purpose of an array... :)

Setting an element is a little tricky, because we have to specify the memory location in the form of a page, and then an offset. But it’s really not that much different from using segments and offsets in base memory.

First, we’ll find the absolute location of the element. This is done by subtracting one from the element number (because we need it to start at 0) and multiplying it by the length of each element:

To find the page, we just divide the absolute offset by 16384, since each page is 16 KB:

And the offset from that page can be found by multiplying the page by 16384 and subtracting that number from the absolute offset:

Now that we have the page and the page offset, we can use the EMS.CopyMem routine from part 1 to copy the data from base memory to the location in EMS.

Below is the EMS.Array.Set sub, which sets an element in an EMS array:

You'll notice that this sub uses SrcSegment and SrcOffset instead of a single variable for the source. The reason for this is that we can't be sure what type the array is, and by using the segment and offset of the variable, our sub can use any type of variable.

To use the EMS.Array.Set sub, you first put the value you want to store in your array in a temporary variable. Then you call EMS.Array.Set, using the segment and offset of that temporary variable as the source:

Once we’ve set an element, we’d probably like to be able to read it back again. The same approach can be used as setting the element; all that is needed is to copy the data from EMS to base memory, instead of from base memory to EMS:

Reading back an element is similar to setting an element:

And if you want to swap two elements, that can easily be achieved also, with the EMS.ExchMem routine:

Swapping two elements is straightforward, as well:

Erasing Arrays

All that's left now is to erase the array when you’re finished with it, to release the EMS memory it is using:

Again, using this should be a no-brainer :)

Simulating Multidimensional Arrays

The array routines we have developed work fine for arrays with a single dimension, but what if you wanted an array with 2 or more dimensions? A good example of this is a map for a tile-based game. Most likely this type of array will have 2 dimensions, something like Map(x, y).

To simulate this type of array, you first have to decide how many elements each dimension has. Using our map example, we'll give the first dimension (x) 400 elements, and we'll give the second dimension (y) 600 elements. When you dimension your array, use the number of elements in the first dimension times the number of elements in your second dimension:

Next, you use this general formula to find the "real" element to pass to the EMS array routines:

Now you're probably saying "what?!", so I'll give an example...here is how you would access Map(274, 421):

That's all there is to it! Now that we've tackled the challenge of storing huge arrays in EMS, we'll move onto some "fun stuff"...

Next: Graphics

It seems that the most widely used screen mode in QuickBasic is screen 13, and for a good reason. It is the only QuickBasic screen mode with 256 colors. (Although ModeX and SVGA modes can also provide 256 colors, they are not as easy to program for.)

Figure 3-1: A typical PC memory map

Screen 13's 320x200 resolution is low, but there’s a nice bonus to this: The amount of memory required for one screen is exactly 64000 bytes, which fits nicely into 64K. (hint-hint...the EMS page frame is 64K...hint-hint)

The downside to screen 13 is that it provides only one graphics page, which makes it very difficult to do flickerless animation. I know what you’re thinking, and you’re right...we can get around this with EMS! :)

Referring to the PC memory map from part one, we can see that the VGA buffer is located at segment A000, offset 0000, and is 64K. The EMS page frame is also 64K, which means that it can easily be used as double buffer. Instead of writing to the VGA buffer, we write to the page frame instead. Then we can copy the contents of the page frame over to the VGA buffer, to produce flickerless animation.

There has to be a catch, right? Well, unfortunately, there is. In screen 13, QuickBasic will only use A000 as the video segment, and provides no easy way to change this.* This means that none of QB’s graphics statements can be used to draw to the double buffer, and we’ll have to write our own routines. Luckily, it’s not that hard.

* It is possible to change the active drawing segment so that QB draws to a different location in memory, but the method is a bit unorthodox...I think I'll save this approach for another tutorial... ;)

We Don't Need No Stinking PSET

As many of you probably already know, you can set pixels in screen 13 by using POKE instead of PSET. The advantage of this is that it is faster than PSET, and you can specify the segment that you want to use with DEF SEG. In our case, we can set the segment to the EMS page frame and draw the pixels directly to EMS.

If you've always used PSET and don't know what I'm talking about, I'll explain... In screen 13, the screen is arranged in a linear bitmap. This means that any pixel can be set by just setting the segment to A000, and then using POKE to set the pixel:

Reading a pixel is exactly the same, except PEEK is used:

In the above example, if the segment was set to A000, the pixel read/writes would have taken place in the video buffer (what you see on the screen). However, if the segment was set to the EMS page frame, the pixel read/writes would have taken place in a buffer in EMS, invisible to the user.

Buffers Here, Buffers There

The only problem now is buffer management. It would be nice if we could have multiple graphics buffers in EMS, but we need a way to keep track of them. We can do this with a few shared variables:

Gfx.Handle holds the EMS handle the pages for the buffers are allocated to, and Gfx.NumBuffers is the number of graphics buffers that have been allocated. Gfx.PageFrame holds the segment of the EMS page frame. We are storing this in a variable instead of using the EMS.PageFrame function because it will be much faster than asking for the page frame each time. Gfx.LastMapped is the first page of the four pages that were last mapped to the page frame. Again, this is used for speed, so we don’t needlessly remap pages that are already mapped. Finally, Gfx.TextSeg and Gfx.TextOff are the segment and offset of the 8x8 ROM font in memory. We will use this font to draw text. (Because PRINT won’t work with our EMS graphics buffers either!)

Setup

We’ll need a way for the programmer to set up these screen buffers. This can be done with one function. All this function has to do is find the number of EMS pages needed, allocate them, and then save the handle and the number of buffers available.

The number of EMS pages needed can be found by taking the number of buffers requested and multiplying it by 4:

PagesNeeded = NumBuffers * 4

(Each buffer needs to be 64 K, and each page is 16 K.)

This function will also take care of a few initialization tasks: getting the page frame address and storing it for later use, and finding the 8x8 ROM font location via interrupt 10h.

You’ll notice that the function also clears each buffer. (Using a sub that we haven’t written yet...I must be psychic :) ). This is needed because EMS pages aren’t necessarily "blank" after they have been allocated; they can contain data from previous programs that have used them. So the function automatically clears them off to get rid of any junk that may be there.

I guess we’d better create the Gfx.Cls routine now, since we already used it...

This routine is a little tricky, because there is no EMS function to "clear" pages, and QB can only write to memory 1 byte at a time. (Clearing the pages this way would be way too slow!) We can get around this by creating a blank 16K array (an integer array with 8192 elements, 2 bytes each), and then using our EMS.CopyMem sub to copy this "blankness" to each of the 4 EMS pages in the buffer that we want to clear. ("Blankness"? And this was supposed to be a technical tutorial...)

Draw Them Pixels

Next we’ll create the basic Gfx.Pset and Gfx.Point subs. These are based on the general method of using PEEK and POKE to set pixels, as described previously. The only interesting part about these subs is probably setting the segment.

If the programmer specifies 0 as the graphics buffer to use, we'll assume that they want to use the video buffer and not an EMS graphics buffer. If they specify a graphics buffer, we need to first check and see if the pages for this buffer are already mapped. If so, we can save some time by not mapping them again. If not, then they must be mapped. No matter which EMS graphics buffer is being used, the segment is always that of the page frame.

With the methods used in these two subs, you should be able to create any type of graphics routines you want...lines, circles, get/put, etc. I’m not going to explain them in detail here, however. (Oh sure, just leave you hanging, right? :) Ok, ok, the source code included with this tutorial has extra graphics routines, if you want to use those instead of creating your own. But after all, this is an EMS tutorial, not a graphics primitives tutorial...)

Note: If you would like to add clipping to any of the included graphics routines, all you have to do is check to make sure that each pixel drawn will be within the limits of the screen: (0, 0)-(319, 199). However, this slows it down a little, so right now the only routine that uses clipping is my Gfx.Put sub.

You should also be aware that none of the graphics routines have error checking; you could easily specify a non-existent graphics buffer. If you would like to implement error checking, all that is needed is to check to make sure the buffer specified is not greater than Gfx.NumBuffer.

Print "Hello World"

There is one more graphics routine I’ll walk you through: printing text on a graphics buffer. (Reading the ROM font from memory can be a challenge if you’ve never done it before. Everybody who *has* done it can stop laughing at the n00bies now.)

The first step is to get the segment and offset of the ROM font, which we already did in our Gfx.Alloc sub. This location in memory contains font data that can be used to draw 8x8 characters. To save space, each pixel in the font is represented by one bit. Since there are 8 bits in one byte, only one byte is needed for a row of pixels in a character. However, since there are 8 rows, a total of 8 bytes are needed for each character. There are 256 characters total, arranged in order from 0 to 255.

To "print" a string using the ROM font, we need to step through the string, one character at a time. For each character in the string, we find the offset of the font character, and then read the font one row at a time, expanding the bits into separate pixels, which are placed into the graphics buffer. After all the rows of the character have been drawn, we move on to the next character in the string, and repeat this process until every character has been drawn.

Copying Buffers

Drawing to hidden buffers in EMS is pretty useless if you can't ever see what's on the buffer...at some time, you'll probably want to copy a buffer from EMS to the video buffer (or even another EMS buffer). Using EMS.CopyMem, making a sub to do this is a piece of cake:

Deallocating the Graphics Buffers

Finally, before the program ends, we need to deallocate the graphics buffers to release the EMS pages. This can be done with a single call to EMS.DeallocPages, passing the graphics handle.

Yet Another Sample Program

Below is the final sample program of the EMS tutorial series. It demonstrates using our EMS array routines to create and access a huge 1,000,000 element integer array. (which takes almost 2 MB!) It also uses our new graphics routines to animate some balls on the screen, using EMS as a double buffer to eliminate flicker.

Thus ends the EMS tutorial series...

There are plenty of other uses for EMS; I’ve just touched the surface to show some examples of what can be done. It’s really not that hard to use now that you know the basic concepts, and you should be able to use it for just about anything you want!

Keep the QB scene alive...

-Plasma

If you have any questions or comments about this article, or found an error, please email me or post a message on the Phat Code forum.

(Thanks to Joakim for pointing out my /AH and long int=4 errors!)