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

docs: Review and update docs for v107. 

Changes include:

- The "Library" menu was replaced with the "Systems" menu
- The "Settings" menu was reorganised
- Game Boy rumble is now under the MBC5 "controller" for the cartridge "port",
  instead of being presented as a part of the base console
- Import instructions now mention that icarus ships with some firmware files,
  and describe the "Firmware" directory that icarus will use for firmware
  it needs.
- Apparently the correct name is "MSU1", not "MSU-1"
- v107 changes the way MSU1 data is stored in game folders
- PowerFest '94 import instructions removed, since I can't get it to work
  with v107
- Links to the official forum have been replaced with links to the unofficial
  forum archive, since the official forum is shutting down
- Links to Mercurial Magic updated to point at qwertymodo's archive, since
  hex_usr is no longer developing it
- Links to nSide updated, since hex_usr no longer uses GitHub.
- Windows build instructions now describe a compiler that is actually
  maintained, instead of stale TDM64-GCC.
- Linux build instructions now mention higan requires SDL 2.0.
- minor wording changes, typos, broken links fixed, etc.
This commit is contained in:
Tim Allen 2018-11-16 16:09:30 +11:00
parent 23dd28952b
commit 0b44399c0a
23 changed files with 357 additions and 317 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
CONTRIBUTING.md
View File

@ -2,8 +2,8 @@ Contributing to higan
=====================
If you would like to propose a change to higan,
you should create an account on the [official forums][f],
go to the "Projects" forum and the "higan" sub-forum,
you should create an account on the [unofficial forums][f],
go to the "Projects" forum,
and post your idea in a new topic there.
[f]: https://board.byuu.org/
[f]: https://helmet.kafuka.org/bboard/

2
README.md
View File

