c64lib - User’s Manual

Well, when you are a happy user of Retro Assembler plugin, then you are even happier, because it’s extremely easy to add C64Lib to your project. The c64lib is a GitHub project, so it can be added as GitHub dependency to your gradle.build file. Put the following lines into your retroProject section of the build file:

Then you will be able to use all four libraries from c64lib. Of course not all four are mandatory. You can use any subset of them as long as you obey dependency graph as shown in Overview.

Retro Assembler plugin downloads all dependencies into default location:

All libraries from c64lib will be downloaded under c64lib subfolder therefore the following location:

must be added to the lib dir so that Kick Assembler will see them when interpreting #import directive. The following must be also a part of your gradle.build file:

The complete gradle.build will be following:

In order to build your executable you just need to execute gradle:

or

In result C64 executables (a prg files) will be created.

but you really want to start using it, you have to enable it first. Following steps are requires as preconditions:

Once it is done, you have to restart your console/terminal application and go to your project location. In your location you run Gradle to install a wrapper:

then you add gradle.build file using following content (or similar):

Of course, the set of used libraries (with libFromGitHub element) may vary as well as the version of Kick Assembler.

And that’s it: from now on you are able to build your project using simple gradlew or gradlew build commands. It’s not even necessary to have Gradle installed. All you need is Java 8 or higher.

As subroutine we understand a piece of ML code that can be used by jumping there with jsr operation. A subroutine always ends with rts which means that at the end of execution program counter will be restored to the position right after original jsr operation and code execution will continue. In this sense a subroutine is an equivalent of procedure, function or method in high level programming languages.

Kick Assembler as such does not provide any special means to create subroutines as it is just a macro assembler. With c64lib we basically share subroutine code just by writing piece of asm code and place it in separate source files.

Subroutines are declared in .asm files located under lib/dir subdirectory. Each subroutine consists of appropriate rts operation so that it should always be accessed with corresponding jsr operation. If soubroutine consumes input parameters, they should be set accordingly before jsr is executed. Depending on the parameter passing method it should be either register setup (that is A, X or Y), memory location setup or pushing to the stack. For stack method there is a convenience library invoke available.

A subroutine code should be imported in place where it needs to be located - we don’t do it at the top of the source file but rather we use #import directive exactly in place where we want to have our subroutine.

Lets consider copyLargeMemForward subroutine as an example. We have to label a place in memory where the subroutine will start and then import the subroutine itself:

The subroutine takes three parameters using stack passing method:

So, before calling subroutine, you have to push 6 bytes to the stack. The easiest way to do it is to use invoke library:

and then:

In result a subroutine will be called and amountOfBytesToCopy bytes will be copied from sourceAddress location to the destinationAddress location.

Some subroutines use this convenient method of distribution. Instead of being declared in separate source file, they are declared where macros and functions are declared - in library source files itself.

Macro-hosted subroutines are used when further parametrisation is needed before subroutine is ready to use. Usually there are some variants that can be turned on or off (in such case such macro can be called multiple times thus generating multiple versions of subroutine). Sometimes subroutine requires some zero-page addresses that we don’t want to hardcode in the library - it would be then up to the user to parametrise subroutine with addresses of choice.

The common library contains helper macros for parameter passing via the stack. Recursive calls to the subroutines are not supported.

Parameters should be pushed onto the stack just before calling subroutine (which is done via jsr instruction). Within the subroutine, parameters must be fetched from the stack in reverse order and stored elsewhere. Before this is done, a return pointer must be preserved in order to enable return from the subroutine (a rts instruction).

There are four macros for pushing parameters to the subroutine:

All these macros are destroying A register, that should be considered when using hybrid invocation (first push params via macros, last set the A parameter value).

The subroutine, once being called, must do the following:

Preserving and restoring of return address may be done via invokeStackBegin and invokeStackEnd macros. Each of these macros takes single argument that denotes temporary address of 2-byte large placeholder where return address can be preserved.

The invokeStackBegin should be called before any parameter is pulled from the stack. The invokeStackEnd should be called before a rts instruction is called.

There are three macros for pulling parameters from the stack (remember to call them in reverse order, this is how the stack works):

There are a bunch of set* pseudocommands that can be used to quickly set given memory cells to some value. The set8 works with 1-byte values, the set16 works with 2-byte values (words).

The following sets content of memory address $B000 to 0:

The following sets content of memory address $C000 to a value stored under address $0F:

It is also possible to set two consecutive bytes to a given 2-byte value, but one needs to use the following macro for that (sets $B000 to $02 and $B001 to $01):

There is also a macro for setting one byte value which can be used as long as immediate addressing is needed:

In order to fill specified memory block with given value a fillMem subroutine can be used.

You can use copy8 pseudocommand to copy one byte from one place to another using A:

You can use copy16 pseudocommand to copy two consecuive bytes from one place to another:

For fast, unrolled copying of data block use copyFast macro. To copy 20 bytes from $B000 to $C000 use the following:

Remember, that copyFast macro will consume a lot of space if count parameter (the last one) will be big.

There is a "slow" copy subroutine that is handy for "unpacking" a PRG file and moving arbitrary sized blocks of data to the target location. This subroutine can be used to move SID data (music) into target location as well as to move VIC-II data (charsets, sprites) into the VIC-II addressable bank. Target and source spaces can overlap as long as target address is bigger than source address.

You can easily increment and decrement 16-bit counters using following macros:

You can add / subtract value to / from a value stored in memory via add16 and sub16 macros.

