diff --git a/AGENTS.md b/AGENTS.md index 85825c44..91c3e3f7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -31,7 +31,7 @@ cd frontend/a2wasm go build . # Build console frontend -cd frontend/a2console +cd frontend/console go build . # Build the libretro core, needs a C toolchain @@ -220,7 +220,9 @@ The project uses GitHub Actions (`.github/workflows/go.yml`) and CircleCI (`.cir ## Additional Resources -- See `README.md` for user documentation and features +- See `README.md` for user documentation +- See `doc/features.md` for the complete feature list and the default configuration - See `doc/command_line.md` for command-line options +- See `doc/frontend_*.md` for a page per frontend: how to build it, how to use it and what it does not do - See `storage/WozSupportStatus.md` for WOZ format support details - Reference implementation uses iz6502 CPU emulator: https://github.com/ivanizag/iz6502 diff --git a/README.md b/README.md index 83f9100d..85ee973b 100644 --- a/README.md +++ b/README.md @@ -4,111 +4,12 @@ Portable emulator of an Apple II+ or //e. Written in Go. ## Features -- Models: - - Apple ][+ with 48Kb of base RAM - - Apple //e with 128Kb of RAM - - Apple //e enhanced with 128Kb of RAM - - Base64A clone with 48Kb of base RAM and paged ROM - - Basis 108 clone (partial) -- Storage - - 16 Sector 5 1/4 diskettes. Uncompressed or compressed witth gzip or zip. Supported formats: - - NIB (read only) - - DSK - - PO - - [WOZ 1.0 or 2.0](storage/WozSupportStatus.md) (read only) - - 13 Sector 5 1/4 diskettes. Uncompressed or compressed witth gzip or zip. Supported formats: - - NIB (read only) - - [WOZ 2.0](storage/WozSupportStatus.md) (read only) - - 3.5 disks in PO or 2MG format - - Hard disk in HDV or 2MG format with ProDOS and SmartPort support - - Cassette tape input from WAV recordings -- Emulated extension cards: - - DiskII controller (state machine based for WOZ files) - - 16Kb Language Card - - 256Kb Saturn RAM - - Parallel Printer Interface card - - 1Mb Memory Expansion Card (slinky) - - RAMWorks style expansion Card (up to 16MB additional) (Apple //e only) - - ThunderClock Plus real time clock - - Apple //e 80 columns card with 64Kb extra RAM and optional RGB modes - - No Slot Clock based on the DS1216 - - Videx Videoterm 80 column card with the Videx Soft Video Switch (Apple ][+ only) - - Videx Ultraterm 80 to 160 column card wuth integrated Video Switch - - SwyftCard (Apple //e only) - - Brain Board - - Brain Board II - - MultiROM card - - Dan ][ Controller card - - ProDOS ROM card - - Microsoft Z80 Softcard using the [Z80](https://github.com/koron-go/z80) emulation from Koron - - Mockinboard A sound card -- Useful cards not emulating a real card - - Bootable SmartPort / ProDOS card with the following smartport devices: - - Block device (hard disks) - - Fujinet network device (supports only http(s) with GET and JSON) - - Fujinet clock (not in Fujinet upstream) - - VidHd, limited to the ROM signature and SHR as used by Total Replay, only for //e models with 128Kb - - FASTChip, limited to what Total Replay needs to set and clear fast mode - - Mouse Card, emulates the entry points, not the softswitches. - - Host console card. Maps the host STDIN and STDOUT to PR# and IN# - - ROMXe, limited to font switching +izapple2 emulates the Apple ][+ and the Apple //e, enhanced or not, and the Base64A and Basis 108 clones. +See [doc/features.md](doc/features.md) for the complete list of features and supported cards and graphic modes. -- Graphic modes: - - Text 40 columns - - Text 80 columns Apple //e - - Text 80 columns Videx VideoTerm - - Text up to 160 columns and 48 lines Videx UltraTerm - - Low-Resolution graphics - - Double-Width Low-Resolution graphics (Apple //e only) - - High-Resolution graphics - - Double-Width High-Resolution graphics (Apple //e only) - - Super High Resolution (VidHD only) - - Mixed mode - - RGB card text 40 columns with 16 colors for foreground and background (mixable) - - RGB card mode 11, mono 560x192 - - RGB card mode 12, ntsc 160*192 - - RGB card mode 13, ntsc 140*192 (regular DHGR) - - RGB card mode 14, mix of modes 11 and 13 on the fly -- Displays: - - Green monochrome monitor with half width pixel support - - NTSC Color TV (extracting the phase from the mono signal) - - RGB for Super High Resolution and RGB card - - ANSI Console, avoiding the SDL2 dependency - - Debug mode: shows four panels with actual screen, page1, page2 and extra info dependant of the video mode -- Tracing capabilities: - - CPU execution disassembled - - Softswitch reads and writes - - ProDOS MLI calls - - Apple Pascal BIOS calls - - SmartPort commands - - BBC MOS calls when using [Applecorn](https://github.com/bobbimanners/) -- Other features: - - Sound - - Joystick support. Up to two joysticks or four paddles - - Mouse support. No mouse capture needed - - Adjustable speed - - Fast disk mode to set max speed while using the disks - - Save directory with `-saveDir`: what the software writes goes to an overlay file per disk, keeping the images untouched and making writable the disks loaded from a compressed file, an URL or the embedded resources - - Single file executable with embedded ROMs and DOS 3.3 - - Pause (thanks a2geek) - - Passes the [A2AUDIT 1.06](https://github.com/zellyn/a2audit) tests as II+, //e, and //e Enhanced. - - Partial pass ot the [ProcessorTests](https://github.com/TomHarte/ProcessorTests) for 6502 and 65c02. Failing test 6502/v1/20_55_13; flags N anv V issues with ADC; and missing some undocumented 6502 opcodes. +## Installation -By default the following configuration is launched: - -- Enhanced Apple //e with 65c02 processor -- RAMWorks card with 80 column, RGB (with Video7 modes) and 8Gb RAM in aux slot -- Parallel print inteface in slot 1 -- VidHD card (SHR support) in slot 2 -- FASTChip Accelerator card in slot 3 -- Mouse card in slot 4 -- SmartPort card with 1 device in slot 5 (if an image is provided with -disk35) -- DiskII controller card in slot 6 -- SmartPort card with 1 device in slot 7 (if an image is provided with -hd) - -## Running the emulator - -No installation required. [Download](https://github.com/ivanizag/izapple2/releases) the single file executable `izapple2xxx_xxx` for linux or Mac, SDL2 graphics or console. Build from source to get the latest features. +No installation required. [Download](https://github.com/ivanizag/izapple2/releases) the single file executable `izapple2` for Linux, Windows or Mac. It is the SDL2 frontend, see [Frontends](#frontends) for the others. Build from source to get the latest features. Optionally, it can be installed with homebrew using: @@ -116,17 +17,17 @@ Optionally, it can be installed with homebrew using: brew install ivanizag/izapple2/izapple2 ``` -### Default mode +## Default mode -Execute without parameters to have an emulated Apple //e Enhanced with 128kb booting DOS 3.3 ready to run Applesoft: +Execute without parameters to have an emulated Apple //e Enhanced with 128kb booting DOS 3.3 ready to run Applesoft. The cards it comes with are in [the default configuration](doc/features.md#the-default-configuration): ``` terminal -casa@servidor:~$ ./izapple2sdl +casa@servidor:~$ ./izapple2 ``` ![DOS 3.3 started](doc/dos33.png) -### Play games +## Play games Download a DSK or WOZ file or use an URL ([Asimov](https://www.apple.asimov.net/images/) is an excellent source): @@ -136,7 +37,7 @@ casa@servidor:~$ ./izapple2 "https://www.apple.asimov.net/images/games/action/ka ![Karateka](doc/karateka.png) -### Play the Total Replay collection +## Play the Total Replay collection Download the excellent [Total Replay](https://archive.org/details/TotalReplay) compilation by [a2-4am](https://github.com/a2-4am/4cade): @@ -149,60 +50,33 @@ Displays super hi-res box art as seen with the VidHD card. ![Total Replay](doc/totalreplay.png) -### Terminal mode - -To run text mode right on the terminal without the SDL2 dependency, use `izapple2console`. It runs on the console using ANSI escape codes. Input is sent to the emulated Apple II one line at a time: - -``` terminal -casa@servidor:~$ ./izapple2console -model 2plus - -############################################ -# # -# APPLE II # -# # -# DOS VERSION 3.3 SYSTEM MASTER # -# # -# # -# JANUARY 1, 1983 # -# # -# # -# COPYRIGHT APPLE COMPUTER,INC. 1980,1982 # -# # -# # -# ]10 PRINT "HELLO WORLD" # -# # -# ]LIST # -# # -# 10 PRINT "HELLO WORLD" # -# # -# ]RUN # -# HELLO WORLD # -# # -# ]_ # -# # -# # -############################################ -Line: - -``` - -### RetroArch and other libretro frontends - -izapple2 can also be built as a libretro core, to run inside RetroArch, Lakka, -Batocera, RetroPie and the rest. On a Mac, -[doc/libretro_macos.md](doc/libretro_macos.md) walks through the whole thing -from installing RetroArch. See [doc/libretro.md](doc/libretro.md) for how -to build it, install it and what it supports. - -### Command line options +## Command line options See [doc/command_line.md](doc/command_line.md) for a complete guide on command line configuration. +## Frontends + +The emulator itself is a Go library. What you run is one of the frontends in the `frontend` directory: they all build the same machine, take the same [command line options](doc/command_line.md) and load the same disks, but they differ in what they can show and in how you talk to them. + +Each one has a page with how to build it, how to use it and what it can not do: + +- [**a2sdl**](doc/frontend_sdl2.md): a window with SDL2. The complete one, and the one in the [releases](https://github.com/ivanizag/izapple2/releases) and in the Homebrew formula. Use this one unless you have a reason not to. +- [**a2sdl3**](doc/frontend_sdl3.md): the same, on SDL3. It needs neither cgo, nor a C compiler, nor SDL developer files, and it cross compiles to every platform from any of them. Experimental, not in the releases. +- [**console**](doc/frontend_console.md): text mode right on the terminal with ANSI escape codes, without the SDL2 dependency. Input goes in a line at a time. +- [**a2libretro**](doc/frontend_libretro.md): a libretro core, to run inside RetroArch, Lakka, Batocera, RetroPie and the rest. On a Mac, [doc/frontend_libretro_macos.md](doc/frontend_libretro_macos.md) walks through the whole thing from installing RetroArch. +- [**a2ebiten**](doc/frontend_ebiten.md): a window with [Ebitengine](https://ebitengine.org/). The same keys as a2sdl, no disks to drop and no joysticks. It is the desktop half of the WebAssembly frontend. +- [**a2wasm**](doc/frontend_wasm.md): the emulator in the browser, compiled to WebAssembly with a React interface around it. +- [**a2fyne**](doc/frontend_fyne.md): a window with [Fyne](https://fyne.io/), a toolbar and a panel listing the cards in the slots. No sound. Unfinished. +- [**headless**](doc/frontend_headless.md): no window and no screen, a command prompt to drive the machine and take snapshots. For scripting and for tests. + +Additionally there is a derived project, [izapplebasic](https://github.com/ivanizag/izapplebasic), that adds a couple of frontends to a simplified Apple ][+ emulator with no cards and tape drive: + +- CLI: with getline like support and command history. +- Telegram: Interactive use. Currently running at + ## Building from source -### Linux - -Besides having a working Go installation, install the SDL2 developer files. Run: +Every frontend is a Go main package in its own directory. With a working Go installation, the build is always: ``` terminal git clone github.com/ivanizag/izapple2 @@ -210,44 +84,7 @@ cd izapple2/frontend/a2sdl go build . ``` -### MacOS +That builds `a2sdl`, the SDL2 frontend, which needs a C compiler and the SDL2 developer files: `libsdl2-dev` on Linux, `brew install SDL2` on MacOS, [mingw-w64](http://mingw-w64.org/doku.php/download/mingw-builds) and the [SDL2 developer files](https://www.libsdl.org/release/) on Windows. See [doc/frontend_sdl2.md](doc/frontend_sdl2.md) for the details. -With a working Go installation, run: - -``` terminal -brew install SDL2 -git clone github.com/ivanizag/izapple2 -cd izapple2/frontend/a2sdl -go build . -``` - -### Windows - -On Windows, CGO needs a gcc compiler. Install [mingw-w64](http://mingw-w64.org/doku.php/download/mingw-builds) and the [SDL2 developer files](https://www.libsdl.org/release/) for mingw-64. - -Run: - -``` terminal -git clone github.com/ivanizag/izapple2 -cd izapple2\frontend\a2sdl -go build . -``` - -To run in Windows, copy the file `SDL2.dll` on the same folder as `a2sdl.exe`. The latest `SDL2.dll` can be found in the [Runtime binary for Windows 64-bit](https://www.libsdl.org/download-2.0.php). - -### The experimental SDL3 frontend - -The `a2sdl3` frontend uses SDL3 through [go-sdl3](https://github.com/Zyko0/go-sdl3), which needs neither cgo nor a C compiler nor any SDL developer files. On Linux, MacOS and Windows alike, run: - -``` terminal -git clone github.com/ivanizag/izapple2 -cd izapple2/frontend/a2sdl3 -go build . -``` - -As there is no cgo involved, it also cross compiles to any of the supported platforms, for example: - -``` terminal -CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build . -``` +The other frontends replace `a2sdl` with their own directory and need other things, or nothing at all. Each page in [Frontends](#frontends) has its own instructions. diff --git a/doc/command_line.md b/doc/command_line.md index ed8fc199..dc26320b 100644 --- a/doc/command_line.md +++ b/doc/command_line.md @@ -23,7 +23,7 @@ The emulator can be started with various command line options to customize the h ## Models -Models are pre-configured hardware setups that define the Apple II variant to emulate. Each model specifies the board type, CPU, ROM, default cards, and other hardware characteristics. It also load a default set of diskettes. +Models are pre-configured hardware setups that define the Apple II variant to emulate. Each model specifies the board type, CPU, ROM, default cards, and other hardware characteristics. It also loads a default set of diskettes. ### Available Models @@ -111,7 +111,7 @@ The default model (`2enh`) configures slots as follows: - **Slot 1:** Empty - **Slot 2:** VidHD - **Slot 3:** FastChip -- **Slot 4:** Empty +- **Slot 4:** Mockingboard - **Slot 5:** Empty - **Slot 6:** Disk II with DOS 3.3 - **Slot 7:** Empty @@ -435,7 +435,7 @@ izapple2 boot.dsk -s7 smartport,image1="harddisk.po" 1. **Flags must come before positional arguments** in the command line 2. **Use quotes** around filenames with spaces: `-s6 "my disk.dsk"` -3. **Boolean flags** use `true`, `false` or nothing: `-showConfig=true` is the same as `-showConfig` +3. **Boolean flags** use `true`, `false` or nothing: `-showConfig=true` is the same as `-showConfig` 4. **View all options** with `izapple2 -h` 5. **Test configurations** with `-showConfig` to see the final setup without starting the emulator diff --git a/doc/cpm65.md b/doc/cpm65.md index 8c5f8acc..79d99244 100644 --- a/doc/cpm65.md +++ b/doc/cpm65.md @@ -5,12 +5,13 @@ CPM-65 is a native port of Digital Research's seminal 1977 operating system CP/M It runs on an Apple IIe with 80 columns. To run use the preconfigured model `cpm65`. -Usefull commands: +Useful commands: -- `ìzapple -model cpm65` : To run the preconfigured setup -- `izapple apple2e.po`: To use the disk apple2e.po to run any release from [cpm65 releases](https://github.com/davidgiven/cpm65/releases/tag/dev) -- `ìzapple -model cpm65 -trace cpm65` : To trace the BDOS calls, skipping the console related calls -- `ìzapple -model cpm65 -trace cpm65full` : To trace all the BDOS calls. +- `izapple2 -model cpm65` : To run the preconfigured setup +- `izapple2 apple2e.po`: To use the disk apple2e.po to run any release from [cpm65 releases](https://github.com/davidgiven/cpm65/releases/tag/dev) +- `izapple2 -model cpm65 -trace cpm65` : To trace the BDOS calls, skipping the console related calls +- `izapple2 -model cpm65 -trace cpm65full` : To trace all the BDOS calls. Todo: + - The address for the BIOS and BDOS entrypoints is hardwired. It should be extracted somehow from the running memory. diff --git a/doc/features.md b/doc/features.md new file mode 100644 index 00000000..6de65282 --- /dev/null +++ b/doc/features.md @@ -0,0 +1,117 @@ +# Features + +- Models: + - Apple ][+ with 48Kb of base RAM + - Apple //e with 128Kb of RAM + - Apple //e enhanced with 128Kb of RAM + - Base64A clone with 48Kb of base RAM and paged ROM + - Basis 108 clone (partial) +- Storage + - 16 Sector 5 1/4 diskettes. Uncompressed or compressed with gzip or zip. Supported formats: + - NIB (read only) + - DSK + - PO + - [WOZ 1.0 or 2.0](../storage/WozSupportStatus.md) (read only) + - 13 Sector 5 1/4 diskettes. Uncompressed or compressed with gzip or zip. Supported formats: + - NIB (read only) + - [WOZ 2.0](../storage/WozSupportStatus.md) (read only) + - 3.5 disks in PO or 2MG format + - Hard disk in HDV or 2MG format with ProDOS and SmartPort support + - Cassette tape input from WAV recordings + +- Emulated extension cards: + - DiskII controller (state machine based for WOZ files) + - 16Kb Language Card + - 256Kb Saturn RAM + - Parallel Printer Interface card + - 1Mb Memory Expansion Card (slinky) + - RAMWorks style expansion Card (up to 16MB additional) (Apple //e only) + - ThunderClock Plus real time clock + - Apple //e 80 columns card with 64Kb extra RAM and optional RGB modes + - No Slot Clock based on the DS1216 + - Videx Videoterm 80 column card with the Videx Soft Video Switch (Apple ][+ only) + - Videx Ultraterm 80 to 160 column card with integrated Video Switch + - SwyftCard (Apple //e only) + - Brain Board + - Brain Board II + - MultiROM card + - Dan ][ Controller card + - ProDOS ROM card + - Microsoft Z80 Softcard using the [Z80](https://github.com/koron-go/z80) emulation from Koron + - Mockingboard A sound card +- Useful cards not emulating a real card + - Bootable SmartPort / ProDOS card with the following smartport devices: + - Block device (hard disks) + - Fujinet network device (supports only http(s) with GET and JSON) + - Fujinet clock (not in Fujinet upstream) + - VidHD, limited to the ROM signature and SHR as used by Total Replay, only for //e models with 128Kb + - FASTChip, limited to what Total Replay needs to set and clear fast mode + - Mouse Card, emulates the entry points, not the softswitches. + - Host console card. Maps the host STDIN and STDOUT to PR# and IN# + - ROMXe, limited to font switching + +- Graphic modes: + - Text 40 columns + - Text 80 columns Apple //e + - Text 80 columns Videx VideoTerm + - Text up to 160 columns and 48 lines Videx UltraTerm + - Low-Resolution graphics + - Double-Width Low-Resolution graphics (Apple //e only) + - High-Resolution graphics + - Double-Width High-Resolution graphics (Apple //e only) + - Super High Resolution (VidHD only) + - Mixed mode + - RGB card text 40 columns with 16 colors for foreground and background (mixable) + - RGB card mode 11, mono 560x192 + - RGB card mode 12, ntsc 160*192 + - RGB card mode 13, ntsc 140*192 (regular DHGR) + - RGB card mode 14, mix of modes 11 and 13 on the fly +- Displays: + - Green monochrome monitor with half width pixel support + - NTSC Color TV (extracting the phase from the mono signal) + - RGB for Super High Resolution and RGB card + - ANSI Console, avoiding the SDL2 dependency + - Debug mode: shows four panels with actual screen, page1, page2 and extra info dependent on the video mode +- Tracing capabilities: + - CPU execution disassembled + - Softswitch reads and writes + - ProDOS MLI calls + - Apple Pascal BIOS calls + - SmartPort commands + - BBC MOS calls when using [Applecorn](https://github.com/bobbimanners/) +- Other features: + - Sound + - Joystick support. Up to two joysticks or four paddles + - Mouse support. No mouse capture needed + - Adjustable speed + - Fast disk mode to set max speed while using the disks + - Save directory with `-saveDir`: what the software writes goes to an overlay file per disk, keeping the images untouched and making writable the disks loaded from a compressed file, an URL or the embedded resources + - Single file executable with embedded ROMs and DOS 3.3 + - Pause (thanks a2geek) + - Passes the [A2AUDIT 1.06](https://github.com/zellyn/a2audit) tests as II+, //e, and //e Enhanced. + - Partial pass of the [ProcessorTests](https://github.com/TomHarte/ProcessorTests) for 6502 and 65c02. Failing test 6502/v1/20_55_13; flags N and V issues with ADC; and missing some undocumented 6502 opcodes. + +## The default configuration + +By default the following configuration is launched: + +- Enhanced Apple //e with 65c02 processor +- RAMWorks card with 80 columns and 8Mb of RAM in the aux slot +- No Slot Clock on the main ROM +- Language card in slot 0 +- VidHD card (SHR support) in slot 2 +- FASTChip accelerator card in slot 3 +- Mockingboard sound card in slot 4 +- DiskII controller card with DOS 3.3 in slot 6 + +Slots 1, 5 and 7 are empty, and the RGB modes of the 80 columns card are added +with `-rgb`. Diskettes and hard disks named in the command line take the slots +they need: diskettes go to slot 6 and then slot 5, block devices to a SmartPort +card in slot 7 and then slot 5. + +Run `izapple2 -showConfig` to see the configuration a command line ends up +with, without starting the machine. + +Everything here is chosen with the [command line options](command_line.md), and +what each frontend can do with it is in its own page, listed in the +[README](../README.md#frontends). diff --git a/doc/frontend_console.md b/doc/frontend_console.md new file mode 100644 index 00000000..77e983cc --- /dev/null +++ b/doc/frontend_console.md @@ -0,0 +1,71 @@ +# The console frontend + +`console` runs the emulator on the terminal. There is no window and no SDL2 +dependency: the text screen of the Apple II is drawn in place with ANSI escape +codes, and what you type is sent to the machine a line at a time. + +It is the frontend for a machine without a graphical session, or for a quick +run over ssh. Only the 40 column text screen exists here: there are no +graphics, no sound and no joysticks. + +## Building + +Nothing to install besides Go: + +``` terminal +git clone github.com/ivanizag/izapple2 +cd izapple2/frontend/console +go build . +``` + +## Running + +The trick of redrawing the screen in place does not work with the Apple //e +ROM, so use one of the Apple ][ models: + +``` terminal +casa@servidor:~$ ./console -model 2plus + +############################################ +# # +# APPLE II # +# # +# DOS VERSION 3.3 SYSTEM MASTER # +# # +# # +# JANUARY 1, 1983 # +# # +# # +# COPYRIGHT APPLE COMPUTER,INC. 1980,1982 # +# # +# # +# ]10 PRINT "HELLO WORLD" # +# # +# ]LIST # +# # +# 10 PRINT "HELLO WORLD" # +# # +# ]RUN # +# HELLO WORLD # +# # +# ]_ # +# # +# # +############################################ +Line: + +``` + +The rest of the [command line options](command_line.md) work as everywhere +else, so the diskettes, the cards and the tracing are the same. + +Ctrl-C quits. + +## Typing + +The `Line:` at the bottom is the terminal reading a line. Nothing reaches the +Apple II until you press Enter, and then the whole line goes in at once. That +is fine for Applesoft and for the monitor, and it is no good for anything that +reads the keyboard while it runs, like a game or a full screen editor. + +The screen is redrawn ten times a second, and only when something changed. diff --git a/doc/frontend_ebiten.md b/doc/frontend_ebiten.md new file mode 100644 index 00000000..43f29544 --- /dev/null +++ b/doc/frontend_ebiten.md @@ -0,0 +1,53 @@ +# The Ebitengine frontend + +`a2ebiten` opens a window with [Ebitengine](https://ebitengine.org/). It has +the screen with all its modes, the sound and the same function keys as +[a2sdl](frontend_sdl2.md), and it is missing the things around them: no +diskettes dropped on the window, no joysticks and no mouse. + +## Building + +Ebitengine needs no SDL, and on Linux and MacOS it needs a C compiler and the +graphics developer files. See +[the Ebitengine install page](https://ebitengine.org/en/documents/install.html) +for the list of packages of your distribution. On Windows it needs nothing. + +``` terminal +git clone github.com/ivanizag/izapple2 +cd izapple2/frontend/a2ebiten +go build . +``` + +## Running + +``` terminal +casa@servidor:~$ ./a2ebiten +``` + +The [command line options](command_line.md) are the same as everywhere else, +and the diskettes have to go in the command line: this frontend has no way to +insert one afterwards. Press F1 for the help. + +## Keys + +The same as [a2sdl](frontend_sdl2.md#keys), with two differences: + +- Ctrl-F5 shows a readout with the speed of the emulated machine and the frame + rate on the corner of the screen, instead of printing the speed on the + terminal. +- There is no paste from the clipboard. + +The help screen that F1 shows is the one of a2sdl and mentions dropping a file +on the window. That does not work here. + +## What is missing + +- **Diskettes dropped on the window.** They go in the command line. +- **Joysticks and paddles**, and the mouse as a joystick. +- **The mouse**, so the models that use it, like `desktop`, are not much use. +- **Pasting** from the clipboard. + +The window is 564x384 and can be resized. The picture is generated at a fixed +1128x768 and scaled to the window, so the modes wider than 560 pixels, like the +Videx cards or the RGB card, are squeezed to fit instead of widening the +window. diff --git a/doc/frontend_fyne.md b/doc/frontend_fyne.md new file mode 100644 index 00000000..db9895b3 --- /dev/null +++ b/doc/frontend_fyne.md @@ -0,0 +1,89 @@ +# The Fyne frontend + +`a2fyne` opens a window with [Fyne](https://fyne.io/). Unlike the other +frontends with a window, it has a proper interface around the screen: a toolbar +with the controls, and a side panel listing the cards in the slots with what +each of them is doing. + +It is missing the latest features. Not much more is done there. + +## Building + +Fyne needs a C compiler and the graphics developer files of the platform. See +[the Fyne prerequisites](https://docs.fyne.io/started/) for the list of +packages of your distribution. + +``` terminal +git clone github.com/ivanizag/izapple2 +cd izapple2/frontend/a2fyne +go build . +``` + +## Running + +``` terminal +casa@servidor:~$ ./a2fyne +``` + +The [command line options](command_line.md) are the same as everywhere else, +and the diskettes have to go in the command line: there is no way to insert one +afterwards. + +## The toolbar + +From left to right: + +- Reset. +- Pause and unpause. +- Full speed or normal speed. +- The screen mode: NTSC colour, plain or green, the current one shown greyed + out. +- Show or hide the four panels with the actual screen, page 1, page 2 and the + extra info of the video mode. +- Save the screen as `snapshot.png`. It says so with a notification of the + desktop. +- Force the keyboard to uppercase, for the software that expects a machine + without lowercase. The title goes uppercase while it is on. +- Full screen. +- Show or hide the panel with the devices. + +## The devices panel + +On the right, and hidden until the toolbar asks for it. It has the state of the +joysticks and then a card per slot, with the name of the card and whatever it +reports about itself: the diskette in each drive of a Disk II, the tracks it is +on, and so on for the rest. + +## Keys + +Fewer than in the other frontends, and not the same ones: + +| Key | What it does | +| --- | --- | +| Ctrl-F1 | Reset | +| F5 | Print the current speed on the terminal | +| F6 | Next screen mode | +| F7 | Show or hide the four panels | +| F9 | Dump the state of the machine on the terminal | +| F10 | Next character set | +| F11 | Show or hide the CPU trace on the terminal | +| F12 | Save the screen as `snapshot.png` | + +Ctrl and a letter reach the machine as the control character. The arrows, +Return, Escape, Backspace and Delete are mapped as usual. On the Base64A, F2 is +the Delete key of that keyboard. + +There is no Pause key and no PrintScreen, use the toolbar. The Tab key never +arrives. + +## What is missing + +- **Sound.** Nothing is connected to the speaker here. +- **The mouse**, so the models that use it, like `desktop`, are not much use. +- **Diskettes dropped on the window**, and the toolbar button to insert one is + written but not enabled. +- **The character map** and the alternate text, which the other frontends show + with F10. +- **A help**, the F1 of the other frontends. + +Joysticks do work, read through GLFW. diff --git a/doc/frontend_headless.md b/doc/frontend_headless.md new file mode 100644 index 00000000..d8509820 --- /dev/null +++ b/doc/frontend_headless.md @@ -0,0 +1,72 @@ +# The headless frontend + +`headless` has no window and no screen. It builds the machine, leaves it +paused and gives you a prompt to drive it: run so many cycles, type something, +print the text screen, save a snapshot. It is the frontend for a script, for a +test, or for looking at what a machine does without watching it happen. + +## Building + +Nothing to install besides Go: + +``` terminal +git clone github.com/ivanizag/izapple2 +cd izapple2/frontend/headless +go build . +``` + +## Running + +``` terminal +casa@servidor:~$ ./headless +* run 40000 +* text +* type 10 PRINT "HELLO WORLD" +* enter +* run 100 +* text +* quit +``` + +The machine is built with the [command line options](command_line.md) like +everywhere else, and starts paused. Nothing happens until you say `start` or +`run`. + +## Commands + +| Command | What it does | +| --- | --- | +| `help` | Prints the list of commands | +| `quit` | Quits | +| `start` | Runs the machine at its normal speed, and returns to the prompt while it runs | +| `pause` | Stops it | +| `run ` | Runs `` thousand cycles at full speed and waits until they are done. Only while paused | +| `cycle` | Prints the cycle count | +| `reset` | Resets the machine | +| `key ` | Queues a key, as a decimal number from 0 to 127 | +| `type ` | Queues the characters of ``. No quotes, it can have spaces | +| `enter` | Queues the Return key. The same as `key 13` | +| `clearkeys` | Empties the key queue | +| `text` | Prints the text screen on the terminal | +| `png` | Saves the screen as `snapshot.png` in NTSC colour | +| `pngm` | The same in monochrome | +| `gif` | Records one second of the screen to `snapshot.gif`, 20 frames of 5 hundredths | + +The keys are queued, not typed: they are handed to the machine as it asks for +them, so a `type` before a `run` is a fine way to feed a program that is not +running yet. + +`run` is the useful one for a script. It asks for full speed, sets a breakpoint +that many cycles ahead and waits, so a DOS 3.3 boot is over in a moment and the +prompt comes back exactly when it is done. A boot from a diskette spends some +37 million cycles, mostly waiting for the drive, so `run 40000` covers it. + +The `help` the program prints is ahead of what it does in a few places: there +is no `stop` (it is `pause`) and no `gifm`, and `png`, `pngm` and `gif` take no +arguments, they always write `snapshot.png` and `snapshot.gif`. + +## What is missing + +There is nothing to insert a diskette while it runs, and nothing to move the +joysticks or press their buttons. Both have to come from the command line, or +not at all. diff --git a/doc/libretro.md b/doc/frontend_libretro.md similarity index 97% rename from doc/libretro.md rename to doc/frontend_libretro.md index 705ad3b2..5bd33cf0 100644 --- a/doc/libretro.md +++ b/doc/frontend_libretro.md @@ -9,10 +9,10 @@ The core is not part of the [releases](https://github.com/ivanizag/izapple2/rele you have to build it from source. It is a small build, the instructions are below. If you just want to run Apple II software on your computer, the regular -`izapple2sdl` executable is easier and does more. Use the core if you already +`izapple2` executable is easier and does more. Use the core if you already live in RetroArch. -On a Mac, [libretro_macos.md](libretro_macos.md) is the whole thing end to end, +On a Mac, [frontend_libretro_macos.md](frontend_libretro_macos.md) is the whole thing end to end, from installing RetroArch to checking that it works. Follow that instead, there are two traps on macOS that it walks you around. @@ -46,7 +46,7 @@ A frontend can only load a core of its own architecture, and the frontend has to be running natively: a Go core cannot run inside a frontend translated by Rosetta, whichever slice it loads. On macOS that rules out the `retroarch` cask of Homebrew, which is an Intel build. See -[libretro_macos.md](libretro_macos.md). +[frontend_libretro_macos.md](frontend_libretro_macos.md). ### Windows @@ -289,7 +289,7 @@ centered. ## What is not supported The core is deliberately smaller than the other frontends. If you need any of -this, use `izapple2sdl`. +this, use `izapple2`. - **Super hi-res graphics.** The VidHD card is removed from the machine, so the box art of the [Total Replay](https://archive.org/details/TotalReplay) @@ -340,7 +340,7 @@ or cross compile with the right `CC`, `GOOS` and `GOARCH`. `runtime.(*mheap).allocNeedsZero`. The frontend is being translated, Rosetta on a Mac, and the Go runtime of the core cannot allocate in a process like that. A core for both architectures does not help, the frontend itself has to run -natively. See [libretro_macos.md](libretro_macos.md). +natively. See [frontend_libretro_macos.md](frontend_libretro_macos.md). **Some keys do nothing, or `p` pauses the emulator.** Those are hotkeys of the frontend, turn on Game Focus, see [Keyboard](#keyboard). diff --git a/doc/libretro_macos.md b/doc/frontend_libretro_macos.md similarity index 98% rename from doc/libretro_macos.md rename to doc/frontend_libretro_macos.md index 2e7b43ed..df7d3533 100644 --- a/doc/libretro_macos.md +++ b/doc/frontend_libretro_macos.md @@ -1,7 +1,7 @@ # Running the libretro core on a Mac From nothing to the core running in RetroArch, with the checks worth doing on -the way. See [libretro.md](libretro.md) for what the core is and what it +the way. See [frontend_libretro.md](frontend_libretro.md) for what the core is and what it supports. ## 1. Install RetroArch diff --git a/doc/frontend_sdl2.md b/doc/frontend_sdl2.md new file mode 100644 index 00000000..ada47770 --- /dev/null +++ b/doc/frontend_sdl2.md @@ -0,0 +1,136 @@ +# The SDL2 frontend + +`a2sdl` is the complete frontend, the one the +[releases](https://github.com/ivanizag/izapple2/releases) and the Homebrew +formula contain. It opens a window with SDL2 and gives you everything the +emulator has: the screen with all its modes, sound, joysticks, the mouse, +diskettes dropped on the window and the whole set of function keys. + +Use this one unless you have a reason not to. The reason is usually SDL2 +itself, which needs a C compiler and its developer files to build: if that is +in the way, [a2sdl3](frontend_sdl3.md) is the same frontend without any of it. + +## Building + +Besides a working Go installation you need a C compiler and the SDL2 developer +files. + +### Linux + +``` terminal +sudo apt-get install libsdl2-dev +git clone github.com/ivanizag/izapple2 +cd izapple2/frontend/a2sdl +go build . +``` + +### MacOS + +``` terminal +brew install SDL2 +git clone github.com/ivanizag/izapple2 +cd izapple2/frontend/a2sdl +go build . +``` + +### Windows + +CGO needs a gcc compiler. Install +[mingw-w64](http://mingw-w64.org/doku.php/download/mingw-builds) and the +[SDL2 developer files](https://www.libsdl.org/release/) for mingw-64, and run: + +``` terminal +git clone github.com/ivanizag/izapple2 +cd izapple2\frontend\a2sdl +go build . +``` + +To run it, copy `SDL2.dll` to the same folder as `a2sdl.exe`. The latest one is +in the [Runtime binary for Windows 64-bit](https://www.libsdl.org/download-2.0.php). + +### A single file executable + +The released binaries are built with SDL2 linked statically, so that they run +on a machine without SDL2 installed: + +``` terminal +go build -tags static -ldflags "-s -w" -o izapple2 . +``` + +That is what the release workflow does, see [release.md](release.md). + +## Running + +``` terminal +casa@servidor:~$ ./a2sdl +``` + +Without arguments you get the default machine, an enhanced Apple //e booting +DOS 3.3. A file on the command line is loaded in the right place by its +extension, and everything else is set with the +[command line options](command_line.md): + +``` terminal +casa@servidor:~$ ./a2sdl "https://www.apple.asimov.net/images/games/action/karateka/karateka (includes intro).dsk" +casa@servidor:~$ ./a2sdl -model 2plus Total\ Replay\ v6.0.1.hdv +``` + +The window is resizable and the picture follows it. Press F1 for the list of +keys without leaving the emulator. + +## Keys + +The Apple II keyboard is where you expect it, with the arrows, Tab, Delete and +Escape mapped to what the Apple II understands. The rest: + +| Key | What it does | +| --- | --- | +| F1 | Show or hide the help | +| Ctrl-F2 | Reset. F2 alone also resets while the help is shown, for the window managers that eat Ctrl-F2 | +| F4 | Show or hide the CPU trace on the terminal | +| F5 | Full speed or normal speed | +| Ctrl-F5 | Print the current speed on the terminal | +| F6 | Next screen mode: NTSC colour, plain, green, with or without scan lines | +| F7 | Show or hide the four panels with the actual screen, page 1, page 2 and the extra info of the video mode | +| F9 | Dump the state of the machine on the terminal | +| F10 | Next character set | +| Ctrl-F10 | Show or hide the character map | +| Shift-F10 | Show or hide the alternate text of the character map | +| F12 or PrintScreen | Save the screen as `snapshot.png` | +| Pause | Pause and unpause the emulation | +| Left alt or option | Open-Apple | +| Right alt or option | Closed-Apple | +| Shift-Insert, Cmd-V | Paste the clipboard, typed in slowly so that the machine keeps up | + +On the Base64A, F3 is the Delete key of that keyboard. + +The title bar says which machine is running and shows `PAUSED!` while it is +paused. With the four panels or the character map on screen it shows what is +being displayed instead. + +## Diskettes + +Drop a file on the window to insert it: on the left half it goes to drive 1, on +the right half to drive 2. It works with everything that goes on the command +line, including compressed images. + +Whatever the emulated software writes goes back to the file it came from. To +keep the images untouched use `-saveDir`, which puts the writes in an overlay +file per disk and makes writable even the disks loaded from an URL, a +compressed file or the embedded resources. + +## Joysticks and mouse + +Joysticks connected to the host are used as the Apple II joysticks, up to two +of them or four paddles. If the machine has no mouse card, the host mouse acts +as a joystick too. + +The mouse card needs no capture: the pointer of the host is the pointer of the +Apple II, wherever it is on the window. + +## Sound + +The speaker and the sound cards, like the Mockingboard, are mixed and sent to +the SDL2 audio device. At full speed the sound gets choppy, which is what +happens when the machine that generates it runs faster than the sound it +generates. diff --git a/doc/frontend_sdl3.md b/doc/frontend_sdl3.md new file mode 100644 index 00000000..6fb351d8 --- /dev/null +++ b/doc/frontend_sdl3.md @@ -0,0 +1,65 @@ +# The SDL3 frontend + +`a2sdl3` is [a2sdl](frontend_sdl2.md) on SDL3. It does the same things, with the +same keys, the same diskettes dropped on the window and the same joysticks. The +difference is in what it takes to build it: it uses SDL3 through +[go-sdl3](https://github.com/Zyko0/go-sdl3), which needs neither cgo, nor a C +compiler, nor SDL developer files. SDL3 itself travels inside the binary, and +is extracted to a temporary directory while the emulator runs. + +It is experimental and it is not in the +[releases](https://github.com/ivanizag/izapple2/releases), which stay on SDL2. + +## Building + +On Linux, MacOS and Windows alike, with nothing installed but Go: + +``` terminal +git clone github.com/ivanizag/izapple2 +cd izapple2/frontend/a2sdl3 +go build . +``` + +As there is no cgo involved it also cross compiles, so a single machine can +build for all of them: + +``` terminal +CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build . +CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build . +``` + +The resulting binary carries the SDL3 library for the target platform, so there +is no DLL to copy next to it. + +## Running + +``` terminal +casa@servidor:~$ ./a2sdl3 +``` + +The same command line as every other frontend, see +[command_line.md](command_line.md). Press F1 for the help. + +## Keys + +The same as [a2sdl](frontend_sdl2.md#keys), including the paste with +Shift-Insert or Cmd-V and the Open-Apple and Closed-Apple on the alt or option +keys. + +The Apple keys are found by scancode instead of by keycode. On the keyboard +layouts where the right alt is AltGr, SDL3 does not report it as an alt key, +and the Closed-Apple would never be pressed if it were looked up by keycode. + +## What is different from SDL2 + +Nothing that you use, and a few things underneath: + +- SDL3 reports where a file was dropped, so the drive it goes to is the one + under the pointer. In SDL2 it is worked out from the last known mouse + position. +- Losing the window focus releases the joystick keys, so an Open-Apple held + while switching windows does not stay pressed. +- Ctrl-C on the terminal quits the same way as closing the window, releasing + everything on the way out. +- The scaling of the picture is a property of the renderer instead of the + global hint SDL2 uses. diff --git a/doc/frontend_wasm.md b/doc/frontend_wasm.md new file mode 100644 index 00000000..c32e2c29 --- /dev/null +++ b/doc/frontend_wasm.md @@ -0,0 +1,97 @@ +# The WebAssembly frontend + +`a2wasm` is the emulator compiled to WebAssembly, running in the browser. The +machine and the screen are the Go code of [a2ebiten](frontend_ebiten.md) built +for `js/wasm`, and around it there is a React interface with the controls and +the disk drives. + +There is nothing to install for whoever opens the page, and there is a fair +amount to build: it is the only frontend that needs Node besides Go. + +## Building + +You need Go and Node 18 or newer. + +``` terminal +git clone github.com/ivanizag/izapple2 +cd izapple2/frontend/a2wasm +npm install +npm run build +``` + +`npm run build` compiles the Go code to WebAssembly, type checks the React +code and puts everything in `dist`, which is a static site that any web server +can serve. To build only the WebAssembly part, run `./build-wasm.sh`: it leaves +`izapple2.wasm`, its gzipped copy and the `wasm_exec.js` of your Go +installation in `public/wasm`. + +The binary is around 26 MB, 7 MB gzipped, so serve it compressed. + +## Running it while working on it + +``` terminal +casa@servidor:~$ npm run dev +``` + +Then open . Vite reloads the page when the React code +changes; a change in the Go code needs `./build-wasm.sh` and a refresh. + +## Serving it + +`dist` is a static site, with two things to get right in the server: + +- `.wasm` files have to be served as `application/wasm`. +- The page asks for `Cross-Origin-Embedder-Policy: require-corp` and + `Cross-Origin-Opener-Policy: same-origin`, which Vite sets by itself while + developing. + +## Using it + +The machine boots by itself when the page loads. The toolbar on top has pause +and resume, reset, a screenshot that downloads a PNG, and the screen mode: NTSC +colour, plain or green. The bar at the bottom shows the speed in MHz. + +The keyboard goes to the emulator once you click on the screen. There are no +joysticks and no mouse. + +To insert a diskette, use the file picker of a drive or drop the file on the +disk panel: the first one goes to drive 1 and the second to drive 2. There is +also a button to load DOS 3.3 from the resources embedded in the binary. The +formats are the same as in the other frontends, compressed ones included. + +## Driving it from JavaScript + +The Go code exports `window.wasmAPI`, which is what the React interface uses +and is there for whatever else you want to do with it: + +``` javascript +wasmAPI.reset() +wasmAPI.pause() +wasmAPI.resume() +wasmAPI.isPaused() +wasmAPI.getFrequency() +wasmAPI.setScreenMode("ntsc") // "ntsc", "plain" or "green" +wasmAPI.screenshot() +wasmAPI.sendKey(13) +wasmAPI.sendText("10 PRINT \"HELLO\"\n") +wasmAPI.loadDisk(1, bytes, "game.dsk") +wasmAPI.loadDiskFromURL(1, "https://example.com/game.dsk") +wasmAPI.loadDiskFromURL(1, "/dos33.dsk") +``` + +An URL is fetched by the browser, so it has to allow it with CORS. + +## What is missing + +- **Command line options.** The machine is the default one and there is no way + to choose a model or to configure the slots yet. +- **Joysticks and mouse.** +- **Sound in some browsers** until you click on the page: they do not start + audio before the visitor asks for something. +- **State that survives a refresh.** Reloading the page starts a new machine. +- **`getDiskInfo`**, which is in the API and always answers null, so the drives + do not show what is in them. + +The notes on how it is put together, the file layout and the deployment +recipes are in +[frontend/a2wasm/README.md](../frontend/a2wasm/README.md). diff --git a/frontend/a2libretro/README.md b/frontend/a2libretro/README.md index 2b19bf96..47ae2449 100644 --- a/frontend/a2libretro/README.md +++ b/frontend/a2libretro/README.md @@ -3,8 +3,8 @@ A [libretro](https://www.libretro.com/) core, to run izapple2 inside RetroArch and the other libretro frontends. -**If you want to use the core, read [doc/libretro.md](../../doc/libretro.md)**, -or [doc/libretro_macos.md](../../doc/libretro_macos.md) on a Mac, +**If you want to use the core, read [doc/frontend_libretro.md](../../doc/frontend_libretro.md)**, +or [doc/frontend_libretro_macos.md](../../doc/frontend_libretro_macos.md) on a Mac, which covers building it for each platform, installing it in the frontends, loading disks, the controls and what it supports. What follows are the notes on how it is put together.