@ -27,11 +27,11 @@ Official higan resources
------------------------
- [Official homepage](https://byuu.org/emulation/higan/)
- [Official forum](https://board.byuu.org/viewforum.php?f=4)
Unofficial higan resources
--------------------------
- [Unofficial forum](https://helmet.kafuka.org/bboard/)
- Documentation for
[the current stable version][stadocs]
- [Source code repository](https://gitlab.com/higan/higan/)

7
README.txt
View File

@ -228,10 +228,13 @@ A: Try Settings -> Video -> Exclusive mode, then switch to fullscreen. This
Online Resources
----------------
Official homepage + forum:
Official homepage:
https://byuu.org/emulation/higan
https://board.byuu.org/viewforum.php?f=4
Unofficial forum:
https://helmet.kafuka.org/bboard/
Unoffical source code repository + documentation:

2
docs/checklinks.sh
View File

@ -8,5 +8,5 @@ checklink \
--summary \
--broken \
--location=http://127.0.0.1:8000/ \
--exclude 'github.com|board.byuu.org' \
--exclude 'github.com|board.byuu.org|helmet.kafuka.org' \
http://127.0.0.1:8000/

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

@ -53,7 +53,7 @@ higan can use a larger number of files per game.
For example,
higan's low-level emulation of Super Famicom co-processors
often requires [separate firmware files][firmware].
higan's [MSU-1 feature][msu1]
higan's [MSU1 feature][msu1]
supports up to 99 audio tracks per game,
and higan supports up to 133 save-states per game.
Thus,
@ -70,7 +70,7 @@ like save-states and the cheat database
to be kept separate from the game's actual data,
by putting it in a sub-folder.
[msu1]: ../guides/import.md#msu-1-games
[msu1]: ../guides/import.md#msu1-games
[firmware]: ../guides/import.md#games-with-co-processor-firmware
For a more detailed motivation for game folders,
@ -128,17 +128,21 @@ to all emulators that support them:
will create this file.
- `*.data.rom`, `*.program.rom`:
Files named like this are usually [co-processor firmware][firmware].
- `msu1.rom`:
Holds streamable data for [the MSU-1][msu1].
Files used by higan's [MSU1 extension][msu1]
are in the `msu1` sub-folder:
- `data.rom`:
Holds data that the MSU1 can stream.
- `track-*.pcm`:
Holds streamable audio for [the MSU-1][msu1].
Holds audio that the MSU1 can stream.
Files that are only useful to higan specifically
are placed in a `higan` sub-folder:
- `cheats.bml`:
All information present in
[the Cheat Editor](../interface/higan-tools.md#the-cheat-editor)
the [Cheat Editor](../interface/higan-tools.md#cheat-editor)
is stored here.
- `notes.txt`:
Everything entered in the [Game Notes] is stored here.

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

@ -4,8 +4,8 @@ is the folder where all the
When [icarus](../interface/icarus.md) imports a game,
it creates or updates
the corresponding game folder in the game library.
When you use the console sub-menu items
in [higan's Library menu](../interface/higan.md#the-library-menu),
When you use the items in
[higan's Systems menu](../interface/higan.md#the-systems-menu),
higan shows you the games for that console
that are already in the library.

4
docs/concepts/manifests.md
View File

@ -9,7 +9,7 @@ and to the console itself.
If you load a game into higan,
you can look at the game's manifest
by opening [the Tools menu](../interface/higan.md#the-tools-menu)
and choosing [Manifest Viewer](../interface/higan-tools.md#the-manifest-viewer).
and choosing [Manifest Viewer](../interface/higan-tools.md#manifest-viewer).
Why manifests?
--------------
@ -17,7 +17,7 @@ Why manifests?
For most consoles,
a manifest isn't strictly necessary:
the raw game data provides enough clues
for emulators to guess the circuit board configuration,
for emulators to guess the correct circuit board configuration,
or at least
to guess a *reasonable* configuration.
However,

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

@ -119,7 +119,7 @@ Manager states
--------------
higan's
[State Manager](../interface/higan-tools.md#the-state-manager)
[State Manager](../interface/higan-tools.md#state-manager)
allows you to create over a hundred save states,
and add a helpful description to each one.

4
docs/credits.md
View File

@ -59,5 +59,5 @@ apologies to anyone we've missed!
For more information,
see the [credits thread](
https://board.byuu.org/viewtopic.php?f=4&t=1631&p=41575#p41575)
on the official forums.
https://helmet.kafuka.org/byuubackup2/viewtopic.php@f=4&t=1631.html)
on the archive of the official forums.

4
docs/guides/drivers.md
View File

@ -5,12 +5,12 @@ playing audio,
and accepting input from game controllers.
Or rather,
there are many standards,
and different ones work best
and different ones work better
on different computers.
Therefore,
higan comes with "drivers"
for video, audio and input,
so you can find the one that works best for you.
so you can find the one that works best for your computer.
To see what drivers you're currently using,
or to choose different ones,
go to the [Advanced tab] of the Settings window.

168
docs/guides/import.md
View File

@ -29,7 +29,7 @@ and (if possible) start playing.
**Note:**
If you want to import many games,
run icarus directly.
See [icarus] documentation for details.
See the [icarus] documentation for details.
To play a game for a particular console from your library,
open the [Systems menu],
@ -75,11 +75,11 @@ for yourself.
To import a game that requires co-processor firmware,
the easiest approach is to drop the firmware files into
icarus' `firmware` directory
icarus' `Firmware` directory
before importing the game.
The directory should be beside the icarus executable,
or it can be `%LOCALAPPDATA%\icarus\firmware` (on Windows)
or `~/.local/share/icarus/firmware/` (on Linux).
or it can be `%LOCALAPPDATA%\icarus\Firmware` (on Windows)
or `~/.local/share/icarus/Firmware/` (on Linux).
If the easy approach doesn't work for a particular game,
it may be because icarus has incorrectly guessed
@ -131,13 +131,13 @@ here's the firmware files you'll need:
</thead>
<tbody>
<tr>
<th scope="row">CX4</th>
<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 1</sup></th>
<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>
@ -148,7 +148,7 @@ here's the firmware files you'll need:
<td><code>269584b347a22953a2989494c850a7c1c027f4ca5add517a60e0c7d8833d0fac</code></td>
</tr>
<tr>
<th scope="row" rowspan=2>DSP1B<br><sup>See Note 2</sup></th>
<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>
@ -228,10 +228,15 @@ here's the firmware files you'll need:
</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 2:**
**Note 3:**
The DSP1B is very similar to the DSP1A,
but fixes some bugs.
Note that icarus' heuristics cannot distinguish between
@ -259,7 +264,7 @@ using the "Load ROM File ..." option in the [Systems menu]
but it does not include the correct firmware data,
nothing will happen,
and higan will just sit there
with "No cartridge loaded" in
with "Unloaded" in
[the status bar](../interface/higan.md#the-status-bar).
Once a game with co-processor firmware is imported,
@ -441,7 +446,14 @@ including the timing change.
Because the Super Game Boy cartridge includes
the original Game Boy hardware,
it needs a boot ROM:
it needs a boot ROM.
icarus includes these files
and can reliably decide when to use them,
so importing either Super Game Boy cartridge
is just like [importing a regular game](#regular-games).
In case you need to check the Super Game Boy boot roms,
here are their details:
<table>
<thead>
@ -468,11 +480,6 @@ it needs a boot ROM:
</tbody>
</table>
icarus includes these files
and can reliably decide when to use them,
so importing either Super Game Boy cartridge
is just like [importing a regular game](#regular-games).
To play a Game Boy game in Super Game Boy mode,
load the Super Game Boy cartridge like any other game.
higan will open another [filesystem browser]
@ -497,14 +504,14 @@ for details.
[blackcarts]: ../notes.md#playing-game-boy-color-games-in-game-boy-mode
MSU-1 games
-----------
MSU1 games
----------
The MSU-1 is a fictional expansion chip
The MSU1 is a fictional expansion chip
invented by higan's author byuu,
designed to allow the Super Famicom
to stream data and audio.
Although the MSU-1 is not specific
Although the MSU1 is not specific
to any particular storage medium,
it gives the Super Famicom similar capabilities
to CD-based add-ons
@ -512,32 +519,32 @@ like the Mega Drive's Mega CD
and the PC Engine's CD-ROM²,
such as CD-quality music and full-motion video.
Although the MSU-1 was invented for higan,
Although the MSU1 was invented for higan,
it is now supported by other Super Famicom emulators too.
The [SD2SNES] programmable cartridge
even allows you to play MSU-1 games on a real console.
even allows you to play MSU1 games on a real console.
There are a number of homebrew games
that make use of the MSU-1,
that make use of the MSU1,
and also mods for commercial Super Famicom games
that add higher-quality music and sometimes video.
One thing to be aware of
when importing an MSU-1 game
when importing an MSU1 game
is that early firmware versions of the SD2SNES
had a bug that caused MSU-1 music to play too quietly.
had a bug that caused MSU1 music to play too quietly.
Skipping over [the full details][msu1vol],
the short version is this:
- If offered the choice between "boosted" or non-boosted audio,
you want the non-boosted version.
- If an MSU-1 mod for a commercial game offers
- If an MSU1 mod for a commercial game offers
"emulator" and "hardware" versions of the patch file,
it means the audio tracks are already boosted.
- Some
[third](https://www.zeldix.net/t1265-#18320)
[parties](https://www.zeldix.net/t1339-#19818)
have created replacement, non-boosted audio tracks
for the most popular MSU-1 mods.
for the most popular MSU1 mods.
If the mod you want to play has a replacement pack,
use it with the "hardware" version of the patch.
- Even without access to non-boosted audio tracks,
@ -548,7 +555,7 @@ the short version is this:
distorting and clipping,
in which case try the "emulator" patch.
To import an MSU-1 game:
To import an MSU1 game:
1. If you have a single, large file
with the `.msu1` extension,
@ -560,11 +567,11 @@ To import an MSU-1 game:
2. Otherwise,
import the Super Famicom ROM with icarus,
[like a regular game](#regular-games).
- If this is a homebrew game with MSU-1 support,
- If this is a homebrew game with MSU1 support,
there will probably be an ordinary ROM
whose name ends in `.sfc`,
which is the file you want to import.
- If this is a commercial game modded for MSU-1 support,
- If this is a commercial game modded for MSU1 support,
there will probably be a patch file
whose name ends in `.ips` or `.bps`.
Get a copy of the correct version of the commercial game,
@ -574,14 +581,17 @@ To import an MSU-1 game:
see "One thing to be aware of..." above.
3. Find the game folder in the [game library]
that icarus created when it imported the game.
4. Copy the MSU-1 data file into the game folder.
- This should be named `msu1.rom`
4. Inside the game folder,
create a new folder named `msu1`.
5. Copy the MSU1 data file into the new `msu1` folder.
- This should be named `data.rom`
- If there's no file by that name,
look for a file with a `.msu` extension
look for a file named `msu1.rom`,
or a file with a `.msu` extension,
and rename it to `msu1.rom`.
- If there's no file ending in `.msu` either,
create an empty file named `msu1.rom`.
5. Copy the audio tracks into the game folder.
6. Copy the audio tracks into the game folder.
- If you have to choose between two sets of audio files,
see "One thing to be aware of..." above.
- These should be named
@ -601,13 +611,13 @@ To import an MSU-1 game:
this game probably just doesn't use the audio-playback feature.
Once the game folder is set up,
playing an MSU-1 game is just like
playing an MSU1 game is just like
[a regular game](#regular-games).
[SD2SNES]: https://sd2snes.de/
[Flips]: http://www.romhacking.net/utilities/1040/
[msu1vol]: http://blog.qwertymodo.com/2017/07/the-msu-1-volume-fiasco-explained.html
[Mercurial Magic]: https://github.com/hex-usr/Mercurial-Magic/
[Mercurial Magic]: https://github.com/qwertymodo/Mercurial-Magic
Patched games
-------------
@ -652,7 +662,7 @@ GBA games can be imported and played just like
Note that some GBA games
have trouble with
[in-game saves](../notes#in-game-saves-and-the-game-boy-advance).
[in-game saves](../notes.md#in-game-saves-and-the-game-boy-advance).
PowerFest '94
-------------
@ -670,85 +680,15 @@ switch between them after a specific time,
extract a score,
and display the combined total at the end.
icarus cannot automatically import
dumps of the PowerFest '94 ROMs,
but if you have the files,
you can import them manually.
Previous versions of higan
could emulate the PowerFest '94 cartridge,
but changes to higan's manifest system in v107
prevent PowerFest '94 from working in that version.
Support will likely be re-added in a future version,
but in the mean time you can use higan v106
and follow [that version's import instructions][pf94v106].
You will need the following files:
<table>
<thead>
<tr>
<th>Part</th>
<th>Filename</th>
<th>Size (bytes)</th>
<th>SHA256</th>
</tr>
</thead>
<tbody>
<tr>
<th scope="row">Scoring</th>
<td><code>program.rom</code></td>
<td>262144</td>
<td><code>2fc9dca305ce3fb2f1a476567de500d50c174fbfbabd32b1b91c3ea6a731b4a1</code></td>
</tr>
<tr>
<th scope="row">Super Mario Bros. - The Lost Levels</th>
<td><code>slot-1.rom</code></td>
<td>524288</td>
<td><code>7fd86113c5f95f794d65807bb75ab91c93c914670c27fc813ffa2ca20a48705e</code></td>
</tr>
<tr>
<th scope="row">Super Mario Kart</th>
<td><code>slot-2.rom</code></td>
<td>524288</td>
<td><code>19eb77affbf8dd068f5d79a3cf80a2084fd73237cd1ae4e47192b4422449e64a</code></td>
</tr>
<tr>
<th scope="row">Ken Griffey Jr. Presents Major League Baseball</th>
<td><code>slot-3.rom</code></td>
<td>1048576</td>
<td><code>d47bc9f9a6289c4f2e7f6bf74095f6ed36b1043a761e3e729ac9af2fc39ae062</code></td>
</tr>
</tbody>
</table>
You will also need
the usual `dsp1.program.rom` and `dsp1.data.rom`
[co-processor firmware](#games-with-co-processor-firmware) files.
**Note:** the versions of
*Super Mario Kart*
and *Ken Griffey Jr...*
in *PowerFest '94*
are not the same as the stand-alone versions of those games.
To "import" *PowerFest '94*,
collect all the files mentioned above, then:
1. Inside [the game library](../concepts/game-library.md),
create the `Super Famicom` folder
(if it does not already exist).
2. Inside the `Super Famicom` folder,
create a `PowerFest '94.sfc` folder
(the `.sfc` extension is important,
but you can choose a different base name if you want).
3. Copy `program.rom` and the `slot-*.rom` files
into the `PowerFest '94.sfc` folder.
4. Copy the `dsp1.*.rom` files into the `PowerFest '94.sfc` folder,
but rename them to `upd7725.*.rom`.
To play *PowerFest '94*,
open the Library menu,
pick the Nintendo sub-menu,
then choose the Super Famicom sub-menu item
to open a filesystem browser listing
all the Super Famicom games in the library.
Select *PowerFest '94* from the list
and click the Open button,
or just double-click the game,
and it will begin playing.
[pf94v106]: https://higan.readthedocs.io/en/v106/guides/import/#powerfest-94
[filesystem browser]: ../interface/common.md#the-filesystem-browser
[Game Library]: ../concepts/game-library.md

11
docs/guides/shaders.md
View File

@ -2,14 +2,14 @@ Most of the consoles higan emulates
were designed for low resolution NTSC televisions,
and their video output is chunky and blocky
by today's standards.
Video shaders customise how a console's video output
Video shaders customise how the emulated console's video output
is drawn to the computer screen,
and can clean up and smooth out the original video,
reproduce the scanlines and blurring of the original display,
or any other visual effect.
The available video shaders are listed in
the "Video Shaders" sub-menu of the [Settings menu].
the "Shader" sub-menu of the [Settings menu].
Which shaders are available depends on
the [video driver] higan is configured to use.
Most drivers only support these shaders:
@ -19,7 +19,8 @@ Most drivers only support these shaders:
the colour of the single nearest console pixel,
sometimes called "nearest neighbour" scaling.
This produces unnaturally crisp and blocky images.
- If you use [aspect correction or non-integral scaling][ac],
- If you enable Scale, Stretch, or Aspect Correction modes
in the Output sub-menu of the [Settings menu],
neighbouring console pixels may be drawn
with a different number of computer pixels due to rounding errors,
causing a distracting rippling effect.
@ -30,8 +31,6 @@ Most drivers only support these shaders:
sometimes called "bilinear" scaling.
This produces unnaturally blurry images.
[ac]: ../interface/higan-settings.md#video
In addition to those,
the OpenGL driver also supports custom shaders.
@ -90,7 +89,7 @@ you'll need to restart higan
for the change to take effect.
Open the Settings menu again,
choose the "Video Shader" sub-menu,
choose the "Shader" sub-menu,
and now the shaders you installed
should be listed at the bottom of the menu.

12
docs/index.md
View File

@ -64,17 +64,17 @@ by the time you read this,
and it may contain errors or omissions.
If you find something that's wrong,
or you have a suggestion,
post a message on the official higan forum.
post a message on the unofficial forum.
Official higan resources
------------------------
- [Official homepage](https://byuu.org/emulation/higan/)
- [Official forum](https://board.byuu.org/viewforum.php?f=4)
Unofficial higan resources
--------------------------
- [Unofficial forum](https://helmet.kafuka.org/bboard/)
- [Source code repository](https://gitlab.com/higan/higan/)
archives official higan releases
and WIP snapshots
@ -85,12 +85,12 @@ Unofficial higan resources
or smarter algorithms for scaling up to modern PC resolutions.
See [Using video shaders][shaders] below for details.
- [Mercurial Magic](https://github.com/hex-usr/Mercurial-Magic/)
is a tool for converting MSU-1 games and mods into a format
is a tool for converting MSU1 games and mods into a format
higan can use.
See [Importing MSU-1 games][msu1] for details.
See [Importing MSU1 games][msu1] for details.
[shaders]: guides/shaders.md
[msu1]: guides/import.md#msu-1-games
[msu1]: guides/import.md#msu1-games
There are also other projects
based on current or older versions of higan,
@ -113,7 +113,7 @@ that you might want to check out.
is a fork of bsnes v094
adapted to work as a
[libretro](https://www.libretro.com/) emulation core.
- [nSide](https://github.com/hex-usr/nSide)
- [nSide](https://gitlab.com/hex-usr/nSide)
is a fork of higan that greatly enhances
its NES emulation support,
and adds minor features to the other cores too.

10
docs/install/linux.md
View File

@ -24,7 +24,7 @@ for the following libraries:
- Mesa
- gtksourceview 2.x
- Cairo
- SDL 1.2
- SDL 2.0
- libXv
- libAO
- OpenAL
@ -35,7 +35,7 @@ On a Debian-derived Linux distribution
you can install everything you need with a command like:
sudo apt-get install build-essential libgtk2.0-dev libpulse-dev \
mesa-common-dev libgtksourceview2.0-dev libcairo2-dev libsdl1.2-dev \
mesa-common-dev libgtksourceview2.0-dev libcairo2-dev libsdl2-dev \
libxv-dev libao-dev libopenal-dev libudev-dev
Once you have all the dependencies installed,
@ -53,7 +53,7 @@ being installed system-wide.
3. Type `cd ~/higan-src`
(or wherever you put the higan source)
and press Enter
4. Type `make -C higan` and press Enter
4. Type `make -C higan target=higan` and press Enter
to build the main higan executable
5. Type `make -C icarus` and press Enter
to build the icarus import tool
@ -68,7 +68,7 @@ as described in the previous section:
2. Type `cd ~/higan-src`
(or wherever you put the higan source)
and press Enter
3. Type `make -C higan install` and press Enter
3. Type `make -C higan target=higan install` and press Enter
to install higan and its supporting files
4. Type `make -C icarus install` and press Enter
to install icarus and its game database
@ -123,7 +123,7 @@ as installed by the above instructions:
2. Type `cd ~/higan-src`
(or wherever you put the higan source)
and press Enter
3. Type `make -C higan uninstall` and press Enter
3. Type `make -C higan target=higan uninstall` and press Enter
4. Type `make -C icarus uninstall` and press Enter
To remove higan's configuration,

78
docs/install/windows.md
View File

@ -51,37 +51,57 @@ or by clicking the download button on the right-hand side of the web-page
and choosing an archive format.
You will need a C++ compiler to compile higan.
We recommend installing [TDM64-GCC][tdm],
preferably the latest version
but anything newer than 4.9 should be fine.
We recommend installing the latest version of [MinGW-W64].
higan does not support building with clang++
(Clang is still not quite there yet for Windows)
nor Microsoft Visual C++
(last we checked, it didn't support all the C++ features higan uses).
**Note:** Make sure you get TDM64-GCC,
not TDM-GCC.
When compiled in x86 (32-bit) mode,
higan may crash at startup
because gcc targeting x86 does not support
Windows' structured exception handling (SEH).
Also,
historically in x86 mode
gcc has miscompiled a part of the NES emulation core.
See the higan forum
[for](https://board.byuu.org/viewtopic.php?p=41977#p41977)
[details](https://board.byuu.org/viewtopic.php?p=42253#p42253).
[MinGW-W64]: https://mingw-w64.org/
Once you've installed the compiler,
open a command-prompt window,
MinGW-W64 is available in a number of variants,
and the installer should ask you which you want.
- **Version:**
Version 8.1.0 is known to work,
later versions may work too.
- **Architecture:**
You *must* choose "x86_64", not "i686".
When built with an i686 compiler,
higan may crash at startup
because gcc targeting x86 does not support
Windows' structured exception handling (SEH).
Also,
historically in x86 mode
gcc has miscompiled a part of the NES emulation core.
See the archive of the official forum
[for](https://helmet.kafuka.org/byuubackup2/viewtopic.php@f=4&t=1636&start=20.html#p41977)
[details](https://helmet.kafuka.org/byuubackup2/viewtopic.php@f=4&t=1636&start=30.html#p42253).
- **Threads:**
Both options should work,
but higan is developed with the "posix" model.
- **Exception:**
You *must* choose "seh",
or higan may crash at startup.
If "seh" is not an option,
make sure "Architecture" is set to "x86_64".
- **Build Revision:**
Choose the largest number, whatever it is.
When the compiler is installed,
it adds a "Run terminal" shortcut to the Start menu
which opens a command-prompt
with all the compiler tools available.
To verify that the compiler is installed correctly,
launch the "Run Terminal" shortcut,
type `g++ --version`
then press Enter
to check it's installed correctly.
then press Enter.
You should see a message like
```text
g++ 1.2.3 20010101
Copyright (C) 2001 Free Software Foundation, Inc.
g++ (x86_64-posix-seh-rev0, Built by MinGW-W64 project) 8.1.0
Copyright (C) 2018 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
```
@ -91,11 +111,11 @@ and the corresponding dates.
If you see an error message like
"'g++' is not recognized as an internal or external command,
operable program or batch file",
you may need to add the compiler's "bin" folder
to your computer's `%PATH%`.
make sure you're using the "Run terminal" shortcut,
or otherwise have MinGW-W64's "bin" directory in your `%PATH%`.
See the compiler's documentation for help with that.
Once mingw is installed and available from the command prompt:
Once the compiler is installed:
1. Put the higan source code in some convenient location,
like `C:\higan-src`
@ -105,11 +125,9 @@ Once mingw is installed and available from the command prompt:
and press Enter
4. Type `mingw32-make -C icarus` and press Enter
to build the icarus import tool
5. Type `mingw32-make -C higan` and press Enter
5. Type `mingw32-make -C higan target=higan` and press Enter
to build the main higan executable
[tdm]: http://tdm-gcc.tdragon.net/download
Installing a compiled build on Windows
--------------------------------------
@ -118,9 +136,9 @@ Installing a compiled build on Windows
2. Assuming you built higan in `C:\higan-src`,
copy `C:\higan-src\icarus\out\icarus.exe`
into the new folder
3. Copy `C:\higan-src\icarus\database` and its contents
3. Copy `C:\higan-src\icarus\Database` and its contents
into the new folder
4. Copy `C:\higan-src\icarus\firmware` and its contents
4. Copy `C:\higan-src\icarus\Firmware` and its contents
into the new folder
5. Copy `C:\higan-src\higan\out\higan.exe`
into the new folder
@ -132,7 +150,7 @@ Installing a compiled build on Windows
The new folder should now contain
`icarus.exe`,
`higan.exe`,
and folders named `database`, `firmware`, `systems`,
and folders named `Database`, `Firmware`, `systems`,
and possibly `shaders`.
This is what you would get by downloading an official build,
as described under

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

@ -57,7 +57,8 @@ higan will prompt for one.
`SUBGAME2` is ignored.
When `GAME` refers to
the [Super Game Boy](../guides/import.md#super-game-boy-games),
the [Super Game Boy](../guides/import.md#super-game-boy-games)
or Super Game Boy 2,
`SUBGAME1` should be
the path to a game folder or ROM file
representing a Game Boy game to insert into the slot.

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

@ -6,7 +6,7 @@ and contains less-frequently-modified settings.
Most of these can be safely ignored,
or set once and never changed again.
This window has a tab for each main category of options:
This window has a tab for each main category of options.
Systems
=======
@ -92,9 +92,9 @@ settings adjust the colour and brightness
of the emulated console's video output:
- **Saturation** adjusts the vibrancy of colours displayed,
where 0% makes things pure grey,
where 0% makes things black-and-white,
100% is normal,
and 200% is garishly brightly coloured.
and 200% is garishly exaggerated colour.
- **Gamma** adjusts how bright mid-range colours are
compared to the brightest colours,
where 100% is normal,
@ -102,20 +102,23 @@ of the emulated console's video output:
This is in addition to
any adjustment applied by
the "Colors" option
in the "Video Emulation" sub-menu
in the "Emulation" sub-menu
of the [Settings menu](higan.md#the-settings-menu).
- **Luminance** adjusts the overall brightness,
where 100% is normal,
and 0% is totally black.
**Overscan Mask**
removes parts of
the video output that would have been hidden
by the bezel around the edge of
a standard-definition television screen.
Some games (particularly on the Famicom)
displayed random glitchy output in this area,
which can be distracting.
**Overscan Area**
controls what parts of the video output are hidden
when "Show Overscan Area" is disabled
in the "Output" sub-menu of
the [Settings menu](higan.md#the-settings-menu).
On a standard-definition television,
the outermost edges of the emulated console's video output
would have been hidden by the bezel,
so some games (particularly on the Famicom)
allowed random glitchy output to appear there,
assuming it wouldn't be visible.
- **Horizontal**
removes pixels from the left and right of the video output.
@ -130,41 +133,7 @@ whether the Super Famicom is in
lo-res (256px) or hi-res (512px)
mode.
**Windowed Mode**
settings apply when higan is running
in a normal window.
- **Aspect Correction**
stretches the image to match the aspect ratio
produced by the original console hardware,
but can cause a "ripple" effect
during horizontal scrolling
due to rounding errors.
[Video shaders](../guides/shaders.md)
can reduce this effect.
- **Integral Scaling**
makes higan draw the emulated video output
at a whole-number multiple of the original size,
rather than completely filling the available space.
This means that every game pixel
uses the same number of computer pixels,
and avoids graphics looking chunky and uneven.
Note that Aspect Correction
is applied after integral scaling,
so some unevenness may be visible
even with this option enabled.
- **Adaptive Sizing**
automatically resizes the higan window
to fit snugly around the emulated video output
whenever it changes size
(because the user loaded a game for a different console,
chose a different option from
the [Video Scale sub-menu](higan.md#the-settings-menu),
toggled Aspect Correction, etc.)
When disabled,
higan generally respects manual resizing.
**Fullscreen Mode**
**Fullscreen**
settings apply
when higan is running fullscreen,
because it was started with the `--fullscreen`
@ -172,10 +141,6 @@ because it was started with the `--fullscreen`
or because the user pressed
the Toggle Fullscreen [hotkey](higan-settings.md#hotkeys).
- **Aspect Correction**
behaves the same way as in Windowed mode above.
- **Integral Scaling**
behaves the same way as in Windowed mode above.
- **Exclusive Mode**
requests exclusive access
to the computer's video output
@ -185,7 +150,7 @@ the Toggle Fullscreen [hotkey](higan-settings.md#hotkeys).
from drawing anything,
and may also temporarily disable any kind of compositing,
reducing video latency.
As of v104,
As of v107,
only the Direct3D video driver is capable of exclusive mode;
with other drivers this option does nothing.
@ -236,52 +201,52 @@ before it is sent to your computer's speakers.
where 0% means only the left speaker produces sound,
50% means both speakers produce sound equally,
and 100% means only the right speaker produces sound.
- **Reverb** adds a slight reverberation effect
to the emulated console's audio output,
as though you were playing the game in a tunnel or small room.
Input
=====
This tab controls which PC inputs
are mapped to which emulated controllers.
This tab controls
how higan handles input for the emulated consoles.
**When focus is lost**
controls what happens when a game is loaded,
but higan is not the current foreground window.
- **Pause Emulation** automatically pauses emulation.
- **Block Input** allows emulation to keep running,
but higan will ignore all configured button presses.
If you're using the keyboard to emulate a controller,
this prevents typing in other applications
from messing with higan,
but music will keep playing.
- **Allow Input** allows emulation to continue as normal.
This allows somebody to play higan with a controller
in one window,
while somebody else types into another application
in another window.
The rest of this tab configures
the mapping from PC inputs to emulated controllers.
The exact PC inputs that can be mapped
depend on [the input driver](../guides/drivers.md#input).
General input settings:
To choose which of the possible controllers to configure:
- **Pause Emulation** automatically pauses emulation
when the main higan window
is not the current foreground window.
- **Allow Input** can be ticked
when "Pause Emulation" is *not* ticked,
and allows configured inputs to keep affecting higan
even when higan is running in the background.
This is particularly relevant if
you configure your PC keyboard to control higan:
if you tick this box,
and switch to a different application
leaving higan running in the background,
typing in that other application may affect
the emulated game running in higan
even though you can't see it!
- The first drop-down list controls
which console's ports appear in the second list.
- The second drop-down list controls
which port's compatible controllers appear in the third list.
- The third drop-down list controls
which controller's inputs are shown
in the mapping list below.
Choosing which of the possible controllers to configure:
Note that some consoles only allow particular controllers
to be used in a particular port.
For example,
the Super Scope controller for the Super Famicom
only works in Controller Port 2.
- The console selector chooses which console's inputs
to display in the mapping list below.
- The port selector chooses which port of the selected console
to display in the mapping list below.
- The controller selector chooses which controller
associated with the given console and port
to display in the mapping list below.
Note that some consoles only allow particular controllers
to be used in a particular port.
For example,
the Super Scope controller for the Super Famicom
only works in Controller Port 2.
Configuring the selected controller:
To configure the selected controller:
- The mapping list includes
every button and axis on the selected controller,
@ -332,6 +297,13 @@ then click one of the
or "Mouse Y-axis"
buttons in the bottom-left of the window.
**Note:**
To use an controller axis mapped to a mouse axis,
higan will need to be in fullscreen mode,
or you'll need to press
the key mapped to "Toggle Mouse Capture"
on the [Hotkeys tab](#hotkeys).
If you start mapping a button or axis,
but decide you don't want to,
you can press Escape
@ -339,10 +311,25 @@ to exit the "Press a key or button to map..." mode
without actually mapping anything.
**Note:**
Consoles in the Game Boy family include
The Game Boy and Game Boy Color consoles
have a "Cartridge" port with controllers
that are not really controllers:
- The "MBC5" controller is automatically used for
games whose cartridge includes the MBC5 memory-mapper
and a rumble motor,
like *Pokémon Pinball*.
See [Rumble Compatibility for Game Boy (Color)][gbcrumble]
for details.
- The "MBC7" controller is automatically used for
games whose cartridge includes the MBC7 memory-mapper
and an accelerometer,
like *Kirby Tilt 'n' Tumble*.
**Note:**
The Game Boy Advance console includes
a Rumble "input" which is really more of an output.
See [Rumble Compatibility for Game Boy (Color)][gbcrumble]
and [Rumble Compatibility for Game Boy Advance][gbarumble]
See [Rumble Compatibility for Game Boy Advance][gbarumble]
for details.
[gbcrumble]: ../notes.md#rumble-compatibility-for-game-boy-color
@ -360,12 +347,12 @@ Hotkeys
This tab is like "Inputs" above,
except it contains controls for higan itself
instead of the emulated console.
instead of for the emulated console.
- **Toggle Fullscreen** puts higan into fullscreen mode,
where the menu and status bar are hidden,
and the emulated console's video output
is enlarged to cover the entire screen.
can cover the entire screen.
Toggling fullscreen also automatically captures the mouse.
- **Toggle Mouse Capture** hides the usual mouse-cursor,
and captures the mouse so it cannot leave the higan window.
@ -440,8 +427,7 @@ for help choosing which drivers you should use.
configures how higan interacts
with the [Game Library](../concepts/game-library.md).
- **Location** selects where higan
looks for games to load.
- **Location** tells higan where to look for games to load.
See [Moving the Game Library](../concepts/game-library.md#moving-the-game-library)
for more information.
- **Ignore Manifests** makes higan ignore
@ -452,7 +438,7 @@ with the [Game Library](../concepts/game-library.md).
to guess a manifest on the fly.
See [Ignoring manifests](../concepts/manifests.md#ignoring-manifests)
for details.
**Other**
- **Auto-Save Memory Periodically** makes higan write

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

@ -3,10 +3,10 @@ appears when you choose
one of the items at the bottom of
[the Tools menu](higan.md#the-tools-menu).
The window has a tab for each tool:
The window has a tab for each tool.
The Cheat Editor
================
Cheat Editor
============
For some consoles,
higan supports applying temporary changes to the code of a running game.
@ -89,8 +89,8 @@ in Super Mario World,
you can lock the time to 999 with these codes:
`7e0f31=09+7e0f32=09+7e0f33=09`.
The State Manager
=================
State Manager
=============
The State Manager allows you to create,
load,
@ -125,8 +125,8 @@ and click "Erase" in the bottom-right corner.
To clear all the slots at once,
click "Reset" in the bottom-right corner.
The Manifest Viewer
===================
Manifest Viewer
===============
As described in
[Game Manifests](../concepts/manifests.md),

121
docs/interface/higan.md
View File

@ -8,8 +8,8 @@ the running game's video output.
The Systems menu
----------------
This menu lists the systems higan emulates,
Choosing any system allows you to play
This menu lists the systems higan emulates.
Choosing any system from this menu allows you to play
games for that system that you've already imported
into higan's [game library](../concepts/game-library.md).
See [Importing and playing games](../guides/import.md).
@ -24,7 +24,7 @@ for example, you can
add the Sufami Turbo to the list
and load *SD Ultra Battle*
in two clicks instead of three.
**Load ROM File ...**
opens a [filesystem browser](common.md#the-filesystem-browser)
allowing you to choose a single ROM file.
@ -39,8 +39,7 @@ The console menu does not appear
until a game is loaded.
Also,
it's not named "console",
it's named for the kind of console
the loaded game runs on.
it's named for the console that runs the loaded game.
For example,
when playing a Game Boy game,
you will have a "Game Boy" menu.
@ -50,7 +49,6 @@ to the particular console being emulated.
All consoles will have some of the following items,
but few consoles have all of them.
**Controller Port 1**
allows you
to connect different emulated controllers
@ -80,7 +78,21 @@ This menu appears for the Famicom,
even though the Famicom did not support alternate controllers,
because the Famicom emulation core also emulates the NES,
which did.
**Controller**
is like "Controller Port 1"
for consoles that only have one controller port.
**Hardware**
appears for consoles with buttons on the main unit,
like the Game Boy,
or Master System.
It only allows the built-in controls to be used.
**Cartridge**
appears for the Game Boy and Game Boy Colour.
The options inside it do nothing.
**Expansion Port**
allows you
to connect different emulated devices
@ -95,6 +107,9 @@ This option allows the same program
to control the emulated SNES,
for development or testing.
**Extension Port**
is the name the Sega Mega Drive used for its expansion port.
**Soft Reset**
restarts the emulated console's CPU
while leaving the console's memory untouched,
@ -124,7 +139,7 @@ as though the emulated console were switched off and on again.
stops the current game,
as though the emulated console were switched off.
You can load a new game
from [the Library menu](#the-library-menu).
from [the Systems menu](#the-systems-menu).
[21fx]: https://github.com/defparam/21FX
@ -134,13 +149,83 @@ The Settings menu
The Settings menu allows you to configure things
that aren't specific to any particular console.
**Video Scale** determines the size
**Size**
determines the size
of the emulated console's video output
when higan is running in windowed mode
(as opposed to fullscreen).
The menu-items that indicate particular sizes
are only approximate, since
aspect correction can be applied,
different consoles have different native image sizes,
and some consoles can change the size of their output image dynamically.
**Video Emulation** applies various effects
- **1x (240p)**
resizes the higan window
so that each pixel of the emulated console's video output
is drawn as a single pixel on the computer screen.
- **2x (480p)**
resizes the higan window
so that each pixel of the emulated console's video output
is drawn as a 2×2 block of pixels on the computer screen.
- **3x (720p)**
resizes the higan window
so that each pixel of the emulated console's video output
is drawn as a 3×3 block of pixels on the computer screen.
- **Shrink Window To Size**
resizes the higan window to fit the emulated console's video output
at its current scale,
so there's no black padding between the image and the window border
(some padding may remain
if "Show Overscan Area" is enabled
in the Output menu).
- **Center Window**
moves the higan window to the centre of the computer screen.
**Output**
controls how higan draws the emulated console's video output
into the space available,
in both windowed and fullscreen modes.
- **Center**
draws the emulated video
at the largest integer multiple of the native size that will fit,
centered in the space available.
This gives the most crisp output,
but often has black borders.
- **Scale**
draws the emulated video
at the largest size that will fit,
and which preserves the image's aspect ratio.
This strikes a balance between
displaying the video output as it was intended,
and eliminating black borders.
- **Stretch**
draws the emulated video
to cover the entire available output area,
even if that distorts the image.
This completely eliminates black borders,
but can look very weird.
- **Adaptive Sizing**
allows higan to resize its window
when the emulated console changes the resolution
of its video output.
This can avoid black borders,
but the window resizing itself might be even more distracting.
- **Aspect Correction**
horizontally stretches the emulated video output
to match the aspect ratio produced by the original console.
It can make the output look more "lumpy",
but is a more accurate representation
of the original console's output.
- **Show Overscan Area**
controls whether the area defined by
the "Overscan Area" sliders in
the [Video settings](higan-settings.md#video)
is clipped from the emulated video output
or shown.
**Emulation** applies various effects
to the emulated console's video output
to reproduce some behaviours
that aren't technically part of the console itself:
@ -165,8 +250,8 @@ that aren't technically part of the console itself:
used by the Super Famicom,
the dim, washed out colours of the original Game Boy Advance,
and the pea-green display of the original Game Boy.
**Video Shader** controls
**Shader** controls
how the low-resolution video output of the emulated console
is scaled up to suit modern high-resolution displays.
[Using video shaders](../guides/shaders.md)
@ -234,15 +319,15 @@ This can also be triggered by
the [pause hotkey](higan-settings.md#hotkeys).
**Cheat Editor ...**
opens [the Cheat Editor tab](higan-tools.md#the-cheat-editor)
opens the [Cheat Editor tab](higan-tools.md#cheat-editor)
of the Tools window.
**State Manager ...**
opens [the State Manager tab](higan-tools.md#the-state-manager)
opens the [State Manager tab](higan-tools.md#state-manager)
of the Tools window.
**Manifest Viewer ...**
opens [the Manifest Viewer tab](higan-tools.md#the-manifest-viewer)
opens the [Manifest Viewer tab](higan-tools.md#manifest-viewer)
of the Tools window.
**Game Notes ...**
@ -275,7 +360,7 @@ at the bottom of the main higan window,
while "Show Status Bar" is ticked in [the Settings menu](#the-settings-menu).
Before any game is loaded,
the status bar displays "No cartridge loaded".
the status bar displays "Unloaded".
When a game is loaded and running,
the status bar displays the current emulation speed
@ -319,7 +404,7 @@ sub-menu that has not had a save-state saved to it,
or when you press the "Load Quick State" hotkey
while the current Quick State slot has not had a save-state saved to it,
The status bar briefly displays "Power cycled"
The status bar briefly displays "System has been power cycled"
when you choose "Power Cycle" from [the console menu](#the-console-menu),
or press the "Power Cycle" hotkey.

2
docs/interface/icarus.md
View File

@ -62,7 +62,7 @@ The icarus Settings dialog contains the following settings:
Command line
------------
icarus can be launched with any of the following command-line arguments:
icarus can be launched in any of the following ways:
> icarus
>

18
docs/notes.md
View File

@ -29,8 +29,8 @@ you may be comparing it
to a Mega Drive calibrated to a different scale
(or to an emulator tweaked to match such a Mega Drive).
[vol]: https://board.byuu.org/viewtopic.php?p=42482#p42482
[va6]: https://board.byuu.org/viewtopic.php?p=42195#p42195
[vol]: https://helmet.kafuka.org/byuubackup2/viewtopic.php@f=4&t=1235&start=140.html#p42482
[va6]: https://helmet.kafuka.org/byuubackup2/viewtopic.php@f=4&t=1235&start=130.html#p42195
Playing Game Boy Color games in Game Boy mode
---------------------------------------------
@ -128,19 +128,23 @@ Rumble compatibility for Game Boy (Color)
The Game Boy and Game Boy Color did not natively support
any kind of rumble or force-feedback system,
but some game cartridges (such as Pokémon Pinball)
but some game cartridges (such as *Pokémon Pinball*)
included a rumble motor within the cartridge itself.
Such cartridges generally used the "MBC5" memory mapper chip.
Because higan does not currently support
game-specific controller features,
to experience the rumble effect in higan
you'll need to configure the console:
To experience the rumble effect in higan,
you'll need to configure the MBC5 "controller"
connected to the "cartridge" port:
- Open
[higan's Input settings](interface/higan-settings.md#input)
- In the list of consoles,
select Game Boy, or Game Boy Color
depending on which console you want to use to play the game
- In the list of ports,
select "Cartridge"
- In the list of controllers,
select "MBC5"
- In the list of inputs,
double-click "Rumble"
or select it and press Enter

4
docs/qs.md
View File

@ -51,7 +51,7 @@ Load a game
-----------
From
[the Library menu](interface/higan.md#the-library-menu),
[the Systems menu](interface/higan.md#the-systems-menu),
choose "Load ROM File ..."
to open [a filesystem browser](interface/common.md#the-filesystem-browser),
and choose the game you want to play.
@ -63,7 +63,7 @@ In the future,
if you want to play this game again,
you can choose "Load ROM File ..." as you did before,
or you can choose the appropriate console name
from the Library menu,
from the Systems menu,
which will list all the games for that console
in the Game Library.

4
docs/release.md
View File

@ -11,5 +11,5 @@ Release checklist
6. Merge changes from master.
7. Copy `target-bsnes/resource/resource.?pp` to the `target-libretro` folder.
7. `git push` to make the new changes available.
[rtd]: https://readthedocs.org/projects/higan/builds/
[rtd]: https://readthedocs.org/projects/higan/builds/