Screen and Graphics (VGA/composite)

Screen and graphics commands affect both the output on the VGA connector (or composite output) and the output to the serial console.

The PC/USB interface is most frequently the serial console, but the console can be redirected to a hardware serial port.

Graphics

Graphics commands operate on the video output only (not USB). Coordinates are measured in pixels with x being the horizontal coordinate and y the vertical coordinate. The top left of the screen is at location x = 0 and y = 0, and the bottom right of the screen defined by the read-only variables x = MM.HRES and y = MM.VRES which change depending on the video mode selected (VGA or composite). Increasing positive numbers represent movement down the screen and to the right.

You can clear the screen with CLS and an individual pixel can be turned on or off and its color set with PIXEL(x,y) = . You can draw lines and boxes with LINE, and circles using CIRCLE. You can also set the screen location (in pixels) of the PRINT output using @(x,y) and the SAVEBMP command will save the current screen as a BMP file. LOADBMP will load and display a bitmap image stored on the SD card.

The origin of graphics commands is in the upper left corner of the screen. Resolution for mode 1, 2, and 3 is 480 horizontal pixels and 432 vertical pixels.

Resolution for mode 4 is 240 horizontal pixels and 216 vertical pixels.

Resolution for composite PAL is 304 horizontal pixels and 216 vertical pixels.

Resolution for composite NTSC is 304 horizontal pixels and 180 vertical pixels.

In mode 1, 2, and 3 the display is 80 characters wide by 36 lines using the internal default font.

In mode 4 the display is 40 characters wide by 18 lines.

In composite PAL the display is 50 characters wide by 18 lines.

In composite NTSC the display is 50 characters wide by 15 lines.

VGA mode 1, 2, or 3:

VGA screen resolution for modes 1, 2, and 3.

In mode 1, 2, and 3 the display is 80 characters wide by 36 lines using the internal default font.

VGA mode 4:

VGA screen resolution for mode 4.

In mode 4 the display is 40 characters wide by 18 lines – default font.

Composite PAL:

Illustration 145: Composite screen resolution for PAL.

In composite PAL the display is 50 characters wide by 18 lines – default font.

Composite screen resolution for NTSC.

Composite NTSC:

In composite NTSC the display is 50 characters wide by 15 lines – default font.

Comparisons of the screen resolutions.

The image above compares the screen resolutions. The red box is VGA mode 1, 2, or 3. The blue box is VGA mode 4. Composite PAL is green and NTSC is purple. The boxes are offset from each other by 5 pixels to make it easier to see lines that would otherwise overlap. Here is the code:

Working with Color

The CGCOLORMAX supports eight colors (black, blue, green, cyan, red, purple, yellow and white). The monochrome CGMMSTICK Maximite support just two (black and white). In most places you can also specify the color as -1 (negative 1) to invert a pixel (this is useful in animation).

Throughout MMBasic you can refer to the colors by their name or their corresponding numbers where black = 0, blue = 1, green = 2, etc through to white = 7. Commands such as LINE and CIRCLE use this color or number to specify the color to draw. For example:

---

CIRCLE (100, 100), 50, CYAN ' will draw a circle in cyan.

CIRCLE (100, 100), 50, 3 ' same

---

You can also specify a default color that will be used for all screen output with the COLOR command. For example: COLOR PURPLE will set the color of text to purple (and any other output where the color is not specified). The COLOR command also takes a second parameter for the background color. So, COLOR YELLOW, BLUE specifies that text will be displayed in yellow on a blue background.

In addition to the COLOR command you can change the color of text by embedding color codes into strings using the CLR$() function. For example, the following will display each word in a different color:

---

Txt$ = "This is " + CLR$(RED) "red " + CLR$(YELLOW) + "yellow"

PRINT Txt$

---

You can also use this function to set the background color by supplying a second parameter. For example:

---

PRINT CLR$(YELLOW,RED) " ALARM "

---

If the function is used without any parameters (eg, CLR$()) it will reset the colors to the defaults set by the last COLOR command. The colors are also reset when the print command terminates.

This function simply generates a two character string where the first character is the number 128 plus the foreground color number and the second character is the number 192 plus the background color number.

You can use this trick to embed color commands in any text, even text read from a text file on the SD card.

COLORS