In example to add 315 to the value stored under $B000:

Alternatively you can use add16 and sub16 pseudocommands:

You can add / subtract value stored in one memory address to / from a value stored in another memory address via addMem16 and subMem16, respectively.

In example to add value from address $B000:$B001 to the value from address $C000:$C001:

Configuration of which one out of four C64 memory banks is addressable by VIC-II chip can be done via reprogramming the CIA-2 chip.

The change can be done via setVICBank`c64lib_setVICBank` macro.

The following code:

sets up the last memory bank ($C000-$FFFF) for VIC-II graphic chip.

There are two distinct memory areas that have to be fconfigured for VIC-II. Their meaning is different depending on the screen mode. For text modes it would be screen memory and charset memory. For bitmap modes it would be screen memory and bitmap memory.

Changes border color.

Usage:

Changes background color 0.

Usage:

Changes background color 1.

Usage:

Changes background color 2.

Usage:

Changes background color 3.

Usage:

Changes background color 0 and border color to the same color.

Usage:

Changes background color 0 and border color to another values in single step, the colors are specified as arguments.

Usage:

Changes VIC memory control and VIC memory bank in one step.

Usage:

Changes VIC display mode and memory settings in one step. VIC bank cannot be changed.

Usage:

Jumps to custom subroutine that can do whatever you want, i.e. play music. Subroutine must end with rts.

Usage:

Sets up hires bitmap mode using given memory layout and VIC bank. Useful for screen splits using totally different memory locations for VIC chip.

Usage:

Sets up multicolor bitmap mode using given memory layout and VIC bank. Useful for screen splits using totally different memory locations for VIC chip.

Usage:

Sets up hires text mode using given memory layout and VIC bank. Useful for screen splits using totally different memory locations for VIC chip.

Usage:

Sets up multicolor text mode using given memory layout and VIC bank. Useful for screen splits using totally different memory locations for VIC chip.

Usage:

Sets up extended text mode using given memory layout and VIC bank. Useful for screen splits using totally different memory locations for VIC chip.

Usage:

Generates colorful raster bar across whole screen including border. Color for each subsequent bar line is fetched from $FF terminated array of colors (values 0..15). Because procedure is cycled using busy waiting on raster, a raster time for whole bar will be consumed. Color array can be cycled or modified in any way to get interesting animation effects.

Usage:

Generates colorful raster bar across whole background. Color for each subsequent bar line is fetched from $FF terminated array of colors (values 0..15). Because procedure is cycled using busy waiting on raster, a raster time for whole bar will be consumed. Color array can be cycled or modified in any way to get interesting animation effects.

Usage:

Scrolls screen horizontally using specified amount of pixels.

Usage:

Applies shallow tech-tech effect (using values 0..7) starting from given raster position. Horizontal scroll value for each corresponding raster line is taken from $FF terminated array of values, each should contain value from 0..7 range. The scroll map can be further modified (i.e. rotated) to achieve interesting animation effects.

Usage:

We would like to display a new level screen for a video game. This screen should play background music, display some information and handle controls to start the game when player is ready. Lets consider the following requirements:

The whole screen can be built using following copper table:

For background raster bar effect we use following arrays defining color cycles:

Additionally, the content of colorCycle2 array is rotated using the following code, that is triggered by second entry of the copper table:

Note that it is essential, that last byte of the colour cycle entry is the same as the screen colour (BLACK in this case) - this restores bg colour of the screen remainder.

Also note, that "rainbow" font effect requires inverted charset to be used, because rainbow is done via rasterbar effect on background colour.

The Copper 64 main subroutine can be configured in following way:

Main subroutine can be then started multiple time using the following code:

As shown above, the Copper 64 subroutine can be easily reused with different copper lists as long as the same effects are used. All to be done is to set up copper list address which is in this example stored in addresses $03 and $04.

The title screen for the TRex-64 video game uses rainbow fonts, both static and animated as well as fade in/fade out effect on credits/instruction text. The fade effect is also done with background colour, so also inverted charset must be used to hide all parts of the background that shouldn’t be visible.

This screen is implemented with following copper list:

In this example we see that copper list can be modified in runtime. Here we modify the background colour at the begining of the fade in section. In another place (handleCredits) we modify this value with simple:

Just each time you want to fade in or out, we have to change colours according to special fade in / fade out array of colours.

We all know that NTSC on C64 is hard, because there are far less raster lines per frame (due to the fact that VIC-II does 60Hz vs 50Hz in PAL). But what is even harder and more awkward: while PAL version has 0 raster line at the very top of the screen, the raster 0 on NTSC is near at the bottom.

For PAL we do have 312 raster lines, and v-blank starts at 300 (the very bottom of the visible screen area). for NTSC we have 263 raster lines, v-blank starts at line 13 (so raster lines 0 to 12 are visible at the very bottom of the screen). So, lets assume we would like to set up an interrupt at the line 251 (PAL). To have this interrupt to be triggered in exactly the same place on NTSC, we do need to set it up in line 1.

Therefore in order to make our copper list work equally well on PAL and NTSC we do have to:

Let’s consider following copper list:

We see that the last raster line is way beyond of the NTSC display capabilities. In fact, IRQ at 280 will never be triggered on NTSC machine. In short, the following raster table will not work there. We have to detect NTSC and modify the table accordingly.

Note that we have to change both byte 0 and 1 of the copper list entry - this is because we have to also clear bit 9 of the raster counter, which is stored in control byte.

To detect NTSC we can use the following code: