In memory of Ben “bushing” Byer, who passed away on Monday, February 8th, 2016.

Difference between revisions of "Dolphin"

From WiiBrew
Jump to navigation Jump to search
(→‎General Notes / Disclaimer: needed to use a small hack to make my non-libogc app run in wiimode)
 
(46 intermediate revisions by 16 users not shown)
Line 1: Line 1:
−
Dolphin is a Wii and GameCube emulator. It allows Wii and GameCube games to be run on a Windows PC, Linux PC or a Mac. As of June 2008 (when it became open source) Dolphin is under active development.
+
{{Infobox homebrew
 +
| image = [[File:Dolphin-logo.svg|200px]]
 +
| title = Dolphin
 +
| type = pc utility
 +
| author = [https://github.com/dolphin-emu/dolphin/graphs/contributors Contributors (GitHub)]
 +
| website = https://dolphin-emu.org
 +
| source = https://github.com/dolphin-emu/dolphin
 +
| download = https://dolphin-emu.org/download/
 +
| license = GPLv2+ (since 2015)
 +
| peripherals =
 +
}}
  
−
== Download ==
+
'''Dolphin''' emulates the Wii and GameCube consoles, as well as various accessories for and derivatives of said consoles. It runs Wii and GameCube software with a x86_64 JIT (Windows, Linux, FreeBSD, macOS) and AArch64 (Android). On June 2008, Dolphin's source was released under the GPLv2 license and is currently under active development.
  
−
Dolphin website is located at [http://www.dolphin-emu.com]. The website does provide 'unofficial' builds but the builds are out of date and often aren't available to download. It is recommended to compile from source. Follow the [http://code.google.com/p/dolphin-emu/wiki/WindowsBuild Windows build instructions], [http://code.google.com/p/dolphin-emu/wiki/Linux_dependencies Linux build instructions] or [http://code.google.com/p/dolphin-emu/wiki/MacOSX_Build Mac build instructions].
+
== Obtaining a build ==
  
−
== Use ==
+
=== Recommended builds ===
 +
[https://dolphin-emu.org dolphin-emu.org] provides a buildbot for [https://dolphin-emu.org/download/ Windows and OS X builds] from Git and a [https://dolphin-emu.org/docs/faq/ FAQ] to help users.
  
−
Dolphin is useful to Wii homebrew as it allows developers to test their code on a PC before running the code on the Wii. However, Dolphin does not support all the features of the Wii and you may experience some problems running your homebrew.
+
=== Building from source ===
 +
Follow the instructions to build under [https://github.com/dolphin-emu/dolphin/wiki/Building-for-Windows Windows], [https://github.com/dolphin-emu/dolphin/wiki/Building-for-Linux Linux] or [https://github.com/dolphin-emu/dolphin/wiki/Building-for-macOS macOS]. Windows and macOS users can use the buildbot to avoid compiling their own source code, but Linux users have to build it themselves in order to use Dolphin.
  
−
# Run Dolphin. If you compiled Dolphin, run Dolphin.exe located within Binary\''Platform'' directory, where ''Platform'' is win32, linux, etc.
+
== Usage with Homebrew ==
−
# Setup the plugins. From the menu, '''Options''' -> '''Configure'''. Select the '''Plugins''' tab
+
From the menu, '''File''' -> '''Open...'''. Select the elf or dol file you would like to run.
−
## Set Graphics to a Dolphin graphics plugin. Select 'Dolphin Direct3D9' if on windows and unsure.
 
−
## Set DSP to a Dolphin DSP plugin. Select 'Dolphin DSP-HLE' if on windows and unsure.
 
−
## Set Pad to a Dolphin pad plugin. Select 'Dolphin KB/X360pad' if on windows and unsure.
 
−
## Set Wiimote to a Dolphin wiimote plugin. Select 'Dolphin Wiimote' if on windows and unsure.
 
−
# Run your homebrew. From the menu, '''File''' -> '''Open...'''. Select the Devkitpro compiled .elf or .dol file. If successful, a new window will be displayed with your homebrew.
 
  
−
== Homebrew and Dolphin ==
+
Note that you can cause the screen to be rendered to the main Dolphin window with the '''Graphics''' → '''Render to main window''' option.
  
 +
=== General Notes / Disclaimer ===
 +
* Dolphin is useful to homebrew as it allows developers to test code on a PC before running it on real hardware. However, Dolphin does not support all the features of the Wii and some problems may be experienced running homebrew.
 +
* You may want to enable the MMU for more accurate emulation.
 +
* Dolphin hooks the typical printf functions when it is able to determine their location. If you are running an elf file (with symbols), and cannot see your debug output, this is could be the reason. Either strip your elf, run the dol, or modify dolphin so this HLE does not take place. The other reason could be that you are writing directly to the XFB (libogc's console output does this). In this case, you additionally need to enable the '''Graphics'''->'''Hacks'''->'''External Frame Buffer''' setting and check '''Real'''.
 +
* Homebrew applications ''may'' hang while initialising sound, i.e. on calling ASND_Init(). A work around would be to skip sound initialisation, so no sound, but there's no need to remove other sound calls in your code. Using the '''DSP LLE''' audio backend will improve sound accuracy, and may help avoid hangs.
 +
* You can find an '''SD Card''' image in something like User\Documents\Wii\sd.raw, kept in the Dolphin folder.  If missing it may create it on the first run, you can add things to the sd.raw image with a tool such as winimage. On Linux, it can be simply mounted directly.
 +
* When using code that makes use of the SD Card make sure you use the '''full path''' name i.e. (sd:/apps/MyApp/gfxfiles/Image.png); using a relative path (/gfxfiles/Image.png) will not work as your application is launching from an unknown location.
 +
* When not using [[libogc]], Dolphin may run the app in GameCube mode. This can be fixed by inserting the u32 <code>0x7c13fba6</code> in a text segment. This instruction does not need to run, but it needs to be in a place that causes it to exist in the binary.
 +
 +
=== Compatibility ===
 +
''Note: This section is pretty outdated''
 +
 +
The following was tested with examples from devkitPro svn r4455, running on Windows 7 (64bit), Dolphin svn r6430. Apps run with default settings unless noted otherwise.
 +
These results are provided so that one can quickly realize which options are needed for common tasks - such as using SD support, homebrew text console, etc.
 
{| class="apptable sortable"
 
{| class="apptable sortable"
 
! width="20%" | Title
 
! width="20%" | Title
−
! Description
+
! Notes
−
! width="35%" | Version
+
|-
 +
| examples\wii\audio\*
 +
| Work acceptably. Requires '''DSP LLE''' plugin to be used. Audio may have artifacts.
 +
|-
 +
| examples\wii\devices\network\sockettest
 +
| Does not work. Socket is not setup successfully.
 +
|-
 +
| examples\wii\devices\usbgecko\gdbstub
 +
| Works correctly. Requires '''USBGecko''' device selected. Sets up a TCP server to accept connections (instead of a serial device). The TCP port used will be displayed on-screen when dolphin begins emulation.
 +
|-
 +
| examples\wii\devices\usbkeyboard\basic_stdin
 +
| Works correctly. Requires '''Graphics'''->'''Hacks'''->'''External Frame Buffer'''->'''Real''' to be checked. Requires '''Config'''->'''Wii'''->'''Connect USB Keyboard''' to be enabled.
 +
|-
 +
| examples\wii\filesystem\directory
 +
| Works correctly. Requires '''Graphics'''->'''Hacks'''->'''External Frame Buffer'''->'''Real''' to be checked. Requires '''Config'''->'''Wii'''->'''Insert SD Card''' to be enabled.
 
|-
 
|-
−
| examples neheGx\Lesson1-5
+
| examples\wii\graphics\gx\gxSprites
 
| Works correctly.
 
| Works correctly.
−
| Using gamecube-examples-20081206, Windows XP (32bit), DevkitPro r16, libogc 1.7.1a, Dolphin R2812.
 
 
|-
 
|-
−
| examples template
+
| examples\wii\graphics\gx\neheGX\lesson1-7
−
| Fails. Only a blank screen is displayed and no hello world text.
+
| Work correctly.
−
| Using gamecube-examples-20081206, Windows XP (32bit), DevkitPro r16, libogc 1.7.1a, Dolphin R2812.
+
|-
 +
| examples\wii\graphics\gx\neheGX\lesson8
 +
| Texturing is broken.
 +
|-
 +
| examples\wii\graphics\gx\triangle
 +
| Works correctly.
 
|-
 
|-
−
| examples gxSprites
+
| examples\wii\template
−
| Fails. Only a blank screen is displayed
+
| Works correctly. Requires '''Graphics'''->'''Hacks'''->'''External Frame Buffer'''->'''Real''' to be checked.
−
| Using gamecube-examples-20081206, Windows XP (32bit), DevkitPro r16, libogc 1.7.1a, Dolphin R2812.
 
 
|}
 
|}
 +
 +
==  Screenshot ==
 +
<gallery>
 +
File:Dolphin_nehe5.PNG|Running NeHe lesson5
 +
File:Dolphin Emulator Main and About Windows.png|Dolphin main window and About window
 +
</gallery>
 +
 +
[[Category:Open source homebrew]]
 +
[[Category:Wii models]]

Latest revision as of 07:22, 8 July 2022

Dolphin
Dolphin-logo.svg
General
Author(s)Contributors (GitHub)
TypePC utility
LicenseGPLv2+ (since 2015)
Links
Download
Website
Source

Dolphin emulates the Wii and GameCube consoles, as well as various accessories for and derivatives of said consoles. It runs Wii and GameCube software with a x86_64 JIT (Windows, Linux, FreeBSD, macOS) and AArch64 (Android). On June 2008, Dolphin's source was released under the GPLv2 license and is currently under active development.

Obtaining a build

Recommended builds

dolphin-emu.org provides a buildbot for Windows and OS X builds from Git and a FAQ to help users.

Building from source

Follow the instructions to build under Windows, Linux or macOS. Windows and macOS users can use the buildbot to avoid compiling their own source code, but Linux users have to build it themselves in order to use Dolphin.

Usage with Homebrew

From the menu, File -> Open.... Select the elf or dol file you would like to run.

Note that you can cause the screen to be rendered to the main Dolphin window with the Graphics → Render to main window option.

General Notes / Disclaimer

  • Dolphin is useful to homebrew as it allows developers to test code on a PC before running it on real hardware. However, Dolphin does not support all the features of the Wii and some problems may be experienced running homebrew.
  • You may want to enable the MMU for more accurate emulation.
  • Dolphin hooks the typical printf functions when it is able to determine their location. If you are running an elf file (with symbols), and cannot see your debug output, this is could be the reason. Either strip your elf, run the dol, or modify dolphin so this HLE does not take place. The other reason could be that you are writing directly to the XFB (libogc's console output does this). In this case, you additionally need to enable the Graphics->Hacks->External Frame Buffer setting and check Real.
  • Homebrew applications may hang while initialising sound, i.e. on calling ASND_Init(). A work around would be to skip sound initialisation, so no sound, but there's no need to remove other sound calls in your code. Using the DSP LLE audio backend will improve sound accuracy, and may help avoid hangs.
  • You can find an SD Card image in something like User\Documents\Wii\sd.raw, kept in the Dolphin folder. If missing it may create it on the first run, you can add things to the sd.raw image with a tool such as winimage. On Linux, it can be simply mounted directly.
  • When using code that makes use of the SD Card make sure you use the full path name i.e. (sd:/apps/MyApp/gfxfiles/Image.png); using a relative path (/gfxfiles/Image.png) will not work as your application is launching from an unknown location.
  • When not using libogc, Dolphin may run the app in GameCube mode. This can be fixed by inserting the u32 0x7c13fba6 in a text segment. This instruction does not need to run, but it needs to be in a place that causes it to exist in the binary.

Compatibility

Note: This section is pretty outdated

The following was tested with examples from devkitPro svn r4455, running on Windows 7 (64bit), Dolphin svn r6430. Apps run with default settings unless noted otherwise. These results are provided so that one can quickly realize which options are needed for common tasks - such as using SD support, homebrew text console, etc.

Title Notes
examples\wii\audio\* Work acceptably. Requires DSP LLE plugin to be used. Audio may have artifacts.
examples\wii\devices\network\sockettest Does not work. Socket is not setup successfully.
examples\wii\devices\usbgecko\gdbstub Works correctly. Requires USBGecko device selected. Sets up a TCP server to accept connections (instead of a serial device). The TCP port used will be displayed on-screen when dolphin begins emulation.
examples\wii\devices\usbkeyboard\basic_stdin Works correctly. Requires Graphics->Hacks->External Frame Buffer->Real to be checked. Requires Config->Wii->Connect USB Keyboard to be enabled.
examples\wii\filesystem\directory Works correctly. Requires Graphics->Hacks->External Frame Buffer->Real to be checked. Requires Config->Wii->Insert SD Card to be enabled.
examples\wii\graphics\gx\gxSprites Works correctly.
examples\wii\graphics\gx\neheGX\lesson1-7 Work correctly.
examples\wii\graphics\gx\neheGX\lesson8 Texturing is broken.
examples\wii\graphics\gx\triangle Works correctly.
examples\wii\template Works correctly. Requires Graphics->Hacks->External Frame Buffer->Real to be checked.

Screenshot

  • Running NeHe lesson5

  • Dolphin main window and About window

Retrieved from "https://wiibrew.org/w/index.php?title=Dolphin&oldid=117465"