Colors can be selected by number, or by a reserved keyword:

0	BLACK
1	BLUE
2	GREEN
3	CYAN
4	RED
5	PURPLE
6	YELLOW
7	WHITE

Color Modes

The video system can be configured into one of four modes using the MODE command. This enables the programmer to trade off the number of colors used on the screen and the graphic resolution against the amount of memory required by the video driver. Modes 1 and 4 use the least amount of memory while mode 3 uses the most. The syntax of the MODE command is:

---

MODE color-mode, palette

---

The ‘color-mode’ can be one of four numbers:

1 Monochrome mode. In this mode the Color MMBasic operates the same as the monochrome MMBasic and has the maximum amount of free memory available for programs and data. The second argument of the MODE command (‘palette’) selects the color to be used for all output. It can be any color number from black to white.

2 Four color mode. In this mode four colors (including black) are available. The actual colors are selected by a number (1 to 6) used in the second argument of the MODE command (‘palette’). See the following image or the MODE command for a listing of the actual colors available.

3 Eight color mode. In this mode all eight colors are available and can be used simultaneously anywhere on the screen. The ‘palette’ argument is not required and will be ignored if specified. MODE 3 uses the most memory but there still is plenty left for programs and data. This is the default when the CGCOLORMAX is first powered up.

4 240×216 pixel mode. In this mode all eight colors are available and the video resolution is halved (meaning that characters and graphics are doubled in size). This mode is most suitable for games as all colors are available, it has the maximum amount of free memory and drawing of graphics is very fast. The ‘palette’ argument is not required and will be ignored if specified.

Color graphics. Examples of the MODE command. (Image actually generated completely in mode 3.)
You can change the mode and the palette at any time and as often as you need, even within a running program.

Scan Line Color Override

In mode 1 (monochrome) there is an additional facility to change the color of each horizontal line of pixels on the screen using the SCANLINE command. This is intended mostly for programmers writing games and provides limited control over color while still providing the maximum amount of free memory. The syntax is:

---

SCANLINE color, startline, endline

---

This command can only be used in MODE 1, 7 (monochrome with the color set to white) and is used to set the color for each horizontal scan line of pixels on the screen.

‘color’ is the color to be used and can be any one of the eight colors, ‘startline’ is the starting scan line to be set to that color and ‘endline’ is the ending line. The scan lines are numbered from 0 at the top of the screen to 431 at the bottom of the screen. The numbering is the same as that used when specifying the vertical coordinates of a pixel.

You can use multiple SCANLINE commands to set multiple scan lines to different colors. For example:

---

SCANLINE RED, 0, 9 ' set the top 10 lines to red

SCANLINE YELLOW, 120 ' and set only line 120 to yellow

SCANLINE BLUE, 200, 219 ' and set a band of 20 to blue

---

To turn off the override imposed by the use of SCANLINE commands you can use the MODE command to reselect mode 1 or a change to a different mode. It is also automatically turned off when control is returned to the command prompt.

Game Playing Features

MMBasic has a number of features that are intended to make it easier to write games on the Maximite.

MODE 4

The color MODE 4 described in the previous section is mostly intended for games. It provides eight colors and leaves plenty of free memory for the other aspects of an animated game (the program, sprites, arrays, and so on).

Because this color mode has only one quarter of the pixels the graphics operations are much faster due to the fact that there are fewer pixels that need to be manipulated by MMBasic when drawing on the screen.

BLIT

This command will move an area of the video screen from one location to another. The destination can overlap the source area and the BLIT command will copy the video data correctly to avoid corruption. On the CGCOLORMAX1 you can also independently specify what color planes to copy.

This method of moving video data is much faster than copying pixels one by one and allows for rapid animation on the screen. It can also be used to replicate a pattern like a border or a brick wall to build a complete image.

SPRITE

A sprite is a 16×16 bit graphic image that can be moved about on the screen independently of the background. When the sprite is displayed MMBasic will automatically save the background text and graphics under the sprite and when the sprite is turned off or moved MMBasic will restore the background.

The sprites are defined in a file which is loaded into memory using the SPRITE LOAD command, the number of sprites contained in the file is only limited by the amount of available memory. Each sprite in the file can contain pixels of any color (on the CGCOLORMAX1 Maximite) and can also have transparent pixels which allow the background to show through.

