From 30ed7f7e0b87d22dd7b1871cf82f92e0d6e712ed Mon Sep 17 00:00:00 2001 From: Tim Allen Date: Thu, 18 Apr 2019 18:04:44 +1000 Subject: [PATCH] Remove higan docs from the bsnes fork. --- docs/checklinks.sh | 12 - docs/concepts/game-folders.md | 154 ------- docs/concepts/game-library.md | 87 ---- docs/concepts/manifests.md | 149 ------- docs/concepts/save-states.md | 129 ------ docs/credits.md | 63 --- docs/faq.md | 283 ------------- docs/guides/drivers.md | 143 ------- docs/guides/import.md | 696 ------------------------------- docs/guides/shaders.md | 217 ---------- docs/index.md | 123 ------ docs/install/general.md | 53 --- docs/install/linux.md | 142 ------- docs/install/windows.md | 169 -------- docs/interface/common.md | 61 --- docs/interface/down.png | 1 - docs/interface/higan-cli.md | 96 ----- docs/interface/higan-settings.md | 453 -------------------- docs/interface/higan-tools.md | 148 ------- docs/interface/higan.md | 413 ------------------ docs/interface/home.png | 1 - docs/interface/icarus.md | 100 ----- docs/interface/refresh.png | 1 - docs/interface/up.png | 1 - docs/notes.md | 223 ---------- docs/qs.md | 102 ----- docs/release.md | 15 - mkdocs.yml | 38 -- 28 files changed, 4073 deletions(-) delete mode 100644 docs/checklinks.sh delete mode 100644 docs/concepts/game-folders.md delete mode 100644 docs/concepts/game-library.md delete mode 100644 docs/concepts/manifests.md delete mode 100644 docs/concepts/save-states.md delete mode 100644 docs/credits.md delete mode 100644 docs/faq.md delete mode 100644 docs/guides/drivers.md delete mode 100644 docs/guides/import.md delete mode 100644 docs/guides/shaders.md delete mode 100644 docs/index.md delete mode 100644 docs/install/general.md delete mode 100644 docs/install/linux.md delete mode 100644 docs/install/windows.md delete mode 100644 docs/interface/common.md delete mode 120000 docs/interface/down.png delete mode 100644 docs/interface/higan-cli.md delete mode 100644 docs/interface/higan-settings.md delete mode 100644 docs/interface/higan-tools.md delete mode 100644 docs/interface/higan.md delete mode 120000 docs/interface/home.png delete mode 100644 docs/interface/icarus.md delete mode 120000 docs/interface/refresh.png delete mode 120000 docs/interface/up.png delete mode 100644 docs/notes.md delete mode 100644 docs/qs.md delete mode 100644 docs/release.md delete mode 100644 mkdocs.yml diff --git a/docs/checklinks.sh b/docs/checklinks.sh deleted file mode 100644 index 46b4d9a7..00000000 --- a/docs/checklinks.sh +++ /dev/null @@ -1,12 +0,0 @@ -#!/bin/sh - -# This uses the official W3C link-checker tool: -# -# https://github.com/w3c/link-checker -# -checklink \ - --summary \ - --broken \ - --location=http://127.0.0.1:8000/ \ - --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 deleted file mode 100644 index 9406710c..00000000 --- a/docs/concepts/game-folders.md +++ /dev/null @@ -1,154 +0,0 @@ -A game folder -is higan's way of grouping all -the information and resources required -to properly emulate a particular game. -For example, -to represent a Super Famicom game named `dkc3`, -higan would create a game folder named `dkc3.sfc`, -and inside it store the game data as `program.rom` -and the save data as `save.ram`: - -```python -+- Super Famicom - | - +- dkc3.sfc - | - +- program.rom - | - +- save.ram -``` - -In contrast, -other emulators typically -group resources related to a game -by requiring that every file has the same base name -but different file extensions. -For example, -if another emulator loaded the game `dkc3.sfc` -it might store the save data in `dkc3.srm`: - -```python -+- Super Famicom - | - +- dkc3.sfc - | - +- dkc3.srm -``` - -Why game folders? ------------------ - -A file extension doesn't offer -much room for description, -so the traditional name-based-grouping system -only really works when games use a small number of files, -Also, -since file extensions traditionally describe -the format of the file in question, -it also means a game can't use -two or more files in the same format. - -Compared to other emulators, -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 [MSU1 feature][msu1] -supports up to 99 audio tracks per game, -and higan supports up to 133 save-states per game. -Thus, -higan suffers from the limitations of name-based-grouping -more than most. - -higan's game folders allow a game -to have unique, descriptive filenames -for all its resources, -and for each file to use the extension -that's most appropriate. -They also allow emulator-specific extras -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#msu1-games -[firmware]: ../guides/import.md#games-with-co-processor-firmware - -For a more detailed motivation for game folders, -see [Game Paks on the higan website][gp]. - -[gp]: https://byuu.org/emulation/higan/game-paks - -What's in a game folder? ------------------------- - -A game folder collects all the information relevant -to emulating a particular game. -Not all of the following files -are relevant for every console, -or even for every game on a console, -but they may be present under particular circumstances. - -All the files directly in the game folder -are expected to be useful -to all emulators that support them: - - - `manifest.bml`: - The [manifest](manifests.md) for this game folder. - - `program.rom`: - For most consoles, - this contains - the executable instructions and graphics data - from the cartridge's ROM chips. - For the Famicom, - this contains only the executable instructions. - - `character.rom`: - For the Famicom, - this contains only the graphics data - from the cartridge's ROM chips. - - `ines.rom`: - While other consoles typically include enough hints - in `program.rom` for icarus to guess a working manifest, - the Famicom does not. - Famicom games not stored in game folders - typically include an "iNES header" to store that information, - which icarus preserves after import as `ines.rom`. - - `save.ram`: - Games that include a save feature - will create this file. - Note that it is only written to disk - when higan exits gracefully; - if higan crashes or is forced to quit, - in-game saves may be lost. - Other emulators sometimes call this an "SRAM file", - even though the same filename is used - with games that included EEPROM or Flash storage, - not just battery-backed Static RAM. - - `rtc.ram`: - Games that include a calendar or real-time clock - will create this file. - - `*.data.rom`, `*.program.rom`: - Files named like this are usually [co-processor firmware][firmware]. - -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 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#cheat-editor) - is stored here. - - `notes.txt`: - Everything entered in the [Game Notes] is stored here. - - `states/quick/slot-*.bst`: - All [Quick States](save-states.md#quick-states) are stored here. - - `states/managed/slot-*.bst`: - All [Manager States](save-states.md#manager-states) are stored here. - -[Game Notes]: ../interface/higan-tools.md#game-notes diff --git a/docs/concepts/game-library.md b/docs/concepts/game-library.md deleted file mode 100644 index 8508bc39..00000000 --- a/docs/concepts/game-library.md +++ /dev/null @@ -1,87 +0,0 @@ -The game library -is the folder where all the -[game folders](game-folders.md) go. -When [icarus](../interface/icarus.md) imports a game, -it creates or updates -the corresponding game folder in the game library. -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. - -Inside the game library folder -there is a sub-folder for each system. -Inside each system folder -are the game folders -for each imported game. - -Why a game library? -------------------- - -higan [requires game folders](game-folders.md#why-game-folders), -but it also invented game folders, -so existing games need -to be converted to game folder format -before higan can play them. -The converted copy of a game needs to go *somewhere*. - -Also, -for people who have a huge collection of games, -the game library only lists the games they actually play, -rather than every possible game, -making it easier to find the games they like. - - -Where is the game library? --------------------------- - -In Windows, -the default location of -the game library is the `Emulation` folder -inside your profile folder -(To find your profile folder, -press `Win+R` to open the Run dialog, -then type `%USERPROFILE%` and press Enter). - -In Linux, -the default location of -the game library is the `Emulation` directory -inside your home directory. - -On all platforms, -the game library location can be configured. -See [Moving the Game Library](#moving-the-game-library) -below. - -Moving the game library ------------------------ - -Moving the game library is a little complicated, -because there are two parts to it: -telling icarus where to put imported games, -and telling higan where to find them. - - 1. Move your existing game library folder - to the new location, - or otherwise create the folder you want higan to use - as its game library. - 1. Launch icarus, - then click the "Settings ..." button in the lower-right, - to open - [the Settings dialog][icsettings]. - 1. Click the "Change ..." button on the right. - A [filesystem browser][fsbrowser] window will appear, - allowing you to choose - where imported games will be stored. - 1. Launch higan, - then from [the Settings menu][settingsmenu], - choose "Advanced ..." - to open [higan's Advanced settings][advsettings]. - 1. Click the "Change ..." button on the right. - A [filesystem browser][fsbrowser] will appear, - allowing you to choose the same folder again. - -[icsettings]: ../interface/icarus.md#the-icarus-settings-dialog -[fsbrowser]: ../interface/common.md#the-filesystem-browser -[settingsmenu]: ../interface/higan.md#the-settings-menu -[advsettings]: ../interface/higan-settings.md#advanced diff --git a/docs/concepts/manifests.md b/docs/concepts/manifests.md deleted file mode 100644 index 96958488..00000000 --- a/docs/concepts/manifests.md +++ /dev/null @@ -1,149 +0,0 @@ -If a [game folder](game-folders.md) is -the emulation equivalent of -a physical game cartridge, -a manifest is like -the circuit board inside the cartridge: -it connects all the other parts together -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#manifest-viewer). - -Why manifests? --------------- - -For most consoles, -a manifest isn't strictly necessary: -the raw game data provides enough clues -for emulators to guess the correct circuit board configuration, -or at least -to guess a *reasonable* configuration. -However, -relying on such heuristics often leads to problems: - - - Inventing heuristics - that correctly guess the configuration - for a particular game is very difficult. - - If you change the rules, - you really need to re-test - the console's entire game library - to check you haven't broken anything. - - Some games accidentally do the wrong thing. - - The Mega Drive game *Warrior of Rome II* - follows the rule for a European game running at 50fps, - when it's really an American game designed for 60fps. - - Some games deliberately do the wrong thing. - - The Game Boy Advance game *Top Gun - Combat Zones* - follows the rule for - (several kinds of) - save-game storage. - If it detects any save-game storage, - it assumes it's running in an emulator - and disables all the main menu options. - - Heuristics are difficult to reason about. - - If a homebrew developer - takes a game that almost does what they want - and changes it slightly, - it may cause the emulator - to do something completely different - because the modified game - is now a closer match to some other game. - - Heuristics can make sensible configurations impossible. - - If a homebrew developer wants - a particular hardware configuration - that no official games happened to use, - it may not be possible - to trigger it heuristically. - - It's not hardware accurate. - - The original console did not use heuristics - to guess a hardware configuration, - it just used the actual configuration - of the actual hardware. - -Manifests provide a way to describe -*exactly* what hardware configuration to use, -no guessing required, -avoiding all these problems entirely. - -Where do manifests come from? ------------------------------ - -Ideally, -everybody who extracts the data from a game cartridge would -also record the board configuration in a manifest file. -Unfortunately, -manifests were invented long after cartridge extracting, -so there are a lot of previously extracted games -with no manifest attached. - -If a game doesn't come with a manifest, -it may be possible to look up the correct manifest. -The -[SNES Preservation Project](https://preservation.byuu.org/) -intends to re-dump every Super Famicom game -and record its board configuration at the same time. -Given a game's data, -you can take the SHA256 fingerprint -and look it up in the Project's database -to find the correct manifest to use. - -Unfortunately, -this doesn't help for any other console. -Even for the Super Famicom, -there will always be games -too rare to acquire for re-dumping, -and homebrew that was never on a physical cartridge to begin with. -For these games, -heuristics will always be needed as a fallback, -but at least if the heuristics are wrong -they can be overridden. - -If you are a homebrew author -or have dumped a previously-unknown cartridge, -and want to write a manifest yourself, -you should read the [official manifest specification][manifest]. - -[manifest]: https://doc.byuu.org/higan/manifests/ - -Ignoring manifests ------------------- - -Occasionally, -a newly-dumped game will turn out to have -a configuration that can't be expressed -in the existing manifest file format, -and a new format must be designed. -If manifests were always written inside game folders, -games with old-format manifests -would break when played in emulators that supported the new format. - -Therefore, -icarus [defaults](../interface/icarus.md#the-icarus-settings-dialog) -to not writing out manifests when it imports games, -and higan [defaults](../interface/higan-settings.md#advanced) -to ignoring manifests that are present. -Instead, -when higan loads a game, -it will ask icarus to generate a temporary manifest in the latest format, -based on the files present in the game folder -and how they are likely to go together. - -If the manifest that icarus generates -for some particular game -is broken or buggy, -you'll need to switch the manifest machinery back on -so you can fix it: - - - Turn on "Create manifests" in icarus' settings - - Re-import the game in question - to store the broken manifest - as `manifest.bml` in the game folder. - - Edit `manifest.bml` as you see fit - - Turn off "Ignore manifests" in higan's settings - - Load the game in higan to check that your changes fixed the problem - -If the manifest format changes in the future, -you'll have to repeat this process -to create a fixed manifest in the new format. diff --git a/docs/concepts/save-states.md b/docs/concepts/save-states.md deleted file mode 100644 index 06587ac3..00000000 --- a/docs/concepts/save-states.md +++ /dev/null @@ -1,129 +0,0 @@ -A real game console -is a complex piece of hardware, -with electricity flowing through it -in complex patterns that can't easily -be paused or recorded. -However, -an emulated console is pure software: -it only changes when the emulation software -deliberately updates it, -so the emulator software can save -the entire state of the emulated console -to disk, -and weeks or months later -bring it back to life -as though nothing had ever happened. - -Save states versus in-game saves --------------------------------- - -Some games include their own systems -for saving and restoring the player's progress. -Here are some of the differences -between save states and in-game saves: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Save statesIn-game saves
- Work exactly the same way - in every game - - Works differently in different games, - some games don't support it at all -
- Save at any time, - anywhere in the game - - Save only at special save-points -
- Loading a save - puts the game back exactly how it was - when you pressed save - - Loading a save - restores some things - (like the player's inventory - or remaining lives), - but may - forget others - (like taking you back to the beginning of the level) -
- You can have dozens of save states - - Most games limit you to about 3 saves -
- Can only be loaded - by the same version of the same emulator - that created it - - Works with any version of any emulator, - can sometimes even be copied to or from physical cartridges -
- -**Note:** -Loading a save state -will reset the entire emulated console -to the way it was when the save state was created, -*including in-game saves*. -If you create a save state, -then make an in-game save, -then load the save state, -**your in-game save will be lost**. -Don't do that. - -Quick states ------------- - -higan has five Quick State slots, -which can be used from -[the Tools menu](../interface/higan.md#the-tools-menu), -or with the appropriate -[hotkeys](../interface/higan-settings.md#hotkeys). - -Quick states are useful -as extra checkpoints -in games whose checkpoints are too far apart, -or in games that don't have checkpoints at all. -Map the "Save Quick State" and "Load Quick State" hotkeys -to your controller, -and you can cheese your way through just about anything. - -Manager states --------------- - -higan's -[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. - -Manager States are more cumbersome to use than Quick States, -since they cannot be accessed with hotkeys, -but are useful when you want quick access -to many different parts of a game. diff --git a/docs/credits.md b/docs/credits.md deleted file mode 100644 index 70656ebc..00000000 --- a/docs/credits.md +++ /dev/null @@ -1,63 +0,0 @@ -higan's original author: - - - byuu - -We'd like to acknowledge -many invaluable contributions made to higan -by the following individuals: - - - Andreas Naive - - Ange Albertini - - anomie - - AWJ - - Bisqwit - - blargg - - Łukasz Krawczyk - - Cydrak - - Danish - - DMV27 - - Dr. Decapitator - - endrift - - Fatbag - - FitzRoy - - gekkio - - GIGO - - Hendricks266 - - hex_usr - - ikari_01 - - jchadwick - - Jonas Quinn - - kode54 - - krom - - Lioncash - - Lord Nightmare - - lowkey - - MerryMage - - Matthew Callis - - mightymo - - Nach - - ncbncb - - neviksti - - OV2 - - Overload - - p4plus2 - - quequotion - - RedDwarf - - Richard Bannister - - Ryphecha - - segher - - Sintendo - - SuperMikeMan - - tetsuo55 - - TmEE - - TRAC - - wareya - - zones - -It's been a long, wild ride... -apologies to anyone we've missed! - -For more information, -see the [credits thread]( -https://helmet.kafuka.org/byuubackup2/viewtopic.php@f=4&t=1631.html) -on the archive of the official forums. diff --git a/docs/faq.md b/docs/faq.md deleted file mode 100644 index f506d906..00000000 --- a/docs/faq.md +++ /dev/null @@ -1,283 +0,0 @@ -I see "tearing" when a game scrolls. How can I enable vsync? ------------------------------------------------------------- - -higan supports synchronising video output -to the display's vertical-synchronisation (or "vsync") signal, -but the option is hidden -because it often causes more problems than it solves -(see the next question). -To enable video synchronisation: - - - Open higan's configuration file, `settings.bml` - - On Windows, look in `%LOCALAPPDATA%\higan` - or beside `higan.exe` - - On Linux, look in `~/.local/share/higan` - - Open it in your favourite text editor - (Windows Notepad will corrupt the file, - use WordPad if you don't have anything better) - - Find the line that says "Video" - - Somewhere below that, find an indented line - that says "Synchronize:false". - - Change "false" to "true" - - Save your changes to `settings.bml` - and restart higan - -Why is video synchronisation a problem for higan? -------------------------------------------------- - -**The short version:** -Turning on video synchronisation -cleans up video tearing, -turning on audio synchronisation -cleans up audio glitches, -but turning on both -makes audio glitches worse. - -**The long version:** -Enabling video synchronisation -locks the frame-rate of the emulated console -to the frame-rate of your computer's display. -If your display's refresh rate exactly matches -the emulated console's, -games play at the correct speed -and everything's fine. - -However, -modern 60Hz displays do not always match -the emulated console's refresh rate: - - - The Super Famicom usually runs a little faster than 60Hz - - the PAL variants of most consoles run at 50Hz - - the WonderSwan runs at 75Hz - - While the Game Boy does run its LCD at 60Hz, - games can turn the LCD off and on at any time, - requiring emulation to pause - until it can get back in sync - with the computer display. - -Because of these frame-rate differences, -enabling video synchronisation -can force games to run -faster or slower than intended. - -The consoles that higan emulates -produce video frames and audio samples at a particular rate. -If video synchronisation causes -the emulated console to run, say, 5% faster than intended, -that means audio samples are also being produced 5% faster. -You might not notice the changed game speed, -but you'll almost certainly notice -the game's audio glitching constantly -as your sound card tries to keep up. - -Enabling -[audio synchronisation](interface/higan.md#the-settings-menu) -normally fixes this kind of audio glitching, -but with video synchronisation it makes things worse: -audio is likely to glitch -while higan waits for a video frame to be shown, -and video is likely to stutter -while higan waits for an audio buffer to complete. - -Games run too fast ------------------- - -higan runs as fast as it can, -but it will pause and wait -for the audio and video drivers to catch up -if [audio synchronisation](interface/higan.md#the-settings-menu) -and [video synchronisation][vsync] -are enabled, respectively. -If games are running way too fast, here are some things to check: - - - Make sure "Synchronize Audio" is ticked in - [the Settings menu](interface/higan.md#the-settings-menu) - - Make sure the Audio driver is not set to "None" - in [the Advanced settings](interface/higan-settings.md#advanced) - (remember to restart higan if you change driver settings) - - Make sure your computer has speakers or headphones connected - (some computers disable all audio if no outputs are available) - - If you want the game to be silent, - tick "Mute Audio" in - [the Settings menu](interface/higan.md#the-settings-menu) - - If you can't connect speakers or headphones to your computer, - or you did but it didn't help, - try enabling the secret [video synchronisation][vsync] option. - -[vsync]: #i-see-tearing-when-a-game-scrolls-how-can-i-enable-vsync - -Games run too slow ------------------- - -Of all the consoles higan can emulate, -higan's Super Famicom emulation -is the most resource intensive. -Full-speed emulation for the Super Famicom base unit -requires an Intel Core 2 Duo (or AMD equivalent), -full-speed for games with the SuperFX chip -requires an Intel Ivy Bridge (or equivalent), -full-speed for the wire-frame animations in *Mega Man X2* -requires an even faster computer. -Low-power CPUs like ARM chips, -or Intel Atom and Celeron CPUs -generally aren't fast enough to emulate the Super Famicom with higan, -although other emulated consoles may work. - -If your computer meets the general speed requirements -but games run too slowly, -try choosing a different -[audio driver](interface/higan-settings.md#advanced), -since that's usually what drives higan's timing. - -On some computers, -the operating system's power-management system -may be confused by higan's unusual pattern of CPU usage -(it runs furiously to calculate the next video frame -and the next few milliseconds of audio, -then stops dead as it waits for output to complete). -If holding down -the [fast forward hotkey](interface/higan-settings.md#hotkeys) -runs too fast but the game normally runs too slow, -try disabling "power saver" mode -or enabling "performance" mode. - -On Linux specifically, -if your desktop environment doesn't provide a way -to change the CPU usage governor, -you can temporarily force your CPUs to run at full-speed -by running the following command in a terminal: - - echo "performance" | sudo tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor - -To put things back to normal, -reboot the computer, or run this command instead: - - echo "ondemand" | sudo tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor - -Why is higan so much slower than other emulators? -------------------------------------------------- - -The consoles higan emulates -generally contain different devices -(say, a CPU, an audio chip and a video chip) -that do their own thing, -but can interrupt each other at any time. -Games can and do depend on timing details like -"when the audio chip is done playing this sound, -it will interrupt the CPU at exactly the right time -for the CPU to fiddle with the video chip". -higan is therefore very cautious about timing: -while it's emulating the CPU (for example), -at every point the emulated audio chip *might* interrupt -the emulated CPU, -higan switches to emulating the audio chip up to the same point -to find out whether it *will* interrupt the CPU. - -In this way, -higan is a little bit like -an office-worker trying to do the jobs of three other people -by running from desk to desk, -sending the same emails -that those three people would send to each other, -leaving itself a note at each desk to remind it -where it was up to when it comes back. -Although this constant switching -is slow and inefficient, -higan does it -to ensure the emulated console -always matches the behaviour -of the original. - -Other emulators, -especially ones that are popular on phones and tablets, -typically work differently. -Although emulated devices *can* interrupt each other at any time, -usually they don't, -and often the only exceptions are a handful of unpopular games. -So it's pretty safe -(and much, much more efficient) -to let certain devices run "ahead" of the others. -For example, -letting the video chip render an entire scanline at a time -instead of working pixel-by-pixel. -The downside is that some games don't work properly -in these emulators, -with game-breaking bugs, -minor visual glitches, -or anything in between. - -Some emulators try to recognise -when the user loads a specific problematic game, -and will adjust the shortcuts the emulator takes -so that the game runs correctly. -This is a good way to increase game compatibility -without losing efficiency, -but it means the emulator does not accurately reflect -how the original console worked, -and it requires the emulator authors to diagnose and work around -each individual supported game, -instead of having one emulator that works for everything. - -Why can't higan use multiple CPU cores? ---------------------------------------- - -These days, -most computers contain multiple CPU cores, -allowing them to run different programs -(or different parts of the same program) -at the same time. -Since higan requires high CPU performance, -sometimes people suggest that it should split its work -into multiple threads -so it can run across multiple cores -instead of stressing one core while the others lie idle. -After all, -the original consoles higan emulates -had separate devices running independently, -so why not run each emulated device in a separate thread? - -The big problem with this approach is timing. -The devices in a physical Super Famicom (for example) -run at whatever speed they run at, -and talk to each other whenever they feel like. -Because every Super Famicom uses the exact same components, -every Super Famicom runs compatible games at the exact same speed, -and games can blindly assume that -when operation X is complete on device A, -device B will have finished operation Y -and be ready to do something new. -Meanwhile, higan's emulated components -take an unpredictable amount of time to do their work, -so without deliberate synchronisation -things would break almost immediately. - -It's not practical to make higan's emulated devices -do their work in exactly the same amount of time -as their hardware counterparts. -The problem is forty years of technology -designed to make programs run as fast as possible: -optimising compilers -and super-scalar, out-of-order CPU architectures -change programs to make them faster, -speeding up some programs more than others -in ways that are very difficult to understand and predict. -Even if higan's emulated devices -ran at the exact, correct speed -on one particular computer, -they'd still run differently on -a computer with a smarter CPU, -or when compiled with a smarter compiler. - -Since higan needs its emulated components -to run at particular speeds, -and it's not practical -to make them run at those speeds naturally, -it must force them manually. -An emulated device runs for a little while, -then all the others are run until they catch up. -It's this careful management, -regular stopping and starting, -that makes higan slow, -not the actual emulation of each device. -Having multiple CPU cores waiting on each other -would not help them wait any faster. diff --git a/docs/guides/drivers.md b/docs/guides/drivers.md deleted file mode 100644 index 36d0beab..00000000 --- a/docs/guides/drivers.md +++ /dev/null @@ -1,143 +0,0 @@ -Unfortunately, -there's no cross-platform standard for -displaying video, -playing audio, -and accepting input from game controllers. -Or rather, -there are many standards, -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 your computer. -To see what drivers you're currently using, -or to choose different ones, -go to the [Advanced tab] of the Settings window. - -[Advanced tab]: ../interface/higan-settings.md#advanced - -Here are the most notable drivers -for each platform -in each category. -If your copy of higan -includes a driver not listed here, -it's probably a reasonable choice, -so try it out and see how you like it. - -**Note:** After changing any driver, -you must restart higan for the change to take effect. - -**Note:** -Video, Audio and Input -all have a special driver named "None". -This is a dummy driver that does nothing -(draws no video, -plays no audio, -accepts no input), -so don't choose it unless you're -trying to diagnose problems with other drivers. - -Video ------ - -On Windows: - - - **OpenGL** is the best choice, - since it's fast - and it supports [custom shaders](shaders.md), - but requires support for OpenGL 3.2. - This excludes some older and weaker hardware. - - **Direct3D** is a good choice - if OpenGL is unavailable. - It also allows - [Exclusive fullscreen](../interface/higan-settings.md#video), - bypassing Windows' desktop compositor. - - **GDI** is the safest choice, - but performs very poorly at large sizes. - -On Linux: - - - **OpenGL** is the best choice, - since it's fast - and it supports [custom shaders](shaders.md), - but requires support for OpenGL 3.2. - You can check what version of OpenGL - your system supports by running - `glxinfo | grep 'core profile version'` - in a terminal. - - **XVideo** is also fast, - but may be low-quality, - and generally only supports the "Blur" shader, - not "None". - - **XShm** is the safest choice, - but performs very poorly at large sizes. - -Audio ------ - -On Windows: - - - **ASIO** offers the lowest possible latency, - but is the least likely to work on any given computer. - - **WASAPI** offers low latency, - but is only slightly more likely to work than ASIO. - It also offers - [Exclusive Mode](../interface/higan-settings.md#audio), - which can improve audio quality and lower latency, - but may be better or worse than shared mode - in practice. - - **XAudio2** is a good choice, - but it requires the latest (June 2010) version - of the [DirectX 9 End-User Runtime][dx9] - to be installed. - - **DirectSound** is the safest choice, - and not a bad one. - -[dx9]: https://www.microsoft.com/en-us/download/details.aspx?id=35 - -On Linux: - - - **PulseAudio** or **PulseAudioSimple** - are almost certainly the drivers to use, - since almost every Linux distribution uses - [PulseAudio](https://en.wikipedia.org/wiki/PulseAudio) - to manage audio output. - The two drivers should behave identically, - but some users report one working better than the other. - - **ALSA** is a good choice - for Linux distributions that do not use PulseAudio. - If PulseAudio is running, - this will wind up using PulseAudio's ALSA emulation, - or failing due to "sound card already in use", - unless you use a tool like `pasuspender`. - - **OSS** may be useful - for non-Linux platforms, - or for Linux systems with the third-party OSSv4 - kernel drivers installed. - For most Linux systems, - this will use ALSA's OSS emulation, - PulseAudio's OSS emulation, - or not work at all. - -**Note:** -By default, -higan uses the audio driver to regulate its emulation speed. -If games run too fast on your computer, -see [Games run too fast](../faq.md#games-run-too-fast) in the FAQ. - -Input ------ - -On Windows, -"Windows" is the only driver available, -and uses RawInput for keyboard and mouse input, -XInput for Xbox controllers, -and DirectInput for other controllers. - -On Linux: - - - **udev** supports every input device, - but requires a modern Linux system. - - **Xlib** is the safest choice, - but only supports keyboard and mouse input. diff --git a/docs/guides/import.md b/docs/guides/import.md deleted file mode 100644 index 4c9978b6..00000000 --- a/docs/guides/import.md +++ /dev/null @@ -1,696 +0,0 @@ -Before it can load a game, -higan requires that all the game's data -be stored correctly in the [Game Library]. -For [regular games](#regular-games) -this is simple, -but some games require special treatment, -especially those that make use of -unusual hardware. - -Regular games -------------- - -higan's importing tool, [icarus], can import games -in the most commonly-used formats -for each supported console, -and also those same formats inside `.zip` files -(as long as the `.zip` file contains only one game). -More advanced compression formats -like RAR or 7-zip are not supported. - -To import a game, -open the [Systems menu], -choose "Load ROM File ..." -to open a [filesystem browser], -choose the ROM file of the game you want to play, -and it will be imported into the library -and (if possible) start playing. - -**Note:** -If you want to import many games, -run icarus directly. -See the [icarus] documentation for details. - -To play a game for a particular console from your library, -open the [Systems menu], -then choose the appropriate console menu item. -A filesystem browser will appear -listing all the games in the library -for that particular console. -Select the game you want to play -and click the Open button, -or just double-click the game, -and it will begin playing. - -**Note:** -Sometimes -the NTSC and PAL variants of a particular console -behave differently, -or the Japanese and American variants. -When choosing a game from the Game Library, -a drop-down list in the bottom-right of the filesystem browser -allows you to choose which regional variant -of the console higan should emulate. -For most consoles, -higan can reliably guess which variant to use, -and the list defaults to "Auto". - -Games with co-processor firmware --------------------------------- - -Many games included extra chips inside the game cartridge, -to provide enhanced capabilities of one kind or another. -Sometimes, -those extra chips were separate CPUs -running their own separate firmware, -and for those cases -higan requires a copy of the co-processor firmware -as well as the actual game data. -Unfortunately, -like games themselves, -most co-processor firmware cannot legally be distributed, -so you'll need to -obtain copies of the relevant firmware data -for yourself. - -To import a game that requires co-processor firmware, -the easiest approach is to drop the firmware files into -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). - -If the easy approach doesn't work for a particular game, -it may be because icarus has incorrectly guessed -which firmware that game needs. -To ensure icarus uses specific firmware with a specific game, -you must combine the game data and the firmware into a single file. -For example, -let's say you want to import *Super Bases Loaded 2* for the Super Famicom, -which is stored in the file `sbl2.sfc` -and requires firmware for the DSP1 co-processor -stored in `dsp1.program.rom` and `dsp1.data.rom`. -On Windows, -you can combine them from the command-line like this: - -```dos -copy /b sbl2.sfc + dsp1.program.rom + dsp1.data.rom -``` - -On Linux, -the equivalent command-line syntax is: - -```bash -cat dsp1.program.rom dsp1.data.rom >> sbl2.sfc -``` - -(note the use of `>>` to append rather than `>` to overwrite) - -**Note:** -For co-processor chips with multiple firmware files, -always put the "program" file before the "data" file. - -Wikipedia [lists which Super Famicom games use which co-processors][wpec], -although not all co-processors require separate firmware. -Once you've figured out which co-processor -(if any) -is used by the game you want to import, -here's the firmware files you'll need: - -[wpec]: https://en.wikipedia.org/wiki/List_of_Super_NES_enhancement_chips#List_of_Super_NES_games_that_use_enhancement_chips - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Co-processorFilenameSize (bytes)SHA256
CX4
See Note 1		cx4.data.rom3072ae8d4d1961b93421ff00b3caa1d0f0ce7783e749772a3369c36b3dbf0d37ef18
DSP1/1A
See Note 2		dsp1.data.rom20480b5da6533e55852ee8fc397977ec5576c5b9f1fb2e05656d8f87123a121b076e
dsp1.program.rom6144269584b347a22953a2989494c850a7c1c027f4ca5add517a60e0c7d8833d0fac
DSP1B
See Note 3		dsp1b.data.rom20488546cbac530830446bb8a277f6b139d4ad64d650bdbac7e4e150e2f095665049
dsp1b.program.rom61442eccb54a8f89374911f7e2db48f1b4cde855655e28103f7bda2982a5b418a187
DSP2dsp2.data.rom20483beef9bffdc1e84c9f99f3301d8bd3e520d2e62909a995320f9faeae8f46ec11
dsp2.program.rom614462a2ef8d2d7db638f4ec0fbcebf0e5bf18a75ee95be06e885d9519a10487f0da
DSP3dsp3.data.rom20487fe51796e9c97fee1fa2aab40592b7c78997f67dd00333e69d0f79a12f3cb69f
dsp3.program.rom6144aea7b622e7c1de346cb15d16afcbedf92b6798507e179f83ed2a4cff40d0e663
DSP4dsp4.data.rom2048ef3ffb4256dd896a60213269b4e2d3bdd120c97e2fd623bddabbf43c2be422af
dsp4.program.rom614489b1826e6038be3a0ea0f923e85d589ff6f02dc1a1819fb2ec8c0cea5b333dcd
ST010st010.data.rom4096dc7056a51b53993d7a8ba5bacf9501f785d2fce5e5be748e9ff2737c5938d4a5
st010.program.rom491522c1f74bb5f466d81c64c326e71ac054489efe1abc9a5d6f91aac7747f2ddab67
ST011st011.data.rom4096b5377d1bebe8adc507a024b6e2b9b8fdf4877e451da84fbad05dff4e4a70311e
st011.program.rom49152d90a5cda380e81cb9ba11a9da7539b173c49b31bedc7a3ac9c3c8b3f97e89e14
ST018st018.data.rom32768c67032238b7182696cb80cf41b61bacda91adb2120b5370bea20c9dbf5cc79b8
st018.program.rom1310726cceff3c6945bb2672040066d218efcd2f31492f3f5c28916c8e53435c2c887e
- -**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 3:** -The DSP1B is very similar to the DSP1A, -but fixes some bugs. -Note that icarus' heuristics cannot distinguish between -a game that uses the DSP1 -and one that uses the DSP1B, -so if it cannot find your game in its database, -it will assume it uses DSP1B. -Many games work just as well with either variant, -but *Pilotwings* requires the DSP1 firmware, -while *Ballz 3D* requires the DSP1B. - -If you try to import a game with icarus, -but it cannot find the required firmware files, -a window will appear saying -"Import completed, but with 1 errors. View log?" -(or however many games were lacking firmware). -If you press "Yes", -a new window will appear listing the games that couldn't be imported, -and what problem was detected: - -> [sbl2.sfc] ROM image is missing data: dsp1.program.rom; dsp1.data.rom - -If you try to import a game -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 "Unloaded" in -[the status bar](../interface/higan.md#the-status-bar). - -Once a game with co-processor firmware is imported, -you can play it just like any [regular game](#regular-games). - -Satellaview games ------------------ - -The [Satellaview] -was a satellite modem peripheral -released for the Super Famicom in Japan. -As well as the actual modem -(designed to sit underneath the Super Famicom), -it also included a cartridge -with software to control the modem, -browse online services, -and download games and data. -This control cartridge was called -*BS-X Sore wa Namae o Nusumareta Machi no Monogatari*, -which in English is -*BS-X The Story of The Town Whose Name Was Stolen*. - -[Satellaview]: https://en.wikipedia.org/wiki/Satellaview - -The control cartridge had a slot that accepted -re-writable "memory paks", -so that people could store the games and data they downloaded. -A small number of games that did not use the Satellaview modem -also had a memory pak slot, -so the game's publishers could -publish extra content for the game -via the Satellaview service -after the game's release. -For the benefit of people who didn't own a Satellaview -some read-only memory paks -were sold in retail stores -containing extra content for specific games. - -Importing a game that has a slot for a memory pak -is just like [importing a regular game](#regular-games). - -To import a memory pak, -you should use [icarus]. -You can use the "Load ROM File ..." menu item -in the [Systems menu], -but higan cannot actually load a memory pak directly, -so once you choose a file to load -it looks like nothing has happened. - -When importing a memory pak, -the name of the memory pak file *must* end in `.bs` -(if it's in a `.zip` file, -that's OK, -but the name *inside* the `.zip` file -must end in `.bs`) -in order for it to be successfully imported. -Sometimes memory pak filenames end in `.sfc`, -which will make higan try to import them as -regular Super Famicom games -and fail. -Rename the file and it should work beautifully. - -Playing a game that has a slot for a memory pak -is just like playing a regular game, -but after you have selected which game you want to play -higan will open another [filesystem browser] -to let you pick which previously-imported memory pak -you want to insert into the game. -If you press "Cancel" at this point, -the game will load without any cartridge in its memory pak slot. - -If you load the control cartridge into higan, -make sure the emulated Satellaview -is connected to the emulated Super Famicom's expansion port -by opening the "Super Famicom" menu, -selecting the "Expansion Port" sub-menu, -and choosing "Satellaview". -If the expansion port was previously -configured with a different option, -power-cycle the Super Famicom -(also in the "Super Famicom" menu) -to make sure the control cartridge will find the Satellaview -when it starts up. -Note that higan's Satellaview emulation is not very accurate, -so the control cartridge may not work as it should. - -Playing a memory pak on its own doesn't make much sense, -it's not a standalone cartridge. -Play a game with a memory pak slot, -and choose which memory pak you want when higan asks for it. - -For more information about the Satellaview service, -a translation patch for the control cartridge -and emulators that do a better job of Satellaview emulation, -see [the BS-X Project](https://bsxproj.superfamicom.org/). - -Sufami Turbo games ------------------- - -The [Sufami Turbo] -was a special cartridge released -for the Super Famicom in Japan. -The Sufami Turbo on its own does nothing, -but it has two slots in the top -that accept Sufami Turbo mini-cartridges. -The game in slot A is the one that actually plays, -but some games can make use of additional data -from a game in slot B. - -Importing the Sufami Turbo cartridge -is just like [importing a regular game](#regular-games). - -To import a mini-cartridge, -you should use [icarus]. -You can use the "Load ROM File ..." menu item -in the [Systems menu], -but higan cannot actually load a mini-cartridge directly, -so once you choose a file to load -it looks like nothing has happened. - -When importing a mini-cartridge, -the name of the file *must* end in `.st` -(if it's in a `.zip` file, -that's OK, -but the name *inside* the `.zip` file -must end in `.st`) -in order for it to be successfully imported. -Sometimes mini-cartridge filenames end in `.sfc`, -which will make higan try to import them as -regular Super Famicom games, -and fail miserably. -Rename the file and it should work beautifully. - -To play a Sufami Turbo game, -load the Sufami Turbo cartridge like any other game. -higan will open another [filesystem browser] -to let you pick which previously-imported mini-cartridge -you want to insert into slot A. -If you press "Cancel" at this point, -the Sufami Turbo cartridge will boot without anything in slot A, -which just displays an image telling you -to turn off your Super Famicom, -insert a game into slot A, -and try again. -If you chose a cartridge for slot A, -higan will open yet another -filesystem browser -to let you choose a mini-cartridge for slot B. -If you press "Cancel" at this point, -the Sufami Turbo cartridge will boot without anything in slot B. - -If you play Sufami Turbo games regularly, -you may want to add the Sufami Turbo base cartridge -to the [Systems menu] -so you don't have to tell higan where it is every time. - -[Sufami Turbo]: https://en.wikipedia.org/wiki/Sufami_Turbo - -Super Game Boy games --------------------- - -The Super Game Boy was a special cartridge -released for the Super Famicom -(and all its regional variants around the world) -that allowed Game Boy games to be played -via the Super Famicom's controllers and video output. -The Super Game Boy does not emulate the Game Boy hardware, -it physically includes all the Game Boy components -so compatibility with Game Boy games is high. -However, the Super Game Boy drives the Game Boy hardware -from the Super Famicom's timing signals, which means -games play 2.4% faster than on a real Game Boy. - -The Super Game Boy 2 was a Japan-only release -that fixed the timing problem of the original Super Game Boy, -and included a different set of default borders. -higan emulates the Super Game Boy 2 completely, -including the timing change. - -Because the Super Game Boy cartridge includes -the original Game Boy hardware, -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: - - - - - - - - - - - - - - - - - - - - - - - - -
CartridgeFilenameSize (bytes)SHA256
SGBsgb1.boot.rom2560e4ddff32fc9d1eeaae812a157dd246459b00c9e14f2f61751f661f32361e360
SGB2sgb2.boot.rom256fd243c4fb27008986316ce3df29e9cfbcdc0cd52704970555a8bb76edbec3988
- -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] -to let you pick which previously-imported Game Boy game -you want to insert into the Super Game Boy. -If you press "Cancel" at this point, -higan will crash, so don't do that. - -If you regularly play Game Boy games -through the Super Game Boy, -you may want to add it to the [Systems menu] -so you don't have to tell higan where it is every time. - -**Note:** -Only games for the original, black-and-white Game Boy -can be used with the Super Game Boy. -Some games designed for the Game Boy Color -were backward compatible with the original Game Boy -and hence the Super Game Boy; -see [Playing Game Boy Color games in Game Boy mode][blackcarts] -for details. - -[blackcarts]: ../notes.md#playing-game-boy-color-games-in-game-boy-mode - -MSU1 games ----------- - -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 MSU1 is not specific -to any particular storage medium, -it gives the Super Famicom similar capabilities -to CD-based add-ons -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 MSU1 was invented for higan, -it is now supported by other Super Famicom emulators too. -The [SD2SNES] programmable cartridge -even allows you to play MSU1 games on a real console. -There are a number of homebrew games -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 MSU1 game -is that early firmware versions of the SD2SNES -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 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 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, - it may be that the existing audio is only slightly boosted, - so try the "hardware" version first, for best quality. - - If the audio tracks are heavily boosted, - the "hardware" patch may sound terrible, - distorting and clipping, - in which case try the "emulator" patch. - -To import an MSU1 game: - - 1. If you have a single, large file - with the `.msu1` extension, - that is a pack for use with [Mercurial Magic], - which can automatically set up a game folder - in the correct format. - Go read Mercurial Magic's documentation - instead of these instructions. - 2. Otherwise, - import the Super Famicom ROM with icarus, - [like a regular game](#regular-games). - - 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 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, - apply the patch with a tool like [Flips], - then import the patched file. - - If there's "hardware" and "emulator" versions of the patch, - 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. 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 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`. - 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 - `track-1.pcm`, - `track-2.pcm`, - ... `track-9.pcm`, - `track-10.pcm`, - etc. - - If there's no files with those names, - there should be other numbered `.pcm` files - that you can rename to match what higan expects. - - If the `.pcm` files have no numbers in the filenames, - there maybe a `.bml` or `.xml` file that lists - which number goes with which file. - - If there's no `.pcm` files at all, - that's OK, - this game probably just doesn't use the audio-playback feature. - -Once the game folder is set up, -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/qwertymodo/Mercurial-Magic - -Patched games -------------- - -The console emulation community -has a long and vibrant history of game modding, -or [ROM hacking], -including fan-translations, -new levels for existing games, -and more. -Since distributing the modified versions of existing games -would be copyright infringement, -the changes are typically distributed as "patches", -a file containing a list of modifications to make, -that can be automatically applied by a "patcher" tool -like [Flips]. - -higan does not support soft-patching, -so if you want to play a patched game in higan, -you will need to use a patcher to apply it yourself, -creating a new, patched copy of the game. - -Then you can import and play the patched game just like -[a regular game](#regular-games). - -[ROM hacking]: http://www.romhacking.net/ - -Game Boy Advance games ----------------------- - -Before you can play Game Boy Advance games, -you must provide a copy of the Game Boy Advance BIOS. -Unlike game-specific firmware, -the GBA BIOS was part of the console, -not the cartridge, -so it must be installed -[into higan](../install/general.md). - -Once the GBA BIOS is installed, -GBA games can be imported and played just like -[any other games](#regular-games). - -Note that some GBA games -have trouble with -[in-game saves](../notes.md#in-game-saves-and-the-game-boy-advance). - -PowerFest '94 -------------- - -[PowerFest '94](https://en.wikipedia.org/wiki/Nintendo_PowerFest_%2794) -was a video game competition -organised by Nintendo, -in which contestants had six minutes -to complete a challenge based on three Super Famicom games. -The PowerFest '94 cartridge -was custom-built for the competition, -and included the three base games -as well as software to run each game, -switch between them after a specific time, -extract a score, -and display the combined total at the end. - -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]. - -[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 -[icarus]: ../interface/icarus.md -[Systems menu]: ../interface/higan.md#the-systems-menu diff --git a/docs/guides/shaders.md b/docs/guides/shaders.md deleted file mode 100644 index ec184838..00000000 --- a/docs/guides/shaders.md +++ /dev/null @@ -1,217 +0,0 @@ -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 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 "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: - - - **None** - draws each computer pixel according to - the colour of the single nearest console pixel, - sometimes called "nearest neighbour" scaling. - This produces unnaturally crisp and blocky images. - - 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. - - **Blur** - draws each computer pixel according to - the weighted average colour - of the four nearest console pixels, - sometimes called "bilinear" scaling. - This produces unnaturally blurry images. - -In addition to those, -the OpenGL driver also supports custom shaders. - -**Note:** -For technical reasons, -higan's emulation of certain consoles -can produce surprising behaviour -in certain shaders, -particularly shaders that compare each console pixel -with its neighbours. -See [Video Shaders and TV-based consoles][vstv] for details. - -[vstv]: #video-shaders-and-tv-based-consoles - -Where to get custom shaders ---------------------------- - - - higan includes some simple example shaders. - If your copy of higan did not come with shaders, - you can get them from the [unofficial higan repository]. - - [quark-shaders] contains many high-quality shaders for use with higan. - - You can write your own. - -[unofficial higan repository]: https://gitlab.com/higan/higan/tree/master/shaders -[quark-shaders]: https://github.com/hizzlekizzle/quark-shaders - -How to install custom shaders ------------------------------ - -Make sure the shader you want to install -is in the correct format: -it should be a folder whose name ends in `.shader`, -it should contain a file named `manifest.bml`, -and probably some `*.fs` or `*.vs` files. - -Place the shader folder inside -the `shaders` folder -of your higan installation. -If you don't have a `shaders` folder, -create it beside the `systems` folder -and `settings.bml`. - - - On Windows, - this is probably the folder containing `higan.exe` - - On Linux, - this is probably `~/.local/share/higan` - -Launch higan, -open the [Settings menu], -and choose "Advanced ..." to open -the [Advanced tab] of the Settings window. -Under "Driver Selection", -make sure "Video" is set to "OpenGL". -If it wasn't already set that way, -you'll need to restart higan -for the change to take effect. - -Open the Settings menu again, -choose the "Shader" sub-menu, -and now the shaders you installed -should be listed at the bottom of the menu. - -Load a game -(so you can see the results), -switch between shaders -to see what they do, -and pick your favourite! - -Notable examples ----------------- - -The quark-shaders repository mentioned above -contains lots of carefully-crafted shaders, -but some are particularly noteworthy: - - - **AANN** implements "anti-aliased nearest neighbour" scaling. - This uses anti-aliasing to hide - the rounding errors often introduced by - aspect ratio correction - and non-integral scaling, - producing an image nearly as crisp as the "None" shader, - but without the distracting ripple effect. - - **Gameboy** emulates the squarish aspect-ratio, - greenish-colours, - and limited palette - of the original Game Boy. - At larger scales, - you can even see the fine gaps between each pixel, - and the shadow that dark colours would cast - on the LCD background. - - **NTSC** performs NTSC encoding, - bandwidth limiting, - and NTSC decoding of the video image to recreate - the colour fringing, - blurring - and shimmer - that most game players would have seen - on real televisions. - Some games depend on NTSC artefacts - to display colours outside the console's official palette - or to create effects like transparency. - -Video Shaders and TV-based consoles ------------------------------------ - -Simple shaders -(like "None" -and the third-party "AANN" shader) -just blindly scale up the images they're given, -but sophisticated shaders -(such as the third-party "xBR" shader) -try to produce higher-quality output -by recognising particular patterns, -like taking three diagonal pixels -and turning that into a smooth diagonal line. - -These shaders assume that -each pixel drawn by the game's artists -becomes a single pixel in the video output they analyze. -The hand-held consoles that higan emulates -(and also the Famicom) -can only output video at one specific resolution, -so this "one pixel equals one pixel" rule holds true, -and pattern-based shaders like "xBR" work just fine. -Unfortunately, -this is not true for most of the TV-based consoles -that higan supports. - -The Super Famicom's "normal" video mode -draws 256 pixels across the width of the screen, -but the "high resolution" mode draws 512. -Since Super Famicom games can enable hi-res mode at any time -(even halfway through a frame), -higan always renders Super Famicom video output 512 pixels wide, -just in case. -This means that in "normal" mode, -each pixel drawn by the game's artists -becomes two pixels in the video output, -breaking the assumption -that pattern-based shaders are based on. - -The Super Famicom has a similar issue in the vertical direction: -normally, -an NTSC-based Super Famicom draws about 240 rows of output every frame, -sometimes referred to as "240p" video. -When a game turns on "interlaced" mode, -it draws the 240 odd-numbered lines of one frame, -then the 240 even-numbered lines of the next, -and so forth. -This is sometimes referred to as "480i" video. -Although interlaced mode cannot be enabled mid-frame -like high-resolution mode, -resolution switching is still complex, -so higan always draws all 480 lines of video output. -This means for a normal, non-interlaced game, -each pixel drawn by the game's artists -becomes four pixels in the video output -(two horizontally and two vertically) -making pattern-based shaders even less useful. -It also breaks most scanline-emulation shaders, -since they typically draw a scanline -for each row of pixels in the video output. - -The Mega Drive has similar problems -to the Super Famicom. -It has the same behaviour with interlacing, -but its high-resolution mode switches -from 256 pixels across to 320 pixels across. -Therefore in normal mode, -each pixel drawn by the game's artists -becomes five pixels in the video output, -while in high-resolution mode, -each pixel drawn by the game's artists -becomes four pixels in the video output -(or 10 and 8 pixels in non-interlaced mode). - -The PC Engine does not support an interlaced mode, -but its horizontal resolution is much more flexible -than the Super Famicom or Mega Drive, -and so it has the same problems with shaders as those consoles. - -[Settings menu]: ../interface/higan.md#the-settings-menu -[video driver]: drivers.md#video -[Advanced tab]: ../interface/higan-settings.md#advanced diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 9612dcce..00000000 --- a/docs/index.md +++ /dev/null @@ -1,123 +0,0 @@ -higan, the multi-system emulator -================================ - -higan emulates a number of 2D video-game consoles, -allowing you to play classic games on a modern general-purpose computer. - -To get started with higan right away, -see the [Quick Start](qs.md) section of the documentation. - - -About higan ------------ - -As of v107, -higan has top-tier support for the following consoles: - - - Nintendo Super Famicom/Super Nintendo Entertainment System, - including add-on hardware: - - Super Game Boy - - Sufami Turbo - - Nintendo Game Boy Advance - -It also includes some level of support for these consoles: - - - Satellaview add-on for the Super Famicom - - Nintendo Famicom/Nintendo Entertainment System - - Nintendo Game Boy - - Nintendo Game Boy Color - - Sega Master System - - Sega Game Gear - - Sega Mega Drive/Genesis - - NEC PC Engine/TurboGrafx 16 (but not the CD-ROM² System/TurboGrafx-CD) - - NEC SuperGrafx - - Bandai WonderSwan - - Bandai WonderSwan Color - - Pocket Challenge v2 - -**Note:** Some consoles were released under different names -in different geographic regions. -To avoid listing all possible names -every time such a console is mentioned, -higan uses the name from the console's region of origin. -In practice, -that means Japanese names: -"Famicom" and "Super Famicom" instead of "NES" and "SNES", -"Mega Drive" instead of "Genesis", -"PC Engine" instead of "TurboGrafx-16". - -higan is actively supported on -FreeBSD 10 and above, and -Microsoft Windows 7 and above. -It also includes some level of support -for GNU/Linux and macOS. - -higan is officially spelled with a lowercase "h", not a capital. - -About this document -------------------- - -This is the semi-official higan manual, -a community-maintained introduction and reference. -It may be out of date -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 unofficial forum. - -Official higan resources ------------------------- - - - [Official homepage](https://byuu.org/emulation/higan/) - -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 - since approximately v067r21. - - [Quark shader repository](https://github.com/hizzlekizzle/quark-shaders) - collects shaders that higan can use - to add special effects like TV scanlines to its video output, - 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 MSU1 games and mods into a format - higan can use. - See [Importing MSU1 games][msu1] for details. - -[shaders]: guides/shaders.md -[msu1]: guides/import.md#msu1-games - -There are also other projects -based on current or older versions of higan, -in whole or in part, -that you might want to check out. - - - [Mednafen](https://mednafen.github.io/) - is another multi-system emulator. - Its Super Famicom emulation is based on bsnes v059, - from the time before bsnes was renamed to higan. - - [BizHawk](http://tasvideos.org/BizHawk.html) - is another multi-system emulator, - specialising in the creation of - tool-assisted speed-runs. - Its Super Famicom emulation is based on bsnes v087. - - [bsnes-plus](https://github.com/devinacker/bsnes-plus) - is a fork of bsnes v073 - that adds improved support for debugging Super Famicom software. - - [bsnes-mercury](https://github.com/libretro/bsnes-mercury/) - is a fork of bsnes v094 - adapted to work as a - [libretro](https://www.libretro.com/) emulation core. - - [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. - It also restores the "balanced" Super Famicom emulation core - that was removed from higan in v099, - which is less CPU intensive - than the current accuracy-focused core. diff --git a/docs/install/general.md b/docs/install/general.md deleted file mode 100644 index a6690077..00000000 --- a/docs/install/general.md +++ /dev/null @@ -1,53 +0,0 @@ -Installing the GBA BIOS ------------------------ - -For most of the systems higan emulates, -the console itself contains (almost) no actual software, -so emulating the system does not require -infringing the copyright of the hardware manufacturer. -However, -the Game Boy Advance is different: -every device contains a standard library of software routines -for [common functions games require][bios], -often called a "BIOS" -by analogy with the Basic Input/Output System -used in IBM PC compatibles. -Although the GBA BIOS is required -in order to emulate GBA games, -it cannot be distributed with higan -for the same legal reasons that commercial games -cannot be distributed with higan, -so you'll need to obtain a copy of the BIOS for yourself. - -If you have a real GBA and a flash-cart, -the Internet contains many tools -that will extract the BIOS image so it can be copied -to your desktop computer. -The correct GBA BIOS file is exactly 16,384 bytes long, -and has the SHA256 hash -`fd2547724b505f487e6dcb29ec2ecff3af35a841a77ab2e85fd87350abd36570`. - -Once you have the correct BIOS file: - - 1. rename it to `bios.rom` - - if you're using Windows, - turn off "hide extensions for known file types" - so you don't wind up with a file called - `bios.rom.dat` - or whatever the file's original extension was. - 2. Copy the file into higan's `Game Boy Advance.sys` folder, - alongside the `manifest.bml` file that is already there. - - In Windows, - find `Game Boy Advance.sys` in the same folder - as `higan.exe` - - In Linux, - find `Game Boy Advance.sys` in - `~/.local/share/higan/` - -**Note:** -If you upgrade this version of higan to a newer version, -make sure the `bios.rom` file -winds up in the `Game Boy Advance.sys` folder -of the new version. - -[bios]: http://problemkaputt.de/gbatek.htm#biosfunctions diff --git a/docs/install/linux.md b/docs/install/linux.md deleted file mode 100644 index 1455431f..00000000 --- a/docs/install/linux.md +++ /dev/null @@ -1,142 +0,0 @@ -Compiling from source on Linux ------------------------------- - -You will need a copy of the higan source-code. -If you download an official release from the higan homepage, -you will need [7-zip](http://www.7-zip.org) -or a compatible tool to extract it. -Alternatively, -you may obtain higan source code from -[the unofficial git repo](https://gitlab.com/higan/higan/) -using the Git source-code management tool, -or by clicking the download button on the right-hand side of the web-page -and choosing an archive format. - -You will also need GCC 7 or higher, -including the C and C++ compiler, -GNU Make, -and development files -(headers, etc.) -for the following libraries: - - - GTK 2.x - - PulseAudio - - Mesa - - gtksourceview 2.x - - Cairo - - SDL 2.0 - - libXv - - libAO - - OpenAL - - udev - -On a Debian-derived Linux distribution -(including Ubuntu and Mint), -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 libsdl2-dev \ - libxv-dev libao-dev libopenal-dev libudev-dev - -Once you have all the dependencies installed, -you may build and install higan. - -Note: Run these commands as yourself, -**do not run them as root** -(no `sudo`, no `su`, etc.), -because higan does not support -being installed system-wide. - - 1. Put the higan source code in some convenient location, - like `~/higan-src` - 2. Open a terminal window - 3. Type `cd ~/higan-src` - (or wherever you put the higan source) - 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 - -Installing a compiled build on Linux ------------------------------------- - -Assuming you have successfully compiled higan -as described in the previous section: - - 1. Open a terminal window - 2. Type `cd ~/higan-src` - (or wherever you put the higan source) - 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 - 5. If the higan source includes a `shaders` subdirectory, - type `make -C shaders install` - to install the example - [video shaders](../guides/shaders.md). - -This installs higan and its associated data files -into the `~/.local` directory hierarchy. - -To confirm higan is installed correctly, -type `higan` in a terminal and press Enter. -If the higan window appears, -everything is working. -On the other hand, -if you get an error message like "command not found", -you should double-check that the directory `~/.local/bin` -is included in your `$PATH` environment variable -by running the following command in a terminal: - - echo "$PATH" | tr ':' '\n' | grep ~/.local/bin - -If the above command prints the full path of `~/.local/bin` -(for example: `/home/yourname/.local/bin`) -then you should be good. -If it prints nothing, -you need to add the following line to `~/.profile`: - - export PATH=~/.local/bin:$PATH - -(this line must be in `~/.profile` because -most GUIs do not read any other files at login) - -If you also have a `~/.bash_profile`, -make sure it reads the contents of `~/.profile` -with a line like this: - - source ~/.profile - -You will need to log out and log back in -for changes to `~/.profile` or `~/.bash_profile` -to take effect. - -Uninstalling a compiled build on Linux --------------------------------------- - -To uninstall higan, -as installed by the above instructions: - - 1. Open a terminal window - 2. Type `cd ~/higan-src` - (or wherever you put the higan source) - 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, -you should also delete the following directories -if they exist: - - - `~/.config/higan/` - - `~/.config/hiro/` - - `~/.local/share/higan/` - - `~/.local/share/hiro/` - -To remove the games imported into higan's library -(including in-game saves and save-states), -delete the directory `~/Emulation`. - -You may also wish to delete the higan source directory. diff --git a/docs/install/windows.md b/docs/install/windows.md deleted file mode 100644 index 541e8d0a..00000000 --- a/docs/install/windows.md +++ /dev/null @@ -1,169 +0,0 @@ -Installing an official release on Windows ------------------------------------------ - -Official higan releases are distributed in -[7-zip](http://www.7-zip.org/) -archives. -You will need to install 7-zip -(or another compatible archiving tool) -to install higan. -Once you have a suitable archiving tool, -extract the contents of the higan archive into a new folder. - -When you're done, -the new folder should contain `higan.exe` and `icarus.exe` -along with other assorted files and folders -that describe the systems higan emulates. -You may put that new folder wherever you like. - -To run higan, open the `higan.exe` file. - -Uninstalling an official release on Windows -------------------------------------------- - -Delete the folder containing `higan.exe` -and the other associated data from the original archive. - -To remove higan's configuration: - - 1. Press Win+R to open the Run dialog - 2. Type `%LOCALAPPDATA%` and press Enter - to open the folder where higan's configuration data lives - 3. Delete the sub-folders named `icarus` and `higan` - if they exist. - -You might also want to remove -[higan's game library](../concepts/game-library.md#where-is-the-game-library) -(including in-game saves and save-states). - -Compiling from source on Windows --------------------------------- - -You will need a copy of the higan source-code. -If you download an official release from the higan homepage, -you will need [7-zip](http://www.7-zip.org/) -or a compatible tool to extract it. -Alternatively, -you may obtain higan source code from -[the unofficial git repo](https://gitlab.com/higan/higan/) -using the Git source-code management tool, -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 that supports C++17 to compile higan. -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). - -[MinGW-W64]: https://mingw-w64.org/ - -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. -You should see a message like - -```text -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. -``` - -...except it should mention the compiler version that you installed -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", -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 the compiler is installed: - - 1. Put the higan source code in some convenient location, - like `C:\higan-src` - 2. Open the command-prompt - 3. Type `cd C:\higan-src` - (or wherever you put the higan source) - and press Enter - 4. Type `mingw32-make -C icarus` and press Enter - to build the icarus import tool - 5. Type `mingw32-make -C higan target=higan` and press Enter - to build the main higan executable - -Installing a compiled build on Windows --------------------------------------- - - 1. In Windows Explorer, - create the folder where you want higan to live - 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 - into the new folder - 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 - 6. Copy `C:\higan-src\higan\systems` - into the new folder - 7. If the higan source includes a `shaders` folder, - copy it into the new folder too. - -The new folder should now contain -`icarus.exe`, -`higan.exe`, -and folders named `Database`, `Firmware`, `systems`, -and possibly `shaders`. -This is what you would get by downloading an official build, -as described under -[Installing an official release on Windows][instwin] -above. - -[instwin]: #installing-an-official-release-on-windows - -Uninstalling a compiled build on Windows ----------------------------------------- - -The process is the same as -[Uninstalling an official release on Windows][uninstwin] -above. You may also wish to delete the higan source folder. - -[uninstwin]: #uninstalling-an-official-release-on-windows diff --git a/docs/interface/common.md b/docs/interface/common.md deleted file mode 100644 index 028d6d47..00000000 --- a/docs/interface/common.md +++ /dev/null @@ -1,61 +0,0 @@ -The Filesystem Browser ----------------------- - -Sometimes higan will need you -to choose a file or folder. -For this, it uses a special Filesystem Browser dialog. -Although many operating systems provide a native filesystem browser, -they do not all allow the same customisations. -Therefore, -higan provides its own filesystem browser -that works the same way on every platform. - -The filesystem browser shows the contents of some particular folder, -and allows you to select one of those items. - -Across the top of the window, -a text-box displays the path of the current folder. -If you want to browse a specific path, -you may edit the contents of this box -and press Enter to switch to the new location. - -The ![two-blue-arrows](refresh.png) button is "Refresh". -Pressing this button will check -if anything has been added to or removed from the current folder -and update the list to match. - -The ![house](home.png) button is "Home". -Pressing this button will switch to your home folder. - -The ![up-arrow](up.png) button is "Parent". -Pressing this button will -switch to the parent of the current folder. - -Most of the filesystem browser lists the contents -of the current folder. -Double-clicking a folder, -or selecting it and pressing Enter, -will switch to showing the contents of that folder. -If the list has keyboard focus, -typing any text will jump to the first item in the list -whose name begins with the text you typed. - -If a drop-down list appears in the bottom-left, -it allows you to choose which files appear in the list, -based on file-extension. - -If this filesystem browser is asking for a file, -you can choose one -by double-clicking it, -by selecting it and pressing Enter, -or by selecting it and clicking the "Select" button in the bottom-right. - -If this filesystem browser is asking for a folder, -you can choose one -by selecting it and clicking the "Select" button in the bottom-right. -Double-clicking -or selecting and pressing Enter don't work, -they just switch to viewing the contents of that folder. - -The "Cancel" button in the bottom-right -closes the filesystem browser without selecting anything. diff --git a/docs/interface/down.png b/docs/interface/down.png deleted file mode 120000 index 4213a70d..00000000 --- a/docs/interface/down.png +++ /dev/null @@ -1 +0,0 @@ -../../hiro/resource/icon/go/down.png \ No newline at end of file diff --git a/docs/interface/higan-cli.md b/docs/interface/higan-cli.md deleted file mode 100644 index 616f1165..00000000 --- a/docs/interface/higan-cli.md +++ /dev/null @@ -1,96 +0,0 @@ - -# Synopsis - -> higan [*\-\-fullscreen*] [*GAME* [*SUBGAME1* [*SUBGAME2*]]] - -# Description - -When launched with `--fullscreen`, -higan will automatically enter fullscreen mode -when it starts, -otherwise it starts in windowed mode. -This is not much use unless you also specify `GAME`, -because you won't be able to load a game -until you exit fullscreen mode -by pressing the "Toggle Fullscreen" -[hotkey](higan-settings.md#hotkeys). - -When `GAME` is not given, -higan starts with no game loaded. - -When `GAME` is the path to an existing -[game folder](../concepts/game-folders.md) -for any supported console, -that game will automatically be loaded -after higan starts. - -When `GAME` is the path to a ROM file -for any supported console, -it will be imported into a game folder in -[the Game Library](../concepts/game-library.md), -and loaded from there after higan starts. - -When `GAME` is of the form `REGION|PATH` -(that is, -a region code, -a vertical bar (`|`), -and a path to a game folder or ROM file) -higan will load the game at `PATH` -into the `REGION` variant of the appropriate console, -rather than detecting which variant the game expects. -This is the command-line equivalent -of choosing a region from -the drop-down in the bottom-right of the filesystem browser window -when you [load a game from the game library](../guides/import.md#regular-games). -The list of region codes differs from console to console, -so load a game from the library -and check the list -before loading it from the command-line. - -When `GAME` refers to a game with -a [Satellaview](../guides/import.md#satellaview-games) memory pak slot, -`SUBGAME1` should be -the path to a game folder or ROM file -representing the memory pak to insert into the slot. -If `SUBGAME1` is not supplied, -higan will prompt for one. -`SUBGAME2` is ignored. - -When `GAME` refers to -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. -If `SUBGAME1` is not supplied, -higan will prompt for one. -`SUBGAME2` is ignored. - -When `GAME` refers to -the [Sufami Turbo](../guides/import.md#sufami-turbo-games), -then `SUBGAME1` should be -the path to a game folder or ROM file -representing the mini-cartridge to be inserted into -slot A of the Sufami Turbo base cartridge, -and `SUBGAME2` is the same thing for slot B. -higan will prompt for -any mini-cartridges not supplied on the command-line. - -When `GAME` refers to any other game, -both `SUBGAME1` and `SUBGAME2` are ignored. - -# Examples - -Play a previously-imported copy of Super Mario World -in fullscreen (assuming Linux defaults): - -```sh -higan --fullscreen "$HOME/Emulation/Super Famicom/Super Mario World.sfc" -``` - -Play a previously-imported copy of Sonic the Hedgehog 3, -forcing higan to emulate a Japanese Mega Drive: - -```sh -higan "NTSC-J|$HOME/Emulation/Mega Drive/Sonic the Hedgehog 3.md" -``` diff --git a/docs/interface/higan-settings.md b/docs/interface/higan-settings.md deleted file mode 100644 index 8fc2eeb8..00000000 --- a/docs/interface/higan-settings.md +++ /dev/null @@ -1,453 +0,0 @@ -The Settings window -appears when you choose -one of the items at the bottom of -[the Settings menu](higan.md#the-settings-menu), -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. - -Systems -======= - -This tab configures the contents of -[the Systems menu](higan.md#the-systems-menu), -so you can make it easier to load the games you care about -and hide things that get in the way. - -Each item in the list represents -a single item in the Systems menu. -If the box at the left is ticked, -that item will be included in the menu, -otherwise it will be hidden—but higan will remember its configuration -in case you want to show it again. - -At the bottom left are -![up-arrow](up.png) and ![down-arrow](down.png) buttons. -These move the selected item -upward or downward in the list. - -The **Append** button in the lower right -adds a new item to the end of the list. -It opens the [System Properties](#system-properties) dialog, -so you can enter the details of the new item. -If you don't want the new item to be at the end, -you can use the up and down buttons -in the lower left -to move it to its intended location. - -The **Modify** button in the lower right -opens the [System Properties](#system-properties) dialog -for the selected item, -so you can make changes. - -The **Remove** button in the lower right -removes the selected item from the list entirely. -Unlike hiding the item, -this forgets whatever configuration the item had. - -System Properties ------------------ - -This dialog appears when clicking "Append" or "Modify" -in the [Systems](#systems) tab. -It allows you to configure a new ("Append") or existing ("Modify") entry -in the [Systems menu](higan.md#the-systems-menu). - - - **System** controls which console will be emulated - when this menu-item is chosen. - - **Load** controls what game will be loaded - into the emulated console - when this menu-item is chosen. - - If left blank, - higan will open [a filesystem browser](common.md#the-filesystem-browser) - allowing you to pick a previously-imported game from - the [game library](../concepts/game-library.md). - - If you choose a particular game, - higan will immediately load it - when the menu-item is chosen. - If the game requires additional data - (for example, the Super Game Boy requires a Game Boy cartridge) - higan will prompt for it. - - **Alias** controls the name of this item, - as displayed in the Systems menu. - - **Append** (present in "Append" mode) closes the dialog - and adds a new item with this configuration - to the list. - - **Modify** (present in "Modify" mode) closes the dialog - and updates the configuration of - the item being modified. - - **Cancel** closes the dialog without making any changes. - -Video -===== - -This tab contains options that affect -how higan displays -the emulated console's video output. - -**Color Adjustment** -settings adjust the colour and brightness -of the emulated console's video output: - - - **Saturation** adjusts the vibrancy of colours displayed, - where 0% makes things black-and-white, - 100% is normal, - and 200% is garishly exaggerated colour. - - **Gamma** adjusts how bright mid-range colours are - compared to the brightest colours, - where 100% is normal, - and 200% makes mid-range colours much darker. - This is in addition to - any adjustment applied by - the "Colors" option - 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 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. - - **Vertical** - removes pixels from the top and bottom of the video output. - -The units are "pixels in the emulated console's standard video-mode". -For example, setting "Horizontal" to 8 -will clip 8/256ths from the left and right sides -of the Super Famicom's video output, -whether the Super Famicom is in -lo-res (256px) or hi-res (512px) -mode. - -**Fullscreen** -settings apply -when higan is running fullscreen, -because it was started with the `--fullscreen` -[command-line option](higan-cli.md) -or because the user pressed -the Toggle Fullscreen [hotkey](higan-settings.md#hotkeys). - - - **Exclusive Mode** - requests exclusive access - to the computer's video output - when higan enters fullscreen mode. - This prevents other applications - or the operating system itself - from drawing anything, - and may also temporarily disable any kind of compositing, - reducing video latency. - As of v107, - only the Direct3D video driver is capable of exclusive mode; - with other drivers this option does nothing. - -Audio -===== - -This tab contains options that affect -how higan reproduces -the emulated console's audio output. - -**Driver** -settings affect -the current [Audio driver](../guides/drivers.md). - - - **Device** allows you to choose - which audio device higan sends - the emulated game's audio to, - if you have more than one. - - **Frequency** controls the sample-rate that higan will use - when generating audio. - If your PC's audio hardware has a "native" sample-rate - and you know what it is, - pick that. - Otherwise, - 44.1kHz or 48kHz should be fine. - - **Latency** controls how much audio output higan calculates in advance. - Higher values reduce the chance of - "popping" or "glitching" noises, - but increase the delay between an action occurring on-screen - and the corresponding sound-effect being played. - - **Exclusive Mode** appears - if the current audio driver - allows higan to take exclusive control of your PC's audio output, - so no other applications can play sounds. - This can improve audio quality, - and lower the effective audio latency. - -**Effects** -are applied to the emulated audio output -before it is sent to your computer's speakers. - - - **Volume** controls the overall loudness of - the emulated console's audio, - where 100% is normal volume, - and 0% is complete silence. - - **Balance** controls the relative loudness of - the left and right 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. - -Input -===== - -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). - -To choose which of the possible controllers to configure: - - - 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. - -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. - -To configure the selected controller: - - - The mapping list includes - every button and axis on the selected controller, - and the PC inputs that will be mapped to it - when it is connected to the selected port of the selected console. - - **Erase** removes the mapping - for the selected button or axis. - - **Reset** removes all the mappings currently in the list. - -To map -a keyboard or gamepad button on your PC to -a controller button, -double-click the controller button in the list, -or select it and press Enter. -The Settings window will grey out, -and a message will appear in the bottom left: -"Press a key or button to map [the button]". -Press the key or button you want to map, -and it should appear in the list -next to the controller button it is mapped to. - -To map -a mouse button on your PC to -a controller button, -select the controller button in the list, -then click one of the "Mouse Left", -"Mouse Middle", -or "Mouse Right" buttons in the bottom-left of the Settings window. - -To map -a joystick axis on your PC to -a controller axis, -double-click the axis in the list, -or select it and press Enter. -The Settings window will grey out, -and a message will appear in the bottom left: -"Press a key or button to map [the axis]". -Press the joystick in the direction you want to map, -and it should appear in the list -next to the controller axis it is mapped to. - -To map -a mouse axis on your PC to -a controller axis, -select the axis in the list, -then click one of the -"Mouse X-axis", -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 -to exit the "Press a key or button to map..." mode -without actually mapping anything. - -**Note:** -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 Advance][gbarumble] -for details. - -[gbcrumble]: ../notes.md#rumble-compatibility-for-game-boy-color -[gbarumble]: ../notes.md#rumble-compatibility-for-game-boy-advance - -**Note:** -Once you've configured which computer inputs -higan should route to which controllers, -make sure the controller in question -is actually connected to the correct controller port -in [the console menu](higan.md#the-console-menu). - -Hotkeys -======= - -This tab is like "Inputs" above, -except it contains controls for higan itself -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 - 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. - This is useful when the mouse is being used to emulate - a light-gun controller like the Super Scope. - - **Save Quick State** saves the current state of the emulated console - to the currently-selected [Quick State][qstates] slot. - - **Load Quick State** restores the emulated console - to the state saved in the currently-selected [Quick State][qstates] slot. - - **Decrement Quick State** selects the previous [Quick State][qstates] slot. - The status bar will briefly display the new current slot number. - - **Increment Quick State** selects the next [Quick State][qstates] slot. - The status bar will briefly display the new current slot number. - - **Pause Emulation** pauses the emulated console - until the Pause Emulation hotkey is pressed a second time, - or "Pause Emulation" is chosen from - [the Tools menu](higan.md#the-tools-menu).. - - **Fast Forward** disables audio and video synchronisation - for as long as it's held down, - so emulation proceeds as quickly as possible. - If your PC struggles to hit "real time" - (60fps for most emulated consoles), - this likely won't have any effect. - - **Soft Reset** restarts the emulated console's CPU - while leaving the console's memory untouched, - just like the "Soft Reset" menu item - in [the console menu](higan.md#the-console-menu). - This hotkey does nothing - when the "Soft Reset" item - does not appear in the console menu. - - **Power Cycle** turns the emulated console off and back on - (a "hard reset"), - just like the "Power Cycle" menu item - in [the console menu](higan.md#the-console-menu). - - **Rotate Display** will rotate the display - of the Game Boy Advance - and WonderSwan (Color). - See [Game Boy Advance rotation](../notes.md#game-boy-advance-rotation) - and [WonderSwan rotation](../notes.md#wonderswan-rotation) - for details. - -[qstates]: ../concepts/save-states.md#quick-states - -Advanced -======== - -This tab contains all the settings -that didn't fit into one of the other categories. - -**Driver Selection** -tells higan how to -accept input, -display video, -and play sound -on this computer. - - - **Video** controls how higan will draw - the emulated console's video output - to the PC screen. - "None" means no video will be drawn. - - **Audio** controls how higan will present - the emulated console's audio output. - "None" means no audio will be played. - - **Input** controls how higan checks for input - from the PC's input devices. - "None" means the emulated console cannot be controlled. - -See [Choosing drivers](../guides/drivers.md) -for help choosing which drivers you should use. - -**Game Library** -configures how higan interacts -with the [Game Library](../concepts/game-library.md). - - - **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 - the [manifest](../concepts/manifests.md) file - in the loaded game's - [game folder](../concepts/game-folders.md) - in favour of asking icarus - 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 - [in-game saves](../concepts/save-states.md#save-states-versus-in-game-saves) - to disk during gameplay, - instead of only when higan exits. - This may cause stuttering, - but means that you haven't lost everything - if higan crashes, - or your computer loses power. - - Note that this does not include - [game notes](higan-tools.md#game-notes) diff --git a/docs/interface/higan-tools.md b/docs/interface/higan-tools.md deleted file mode 100644 index 49b0f48f..00000000 --- a/docs/interface/higan-tools.md +++ /dev/null @@ -1,148 +0,0 @@ -The Tools window -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. - -Cheat Editor -============ - -For some consoles, -higan supports applying temporary changes to the code of a running game. -For example, -you could disable the code that detects when the player takes damage, -resulting in an "invulnerability" mode. -Currently, -higan supports cheats for the following consoles: - - - Famicom - - Super Famicom - - Game Boy - - Master System - - PC Engine - - Wonder Swan - -To add a new cheat, -select an unused row in the list, -then type the relevant codes in the "Code(s)" field at the bottom, -and a description in the "Description" field. -See [Cheat code formats](#cheat-code-formats) -for a description of the codes higan understands. - -To enable or disable an existing cheat, -tick the checkbox in the first column of the list. -The change should take effect immediately. - -To clear out an existing cheat, -select it from the list -and click the "Erase" button in the bottom right, -or just manually delete -the contents of the "Code(s)" and "Description" fields. - -To clear out all existing cheats, -click the "Reset" button in the bottom right. - -Changes made in the Cheat Editor are saved to disk -when the game is unloaded, -or when higan exits. -higan stores the known cheats for a particular game -in `higan/cheats.bml` -inside the game's [game folder](../concepts/game-folders.md). - -If your copy of higan includes a cheat database -(a file named `cheats.bml` -in the same folder as `Super Famicom.sys` -and the other `*.sys` folders), -you can click the "Find Codes ..." button in the bottom left -to load all known cheats for the currently-running game. - -Cheat code formats ------------------- - -A cheat code of the format `addr=data` -will cause the emulated console to obtain `data` -whenever it reads from memory address `addr`. -A cheat code of the format `addr=comp?data` -will cause reads from `addr` to obtain `data`, -but only if the true value at `addr` is `comp`. -In both formats, -`data` is a single byte expressed as two hexadecimal digits, -`comp` is also a single byte expressed as two hexadecimal digits, -and `addr` is a memory address in the emulated console, -expressed as however many hexadecimal digits are required -for the console in question -(typically 4 for 8-bit CPUs, -6 for 16-bit CPUs, -and 8 for 32-bit CPUs). - -For compatibility with older versions of higan, -the older syntaxes of `addr/data` and `addr/comp/data` -are still supported. - -For cheats that require more than a single-byte change, -higan allows multiple codes to be combined with `+` -so that all of them can have a single description -and be toggled with a single click. -For example, -in Super Mario World, -you can lock the time to 999 with these codes: -`7e0f31=09+7e0f32=09+7e0f33=09`. - -State Manager -============= - -The State Manager allows you to create, -load, -and remove Manager states. -For more information on Manager states, -quick states, -saved games -and how they compare, -see [Save States](../concepts/save-states.md). - -To save the current state of the loaded game -in a new slot, -or to replace the contents of an existing slot, -select the slot in the list -then click "Save" in the bottom-left corner. -You can then type a description in the "Description" field, -to help you find the state again later. - -To rename a state, -select the slot in the list -and edit the "Description" field. - -To load a state, -select the slot in the list -and click "Load" in the bottom-left corner, -or just double-click the slot. - -To clear the state out of a slot, -select the slot in the list -and click "Erase" in the bottom-right corner. - -To clear all the slots at once, -click "Reset" in the bottom-right corner. - -Manifest Viewer -=============== - -As described in -[Game Manifests](../concepts/manifests.md), -higan uses a "manifest" to -describe how the various parts of a game cartridge -are wired up together. -The Manifest Viewer lets you examine -the configuration higan is using for the loaded game. - -Game Notes -========== - -The Game Notes tab -is a place where you can write whatever you want -about the running game. -This information is automatically stored inside -the [game folder](../concepts/game-folders.md) -and loaded back into this tab -every time the game is loaded. diff --git a/docs/interface/higan.md b/docs/interface/higan.md deleted file mode 100644 index 5e2b996c..00000000 --- a/docs/interface/higan.md +++ /dev/null @@ -1,413 +0,0 @@ -When you launch higan -the main window appears, -with a menu-bar across the top, -a status-bar across the bottom, -and a large area in the middle that shows -the running game's video output. - -The Systems menu ----------------- - -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). - -You can customise this menu -in [higan's Systems settings](higan-settings.md#systems) -to hide systems you don't care about, -or add a specific cartridge for any supported system. -This makes it more convenient -to play games that involve mini-cartridges: -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. -It will be imported and immediately start playing. -See [Importing and playing games](../guides/import.md). - -The console menu ---------------- - -**Note:** -The console menu does not appear -until a game is loaded. -Also, -it's not named "console", -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. - -The console menu contains commands relevant -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 -to the first controller port, -if there is one. -See [higan's Input settings](higan-settings.md#input) -for information about configuring -which PC controller inputs are used -for the emulated controllers. - -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 Port 2** -allows you -to connect different emulated controllers -to the second controller port, -if there is one. -See [higan's Input settings](higan-settings.md#input) -for information about configuring -which PC controller inputs are used -for the emulated controllers. - -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 -to the console's expansion port, -if there is one. - -For the Super Famicom, -the [21fx][21fx] is a homebrew device -that allows a program running on a PC -to control a physical Super Famicom (or SNES). -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, -like pressing the "reset" button -on a physical console. - -This menu item does not appear -for consoles that did not have a "reset" button, -like hand-helds. - -It also does not appear for the Sega Master System, -since that console's reset button is wired up like a controller -rather than directly attached to the CPU. -To reset the Master System, -bind a keyboard or joypad button -to the "Reset" function -on the "Controls" controller -in the "Hardware" port -of the Sega Master System -in [higan's Input settings](higan-settings.md#input). - -**Power Cycle** -restarts the loaded game -as though the emulated console were switched off and on again. - -**Unload** -stops the current game, -as though the emulated console were switched off. -You can load a new game -from [the Systems menu](#the-systems-menu). - -[21fx]: https://github.com/defparam/21FX - -The Settings menu ------------------ - -The Settings menu allows you to configure things -that aren't specific to any particular console. - -**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. - - - **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: - - - **Blurring** - simulates the limited horizontal resolution - of standard-definition TVs - by blurring together horizontally-adjacent pixels. - For hand-held consoles, - this simulates the slow response time - of the cheap LCD screens these consoles used - by blending each output frame with the previous one. - - Games like - *Jurassic Park* for the Super Famicom - or *Chikyuu Kaihou Gun ZAS* for the Game Boy - depend on this to emulate a transparency effect. - - **Colors** - simulates the way a console's display device - differs from modern computer monitor's colour reproduction. - In particular, - it simulates the slightly-different gamma correction - 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. - -**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) -describes all the options in this sub-menu. - -**Synchronize Audio** -causes higan to wait for audio playback to complete -before resuming emulation. -This should reduce popping and glitching noises, -and slows the emulation down to approximately the correct speed. -If your PC cannot emulate at full-speed, -(60fps for most consoles, 75fps for WonderSwan) -this has no noticeable effect. - -**Mute Audio** -causes higan to not output sound from the emulated console. -The sound hardware is still emulated. - -**Show Status Bar** -causes higan to show or hide the status bar -at the bottom of the window. -This option has no effect in fullscreen mode. -See [The status bar](#the-status-bar) for more information. - -**Systems ...** -opens [higan's Systems settings](higan-settings.md#systems). - -**Video ...** -opens [higan's Video settings](higan-settings.md#video). - -**Audio ...** -opens [higan's Audio settings](higan-settings.md#audio). - -**Input ...** -opens [higan's Input settings](higan-settings.md#input). - -**Hotkeys ...** -opens [higan's Hotkeys settings](higan-settings.md#hotkeys). - -**Advanced ...** -opens [higan's Advanced settings](higan-settings.md#advanced). - -[svsa]: #why-do-synchronize-video-and-synchronize-audio-conflict - -The Tools menu --------------- - -The Tools menu -contains features for manipulating the emulated console. - -**Save Quick State** -stores the current state of the emulated console -into one of the quick state slots. -See [Save States](../concepts/save-states.md) for more information. - -**Load Quick State** -restores the emulated console to -a state previously saved to one of the quick state slots. -See [Save States](../concepts/save-states.md) for more information. - -**Pause Emulation** -pauses the emulated console -until this menu-item is selected again. -This can also be triggered by -the [pause hotkey](higan-settings.md#hotkeys). - -**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#state-manager) -of the Tools window. - -**Manifest Viewer ...** -opens the [Manifest Viewer tab](higan-tools.md#manifest-viewer) -of the Tools window. - -**Game Notes ...** -opens [the Game Notes tab](higan-tools.md#game-notes) -of the Tools window. - -The Help menu -------------- - -The Help menu contains information about higan itself. - -**Documentation** -loads the official higan documentation -in your web-browser. - -**Credits** -loads a list of people who have contributed to higan -in your web-browser. - -**About** -opens the About dialog, -which displays basic information about higan, -including the version number. - -The status bar --------------- - -The status bar appears -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 "Unloaded". - -When a game is loaded and running, -the status bar displays the current emulation speed -in frames-per-second. -For PAL-based consoles, -this should be around 50 FPS for "full speed" emulation, -for NTSC and most portable consoles the ideal speed is 60 FPS, -but the WonderSwan runs at 75 FPS. -If the number is too low, -you may need a faster computer, -or a faster [video driver](../guides/drivers.md#video). -If the number is too high, -you may need to [Synchronize Audio](#the-settings-menu), -or you may have pressed the "turbo" [hotkey](higan-settings.md#hotkeys). - -The status bar displays "Paused" -if you have pressed the "pause" [hotkey](higan-settings.md#hotkeys), -selected "Pause Emulation" from [the Tools menu](#the-tools-menu), -or if "When focus is lost: Pause Emulation" is ticked -in [higan's Input settings](higan-settings.md#input) -and the main higan window is not the foreground window. -To resume emulation, -make sure the main higan window is in the foreground, -select "Pause Emulation" from the Tools menu again, -and/or press the "pause" hotkey. - -The status bar briefly displays "Selected quick state slot X" -(where X is one of the Quick State slot numbers) -when you press the "Increment Quick State" -or "Decrement Quick State" -hotkeys, -to show which Quick State slot will be used -the next time you press the "Save Quick State" -or "Load Quick State" hotkeys. - -The status bar briefly displays "Slot X quick state does not exist" -(where X is one of the Quick State slot numbers) -when you choose a slot from the -[Tools](#the-tools-menu) → "Load Quick State" -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 "System has been power cycled" -when you choose "Power Cycle" from [the console menu](#the-console-menu), -or press the "Power Cycle" hotkey. - -The status bar briefly displays "Display rotation not supported" -when you press the "Rotate Display" hotkey -while the emulated console does not support display rotation. diff --git a/docs/interface/home.png b/docs/interface/home.png deleted file mode 120000 index 75c9289a..00000000 --- a/docs/interface/home.png +++ /dev/null @@ -1 +0,0 @@ -../../hiro/resource/icon/go/home.png \ No newline at end of file diff --git a/docs/interface/icarus.md b/docs/interface/icarus.md deleted file mode 100644 index 4e4f60ad..00000000 --- a/docs/interface/icarus.md +++ /dev/null @@ -1,100 +0,0 @@ -icarus is a separate tool -bundled with higan -that allows you to bulk-import ROM files -into higan's [game library]. - -Bulk importing ROM files ------------------------- - -icarus' main window -is [a filesystem browser](common.md#the-filesystem-browser), -with customisations: - - - The filesystem browser only lists - files with extensions typically used for ROM dumps from - consoles higan emulates, - plus `.zip` files since ROM dumps are often compressed. - - Each matching file has a check-box next to it. - - You can tick the check-box next to every listed file at once - by pressing "Select All" in the bottom-left. - - You can un-tick all the check-boxes - by pressing "Unselect All" in the bottom-left. - -Pressing "Import ..." in the bottom-right -will close the filesystem browser -then try to import all the files -whose check-boxes are ticked -into the [game library]. -icarus displays a progress dialog during the import process, -and a result window if any errors occurred. - -**Note:** Some games require extra steps to import correctly; -see [Importing and playing games](../guides/import.md) for details. - -The icarus Settings dialog --------------------------- - -Pressing "Settings ..." -in the bottom-right corner of the main icarus window -opens the settings dialog. - -The icarus Settings dialog contains the following settings: - - - **Library Location** determines - where icarus puts the games it imports. - See [Moving the Game Library][movgamelib] - for details. - - **Create Manifests** causes icarus to - include a [manifest] file - inside the [game folder] for each imported game. - See [Ignoring manifests](../concepts/manifests.md#ignoring-manifests) - for details. - - **Use Database** causes icarus to use manifest information - from its database of known-good manifests, - if it's importing a game it recognises. - For unrecognised games, - and for all games if this box is unticked, - icarus guesses the manifest data. - This option is still relevant when "Create Manifests" is unticked: - higan uses icarus to generate a manifest when a game is loaded, - not just at import-time. - -Command line ------------- - -icarus can be launched in any of the following ways: - -> icarus -> -> icarus \-\-import *FILE* -> -> icarus \-\-manifest *GAME* - -When run without arguments, -icarus runs interactively -as described under [Bulk importing ROM files](#bulk-importing-rom-files) above. - -When run with the `--import` flag, -`FILE` should be the path to a ROM file -for one of the consoles higan supports, -or a `.zip` file containing such a ROM file. -icarus will import it into the [game library] -just as it would if running interactively, -and the full path to the ressulting game folder -is printed to icarus' standard output. - -If the game cannot be imported correctly -due to missing firmware, -icarus prints no output. - -When run with the `--manifest` flag, -`GAME` should be the path to a [game folder], -such as a game previously imported into the [game library]. -icarus will examine the game, -come up with a [manifest] describing the game's memory layout, -and print it to standard output. - -[game library]: ../concepts/game-library.md -[movgamelib]: ../concepts/game-library.md#moving-the-game-library -[game folder]: ../concepts/game-folders.md -[manifest]: ../concepts/manifests.md diff --git a/docs/interface/refresh.png b/docs/interface/refresh.png deleted file mode 120000 index f4c32d38..00000000 --- a/docs/interface/refresh.png +++ /dev/null @@ -1 +0,0 @@ -../../hiro/resource/icon/action/refresh.png \ No newline at end of file diff --git a/docs/interface/up.png b/docs/interface/up.png deleted file mode 120000 index 9deab84a..00000000 --- a/docs/interface/up.png +++ /dev/null @@ -1 +0,0 @@ -../../hiro/resource/icon/go/up.png \ No newline at end of file diff --git a/docs/notes.md b/docs/notes.md deleted file mode 100644 index ec8968ee..00000000 --- a/docs/notes.md +++ /dev/null @@ -1,223 +0,0 @@ -The consoles that higan emulates -are similar in many ways, -but some of them do have particular quirks of their own. - -Music and Sound Effect Volume on the Mega Drive ------------------------------------------------ - -The Mega Drive has two different audio-generating chips: - - - the SN76489 or "PSG" chip - inherited from the Master System, - mostly used for sound-effects - - the YM2612 or "FM" chip, - mostly used for music - -With two different sound sources, -it's important that they have similar volumes -or one kind of sound will drown out the other. -Sega did *not* do this, -and different hardware revisions -used different relative volumes. - -higan currently -sets the PSG volume to [125% of the FM volume][vol], -based on [a Sega Genesis model 1 VA6][va6] that byuu owns. -If you feel sound-effects in higan's Mega Drive emulation -are too loud or too quiet compared to the music, -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://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 ---------------------------------------------- - -Games for the original Game Boy -came in solid grey cartridges, -and only supported four-shade grey-scale graphics. -ROM files for these games -typically have filenames ending in `.gb`. - -The Game Boy Color played all the original Game Boy games, -but extended the hardware to support colour graphics. -Games that required -the extra hardware in the Game Boy Color -came in transparent cartridges, -and had a slightly different shape -to prevent them from being used in original Game Boys. -ROM files for these games -typically have filenames ending in `.gbc`. - -However, -there were also some games -that could use colour if it was available, -but would stick to grey-scale if it wasn't. -These games came in black cartridges. -ROM files for these games -typically have filenames ending in `.gbc` -(since they are genuinely designed for the Game Boy Color) -or `.gbb`. - -Sometimes people ask -for higan to include these backwards-compatible Game Boy Color games -when asking for a Game Boy game to load. -However, -this would make higan much more complex -for not much benefit: -it's just the same game as in Color mode, -but with bits chopped off. -You might as well play backward-compatible games -in Game Boy Color mode -and get the full experience the developers intended. - -If you really, really want to see -what a particular game's backward-compatible mode looked like, -change the filename to end with `.gb` -(instead of `.gbc` or `.gbb`) -before [importing it](guides/import.md). -If you want to experiment -with loading in-game saves from colour-mode in monochrome mode -or vice-versa, -you can import the game once with `.gb` -and once with `.gbc`, -then manually copy files between the -[game folders](concepts/game-folders.md) -in the "Game Boy" and "Game Boy Color" sub-folders -of the [Game Library](concepts/game-library.md) folder. - -Do not expect save-states to be compatible between -Game Boy and Game Boy Color. - -In-Game Saves and the Game Boy Advance --------------------------------------- - -For most of the consoles that higan emulates, -in-game saves are simple: -the cartridge contains some battery-backed RAM -that the game accesses like any other memory, -and the game's internal header usually contains some hint -about where in memory the save data appears -and how large it is. - -The Game Boy Advance is different. -By the time of the GBA, -many save-storage technologies were available, -most with a more complex interface than plain memory. -Frustratingly, the GBA's internal header -does *not* describe which storage variant the game expects. -Therefore, -when importing a GBA game, -higan must guess which storage type to use -and sometimes it guesses incorrectly. - -If higan guesses incorrectly for a game you want to play, -you will need to override the automatically-generated manifest. -See [Ignoring manifests](concepts/manifests.md#ignoring-manifests) -for details. - -For more discussion of the GBA save type mess, -see [What's the deal with... GBA save files?][gbasaves] - -[gbasaves]: http://zork.net/~st/jottings/GBA_saves.html - -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*) -included a rumble motor within the cartridge itself. -Such cartridges generally used the "MBC5" memory mapper chip. - -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 - - Press any button on the gamepad that should shake - when the game turns on the rumble effect. - -Rumble compatibility for Game Boy Advance ------------------------------------------ - -The original Game Boy Advance -and the Game Boy Advance SP -did not support any kind of rumble or force-feedback system, -but the Game Boy Player add-on for the GameCube -allowed Game Boy Advance games -to use the rumble feature in GameCube controllers. - -Because rumble is a feature of the Game Boy Player, -to experience the rumble effect in higan -you'll need to configure the console itself: - - - Open - [higan's Input settings](interface/higan-settings.md#input) - - In the list of consoles, - select Game Boy Advance - - In the list of inputs, - double-click "Rumble" - or select it and press Enter - - Press any button on the gamepad that should shake - when the game turns on the rumble effect. - -As well as the Game Boy Player rumble feature, -some Game Boy Advance cartridges -included a rumble motor within the cartridge itself. -higan does not support this rumble technology, -but that's not a big deal: -the only two such games are *Drill Dozer*, -which can use Game Boy Player rumble, -and *WarioWare: Twisted*, -which doesn't work anyway -because it requires gyroscope hardware -that higan does not yet emulate. - -Game Boy Advance rotation -------------------------- - -Some Game Boy Advance homebrew games, -as well as a bonus mode in *Dr Mario + Puzzle League*, -expect the player to physically rotate the device -so the screen is tall rather than wide. -higan supports this feature with -a Rotate [hotkey](interface/higan-settings.md#hotkeys). - -When the user presses the Rotate hotkey, -the console's video output is rotated 90° anti-clockwise, -and the directional-pad controls are also rotated -so that (for example) pushing the button for "up" -sends the signal "right" to the emulated console, -so that the player character moves "up" on the rotated screen. - -WonderSwan rotation -------------------- - -The WonderSwan hardware -included multiple sets of buttons -so the player could hold the device -vertically or horizontally. -*Makaimura for WonderSwan* includes a level -that requires the player to repeatedly rotate -the device as they play. -higan supports this feature with -a Rotate [hotkey](interface/higan-settings.md#hotkeys). - -When the user presses the Rotate hotkey, -the console's video output is rotated 90° anti-clockwise, -and the X and Y button cluster mappings -are adjusted to match. diff --git a/docs/qs.md b/docs/qs.md deleted file mode 100644 index c58ad294..00000000 --- a/docs/qs.md +++ /dev/null @@ -1,102 +0,0 @@ -If this is your first time using higan, -welcome! -Here's a brief guide to getting started: - -Install higan -------------- - -On Windows, -this should be as easy as downloading -the latest release archive from -[the higan homepage](https://byuu.org/emulation/higan/) -and extracting it. -[More information...](install/windows.md) - -On Linux, -if your distribution doesn't already include the latest version, -you'll need to compile it yourself — but don't worry, -it's not too complex. -[More information...](install/linux.md) - -Configuring inputs ------------------- - -Once higan's installed, -start it up. -Open the "Settings" menu, -and choose "Input ..." -to open [the Input settings](interface/higan-settings.md#input). - -higan supports a *lot* of different controllers -for a lot of different consoles, -so you don't need to configure everything immediately. -For most consoles, -it's enough to just configure -whatever shows up in the list -when you choose that console. -For example, -when you pick the Super Famicom, -you're shown the inputs -for a Gamepad -in Controller Port 1. - -Once you've configured the controls -just the way you want them, -higan will remember them -— you don't need to re-configure them -every time you start higan, -or every time you load a game. - -Load a game ------------ - -From -[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. -It will be added to -[the Game Library](concepts/game-library.md), -and it will start running immediately. - -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 Systems menu, -which will list all the games for that console -in the Game Library. - -Connect a controller --------------------- - -Once the game is running, -a new menu will appear -named after the appropriate console. -For example, -if you're playing Super Mario World, -that's a Super Famicom game -so there will be a Super Famicom menu. - -Open [the console menu](interface/higan.md#the-console-menu), -and if there is a sub-menu for a controller port, -make sure the port is using -the controller you [set up previously](#configuring-inputs). -If you configured inputs for a Gamepad in Controller Port 1, -the Controller Port 1 sub-menu -should be set to Gamepad. -Like a real console, -higan's controller ports -start out with nothing plugged in, -so if the game you're playing needs a gamepad connected, -you'll have to connect it! - -This doesn't apply to hand-held consoles -like the Game Boy and WonderSwan, -since the "controller" is always connected. -This *does* apply to the Famicom, -even though the Famicom's controllers are hard-wired, -because higan uses the name "Famicom" -to refer to Nintendo's 8-bit home console -in all territories, -including the Nintendo Entertainment System. diff --git a/docs/release.md b/docs/release.md deleted file mode 100644 index c1179af9..00000000 --- a/docs/release.md +++ /dev/null @@ -1,15 +0,0 @@ -Release checklist -================= - - 1. Commit the new release - 2. Tag the commit - 3. `git push --tags origin master` to push the commit and tag at the - same time. - 4. Go to [the docs admin][rtd] and verify that it's building the new - version as 'stable' and under its tag name. - 5. Check out the `libretro` branch. - 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/ diff --git a/mkdocs.yml b/mkdocs.yml deleted file mode 100644 index 2c0dc51b..00000000 --- a/mkdocs.yml +++ /dev/null @@ -1,38 +0,0 @@ -site_name: higan - -docs_dir: docs -site_dir: docs_build -theme: readthedocs - -pages: - - Introduction: index.md - - Quick Start: qs.md - - Building and Installing: - - Windows: install/windows.md - - Linux: install/linux.md - - General: install/general.md - - User Interface: - - higan's main window: interface/higan.md - - higan's Settings window: interface/higan-settings.md - - higan's Tools window: interface/higan-tools.md - - higan's command line: interface/higan-cli.md - - icarus: interface/icarus.md - - Common: interface/common.md - - Guides: - - Importing and playing games: guides/import.md - - Using video shaders: guides/shaders.md - - Choosing drivers: guides/drivers.md - - Concepts: - - Game Folders: concepts/game-folders.md - - Game Manifests: concepts/manifests.md - - The Game Library: concepts/game-library.md - - Save States: concepts/save-states.md - - Frequently Asked Questions: faq.md - - Console-specific Notes: notes.md - - Credits: credits.md - -markdown_extensions: - - smarty - - toc: - permalink: true -