From 0b44399c0aa4dec487bb221a17a2a127ab83759d Mon Sep 17 00:00:00 2001 From: Tim Allen Date: Fri, 16 Nov 2018 16:09:30 +1100 Subject: [PATCH] docs: Review and update docs for v107. Changes include: - The "Library" menu was replaced with the "Systems" menu - The "Settings" menu was reorganised - Game Boy rumble is now under the MBC5 "controller" for the cartridge "port", instead of being presented as a part of the base console - Import instructions now mention that icarus ships with some firmware files, and describe the "Firmware" directory that icarus will use for firmware it needs. - Apparently the correct name is "MSU1", not "MSU-1" - v107 changes the way MSU1 data is stored in game folders - PowerFest '94 import instructions removed, since I can't get it to work with v107 - Links to the official forum have been replaced with links to the unofficial forum archive, since the official forum is shutting down - Links to Mercurial Magic updated to point at qwertymodo's archive, since hex_usr is no longer developing it - Links to nSide updated, since hex_usr no longer uses GitHub. - Windows build instructions now describe a compiler that is actually maintained, instead of stale TDM64-GCC. - Linux build instructions now mention higan requires SDL 2.0. - minor wording changes, typos, broken links fixed, etc. --- CONTRIBUTING.md | 6 +- README.md | 2 +- README.txt | 7 +- docs/checklinks.sh | 2 +- docs/concepts/game-folders.md | 16 +-- docs/concepts/game-library.md | 4 +- docs/concepts/manifests.md | 4 +- docs/concepts/save-states.md | 2 +- docs/credits.md | 4 +- docs/guides/drivers.md | 4 +- docs/guides/import.md | 168 ++++++++++------------------- docs/guides/shaders.md | 11 +- docs/index.md | 12 +-- docs/install/linux.md | 10 +- docs/install/windows.md | 78 ++++++++------ docs/interface/higan-cli.md | 3 +- docs/interface/higan-settings.md | 178 ++++++++++++++----------------- docs/interface/higan-tools.md | 14 +-- docs/interface/higan.md | 121 +++++++++++++++++---- docs/interface/icarus.md | 2 +- docs/notes.md | 18 ++-- docs/qs.md | 4 +- docs/release.md | 4 +- 23 files changed, 357 insertions(+), 317 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7bc82c06..e86c5478 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,8 +2,8 @@ Contributing to higan ===================== If you would like to propose a change to higan, -you should create an account on the [official forums][f], -go to the "Projects" forum and the "higan" sub-forum, +you should create an account on the [unofficial forums][f], +go to the "Projects" forum, and post your idea in a new topic there. -[f]: https://board.byuu.org/ +[f]: https://helmet.kafuka.org/bboard/ diff --git a/README.md b/README.md index 079a1796..275f37ec 100644 --- a/README.md +++ b/README.md @@ -27,11 +27,11 @@ Official higan resources ------------------------ - [Official homepage](https://byuu.org/emulation/higan/) - - [Official forum](https://board.byuu.org/viewforum.php?f=4) Unofficial higan resources -------------------------- + - [Unofficial forum](https://helmet.kafuka.org/bboard/) - Documentation for [the current stable version][stadocs] - [Source code repository](https://gitlab.com/higan/higan/) diff --git a/README.txt b/README.txt index 006fd6e8..774fbef8 100644 --- a/README.txt +++ b/README.txt @@ -228,10 +228,13 @@ A: Try Settings -> Video -> Exclusive mode, then switch to fullscreen. This Online Resources ---------------- -Official homepage + forum: +Official homepage: https://byuu.org/emulation/higan - https://board.byuu.org/viewforum.php?f=4 + +Unofficial forum: + + https://helmet.kafuka.org/bboard/ Unoffical source code repository + documentation: diff --git a/docs/checklinks.sh b/docs/checklinks.sh index 469a730b..46b4d9a7 100644 --- a/docs/checklinks.sh +++ b/docs/checklinks.sh @@ -8,5 +8,5 @@ checklink \ --summary \ --broken \ --location=http://127.0.0.1:8000/ \ - --exclude 'github.com|board.byuu.org' \ + --exclude 'github.com|board.byuu.org|helmet.kafuka.org' \ http://127.0.0.1:8000/ diff --git a/docs/concepts/game-folders.md b/docs/concepts/game-folders.md index eb4c117d..9406710c 100644 --- a/docs/concepts/game-folders.md +++ b/docs/concepts/game-folders.md @@ -53,7 +53,7 @@ higan can use a larger number of files per game. For example, higan's low-level emulation of Super Famicom co-processors often requires [separate firmware files][firmware]. -higan's [MSU-1 feature][msu1] +higan's [MSU1 feature][msu1] supports up to 99 audio tracks per game, and higan supports up to 133 save-states per game. Thus, @@ -70,7 +70,7 @@ like save-states and the cheat database to be kept separate from the game's actual data, by putting it in a sub-folder. -[msu1]: ../guides/import.md#msu-1-games +[msu1]: ../guides/import.md#msu1-games [firmware]: ../guides/import.md#games-with-co-processor-firmware For a more detailed motivation for game folders, @@ -128,17 +128,21 @@ to all emulators that support them: will create this file. - `*.data.rom`, `*.program.rom`: Files named like this are usually [co-processor firmware][firmware]. - - `msu1.rom`: - Holds streamable data for [the MSU-1][msu1]. + +Files used by higan's [MSU1 extension][msu1] +are in the `msu1` sub-folder: + + - `data.rom`: + Holds data that the MSU1 can stream. - `track-*.pcm`: - Holds streamable audio for [the MSU-1][msu1]. + Holds audio that the MSU1 can stream. Files that are only useful to higan specifically are placed in a `higan` sub-folder: - `cheats.bml`: All information present in - [the Cheat Editor](../interface/higan-tools.md#the-cheat-editor) + the [Cheat Editor](../interface/higan-tools.md#cheat-editor) is stored here. - `notes.txt`: Everything entered in the [Game Notes] is stored here. diff --git a/docs/concepts/game-library.md b/docs/concepts/game-library.md index 3c0e2330..8508bc39 100644 --- a/docs/concepts/game-library.md +++ b/docs/concepts/game-library.md @@ -4,8 +4,8 @@ is the folder where all the When [icarus](../interface/icarus.md) imports a game, it creates or updates the corresponding game folder in the game library. -When you use the console sub-menu items -in [higan's Library menu](../interface/higan.md#the-library-menu), +When you use the items in +[higan's Systems menu](../interface/higan.md#the-systems-menu), higan shows you the games for that console that are already in the library. diff --git a/docs/concepts/manifests.md b/docs/concepts/manifests.md index d12adff3..96958488 100644 --- a/docs/concepts/manifests.md +++ b/docs/concepts/manifests.md @@ -9,7 +9,7 @@ and to the console itself. If you load a game into higan, you can look at the game's manifest by opening [the Tools menu](../interface/higan.md#the-tools-menu) -and choosing [Manifest Viewer](../interface/higan-tools.md#the-manifest-viewer). +and choosing [Manifest Viewer](../interface/higan-tools.md#manifest-viewer). Why manifests? -------------- @@ -17,7 +17,7 @@ Why manifests? For most consoles, a manifest isn't strictly necessary: the raw game data provides enough clues -for emulators to guess the circuit board configuration, +for emulators to guess the correct circuit board configuration, or at least to guess a *reasonable* configuration. However, diff --git a/docs/concepts/save-states.md b/docs/concepts/save-states.md index 34fa956e..06587ac3 100644 --- a/docs/concepts/save-states.md +++ b/docs/concepts/save-states.md @@ -119,7 +119,7 @@ Manager states -------------- higan's -[State Manager](../interface/higan-tools.md#the-state-manager) +[State Manager](../interface/higan-tools.md#state-manager) allows you to create over a hundred save states, and add a helpful description to each one. diff --git a/docs/credits.md b/docs/credits.md index c1edad02..70656ebc 100644 --- a/docs/credits.md +++ b/docs/credits.md @@ -59,5 +59,5 @@ apologies to anyone we've missed! For more information, see the [credits thread]( -https://board.byuu.org/viewtopic.php?f=4&t=1631&p=41575#p41575) -on the official forums. +https://helmet.kafuka.org/byuubackup2/viewtopic.php@f=4&t=1631.html) +on the archive of the official forums. diff --git a/docs/guides/drivers.md b/docs/guides/drivers.md index 6c3a7ea5..36d0beab 100644 --- a/docs/guides/drivers.md +++ b/docs/guides/drivers.md @@ -5,12 +5,12 @@ playing audio, and accepting input from game controllers. Or rather, there are many standards, -and different ones work best +and different ones work better on different computers. Therefore, higan comes with "drivers" for video, audio and input, -so you can find the one that works best for you. +so you can find the one that works best for your computer. To see what drivers you're currently using, or to choose different ones, go to the [Advanced tab] of the Settings window. diff --git a/docs/guides/import.md b/docs/guides/import.md index 5fd0c9aa..4c9978b6 100644 --- a/docs/guides/import.md +++ b/docs/guides/import.md @@ -29,7 +29,7 @@ and (if possible) start playing. **Note:** If you want to import many games, run icarus directly. -See [icarus] documentation for details. +See the [icarus] documentation for details. To play a game for a particular console from your library, open the [Systems menu], @@ -75,11 +75,11 @@ for yourself. To import a game that requires co-processor firmware, the easiest approach is to drop the firmware files into -icarus' `firmware` directory +icarus' `Firmware` directory before importing the game. The directory should be beside the icarus executable, -or it can be `%LOCALAPPDATA%\icarus\firmware` (on Windows) -or `~/.local/share/icarus/firmware/` (on Linux). +or it can be `%LOCALAPPDATA%\icarus\Firmware` (on Windows) +or `~/.local/share/icarus/Firmware/` (on Linux). If the easy approach doesn't work for a particular game, it may be because icarus has incorrectly guessed @@ -131,13 +131,13 @@ here's the firmware files you'll need: - CX4 + CX4
See Note 1 cx4.data.rom 3072 ae8d4d1961b93421ff00b3caa1d0f0ce7783e749772a3369c36b3dbf0d37ef18 - DSP1/1A
See Note 1 + DSP1/1A
See Note 2 dsp1.data.rom 2048 0b5da6533e55852ee8fc397977ec5576c5b9f1fb2e05656d8f87123a121b076e @@ -148,7 +148,7 @@ here's the firmware files you'll need: 269584b347a22953a2989494c850a7c1c027f4ca5add517a60e0c7d8833d0fac - DSP1B
See Note 2 + DSP1B
See Note 3 dsp1b.data.rom 2048 8546cbac530830446bb8a277f6b139d4ad64d650bdbac7e4e150e2f095665049 @@ -228,10 +228,15 @@ here's the firmware files you'll need: **Note 1:** +The CX4 firmware is shipped with higan, +because it just contains mathematical tables +and not a copyrightable program. + +**Note 2:** The DSP1 and DSP1A are physically different, but the firmware inside is identical. -**Note 2:** +**Note 3:** The DSP1B is very similar to the DSP1A, but fixes some bugs. Note that icarus' heuristics cannot distinguish between @@ -259,7 +264,7 @@ using the "Load ROM File ..." option in the [Systems menu] but it does not include the correct firmware data, nothing will happen, and higan will just sit there -with "No cartridge loaded" in +with "Unloaded" in [the status bar](../interface/higan.md#the-status-bar). Once a game with co-processor firmware is imported, @@ -441,7 +446,14 @@ including the timing change. Because the Super Game Boy cartridge includes the original Game Boy hardware, -it needs a boot ROM: +it needs a boot ROM. +icarus includes these files +and can reliably decide when to use them, +so importing either Super Game Boy cartridge +is just like [importing a regular game](#regular-games). + +In case you need to check the Super Game Boy boot roms, +here are their details: @@ -468,11 +480,6 @@ it needs a boot ROM:
-icarus includes these files -and can reliably decide when to use them, -so importing either Super Game Boy cartridge -is just like [importing a regular game](#regular-games). - To play a Game Boy game in Super Game Boy mode, load the Super Game Boy cartridge like any other game. higan will open another [filesystem browser] @@ -497,14 +504,14 @@ for details. [blackcarts]: ../notes.md#playing-game-boy-color-games-in-game-boy-mode -MSU-1 games ------------ +MSU1 games +---------- -The MSU-1 is a fictional expansion chip +The MSU1 is a fictional expansion chip invented by higan's author byuu, designed to allow the Super Famicom to stream data and audio. -Although the MSU-1 is not specific +Although the MSU1 is not specific to any particular storage medium, it gives the Super Famicom similar capabilities to CD-based add-ons @@ -512,32 +519,32 @@ like the Mega Drive's Mega CD and the PC Engine's CD-ROM², such as CD-quality music and full-motion video. -Although the MSU-1 was invented for higan, +Although the MSU1 was invented for higan, it is now supported by other Super Famicom emulators too. The [SD2SNES] programmable cartridge -even allows you to play MSU-1 games on a real console. +even allows you to play MSU1 games on a real console. There are a number of homebrew games -that make use of the MSU-1, +that make use of the MSU1, and also mods for commercial Super Famicom games that add higher-quality music and sometimes video. One thing to be aware of -when importing an MSU-1 game +when importing an MSU1 game is that early firmware versions of the SD2SNES -had a bug that caused MSU-1 music to play too quietly. +had a bug that caused MSU1 music to play too quietly. Skipping over [the full details][msu1vol], the short version is this: - If offered the choice between "boosted" or non-boosted audio, you want the non-boosted version. - - If an MSU-1 mod for a commercial game offers + - If an MSU1 mod for a commercial game offers "emulator" and "hardware" versions of the patch file, it means the audio tracks are already boosted. - Some [third](https://www.zeldix.net/t1265-#18320) [parties](https://www.zeldix.net/t1339-#19818) have created replacement, non-boosted audio tracks - for the most popular MSU-1 mods. + for the most popular MSU1 mods. If the mod you want to play has a replacement pack, use it with the "hardware" version of the patch. - Even without access to non-boosted audio tracks, @@ -548,7 +555,7 @@ the short version is this: distorting and clipping, in which case try the "emulator" patch. -To import an MSU-1 game: +To import an MSU1 game: 1. If you have a single, large file with the `.msu1` extension, @@ -560,11 +567,11 @@ To import an MSU-1 game: 2. Otherwise, import the Super Famicom ROM with icarus, [like a regular game](#regular-games). - - If this is a homebrew game with MSU-1 support, + - If this is a homebrew game with MSU1 support, there will probably be an ordinary ROM whose name ends in `.sfc`, which is the file you want to import. - - If this is a commercial game modded for MSU-1 support, + - If this is a commercial game modded for MSU1 support, there will probably be a patch file whose name ends in `.ips` or `.bps`. Get a copy of the correct version of the commercial game, @@ -574,14 +581,17 @@ To import an MSU-1 game: see "One thing to be aware of..." above. 3. Find the game folder in the [game library] that icarus created when it imported the game. - 4. Copy the MSU-1 data file into the game folder. - - This should be named `msu1.rom` + 4. Inside the game folder, + create a new folder named `msu1`. + 5. Copy the MSU1 data file into the new `msu1` folder. + - This should be named `data.rom` - If there's no file by that name, - look for a file with a `.msu` extension + look for a file named `msu1.rom`, + or a file with a `.msu` extension, and rename it to `msu1.rom`. - If there's no file ending in `.msu` either, create an empty file named `msu1.rom`. - 5. Copy the audio tracks into the game folder. + 6. Copy the audio tracks into the game folder. - If you have to choose between two sets of audio files, see "One thing to be aware of..." above. - These should be named @@ -601,13 +611,13 @@ To import an MSU-1 game: this game probably just doesn't use the audio-playback feature. Once the game folder is set up, -playing an MSU-1 game is just like +playing an MSU1 game is just like [a regular game](#regular-games). [SD2SNES]: https://sd2snes.de/ [Flips]: http://www.romhacking.net/utilities/1040/ [msu1vol]: http://blog.qwertymodo.com/2017/07/the-msu-1-volume-fiasco-explained.html -[Mercurial Magic]: https://github.com/hex-usr/Mercurial-Magic/ +[Mercurial Magic]: https://github.com/qwertymodo/Mercurial-Magic Patched games ------------- @@ -652,7 +662,7 @@ GBA games can be imported and played just like Note that some GBA games have trouble with -[in-game saves](../notes#in-game-saves-and-the-game-boy-advance). +[in-game saves](../notes.md#in-game-saves-and-the-game-boy-advance). PowerFest '94 ------------- @@ -670,85 +680,15 @@ switch between them after a specific time, extract a score, and display the combined total at the end. -icarus cannot automatically import -dumps of the PowerFest '94 ROMs, -but if you have the files, -you can import them manually. +Previous versions of higan +could emulate the PowerFest '94 cartridge, +but changes to higan's manifest system in v107 +prevent PowerFest '94 from working in that version. +Support will likely be re-added in a future version, +but in the mean time you can use higan v106 +and follow [that version's import instructions][pf94v106]. -You will need the following files: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
PartFilenameSize (bytes)SHA256
Scoringprogram.rom2621442fc9dca305ce3fb2f1a476567de500d50c174fbfbabd32b1b91c3ea6a731b4a1
Super Mario Bros. - The Lost Levelsslot-1.rom5242887fd86113c5f95f794d65807bb75ab91c93c914670c27fc813ffa2ca20a48705e
Super Mario Kartslot-2.rom52428819eb77affbf8dd068f5d79a3cf80a2084fd73237cd1ae4e47192b4422449e64a
Ken Griffey Jr. Presents Major League Baseballslot-3.rom1048576d47bc9f9a6289c4f2e7f6bf74095f6ed36b1043a761e3e729ac9af2fc39ae062
- -You will also need -the usual `dsp1.program.rom` and `dsp1.data.rom` -[co-processor firmware](#games-with-co-processor-firmware) files. - -**Note:** the versions of -*Super Mario Kart* -and *Ken Griffey Jr...* -in *PowerFest '94* -are not the same as the stand-alone versions of those games. - -To "import" *PowerFest '94*, -collect all the files mentioned above, then: - - 1. Inside [the game library](../concepts/game-library.md), - create the `Super Famicom` folder - (if it does not already exist). - 2. Inside the `Super Famicom` folder, - create a `PowerFest '94.sfc` folder - (the `.sfc` extension is important, - but you can choose a different base name if you want). - 3. Copy `program.rom` and the `slot-*.rom` files - into the `PowerFest '94.sfc` folder. - 4. Copy the `dsp1.*.rom` files into the `PowerFest '94.sfc` folder, - but rename them to `upd7725.*.rom`. - -To play *PowerFest '94*, -open the Library menu, -pick the Nintendo sub-menu, -then choose the Super Famicom sub-menu item -to open a filesystem browser listing -all the Super Famicom games in the library. -Select *PowerFest '94* from the list -and click the Open button, -or just double-click the game, -and it will begin playing. +[pf94v106]: https://higan.readthedocs.io/en/v106/guides/import/#powerfest-94 [filesystem browser]: ../interface/common.md#the-filesystem-browser [Game Library]: ../concepts/game-library.md diff --git a/docs/guides/shaders.md b/docs/guides/shaders.md index 7443ef7c..ec184838 100644 --- a/docs/guides/shaders.md +++ b/docs/guides/shaders.md @@ -2,14 +2,14 @@ Most of the consoles higan emulates were designed for low resolution NTSC televisions, and their video output is chunky and blocky by today's standards. -Video shaders customise how a console's video output +Video shaders customise how the emulated console's video output is drawn to the computer screen, and can clean up and smooth out the original video, reproduce the scanlines and blurring of the original display, or any other visual effect. The available video shaders are listed in -the "Video Shaders" sub-menu of the [Settings menu]. +the "Shader" sub-menu of the [Settings menu]. Which shaders are available depends on the [video driver] higan is configured to use. Most drivers only support these shaders: @@ -19,7 +19,8 @@ Most drivers only support these shaders: the colour of the single nearest console pixel, sometimes called "nearest neighbour" scaling. This produces unnaturally crisp and blocky images. - - If you use [aspect correction or non-integral scaling][ac], + - If you enable Scale, Stretch, or Aspect Correction modes + in the Output sub-menu of the [Settings menu], neighbouring console pixels may be drawn with a different number of computer pixels due to rounding errors, causing a distracting rippling effect. @@ -30,8 +31,6 @@ Most drivers only support these shaders: sometimes called "bilinear" scaling. This produces unnaturally blurry images. -[ac]: ../interface/higan-settings.md#video - In addition to those, the OpenGL driver also supports custom shaders. @@ -90,7 +89,7 @@ you'll need to restart higan for the change to take effect. Open the Settings menu again, -choose the "Video Shader" sub-menu, +choose the "Shader" sub-menu, and now the shaders you installed should be listed at the bottom of the menu. diff --git a/docs/index.md b/docs/index.md index da47992a..9612dcce 100644 --- a/docs/index.md +++ b/docs/index.md @@ -64,17 +64,17 @@ by the time you read this, and it may contain errors or omissions. If you find something that's wrong, or you have a suggestion, -post a message on the official higan forum. +post a message on the unofficial forum. Official higan resources ------------------------ - [Official homepage](https://byuu.org/emulation/higan/) - - [Official forum](https://board.byuu.org/viewforum.php?f=4) Unofficial higan resources -------------------------- + - [Unofficial forum](https://helmet.kafuka.org/bboard/) - [Source code repository](https://gitlab.com/higan/higan/) archives official higan releases and WIP snapshots @@ -85,12 +85,12 @@ Unofficial higan resources or smarter algorithms for scaling up to modern PC resolutions. See [Using video shaders][shaders] below for details. - [Mercurial Magic](https://github.com/hex-usr/Mercurial-Magic/) - is a tool for converting MSU-1 games and mods into a format + is a tool for converting MSU1 games and mods into a format higan can use. - See [Importing MSU-1 games][msu1] for details. + See [Importing MSU1 games][msu1] for details. [shaders]: guides/shaders.md -[msu1]: guides/import.md#msu-1-games +[msu1]: guides/import.md#msu1-games There are also other projects based on current or older versions of higan, @@ -113,7 +113,7 @@ that you might want to check out. is a fork of bsnes v094 adapted to work as a [libretro](https://www.libretro.com/) emulation core. - - [nSide](https://github.com/hex-usr/nSide) + - [nSide](https://gitlab.com/hex-usr/nSide) is a fork of higan that greatly enhances its NES emulation support, and adds minor features to the other cores too. diff --git a/docs/install/linux.md b/docs/install/linux.md index f27ee227..c74d33bc 100644 --- a/docs/install/linux.md +++ b/docs/install/linux.md @@ -24,7 +24,7 @@ for the following libraries: - Mesa - gtksourceview 2.x - Cairo - - SDL 1.2 + - SDL 2.0 - libXv - libAO - OpenAL @@ -35,7 +35,7 @@ On a Debian-derived Linux distribution you can install everything you need with a command like: sudo apt-get install build-essential libgtk2.0-dev libpulse-dev \ - mesa-common-dev libgtksourceview2.0-dev libcairo2-dev libsdl1.2-dev \ + mesa-common-dev libgtksourceview2.0-dev libcairo2-dev libsdl2-dev \ libxv-dev libao-dev libopenal-dev libudev-dev Once you have all the dependencies installed, @@ -53,7 +53,7 @@ being installed system-wide. 3. Type `cd ~/higan-src` (or wherever you put the higan source) and press Enter - 4. Type `make -C higan` and press Enter + 4. Type `make -C higan target=higan` and press Enter to build the main higan executable 5. Type `make -C icarus` and press Enter to build the icarus import tool @@ -68,7 +68,7 @@ as described in the previous section: 2. Type `cd ~/higan-src` (or wherever you put the higan source) and press Enter - 3. Type `make -C higan install` and press Enter + 3. Type `make -C higan target=higan install` and press Enter to install higan and its supporting files 4. Type `make -C icarus install` and press Enter to install icarus and its game database @@ -123,7 +123,7 @@ as installed by the above instructions: 2. Type `cd ~/higan-src` (or wherever you put the higan source) and press Enter - 3. Type `make -C higan uninstall` and press Enter + 3. Type `make -C higan target=higan uninstall` and press Enter 4. Type `make -C icarus uninstall` and press Enter To remove higan's configuration, diff --git a/docs/install/windows.md b/docs/install/windows.md index 66bd5f92..8f760981 100644 --- a/docs/install/windows.md +++ b/docs/install/windows.md @@ -51,37 +51,57 @@ or by clicking the download button on the right-hand side of the web-page and choosing an archive format. You will need a C++ compiler to compile higan. -We recommend installing [TDM64-GCC][tdm], -preferably the latest version -but anything newer than 4.9 should be fine. +We recommend installing the latest version of [MinGW-W64]. higan does not support building with clang++ (Clang is still not quite there yet for Windows) nor Microsoft Visual C++ (last we checked, it didn't support all the C++ features higan uses). -**Note:** Make sure you get TDM64-GCC, -not TDM-GCC. -When compiled in x86 (32-bit) mode, -higan may crash at startup -because gcc targeting x86 does not support -Windows' structured exception handling (SEH). -Also, -historically in x86 mode -gcc has miscompiled a part of the NES emulation core. -See the higan forum -[for](https://board.byuu.org/viewtopic.php?p=41977#p41977) -[details](https://board.byuu.org/viewtopic.php?p=42253#p42253). +[MinGW-W64]: https://mingw-w64.org/ -Once you've installed the compiler, -open a command-prompt window, +MinGW-W64 is available in a number of variants, +and the installer should ask you which you want. + + - **Version:** + Version 8.1.0 is known to work, + later versions may work too. + - **Architecture:** + You *must* choose "x86_64", not "i686". + When built with an i686 compiler, + higan may crash at startup + because gcc targeting x86 does not support + Windows' structured exception handling (SEH). + Also, + historically in x86 mode + gcc has miscompiled a part of the NES emulation core. + See the archive of the official forum + [for](https://helmet.kafuka.org/byuubackup2/viewtopic.php@f=4&t=1636&start=20.html#p41977) + [details](https://helmet.kafuka.org/byuubackup2/viewtopic.php@f=4&t=1636&start=30.html#p42253). + - **Threads:** + Both options should work, + but higan is developed with the "posix" model. + - **Exception:** + You *must* choose "seh", + or higan may crash at startup. + If "seh" is not an option, + make sure "Architecture" is set to "x86_64". + - **Build Revision:** + Choose the largest number, whatever it is. + +When the compiler is installed, +it adds a "Run terminal" shortcut to the Start menu +which opens a command-prompt +with all the compiler tools available. + +To verify that the compiler is installed correctly, +launch the "Run Terminal" shortcut, type `g++ --version` -then press Enter -to check it's installed correctly. +then press Enter. You should see a message like ```text -g++ 1.2.3 20010101 -Copyright (C) 2001 Free Software Foundation, Inc. +g++ (x86_64-posix-seh-rev0, Built by MinGW-W64 project) 8.1.0 +Copyright (C) 2018 Free Software Foundation, Inc. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. ``` @@ -91,11 +111,11 @@ and the corresponding dates. If you see an error message like "'g++' is not recognized as an internal or external command, operable program or batch file", -you may need to add the compiler's "bin" folder -to your computer's `%PATH%`. +make sure you're using the "Run terminal" shortcut, +or otherwise have MinGW-W64's "bin" directory in your `%PATH%`. See the compiler's documentation for help with that. -Once mingw is installed and available from the command prompt: +Once the compiler is installed: 1. Put the higan source code in some convenient location, like `C:\higan-src` @@ -105,11 +125,9 @@ Once mingw is installed and available from the command prompt: and press Enter 4. Type `mingw32-make -C icarus` and press Enter to build the icarus import tool - 5. Type `mingw32-make -C higan` and press Enter + 5. Type `mingw32-make -C higan target=higan` and press Enter to build the main higan executable -[tdm]: http://tdm-gcc.tdragon.net/download - Installing a compiled build on Windows -------------------------------------- @@ -118,9 +136,9 @@ Installing a compiled build on Windows 2. Assuming you built higan in `C:\higan-src`, copy `C:\higan-src\icarus\out\icarus.exe` into the new folder - 3. Copy `C:\higan-src\icarus\database` and its contents + 3. Copy `C:\higan-src\icarus\Database` and its contents into the new folder - 4. Copy `C:\higan-src\icarus\firmware` and its contents + 4. Copy `C:\higan-src\icarus\Firmware` and its contents into the new folder 5. Copy `C:\higan-src\higan\out\higan.exe` into the new folder @@ -132,7 +150,7 @@ Installing a compiled build on Windows The new folder should now contain `icarus.exe`, `higan.exe`, -and folders named `database`, `firmware`, `systems`, +and folders named `Database`, `Firmware`, `systems`, and possibly `shaders`. This is what you would get by downloading an official build, as described under diff --git a/docs/interface/higan-cli.md b/docs/interface/higan-cli.md index 6ccd7436..616f1165 100644 --- a/docs/interface/higan-cli.md +++ b/docs/interface/higan-cli.md @@ -57,7 +57,8 @@ higan will prompt for one. `SUBGAME2` is ignored. When `GAME` refers to -the [Super Game Boy](../guides/import.md#super-game-boy-games), +the [Super Game Boy](../guides/import.md#super-game-boy-games) +or Super Game Boy 2, `SUBGAME1` should be the path to a game folder or ROM file representing a Game Boy game to insert into the slot. diff --git a/docs/interface/higan-settings.md b/docs/interface/higan-settings.md index 6f782237..8fc2eeb8 100644 --- a/docs/interface/higan-settings.md +++ b/docs/interface/higan-settings.md @@ -6,7 +6,7 @@ and contains less-frequently-modified settings. Most of these can be safely ignored, or set once and never changed again. -This window has a tab for each main category of options: +This window has a tab for each main category of options. Systems ======= @@ -92,9 +92,9 @@ settings adjust the colour and brightness of the emulated console's video output: - **Saturation** adjusts the vibrancy of colours displayed, - where 0% makes things pure grey, + where 0% makes things black-and-white, 100% is normal, - and 200% is garishly brightly coloured. + and 200% is garishly exaggerated colour. - **Gamma** adjusts how bright mid-range colours are compared to the brightest colours, where 100% is normal, @@ -102,20 +102,23 @@ of the emulated console's video output: This is in addition to any adjustment applied by the "Colors" option - in the "Video Emulation" sub-menu + in the "Emulation" sub-menu of the [Settings menu](higan.md#the-settings-menu). - **Luminance** adjusts the overall brightness, where 100% is normal, and 0% is totally black. -**Overscan Mask** -removes parts of -the video output that would have been hidden -by the bezel around the edge of -a standard-definition television screen. -Some games (particularly on the Famicom) -displayed random glitchy output in this area, -which can be distracting. +**Overscan Area** +controls what parts of the video output are hidden +when "Show Overscan Area" is disabled +in the "Output" sub-menu of +the [Settings menu](higan.md#the-settings-menu). +On a standard-definition television, +the outermost edges of the emulated console's video output +would have been hidden by the bezel, +so some games (particularly on the Famicom) +allowed random glitchy output to appear there, +assuming it wouldn't be visible. - **Horizontal** removes pixels from the left and right of the video output. @@ -130,41 +133,7 @@ whether the Super Famicom is in lo-res (256px) or hi-res (512px) mode. -**Windowed Mode** -settings apply when higan is running -in a normal window. - - - **Aspect Correction** - stretches the image to match the aspect ratio - produced by the original console hardware, - but can cause a "ripple" effect - during horizontal scrolling - due to rounding errors. - [Video shaders](../guides/shaders.md) - can reduce this effect. - - **Integral Scaling** - makes higan draw the emulated video output - at a whole-number multiple of the original size, - rather than completely filling the available space. - This means that every game pixel - uses the same number of computer pixels, - and avoids graphics looking chunky and uneven. - Note that Aspect Correction - is applied after integral scaling, - so some unevenness may be visible - even with this option enabled. - - **Adaptive Sizing** - automatically resizes the higan window - to fit snugly around the emulated video output - whenever it changes size - (because the user loaded a game for a different console, - chose a different option from - the [Video Scale sub-menu](higan.md#the-settings-menu), - toggled Aspect Correction, etc.) - When disabled, - higan generally respects manual resizing. - -**Fullscreen Mode** +**Fullscreen** settings apply when higan is running fullscreen, because it was started with the `--fullscreen` @@ -172,10 +141,6 @@ because it was started with the `--fullscreen` or because the user pressed the Toggle Fullscreen [hotkey](higan-settings.md#hotkeys). - - **Aspect Correction** - behaves the same way as in Windowed mode above. - - **Integral Scaling** - behaves the same way as in Windowed mode above. - **Exclusive Mode** requests exclusive access to the computer's video output @@ -185,7 +150,7 @@ the Toggle Fullscreen [hotkey](higan-settings.md#hotkeys). from drawing anything, and may also temporarily disable any kind of compositing, reducing video latency. - As of v104, + As of v107, only the Direct3D video driver is capable of exclusive mode; with other drivers this option does nothing. @@ -236,52 +201,52 @@ before it is sent to your computer's speakers. where 0% means only the left speaker produces sound, 50% means both speakers produce sound equally, and 100% means only the right speaker produces sound. - - **Reverb** adds a slight reverberation effect - to the emulated console's audio output, - as though you were playing the game in a tunnel or small room. Input ===== -This tab controls which PC inputs -are mapped to which emulated controllers. +This tab controls +how higan handles input for the emulated consoles. + +**When focus is lost** +controls what happens when a game is loaded, +but higan is not the current foreground window. + + - **Pause Emulation** automatically pauses emulation. + - **Block Input** allows emulation to keep running, + but higan will ignore all configured button presses. + If you're using the keyboard to emulate a controller, + this prevents typing in other applications + from messing with higan, + but music will keep playing. + - **Allow Input** allows emulation to continue as normal. + This allows somebody to play higan with a controller + in one window, + while somebody else types into another application + in another window. + +The rest of this tab configures +the mapping from PC inputs to emulated controllers. The exact PC inputs that can be mapped depend on [the input driver](../guides/drivers.md#input). -General input settings: +To choose which of the possible controllers to configure: - - **Pause Emulation** automatically pauses emulation - when the main higan window - is not the current foreground window. - - **Allow Input** can be ticked - when "Pause Emulation" is *not* ticked, - and allows configured inputs to keep affecting higan - even when higan is running in the background. - This is particularly relevant if - you configure your PC keyboard to control higan: - if you tick this box, - and switch to a different application - leaving higan running in the background, - typing in that other application may affect - the emulated game running in higan - even though you can't see it! + - The first drop-down list controls + which console's ports appear in the second list. + - The second drop-down list controls + which port's compatible controllers appear in the third list. + - The third drop-down list controls + which controller's inputs are shown + in the mapping list below. -Choosing which of the possible controllers to configure: +Note that some consoles only allow particular controllers +to be used in a particular port. +For example, +the Super Scope controller for the Super Famicom +only works in Controller Port 2. - - The console selector chooses which console's inputs - to display in the mapping list below. - - The port selector chooses which port of the selected console - to display in the mapping list below. - - The controller selector chooses which controller - associated with the given console and port - to display in the mapping list below. - Note that some consoles only allow particular controllers - to be used in a particular port. - For example, - the Super Scope controller for the Super Famicom - only works in Controller Port 2. - -Configuring the selected controller: +To configure the selected controller: - The mapping list includes every button and axis on the selected controller, @@ -332,6 +297,13 @@ then click one of the or "Mouse Y-axis" buttons in the bottom-left of the window. +**Note:** +To use an controller axis mapped to a mouse axis, +higan will need to be in fullscreen mode, +or you'll need to press +the key mapped to "Toggle Mouse Capture" +on the [Hotkeys tab](#hotkeys). + If you start mapping a button or axis, but decide you don't want to, you can press Escape @@ -339,10 +311,25 @@ to exit the "Press a key or button to map..." mode without actually mapping anything. **Note:** -Consoles in the Game Boy family include +The Game Boy and Game Boy Color consoles +have a "Cartridge" port with controllers +that are not really controllers: + + - The "MBC5" controller is automatically used for + games whose cartridge includes the MBC5 memory-mapper + and a rumble motor, + like *Pokémon Pinball*. + See [Rumble Compatibility for Game Boy (Color)][gbcrumble] + for details. + - The "MBC7" controller is automatically used for + games whose cartridge includes the MBC7 memory-mapper + and an accelerometer, + like *Kirby Tilt 'n' Tumble*. + +**Note:** +The Game Boy Advance console includes a Rumble "input" which is really more of an output. -See [Rumble Compatibility for Game Boy (Color)][gbcrumble] -and [Rumble Compatibility for Game Boy Advance][gbarumble] +See [Rumble Compatibility for Game Boy Advance][gbarumble] for details. [gbcrumble]: ../notes.md#rumble-compatibility-for-game-boy-color @@ -360,12 +347,12 @@ Hotkeys This tab is like "Inputs" above, except it contains controls for higan itself -instead of the emulated console. +instead of for the emulated console. - **Toggle Fullscreen** puts higan into fullscreen mode, where the menu and status bar are hidden, and the emulated console's video output - is enlarged to cover the entire screen. + can cover the entire screen. Toggling fullscreen also automatically captures the mouse. - **Toggle Mouse Capture** hides the usual mouse-cursor, and captures the mouse so it cannot leave the higan window. @@ -440,8 +427,7 @@ for help choosing which drivers you should use. configures how higan interacts with the [Game Library](../concepts/game-library.md). - - **Location** selects where higan - looks for games to load. + - **Location** tells higan where to look for games to load. See [Moving the Game Library](../concepts/game-library.md#moving-the-game-library) for more information. - **Ignore Manifests** makes higan ignore @@ -452,7 +438,7 @@ with the [Game Library](../concepts/game-library.md). to guess a manifest on the fly. See [Ignoring manifests](../concepts/manifests.md#ignoring-manifests) for details. - + **Other** - **Auto-Save Memory Periodically** makes higan write diff --git a/docs/interface/higan-tools.md b/docs/interface/higan-tools.md index b05f04fd..49b0f48f 100644 --- a/docs/interface/higan-tools.md +++ b/docs/interface/higan-tools.md @@ -3,10 +3,10 @@ appears when you choose one of the items at the bottom of [the Tools menu](higan.md#the-tools-menu). -The window has a tab for each tool: +The window has a tab for each tool. -The Cheat Editor -================ +Cheat Editor +============ For some consoles, higan supports applying temporary changes to the code of a running game. @@ -89,8 +89,8 @@ in Super Mario World, you can lock the time to 999 with these codes: `7e0f31=09+7e0f32=09+7e0f33=09`. -The State Manager -================= +State Manager +============= The State Manager allows you to create, load, @@ -125,8 +125,8 @@ and click "Erase" in the bottom-right corner. To clear all the slots at once, click "Reset" in the bottom-right corner. -The Manifest Viewer -=================== +Manifest Viewer +=============== As described in [Game Manifests](../concepts/manifests.md), diff --git a/docs/interface/higan.md b/docs/interface/higan.md index ef0465df..5e2b996c 100644 --- a/docs/interface/higan.md +++ b/docs/interface/higan.md @@ -8,8 +8,8 @@ the running game's video output. The Systems menu ---------------- -This menu lists the systems higan emulates, -Choosing any system allows you to play +This menu lists the systems higan emulates. +Choosing any system from this menu allows you to play games for that system that you've already imported into higan's [game library](../concepts/game-library.md). See [Importing and playing games](../guides/import.md). @@ -24,7 +24,7 @@ for example, you can add the Sufami Turbo to the list and load *SD Ultra Battle* in two clicks instead of three. - + **Load ROM File ...** opens a [filesystem browser](common.md#the-filesystem-browser) allowing you to choose a single ROM file. @@ -39,8 +39,7 @@ The console menu does not appear until a game is loaded. Also, it's not named "console", -it's named for the kind of console -the loaded game runs on. +it's named for the console that runs the loaded game. For example, when playing a Game Boy game, you will have a "Game Boy" menu. @@ -50,7 +49,6 @@ to the particular console being emulated. All consoles will have some of the following items, but few consoles have all of them. - **Controller Port 1** allows you to connect different emulated controllers @@ -80,7 +78,21 @@ This menu appears for the Famicom, even though the Famicom did not support alternate controllers, because the Famicom emulation core also emulates the NES, which did. - + +**Controller** +is like "Controller Port 1" +for consoles that only have one controller port. + +**Hardware** +appears for consoles with buttons on the main unit, +like the Game Boy, +or Master System. +It only allows the built-in controls to be used. + +**Cartridge** +appears for the Game Boy and Game Boy Colour. +The options inside it do nothing. + **Expansion Port** allows you to connect different emulated devices @@ -95,6 +107,9 @@ This option allows the same program to control the emulated SNES, for development or testing. +**Extension Port** +is the name the Sega Mega Drive used for its expansion port. + **Soft Reset** restarts the emulated console's CPU while leaving the console's memory untouched, @@ -124,7 +139,7 @@ as though the emulated console were switched off and on again. stops the current game, as though the emulated console were switched off. You can load a new game -from [the Library menu](#the-library-menu). +from [the Systems menu](#the-systems-menu). [21fx]: https://github.com/defparam/21FX @@ -134,13 +149,83 @@ The Settings menu The Settings menu allows you to configure things that aren't specific to any particular console. - -**Video Scale** determines the size +**Size** +determines the size of the emulated console's video output when higan is running in windowed mode (as opposed to fullscreen). +The menu-items that indicate particular sizes +are only approximate, since +aspect correction can be applied, +different consoles have different native image sizes, +and some consoles can change the size of their output image dynamically. -**Video Emulation** applies various effects + - **1x (240p)** + resizes the higan window + so that each pixel of the emulated console's video output + is drawn as a single pixel on the computer screen. + - **2x (480p)** + resizes the higan window + so that each pixel of the emulated console's video output + is drawn as a 2×2 block of pixels on the computer screen. + - **3x (720p)** + resizes the higan window + so that each pixel of the emulated console's video output + is drawn as a 3×3 block of pixels on the computer screen. + - **Shrink Window To Size** + resizes the higan window to fit the emulated console's video output + at its current scale, + so there's no black padding between the image and the window border + (some padding may remain + if "Show Overscan Area" is enabled + in the Output menu). + - **Center Window** + moves the higan window to the centre of the computer screen. + +**Output** +controls how higan draws the emulated console's video output +into the space available, +in both windowed and fullscreen modes. + + - **Center** + draws the emulated video + at the largest integer multiple of the native size that will fit, + centered in the space available. + This gives the most crisp output, + but often has black borders. + - **Scale** + draws the emulated video + at the largest size that will fit, + and which preserves the image's aspect ratio. + This strikes a balance between + displaying the video output as it was intended, + and eliminating black borders. + - **Stretch** + draws the emulated video + to cover the entire available output area, + even if that distorts the image. + This completely eliminates black borders, + but can look very weird. + - **Adaptive Sizing** + allows higan to resize its window + when the emulated console changes the resolution + of its video output. + This can avoid black borders, + but the window resizing itself might be even more distracting. + - **Aspect Correction** + horizontally stretches the emulated video output + to match the aspect ratio produced by the original console. + It can make the output look more "lumpy", + but is a more accurate representation + of the original console's output. + - **Show Overscan Area** + controls whether the area defined by + the "Overscan Area" sliders in + the [Video settings](higan-settings.md#video) + is clipped from the emulated video output + or shown. + +**Emulation** applies various effects to the emulated console's video output to reproduce some behaviours that aren't technically part of the console itself: @@ -165,8 +250,8 @@ that aren't technically part of the console itself: used by the Super Famicom, the dim, washed out colours of the original Game Boy Advance, and the pea-green display of the original Game Boy. - -**Video Shader** controls + +**Shader** controls how the low-resolution video output of the emulated console is scaled up to suit modern high-resolution displays. [Using video shaders](../guides/shaders.md) @@ -234,15 +319,15 @@ This can also be triggered by the [pause hotkey](higan-settings.md#hotkeys). **Cheat Editor ...** -opens [the Cheat Editor tab](higan-tools.md#the-cheat-editor) +opens the [Cheat Editor tab](higan-tools.md#cheat-editor) of the Tools window. **State Manager ...** -opens [the State Manager tab](higan-tools.md#the-state-manager) +opens the [State Manager tab](higan-tools.md#state-manager) of the Tools window. **Manifest Viewer ...** -opens [the Manifest Viewer tab](higan-tools.md#the-manifest-viewer) +opens the [Manifest Viewer tab](higan-tools.md#manifest-viewer) of the Tools window. **Game Notes ...** @@ -275,7 +360,7 @@ at the bottom of the main higan window, while "Show Status Bar" is ticked in [the Settings menu](#the-settings-menu). Before any game is loaded, -the status bar displays "No cartridge loaded". +the status bar displays "Unloaded". When a game is loaded and running, the status bar displays the current emulation speed @@ -319,7 +404,7 @@ sub-menu that has not had a save-state saved to it, or when you press the "Load Quick State" hotkey while the current Quick State slot has not had a save-state saved to it, -The status bar briefly displays "Power cycled" +The status bar briefly displays "System has been power cycled" when you choose "Power Cycle" from [the console menu](#the-console-menu), or press the "Power Cycle" hotkey. diff --git a/docs/interface/icarus.md b/docs/interface/icarus.md index f0425651..4e4f60ad 100644 --- a/docs/interface/icarus.md +++ b/docs/interface/icarus.md @@ -62,7 +62,7 @@ The icarus Settings dialog contains the following settings: Command line ------------ -icarus can be launched with any of the following command-line arguments: +icarus can be launched in any of the following ways: > icarus > diff --git a/docs/notes.md b/docs/notes.md index 06ddc8e5..ec8968ee 100644 --- a/docs/notes.md +++ b/docs/notes.md @@ -29,8 +29,8 @@ you may be comparing it to a Mega Drive calibrated to a different scale (or to an emulator tweaked to match such a Mega Drive). -[vol]: https://board.byuu.org/viewtopic.php?p=42482#p42482 -[va6]: https://board.byuu.org/viewtopic.php?p=42195#p42195 +[vol]: https://helmet.kafuka.org/byuubackup2/viewtopic.php@f=4&t=1235&start=140.html#p42482 +[va6]: https://helmet.kafuka.org/byuubackup2/viewtopic.php@f=4&t=1235&start=130.html#p42195 Playing Game Boy Color games in Game Boy mode --------------------------------------------- @@ -128,19 +128,23 @@ Rumble compatibility for Game Boy (Color) The Game Boy and Game Boy Color did not natively support any kind of rumble or force-feedback system, -but some game cartridges (such as Pokémon Pinball) +but some game cartridges (such as *Pokémon Pinball*) included a rumble motor within the cartridge itself. +Such cartridges generally used the "MBC5" memory mapper chip. -Because higan does not currently support -game-specific controller features, -to experience the rumble effect in higan -you'll need to configure the console: +To experience the rumble effect in higan, +you'll need to configure the MBC5 "controller" +connected to the "cartridge" port: - Open [higan's Input settings](interface/higan-settings.md#input) - In the list of consoles, select Game Boy, or Game Boy Color depending on which console you want to use to play the game + - In the list of ports, + select "Cartridge" + - In the list of controllers, + select "MBC5" - In the list of inputs, double-click "Rumble" or select it and press Enter diff --git a/docs/qs.md b/docs/qs.md index 57a4a3b2..c58ad294 100644 --- a/docs/qs.md +++ b/docs/qs.md @@ -51,7 +51,7 @@ Load a game ----------- From -[the Library menu](interface/higan.md#the-library-menu), +[the Systems menu](interface/higan.md#the-systems-menu), choose "Load ROM File ..." to open [a filesystem browser](interface/common.md#the-filesystem-browser), and choose the game you want to play. @@ -63,7 +63,7 @@ In the future, if you want to play this game again, you can choose "Load ROM File ..." as you did before, or you can choose the appropriate console name -from the Library menu, +from the Systems menu, which will list all the games for that console in the Game Library. diff --git a/docs/release.md b/docs/release.md index ff52fa3c..c1179af9 100644 --- a/docs/release.md +++ b/docs/release.md @@ -11,5 +11,5 @@ Release checklist 6. Merge changes from master. 7. Copy `target-bsnes/resource/resource.?pp` to the `target-libretro` folder. 7. `git push` to make the new changes available. - - [rtd]: https://readthedocs.org/projects/higan/builds/ + +[rtd]: https://readthedocs.org/projects/higan/builds/