To manipulate the sprites you can use the command SPRITE ON which will display a specific sprite at a specified location on the screen. SPRITE MOVE will move a sprite to a new location and restore the background. SPRITE OFF will remove a sprite from the screen and restore the background.

Sprites should not overlap but if they do you should turn them off in the reverse sequence that you turned them on before you turn them on again at their new location. This will enable the background image to be correctly maintained.

For example, the following two sprites overlap:

---

SPRITE ON 1, 100, 150 ' sprite 1 is drawn at x = 100, y = 150

SPRITE ON 2, 110, 160 ' sprite 2 overlaps

---

To move the sprites they need to be turned off in the reverse sequence:

---

SPRITE OFF 2

SPRITE OFF 1

---

Then they can be redrawn at their new location:

---

SPRITE ON 1, 104, 154 ' sprite 1 is drawn at x = 104, y = 154

SPRITE ON 2, 116, 166 ' sprite 2 still overlaps

---

Because sprites are drawn so fast the user is unaware that the sprite has been turned off then redrawn.

An alternative to turning sprites off in sequence is to specify the background color when using the SPRITE ON or SPRITE MOVE commands. The background color is optional and is specified at the end of the command.

For example:

---

SPRITE ON 1, 100, 100, BLUE

---

This results in a much faster operation when using a solid background color because MMBasic does not have to copy the background to a buffer. It also means the MMBasic will always restore the correct color, even if sprites overlap.

Sprite Collision Detection

You can use the COLLISION() function to detect if a sprite has collided with another sprite or the edges of the screen. A collision is reported if the non transparent portion of the sprite is just touching (ie, the non transparent pixels are adjacent) or overlapping the non transparent portion of another sprite or the edge of the screen.

To detect if a sprite has collided with another sprite you use:

---

R = COLLISION (n, SPRITE)

---

And to detect if it has collided with the screen edge you use:

---

R = COLLISION (n, EDGE)

---

Where ‘n’ is the number of the sprite to test.

In both cases the value returned by the function indicates if the collision was on the left of the sprite, the right, the top, etc.

Following a collision COLLISION () will return:

&B0001 Indicating a collision with something on the left of the sprite

&B0010 Collision on the right

&B0100 Collision on the top

&B1000 Collision on the bottom

Note that it is possible for these results to be combined. For example; a result of &B0101 indicates that the sprite has collided with something both at the top and left of the sprite (for example the top left corner of the screen).

When testing for collisions with other sprites it is possible for the function to return &B1111 indicating that there are collisions on all sides. This can happen if the sprite is surrounded on all sides by other sprites.

If the sprite is overlapping another (ie, one or more non transparent pixels are on top of another sprite’s non transparent pixels) bit &B10000 will be set in the value returned by COLLISION () in addition to the bits for left, right, etc as described above.

Sprite Definition Files

This section describes the format of a sprite file that can be loaded using the SPRITE LOAD command.

A sprite file is similar to a font file except that it contains the definition of sprites which are 16×16 bit graphical objects that can be moved about on the video screen without disturbing background text of graphics. The sprite file is just a text file containing ordinary characters which are loaded line by line to build the bitmap of each sprite. Currently the dimensions of each sprite are fixed at 16×16 bits although alternative sizes may be allowed in the future.

The first non-comment line in the file must be the specifications for the sprite file as follows:

dimension, number

Where ‘dimension’ is the height and width of the sprites in pixels. At this time it must be the number 16. ‘number’ is the number of sprites in the file and is limited only by the amount of free memory available. The remainder of the lines specify the bitmap for each sprite.

Each line represents a horizontal row of pixels with each character in the line defining the color of the pixel. The character can be a single numeric digit in the range of 0 to 7 representing the colors black to white or it can be a space which means that that particular pixel will be transparent (ie, the background will show through).

Each sprite must immediately follow the preceding sprite in the file and be defined by 16 lines each of 16 characters wide (although trailing spaces can be omitted and will be assumed to be transparent pixels).

A comment line has an apostrophe (‘) as the first character and can occur anywhere. A comment line is completely ignored; all other lines are significant.

The following example is of a file that contains a single sprite consisting of a red ball with a white border and a blue center dot: