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

`vbmClearSprite16`

Systems: VIC20
Parameters: a, a, a

vbmClearSprite16( [address1], [address2], [address3] );

[address1] - pre-shifted address table for the left side of an 16x16 sprite
[address2] - pre-shifted address table for the middle of an 16x16 sprite
[address3] - pre-shifted address table for the right side of an 16x16 sprite

Description

A simple sprite routine to erase or cut-out a 16x16 sprite on the bitmap.

This has two useful purposes. It can be used to clear a sprite that has been previously drawn (see example below) or it can be used to 'cut out' a mask of a sprite to then draw the real sprite within. You may wish to do this for multicolor sprites or if you want your sprites to be more visible when moving over background graphics.

Three parameters are required; the addresses of the pre-shifted 'address table' for the left, middle and right side of a sprite. The pre-shifted address table is a list of addresses to point to where each pre-shifted frame can be found in memory.

For example: $a000, $a080, $a1000, $a180

The address table will need to be defined if you import your sprites already pre-shifted. If you use the vbmSpriteShiftL / R commands, these will build the address table for you.

Limitations

Some compromises have been made for the basic 16x16 sprite command.

Firstly, it will write the sprite to wherever the built in screenmemory zero page pointer is pointing to. This could be partly outside of the bitmap memory ($1100 to $1FFF) if you position your sprite off of the screen edges. Therefore, do not use this command if you wish to place sprite your sprite partly off the screen.

Secondly, this sprite command cannot be used with the vbmScrollLeft / Right commands which re-arrange the character map used for the bitmap.

Should either of the above be requirements, use vbmSpriteSlice instead which allows you to draw each sprite column seperately and you can specify the start and end line of the sprite to draw. As such you can only draw the columns and lines as needed in the correct locations.

There are three ways to draw a sprite:

vbmDrawSprite16 - draws a sprite, merging it with the bitmap
vbmDrawSprite16E - draws a sprite, merging it with the bitmap using the EOR operation
vbmClearSprite16 - clears a sprite from the bitmap, effectively 'cutting it out'

Example


        x,y :byte;

        // define a sprite character - the first 8 bits (pixels)
        spr16L : array[] of byte = (
            %11111111,
            %10000001,
            %00111100,
            %00100100,
            %00100100,
            %00111100,
            %10000001,
            %11111111,

            %01100110,
            %10011001,
            %01100110,
            %10011001,
            %01100110,
            %10011001,
            %01100110,
            %10011001
        );
        // the second 8 bits (pixels)
        spr16R : array[] of byte = (        
            %01100110,
            %10011001,
            %01100110,
            %10011001,
            %01100110,
            %10011001,
            %01100110,
            %10011001,

            %11111111,
            %10000001,
            %00111100,
            %00100100,
            %00100100,
            %00111100,
            %10000001,
            %11111111
        );

        // where to store the pre-shifted addresses of the sprite
        // a 16x16 sprite is made up of two columns of characters but needs three columns to allow it to move smoothly
        spr16L0 : array[8] of integer;  // the left 8-pixels
        spr16M0 : array[8] of integer;  // the middle 8-pixels
        spr16R0 : array[8] of integer;  // the right 8-pixels

        ...

        // sprite 16x16 - pre-shift in 8 positions, using 128 bytes ($80)

        vbmSpriteShiftR( spr16L, ^$a000, 1, 16, spr16L0 ); // spr16L into addr A000, 1 pixel increments, 16 lines
        vbmSpriteShiftL( spr16L, ^$a080, 1, 16, spr16M0 ); // spr16L into addr A080, 1 pixel increments, 16 lines

        vbmSpriteShiftR( spr16R, ^$a100, 1, 16, spr16R0 ); // spr16R into addr A100, 1 pixel increments, 16 lines    
        vbmSpriteStitch( ^$a100, ^$a080, 128 );  // 8 x 16 = 128 ($80) bytes to stitch
        vbmSpriteShiftL( spr16R, ^$a100, 1, 16, spr16R0 ); // spr16R into addr A100, 1 pixel increments, 16 lines

        y := 10;

        for x := 0 to 100 do
        begin

            vbmSetPosition1( x, y ); // position the sprite, 1 pixel increments
            vbmDrawSprite16( spr16L0, spr16M0, spr16R0 );  // draw the sprite

            waitforraster( 0 ); // wait for raster

            vbmSetPosition1( x, y ); // position the sprite, 1 pixel increments
            vbmClearSprite16( spr16L0, spr16M0, spr16R0 );  // erase the sprite     

        end;

vbmClearSprite16