ShuriZma
/
bsnes
mirror of https://github.com/bsnes-emu/bsnes.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Remove higan docs from the bsnes fork.

This commit is contained in:
Tim Allen 2019-04-18 18:04:44 +10:00
parent e05672183b
commit 30ed7f7e0b
28 changed files with 0 additions and 4073 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
docs/checklinks.sh
View File

@ -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/

154
docs/concepts/game-folders.md
View File

@ -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

87
docs/concepts/game-library.md
View File

@ -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

149
docs/concepts/manifests.md
View File

@ -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.

129
docs/concepts/save-states.md
View File

@ -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:
<table>
<thead>
<tr>
<th>Save states</th>
<th>In-game saves</th>
</tr>
</thead>
<tbody>
<tr>
<td>
Work exactly the same way
in every game
</td>
<td>
Works differently in different games,
some games don't support it at all
</td>
</tr>
<tr>
<td>
Save at any time,
anywhere in the game
</td>
<td>
Save only at special save-points
</td>
</tr>
<tr>
<td>
Loading a save
puts the game back exactly how it was
when you pressed save
</td>
<td>
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)
</td>
</tr>
<tr>
<td>
You can have dozens of save states
</td>
<td>
Most games limit you to about 3 saves
</td>
</tr>
<tr>
<td>
Can only be loaded
by the same version of the same emulator
that created it
</td>
<td>
Works with any version of any emulator,
can sometimes even be copied to or from physical cartridges
</td>
</tr>
</tbody>
</table>
**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.

63
docs/credits.md
View File

@ -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.

283
docs/faq.md
View File

@ -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.

143
docs/guides/drivers.md
View File

@ -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.

696
docs/guides/import.md
View File

