title: "vbmSetDisplayMode" description: TRSE built-in method (from IDE help)

`vbmSetDisplayMode`

Systems: VIC20
Parameters: n

vbmSetDisplayMode( [byte] );

[byte] - 0 - 15: Mode 0 is the default and creates a full screen bitmap

Description

Set up the Vic Bitmap Mode (VBM) with a specified width and height. 8K or more of RAM is required to use this mode. More information about the Vic Bitmap Mode (VBM) can be found in the Platform help section.

The display mode needs to be set up before any other VBM command is executed.

0 - 20 x 24 characters - 160 x 192 pixels. Free RAM: $10f0 - $10ff
1 - As above but the last column is not shown. To be used for scrolling bitmaps.
2 - 20 x 22 characters - 160 x 176 pixels. Free RAM: $10dc - $10ff, $1ec0 - $1fff
3 - As above but the last column is not shown. To be used for scrolling bitmaps.
4 - 20 x 20 characters - 160 x 160 pixels. Free RAM: $10c8 - $10ff, $1d80 - $1fff
5 - As above but the last column is not shown. To be used for scrolling bitmaps.
6 - 20 x 18 characters - 160 x 144 pixels. Free RAM: $1084 - $10ff, $1c40 - $1fff
7 - As above but the last column is not shown. To be used for scrolling bitmaps.
8 - 18 x 24 characters - 144 x 192 pixels. Free RAM: $10d8 - $10ff, $1e80 - $1fff
9 - As above but the last column is not shown. To be used for scrolling bitmaps.
10 - 18 x 22 characters - 144 x 176 pixels. Free RAM: $10c6 - $10ff, $1d60 - $1fff
11 - As above but the last column is not shown. To be used for scrolling bitmaps.
12 - 18 x 20 characters - 144 x 160 pixels. Free RAM: $10b4 - $10ff, $1c40 - $1fff
13 - As above but the last column is not shown. To be used for scrolling bitmaps.
14 - 18 x 18 characters - 144 x 144 pixels. Free RAM: $10a2 - $10ff, $1820 - $1fff
15 - As above but the last column is not shown. To be used for scrolling bitmaps.

How it works

The default VBM mode 0 creates a full screen bitmap using 240 (20 x 12) double heigh characters. This presents a 160 x 192 pixel display on screen. Other modes create a variety of screen sizes with free RAM to use between the screen and bitmap and also at the end of the bitmap.

The way characters are laid out is a little differently to what you may be used to on the standard Vic 20 character screen. This is to make manipulating the bitmap simpler and easier to understand.

The first double height character is 16 (a space and ! character) and this is placed at the top left of the screen. Beneath that character 17 is placed (a " and # character), then 18 (a $ and %) and so on unit character 27 (a 6 and a 7 character) which is in the 12th row on mode 0.

Character 28 (an 8 and a 9) is printed in the next column back at the top. This pattern is repeated, filling each column in turn until all 20 columns have been populated.

Try the following code snippet to see the character pattern created on the screen:


    vbmSetDisplayMode(0);
    vbmDebug(1);

vbmDebug with a parameter of 1 will show the original ROM character set.

Screen and Character memory

The Vic 20 is set up to have both the screen memory and character memory start at address $1000 (4096). It is also set to use double height characters which allows the screen memory to be completely filled with 240 characters in mode 0 & 1. Other modes require fewer characters.

$1000 to $10F0

The screen memory occupies $1000 through to $10F0. $1100 through to $1FFF is therefore free for the bitmap. Other screen modes require fewer characters so more memory will be available to use for your own program.

$1100 to $1FFF

The character memory occupies $1000 through to $1FFF, however, as this overlaps with the screen memory, the first 240 bytes cannot be used. This is why the first character printed to the screen memory is number 16 (space and !) and not number 0. The usable character memory therefore starts at $1100 (character 16) and this extends to $1FFF. Writing to this area of memory will modify the bitmap. Other modes require fewer characters and as such a smaller bitmap so some bytes will be available to use at the end of the bitmap in some modes.

Working with the bitmap

You are free to write your own routines to modify the btimap memory ($1100 through to $1FFF) should you wish to. However, in Turbo Rascal, there are a number of commands that make some common bitmap tasks easier to do, so you can concentrate on creating your game or demo.

Example

The following code sets up the Vic Bitmap mode, clears the screen and initialises color memory with green, then writes a message to the screen over a number of lines.


    program HelloWorld;
    var  

    // declare all your include files here
    font: incbin( "font8x8.bin", $4000 ); // character set for first 64 PETSCII Screen Codes


    @startblock $2000 "CODE"
    // declare all your variables and procedures here
        message: CSTRING = "HELLO WORLD";

        i : byte;

    begin

        // set the default display mode showing all 20 columns
        vbmSetDisplayMode( 0 );

        // Clear the bitmap with a value of 0
        vbmClear( 0 );

        // set the colour memory to GREEN
        vbmClearColor( GREEN );


        fori i := 0 to 9 do
        begin

            // write a message to the screen
            // using the font (character set)
            // params are: text, characterset, x, y, line spacing
            vbmDrawText( message, font, i, i << 4, 8 );

        end;

        loop();

    end.

vbmSetDisplayMode