This documentation is currently being updated to reflect massive changes between version 0.3 and the next release, 0.5. Generally, these updates are happening in the order of disks: STDIO, then COMMON, etc. Once this is finished, v0.5.0 will go live, and future updates will be piecemeal, by and large, rather than in large chunks.
This is a general purpose library in 6502 Assembly for the Apple II. Originally, I began this project as research for a platform study of the Apple \]\[ system, learning Assembly for the first time. However, after speaking to a number of folk who are still actively involved in a community of enthusiasts, I noticed that there was no cohesive place for a first-time learner to find well-documented code, basic data structures and control loops, or even a good and intuitive listing of hooks for the system. There are plenty of books--some very old, some very new--that detail these things somewhat cohesively and are fantastic resources for beginners, but very few of them adequately serve as an good basis for understanding the platform as a whole. There are also many webpages out there dedicated to this matter--but as is the nature of the Internet, they are fractured resources that come and go at the blink of an eye. Thus, Appl\]\[AsmLib began.
Ultimately, my aim is to create a large enough collection of routines to address any domain of development for the Apple II family in Assembly while maintaining an ease of access to beginners that is hard to come by. I'll do my best to acknowledge when a routine is inspired by (or mostly copied from) another source, and will exclude them from the Apache License 2.0 when necessary; I hope to replace anything of this sort with original work as I revise. If you find your own source here, but would rather it not be here, please reach out to me and I'll remove it immediately.
As someone who spends a _lot_ of time thinking about, writing about, and teaching different facets of technical writing (in its broadest sense), I can confirm the following: there are hundreds of thousands of books written about the 6502 architecture and Assembly programming. I can also confirm that these books--as well as most websites--tend to approach the subject from a "writerly" position rather than a reader-centered one; that is, it's written for engineers and computer scientists who have already spent a lot of time and money understanding the theory, learning the jargon, and training themselves to be able to do things by muscle memory. That's great for established engineers, mathemeticians, computer scientists and the like, as well as those who can afford to dedicate years of their lives (and again, gobs of $$$) to obtain a degree that qualifies them as entry level in the field. It is not so great, however, for beginners, hobbyists, or those trying to study it from a non-engineering theoretical perspective. That is, at least, part of the gap I am hoping to fill.
That said, I myself would have failed quite readily without at least a few key texts and websites, and it would be remiss to not list them here. And if you're committed to learning this, know that there is no good replacement to sitting down, typing out a listing from a book, compiling and then trying to figure out what the hell you just did--or what you did wrong! There is no doing without learning, and there is no learning without doing; but maybe these can help.
More books have been written over the past forty years than could be read within a reasonable timeframe. However, I have found some books more fruitful than others in understanding both the technical aspects of the Apple \]\[ as well as the cultural ones. If you know of any essential books or websites that are missing here, by all means get in touch or contribute it here yourself!
* Bill Martens, Brian Wiser, William F. Luebbert, Phil Daley. [_What's Where in the Apple, Enhanced Edition: A Complete Guide to the Apple \]\[ Computer_.](https://www.amazon.com/gp/product/136517364X/) October 11, 2016.
Each disk contains a single Macro (.mac) file, one or more subroutine files related to the overarching theme of the disk, and a "minified" version of the mac and subroutine files that the entire library relies upon. Additionally, each library has a correlating .hooks file for declaring useful hooks at the beginning of a program used in that library's operations, as well as a variable file that must be included with any subroutine's inclusion into the main listing.
In the following disk descriptions, we'll be listing the .mac contents that are relevant to the theme of the disk only, as many of the macros are calls to single subroutines. A table in section XXX lists the calls each macro makes to each subroutine, and the same information can be obtained from the detailed descriptions of macros and subroutines.
This disk is dedicated to Standard Input/Output operations, and a couple non-standard ones. Note that this is for 40-column mode only in order to keep compatibility with earlier hardware, and focuses on screen output alone in order to help with execution speed. However, most of these subroutines will work in 80col mode, with the exception of those that directly read or write the screen memory.
This disk is dedicated to common and useful subroutines that don't necessarily fit neatly into another category worth dedicating an entire disk to, as well as the fully commented code for the required libraries and macros that exist on every disk in minified form.
This disk contains libraries and subroutines related to the management of one-dimensional and two-dimensional arrays. Since these arrays use a singly byte for indexing, they are referred to as 8-bit arrays, even though you could technically use 64k of memory by increasing element lengths or simply having a 2D array of 256x256. Support for 16-bit indexing will be added in the future.
This disk hold routines related to standard mathematical calculations for signed and unsigned integer math as well as macros that use Applesoft's floating-point routines. Note that this only includes some rather basic math functions; more complicated problems should be addressed by the main program using the libraries.
This disk holds routines and macros related to string and substring manipulation. In the future, certain tasks like "TONUM" and "TOSTR" may be relegated to their own disk for data type conversion routines.
The following disks are in pre-production/planning, and will be part of future versions of the library. I am currently focusing on the six core disks to make sure everything works seamlessly and functions the same across different subroutine calls, which is taking time to sort out. Once production of each of these disks begins, I'll be moving them from this section to the actual disks section.
* ~~`LGET`: Get color of low-resolution screen at x,y.~~
* ~~`LPUT`: plot a low resolution block at x,y on the screen.~~
* ~~`LCHAR`: plot a text character on the low resolution screen at x,y.~~
* ~~`LPRN`: plot a string of characters on the low resolution screen at x,y.~~
* ~~`LINV`: Invert colors on the low resolution screen.~~
~~Disk 9: Sound~~
* ~~sound.mac: Music and sound effects library for the internal speaker (not add-on cards like Mockingboard). Note that this is not really for "real-time" music generation while doing something else, as that would involve counting the cycles in loops that a library would not necessarily have access to. In the future, I may try to create a library that does this, but it would still be pretty limited and the main execution would have to follow a very rigid format. I may also create a library that takes advantage of the Mockingboard.~~
* ~~`STONE`: Play a tone at the specified megahertz for a specified duration of milliseconds.~~
* ~~`SNOTE`: Play a specified musical note at the specified octave for a specified duration in milliseconds.~~
* ~~`SWAIT`: See the `DELAY` Macro, as this is simply a slightly modified version for music timing.~~
* ~~`SDRUM`: Send a sharp sound to the speaker that emulates the nois of a bass drum.~~
* ~~`SHATC`: Send a short click that emulates a closed hi hat.~~
* ~~`SHATO`: Send a long bout of noise to emulate an open hi hat.~~
* ~~`SSTAT`: Send static to the speaker for a specified number of milliseconds.~~
* ~~`SARPG`: Send a series of Arpeggio notes to the speaker to emulate multiple notes at once or chords.~~
* ~~`SASC`: Play a series of tones between a low and high mhz, ascending at a given rate.~~
* ~~`SDESC`: Play a series of tones between a high and low mhz, descending at a given rate.~~
* ~~`SENV`: Rudimentary envelope for notes achieved by manipulating octave frequencies.~~
* ~~`SQKEY`: Set the keypress to signal the library to halt playing a note.~~
* ~~`SPLOD`: a sound effect resembling an explosion sound. Customizeable via parameters.~~
* ~~`SPLAY`: play a sequence of given notes found at a given memory address. Follows same sequence as `SNOTE` parameters, ending with #00.~~
* ~~`SALRM`: play an alarm sound.~~
* ~~`SLAZE`: play a lazer sound at a specific frequency.~~
* ~~stdio80.mac: stdio library for 80-column output. Most of these will be identical to the routines on the stdio disk.~~
* ~~`80CB`: Move Cursor Backward by [n] spaces~~
* ~~`80CD`: Move Cursor Down by [n] spaces~~
* ~~`80CF`: Move Cursor Forward by [n] spaces~~
* ~~`80CU`: Move Cursor Up by [n] spaces~~
* ~~`80INP`: String Input Macro~~
* ~~`80PBX`: Read State of Paddle Button [x]~~
* ~~`80PCR`: Print Carraige Return~~
* ~~`80PDL`: Read Current Paddle State~~
* ~~`80PRN`: Flexible (screen) Printing routine~~
* ~~`80RCP`: Read Cursor Position~~
* ~~`80SCP`: Set Cursor position at [x],[y]~~
* ~~`80SCX`: Set Cursor Horizontal Position~~
* ~~`80SCY`: Set Cursor Vertical Position~~
* ~~`80TFIL`: Text Fill square [x1],[x2],[y1],[y2] with Character [n]~~
* ~~`80THLN`: Text Horizontal Line Fill with Character [n]~~
* ~~`80TVLN`: Text Vertical Line Fill with Character [n]~~
* ~~80to40.mac: a simple set of macros that calls the 80-column macros when 40-column macros are invoked. Obviously, the 40-column stdio.mac cannot be used simultaneously.~~
~~Disk 11: HiRes~~
* ~~hires.mac: Library for fast(er) graphics in high resolution mode.~~
* ~~`HHLIN`: High resolution horizontal line.~~
* ~~`HVLIN`: High resolution vertical line.~~
* ~~`HLINE`: High resolution line from x1,y1 to x2,y2.~~
* ~~`HCIRC`: High resolution circle at position x,y with a radius of r.~~
* ~~`HSQR`: High resolution square at position x,y with a width of w.~~
* ~~`HBLIT`: High resolution sprite blitting macro.~~
* ~~`HCOLR`: Change High resolution color.~~
* ~~`HGET`: Get color of high-resolution screen at x,y.~~
* ~~`HPUT`: plot a high resolution block at x,y on the screen.~~
* ~~`HCHAR`: plot a text character on the high resolution screen at x,y.~~
* ~~`HPRN`: plot a string of characters on the high resolution screen at x,y.~~
~~Disk 12: DblLoRes~~
* ~~dlres.mac: library for double low resolution graphics. Only available on IIe (with 80col card), //c, and IIgs.~~
The following table shows which subroutines each Macro calls, along with the resulting registers, flags, and memory locations clobbered. This is up to date for version 0.3.0. Note that by "clobbered" here, I don't mean that the register or memory location has trash in it; it's just been altered in some way. For list of what useful imformation is passed after a Macro is executed, see [the cheat sheet](#macro-usage-cheat-sheet).
Once Macros are mostly finished in how they are called, you can find how to use them here. New versions, of course, always run the risk of changing something integral; This cheat sheet will be updated accordingly.