@ -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
<table>
<thead>
<tr>
<th>Co-processor</th>
<th>Filename</th>
<th>Size (bytes)</th>
<th>SHA256</th>
</tr>
</thead>
<tbody>
<tr>
<th scope="row">CX4<br><sup>See Note 1</sup></th>
<td><code>cx4.data.rom</code></td>
<td>3072</td>
<td><code>ae8d4d1961b93421ff00b3caa1d0f0ce7783e749772a3369c36b3dbf0d37ef18</code></td>
</tr>
<tr>
<th scope="row" rowspan=2>DSP1/1A<br><sup>See Note 2</sup></th>
<td><code>dsp1.data.rom</code></td>
<td>2048</td>
<td><code>0b5da6533e55852ee8fc397977ec5576c5b9f1fb2e05656d8f87123a121b076e</code></td>
</tr>
<tr>
<td><code>dsp1.program.rom</code></td>
<td>6144</td>
<td><code>269584b347a22953a2989494c850a7c1c027f4ca5add517a60e0c7d8833d0fac</code></td>
</tr>
<tr>
<th scope="row" rowspan=2>DSP1B<br><sup>See Note 3</sup></th>
<td><code>dsp1b.data.rom</code></td>
<td>2048</td>
<td><code>8546cbac530830446bb8a277f6b139d4ad64d650bdbac7e4e150e2f095665049</code></td>
</tr>
<tr>
<td><code>dsp1b.program.rom</code></td>
<td>6144</td>
<td><code>2eccb54a8f89374911f7e2db48f1b4cde855655e28103f7bda2982a5b418a187</code></td>
</tr>
<tr>
<th scope="row" rowspan=2>DSP2</th>
<td><code>dsp2.data.rom</code></td>
<td>2048</td>
<td><code>3beef9bffdc1e84c9f99f3301d8bd3e520d2e62909a995320f9faeae8f46ec11</code></td>
</tr>
<tr>
<td><code>dsp2.program.rom</code></td>
<td>6144</td>
<td><code>62a2ef8d2d7db638f4ec0fbcebf0e5bf18a75ee95be06e885d9519a10487f0da</code></td>
</tr>
<tr>
<th scope="row" rowspan="2">DSP3</th>
<td><code>dsp3.data.rom</code></td>
<td>2048</td>
<td><code>7fe51796e9c97fee1fa2aab40592b7c78997f67dd00333e69d0f79a12f3cb69f</code></td>
</tr>
<tr>
<td><code>dsp3.program.rom</code></td>
<td>6144</td>
<td><code>aea7b622e7c1de346cb15d16afcbedf92b6798507e179f83ed2a4cff40d0e663</code></td>
</tr>
<tr>
<th scope="row" rowspan="2">DSP4</th>
<td><code>dsp4.data.rom</code></td>
<td>2048</td>
<td><code>ef3ffb4256dd896a60213269b4e2d3bdd120c97e2fd623bddabbf43c2be422af</code></td>
</tr>
<tr>
<td><code>dsp4.program.rom</code></td>
<td>6144</td>
<td><code>89b1826e6038be3a0ea0f923e85d589ff6f02dc1a1819fb2ec8c0cea5b333dcd</code></td>
</tr>
<tr>
<th scope="row" rowspan="2">ST010</th>
<td><code>st010.data.rom</code></td>
<td>4096</td>
<td><code>dc7056a51b53993d7a8ba5bacf9501f785d2fce5e5be748e9ff2737c5938d4a5</code></td>
</tr>
<tr>
<td><code>st010.program.rom</code></td>
<td>49152</td>
<td><code>2c1f74bb5f466d81c64c326e71ac054489efe1abc9a5d6f91aac7747f2ddab67</code></td>
</tr>
<tr>
<th scope="row" rowspan="2">ST011</th>
<td><code>st011.data.rom</code></td>
<td>4096</td>
<td><code>b5377d1bebe8adc507a024b6e2b9b8fdf4877e451da84fbad05dff4e4a70311e</code></td>
</tr>
<tr>
<td><code>st011.program.rom</code></td>
<td>49152</td>
<td><code>d90a5cda380e81cb9ba11a9da7539b173c49b31bedc7a3ac9c3c8b3f97e89e14</code></td>
</tr>
<tr>
<th scope="row" rowspan="2">ST018</th>
<td><code>st018.data.rom</code></td>
<td>32768</td>
<td><code>c67032238b7182696cb80cf41b61bacda91adb2120b5370bea20c9dbf5cc79b8</code></td>
</tr>
<tr>
<td><code>st018.program.rom</code></td>
<td>131072</td>
<td><code>6cceff3c6945bb2672040066d218efcd2f31492f3f5c28916c8e53435c2c887e</code></td>
</tr>
</tbody>
</table>
**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:
<table>
<thead>
<tr>
<th>Cartridge</th>
<th>Filename</th>
<th>Size (bytes)</th>
<th>SHA256</th>
</tr>
</thead>
<tbody>
<tr>
<th scope="row">SGB</th>
<td><code>sgb1.boot.rom</code></td>
<td>256</td>
<td><code>0e4ddff32fc9d1eeaae812a157dd246459b00c9e14f2f61751f661f32361e360</code></td>
</tr>
<tr>
<th scope="row">SGB2</th>
<td><code>sgb2.boot.rom</code></td>
<td>256</td>
<td><code>fd243c4fb27008986316ce3df29e9cfbcdc0cd52704970555a8bb76edbec3988</code></td>
</tr>
</tbody>
</table>
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

217
docs/guides/shaders.md
View File

@ -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

123
docs/index.md
View File

@ -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.

53
docs/install/general.md
View File

@ -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

142
docs/install/linux.md
View File

@ -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.

169
docs/install/windows.md
View File

@ -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

61
docs/interface/common.md
View File

@ -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.

1
docs/interface/down.png
View File

@ -1 +0,0 @@
../../hiro/resource/icon/go/down.png

96
docs/interface/higan-cli.md
View File

@ -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"
```

453
docs/interface/higan-settings.md
View File

@ -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)

148
docs/interface/higan-tools.md
View File

@ -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.

413
docs/interface/higan.md
View File

@ -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.

1
docs/interface/home.png
View File

@ -1 +0,0 @@
../../hiro/resource/icon/go/home.png

100
docs/interface/icarus.md
View File

@ -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

1
docs/interface/refresh.png
View File

@ -1 +0,0 @@
../../hiro/resource/icon/action/refresh.png

1
docs/interface/up.png
View File

@ -1 +0,0 @@
../../hiro/resource/icon/go/up.png

223
docs/notes.md
View File

@ -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.

102
docs/qs.md
View File

@ -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.

15
docs/release.md
View File

@ -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/

38
mkdocs.yml
View File

@ -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