VIC20 3k Super-Expander Cartridge
User Manual


    Programs created with Super Expander's special statements wi11
    not work on a machine without the Super Expander plugged in.

    Finally, the extra 3K memory expansion is provided automatically
    when you plugin the Super Expander... you will see the screen
    come up with approximately 3000 extra bytes of memory when
    you turn it on.

    GETTING STARTED

         1. Turn on your television set.
         2, Turn your VIC 291 off.
         3. Insert the cartridge.
         4. Turn the VIC 20 on.
         5. Your Super Expander is now activated and you may write
         programs in BASIC using the special commands, statements
         and functions listed below.

    II. USING SUPER EXPANDER GRAPHICS
    A few special notes are in order before you begin working through
    the manual.  To begin with, it should be noted that for purposes of
    graphics plotting, the Super Expander cartridge divides the
    screen area into 1024, by 1024 coordinates.  For example, if you
    type POINT1,512,512 you will draw a point at the very middle of
    the screen.  These are "Pseudo-coordinates" which means the
    VIC accepts inputs based on 1024x1024 dot coordinates and
    scales the plotting down to the VIC's actual screen size/resolution.

    A full range of graphic instructions is automatically added to your
    VIC's standard BASIC instruction set when you plug in the Super
    Expander cartridge.  These instructions are listed and explained
    below.

    NOTE: WHEN WORKING WITH GRAPHICS THERE ARE TWO
    IMPORTANT PARAMETERS WHICH YOU MUST INCLUDE AT
    THE BEGINNING OF YOUR PROGRAM. These setup the graphics
    screen so you can plot, include characters mixed with graphics,
    etc.  The two graphic commands you should begin your program
    with are: GRAPHIC and COLOR.  GRAPHIC sets the VIC in the
    "GRAPHIC MODE" you want to use, and "COLOR" specifies the
    colors you will be working with.

    INSTRUCTION                          EFFECT
    GRAPHIC        Prepares the screen for graphics
    SCNCLR         Clears a graphic screen
    COLOR          Select screen, border, character, and auxiliary
                   coler,s
    REGION         Select character color
    DRAW           Plots a line between two points
    POINT          Plots asingle point
    CIRCLE         Draw a circle, ellipse, or arc
    PAINT          Fill in an enclosed area in a color
    CHAR           Puts text on the graphic screen
    SOUND          Set 4 tones and volurne all at once

    FUNCTION                    RETURN VALUE
    RG R (x)       Current graphic mode
    RCOLR(X)       The value in a color register
    RDOT(x,y)      The color of a point on the screen
    RPOT(X)        The position of the game paddle
    RPEN(X)        The positlon of the light pen
    RJOY(x)        The position of the joystick
    RSND(x)        The value in a sound register


    GRAPHIC n

    This sets up the graphic screen and activates the graphics
    instruction set.  There are 5 different GRAPHIC modes, which are
    activated by typing GRAPHIC and the number, as an instruction in
    your program.
    Exannple:
        10 GRAPHIC 2
        20 COLOR 1, 2, 3, 4
        Type RUN and hit RETURN.

    Value of n    Mode
    0             Text mode (norrnal)
    1             Muuti-color mode
    2             High resolution mode
    3             Mixed multi and high-res
    4             Return to text mode

    Mode 0 is the VIC's normal text mode.  Once the mode has been
    changed, the GRAPHIC 4 statement is used to return to this
    mode.

    In mode 1, there are 80 points across a line, and 160 lines.  Each
    point is drawn in one of the 4 color registers: screen color, border
    color, character color, or auxiliary color, A point placed in the
    screen color is invisible, since it is the same as the background; 
    this can be used to erase other points.  Points drawn in either the
    screen, border, or auxiliary colors will change instantly when
    these colors are changed. The character color is associated with
    each specific 4 dot by 16 dot space of the screen. This means that
    if a dot is plotted in that space in a character color, all other points
    in that space that were drawn in the character color will change to
    the new character color.

    In mode 2, there are 160 points across a line, and 160 lines.  The
    points are half as wide as in mode 1, and therefore give twice as
    fine resolution to the screen.  However, the color resolution is
    more limited. Dots can be plotted only in a character color.Within
    each specific space on the screen, which is an 8 by 8 dot area.
    there can be only one character color, so you can only have dots in
    that color displayed on the screen.

    Mode3 is a mixture of modes 1 and 2. When the character color is
    less than 8, the plotting is done in high resolution.  When the
    character color is greater than 7, multi-color mode is in effect.

    Mode 4 returns the screen to text mode from a graphic mode.
    WARNING: if the VIC was already in text mode, this will mess up
    the VIC until you turn it off and then on again.


    SCNCLR

    This statement clears the entire graphic screen.  It may be typed
    directly or included in a program line.

 
    COLOR sc, bo, ch, au

    This sets up the 4 different color registers.  The variables here
    have these limits:

       sc = 0 to 15
       bow= 0 to 7
       ch = 0 to 7 normal, 8 to 15 multi-color
       au = 0 to 15

    The colors are:

        0           black
        1           white
        2           red
        a           cyan
        4           purple
        5           green
        6           blue
        7           yellow
        8           orange
        9           light orange
        10          pink
        11          light cyan
        12          light purple
        13          light green
        14          light blue
        15          light yellow


   NOTE: in GRAPHIC 3 mode, character color numbers greater
   than 7 set multi-color mode.  In this case, the actual character
   in that spare is the color number minus 6.

   EXAMPLE: COLOR 1, 2,3,4


   REGION c

   This works like the COLOR statement, except that only the
   character color is affected.

   EXAMPLE: REGION 7


   DRAW c, x1, y1 TO x2, Y2 [TO x3, y3... TO xn,
   yn]
   or
   DRAW c TO x1, y1

   This allows you to draw lines in the screen.  The variable c is the
   color of the line, on the following chart:
    c            High-res                     Multi-color

    0            screen                       screen
    1            character                    border
    2            character                    character
    3            character                    auxiliary

   The x and y variables are the coordinates of the end-points of the
   line.  The values of X and Y can be f rom 0 to 1023.  An X value of 0 is
   the left edge of the screen, and X=1023 is the right edge, and the
   Y values determine the up-and-down position.  The values from 0
   to 1023 are scaled down to the actual (160 by 160 or 80 by 160)
   size of the screen.

   EXAMPLE 1: DRAW 1, 0, 0 TO 100, 100
   EXAMPLE 2: DRAW 1, 0, 0 TO 0, 100 TO 100, 100TO100,0TO0,0

        EXAMPLE 1                 EXAMPLE'2

	{pictures omitted}


   POINT c, x, y
   or
   POINT c, x1, y1, x2, Y2, ..., xn, yn

   This sets a point or points on the screen in the specified color. The
   points are given in the 0 to 1023 form.

   EXAMPLE 1: POINT 1, 500,500
   EXAMPLE 2: POINT 2, 500, 500, 600, 600, 700, 700


   CIRCLE c, x, y, rx, ry [,as,ae]

   Where: c is the color register (see chart in DRAW statement) in
         which the circle is drawn
         x and y are the coordinates of the center of the circle
         rx and ry are width and height of the circle
         as and ae are the optional starting and ending angles of
           the arc, in gradians (0 to 100 degrees in a full circle)

    EXAMPLE 1: CIRCLE 1, 511,511, 300,400
    EXAMPLE 2: CIRCLE 1, 200, 900, 100, 100
    EXAMPLE 3: CIRCLE 2,500,600,200,300,10,70

                             EXAMPLE 1

	{pictures omitted}

           EXAMPLE 2                            EXAMPLE 3

	{pictures omitted}


    PAINT c, x, y

    This paints an enclosed area in a color. c is the color register, and x
    and y are any point within the area to be painted.  Each area can
    only be painted once.  Because of the color limitations of some
    GRAPHIC modes, some nearby shapes may be distorted by this
    operation.  If an area is bounded by multi-color mode areas, it must
    be PAINTed in the multi-color mode.

    EXAMPLE:    10 GRAPHIC 1
                20 COLOR 1, 7, 0, 1 0
                30 CIRCLE 2, 511, 511, 200, 300
                40 PAINT 3,.511, 511
                50 PAINT 1, 511, 0


    CHAR ro, co, "text"

    This will put norrnal text on a graphic screen.  The ro and co
    variables are the row and column on which the text is to appear.
    The text can be any string variable or text inside quote marks.  Text
    should only be displayed when in the high-resolution mode, or the
    mixed mode, but never in multi-color mode.

    EXAMPLE: CHAR 1, 1, "HELLO THERE"


    SOUND s1, s2, s3, s4, v

    This sets all 4 sound "speakers" and the volume control all at
    once.  The Sl value is put into register 1. If its value is less than 128,
    no sound will play from that speaker.  The volume can range from 0
    (off) to 15. This lets you create multi-speaker sound effects.

    EXAMPLE: SOUND 225,225,225,0,15


    RGR(X)

    This function reads the graphic mode that was set with the
    GRAPHIC command.  The value of x can be from 0 to 255, and
    doesn't effect the result.

    EXAMPLE: X = RGR(O)


    RCOLR(X)

    This reads the color from any of the 4 registers depending on the
    value of x on the following table:

    X         COLOR REGISTER

    0         screen color
    1         border color
    2         character color
    3         auxiliary color

    EXAMPLE: X = RCOLR(2)


    RDOT(X, Y)

    This reads the color value of a dot on the screen.  The values of x
    and y are the coordinates of the point, and the color value
    returned is the register of the color on that space.

    EXAMPLE: X = RDOT(511, 511)
 

    RPOT(X)

    This reads the value of the paddle.  If x = 0, paddle X is read, and if
    x = 1, paddle Y is read.

    EXAMPLE: 10 GRAPHIC2:COLOR11,6,6,6
             20 X=RPOT(0):Y=RPOT(1):J=RJOY(0)
             30 IFJ=12THEN:SCNCLR
             40 IFJ=4THEN:REGION2
             50 IFJ=STHEN.REGION6
             60 POINT2,X*4,Y*4:GOTO20


    RPEN(X)

    This reads the screen coordinate of the light pen.  It x=O, the X
    coordinate is returned, and if x=1, the Y coordinate.

    EXAMPLE: X = RPEN(0)


    RJOY(X)

    This reads the value of the joystick.  The x variable must be
    between 0 and 255, and has no effect on the outcome.
 
    EXAMPLE:    10 GRAPHIC2:COLOR11,6,6,6:X=170:Y=170
                20 J=RJOY(0)
                30 X=X+((JAND4)=4)-((JAND8)=8)
                40 Y=Y+((JAND1)=1)-((JAND2)=2)
                50 POINT3,X*3,Y*3:IFJ=128THEN:SCNCLR
                60 GOT020


    RSND(X)

    This reads the value of any of the sound registers, depending on
    the value of x from this chart:

    X           sound register
    1           sound 1
    2           sound 2
    3           sound 3
    4           sound 4
    5           volume


    III.  WRITING SUPER EXPANDER MUSIC

    The Super Expander's music writing mode lets you play notes
    directly by typing on the keyboard, or, more important, by using
    the PRINT statement in your BASIC PROGRAMS.  It is "interrupt
    driven", which lets music play while the program proceeds with
    other tasks.  It is designed primarily for playing of music, as
    opposed to sound effects, and makes writing programs with
    chords much easier.

    Music mode is entered by holding down the CTRL key and hitting
    the left arrow (<=). When you type this in quotes in a program a
    "reverse f" should appear.  This is a special symbol that shows you
    where music mode is included in your program.  Now any key you
    type will be interpreted by the music package, until the RFTURN
    key is hit.  Here are the characters recognized by music mode:

     Character                          Effect

     p                                  Screen echo on
     0                                  Screen echo off
     v                                  Volume selection
     S                                  Sound register selection
     0 (the letter 0, not the number)   Octave selection
     T                                  Temposelection
     R                                  Rest for 1 beat
     C, D, E, F, G, A, B                Play note
     #                                  Play the next note sharp
     $                                  Play the next note flat
     RETURN                             Ends music mode

    When PRINTING strings of these characters, the semicolon (;)
    can be used to prevent the RETURN character from ending music
    mode.

    The screen echo is normally off.  Any characters recognized by the
    music, package are not displayed on the screen.  However, when
    the echo is turned on, they appear normally.

    Some of the letters recognized by music mode must be followed
    by a single digit.  Here is a table of these letters and their
    associated numbers:

     Letter      Numbers            Value of numbers

     v           0 to 9             0 is quietest, 9 loudest
     5           1 to 4             Speaker no.
     0           1 to 3             1 is lowest, 3 is highest
     T           0 to 9             Tempo

    The tempo is selected according to this chart:

     Tempo       Beats per          Duration of note
     number      minute             times 1/60 second

     0           900                4
     1           600                6
     2           450                8
     3           300                12
     4           225                16
     5           15d                24
     5           112.5              32
     7           56.25              64
     a           28.                128
     9           14.                255

    Each sound register has 3 complete octaves in its range. However,
    since register 2 is one octave higher than register 1, the three,
    octaves are different.  When playing notes in different sound
    registers, be sure that the octaves used are chosen correctly.

    Here are some examples of strings that play music (the reversed f
    symbol means hold down the CTRL Key and type the left arrow
    key at the top left corner of the keyboard).

     10 PRINT"ALL THE SAME NOTE {ctrl <=} T7 V9 Sl 03 C S2 C
        S3 01 C"
     20 PRINT "SCALE {ctrl <=} T3 V9 S2 01 CDEFGAB 02
        BDEFGAB 03 CDEFGAB"
     30 PRINT "CHORDS {ctrl <=} T5 V9 S1 03 C S2 E S3 01 G";
     40 PRINT "S1 03 D S2 02 #F S3 01 B";
     50 PRINT "S1 03 E S2 02 A S3 02 C"


    IV.  PROGRAMMABLE FUNCTION KEYS

    There are 8 functions that can be accessed with the function keys
    along with the SHIFT key. These are pre-assigned to the following:

     Key           Text

     fl            GRAPHIC
     f2            COLOR
     f3            DRAW
     f4            SOUND
     f5            CIRCLE
     f6            RUN + RETURN
     f7            POINT
     f8            LIST + RETURN

    Any time you hit these keys, the characters with which they are
    programmed enter the input buffer exactly as if you had typed
    them in yourself.  Each key can be programmed with up to 128
    characters, using the KEY command.


    KEY
    or
    KEY n, "string"

    The word KEY all by itself makes the VIC display a list of all 8 func-
    tion keys and their current value.  This is formatted on the screen so
    the contents of the strings can be edited by moving the cursor up to
    the string, making the desired change, and hitting RETURN, just
    like editing a program.  You can change any key in the KEY MENU by
    changing the information inside the quotation marks and hitting
    return or by typing the KEY command using the forrnat showm in the
    example below.

    When followed by a number, this command changes the string
    value of the key to the new value.  This can be up to 128
    characters, including cursor and color controls, the RETURN
    (CHR$(13)), or any other character.  The keys can be changed.
    under program control as well.
 
    EXAMPLE:  KEY 1, "ISN'T IT AMAZING?"

    V. 3K MEMORY EXPANSION

    When the 3K cartridge is used to expand the VIC-20, the BASIC
    program area is changed so it starts at location 1024 ($0400).

    Note that with the 3K cartridge plugged in, only on-board memory
    (4096-8191 or $1000-1FFF) can be used as VIC screen and hi-
    resolution graphics areas.

