dreamcast.wiki - User contributions [en]

Engine & Library

2024-09-25T09:08:01Z

Voxel: fix urls for LMP3D, gldc

This list is an adaptation of the [https://github.com/dreamcastdevs/awesome-dreamcast awesome-dreamcast] repo on github.

==Tutorial==
*[https://dreamcast.wiki Dreamcast.wiki] - A brand new wiki with up-to-date information about the Dreamcast.
*[https://dcemulation.org/index.php?title=Development DCEmu Developement Wiki] - Great resource to start. Somewhat incomplete in certain aspect.
*[https://github.com/dreamcastdevs/dreamcast_tutorial Dreamcast-tutorial Github] - A new-ish sets of tutorial with code example. Covers the basic (installing the toolchain, graphics, audio, controller)

==Framework==
*[https://sourceforge.net/projects/cadcdev/ KOS] - The pseudo-OS that's been used in a lot of homebrew/indie.
*[https://www.dreamsdk.org DreamSDK] - A multitool environment made for Windows. Maintained by [SiZiOUS](User:SiZiOUS)
*[http://wiki.bennugd.org/index.php?title=Bennu_Wiki BennuGD] - A multi-platform engine
*[https://github.com/FaucetDC/WincastCE WincastCE] - An experimental windows CE shell (?)
*[https://github.com/DC-SWAT/DreamShell DreamShell] - The popular alternative operating system for loading games/app from SD Card and IDE Drive
*[[libronin]] - an independent development library created by the DreamSNES team

==Engine==
*[[Simulant]] - A general purpose 2D-3D engine in active developement.
*[[nuQuake]] - Quake engine by MrNeo240
*[[RADquake]] - Quake engine by Ian Micheal
*[https://github.com/ianmicheal/Dreambor6.0 DreamBOR - unofficial] - OpenBOR dreamcast port forked an improved by Ian Michael
*[https://github.com/CaptainDreamcast/DolmexicaInfinite DolmexicaInfinite] - A Mugen-like engine for fighter games
*[[Antiruins]] - Minimal 2D game engine with Lua scripting by Lerabot.

==Graphics==
*[https://gitlab.com/simulant/GLdc GLdc] - A OpenGL 1.2 implementation started by Kazade
*[https://github.com/Kannagi/LMP3D LMP3D] - A multi-platform 3D Lib. (*Looks abandoned but might be good for research*)
*[https://github.com/multimediamike/dreamroq DreamROQ] - A ROQ video player. (*Stable, no sound*)

==Audio==
*[https://gitlab.com/simulant/ALdc ALdc] - A OpenAL 1.2 implementation started by Kazade
*https://github.com/Aurelien34/DreamcastAicaSoundDriver - A hardware accelerated S3M and sfx AICA driver.

==VMU==
*[https://github.com/Protofall/Crayon-Utilities CrayonUtil] - Mostly tools for VMU icons, but also some texture converters. Made by [Protofall](https://github.com/Protofall)

==Utilities==
*[https://github.com/CaptainDreamcast/prism Prism] - CaptainDreamcast's set of utilities for Physics, files loading, etc. (*untested*)

==Memory Management==

==Debugging==

==Random==
*[https://github.com/Protofall/Homebrew-Tests Homebrew Tests (Protofall)]

Visual Studio Code

2024-09-21T07:09:12Z

Voxel:

This is a guide to setup your [https://code.visualstudio.com/ Visual Studio Code] project with debugging support on both on a real Dreamcast and with an emulator.

== Prerequisites ==
To start with, this tutorial makes the following assumptions:
* You have already installed and [https://dreamcast.wiki/Getting_Started_with_Dreamcast_development set up your KallistiOS development environment]]
# if you want to be able to debug, be sure to compile gdb as specified on that page
* You have already downloaded and installed [https://code.visualstudio.com/ Visual Studio Code] (version 1.78.2 was used for this tutorial)

== VSCode Setup ==
* Launch Visual Studio Code
* (optional but recommended) To keep your configuration settings, plugins, ... specific to Dreamcast projects only:
# Create a "Profile" (Menu: File-Preferences-Profiles) called "Dreamcast"
* Install the following extensions: (Menu: View-Extensions)
# Required:
## [https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools C/C++] from Microsoft
# Required only if you are using WSL (Windows Subsystem for Linux):
## [https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl WSL from Microsoft]
# (Not recommended at this moment:)
## ([https://marketplace.visualstudio.com/items?itemName=ms-vscode.makefile-tools Makefile Tools] from Microsoft: the current version (June 2023) is not really adapted for remote debugging)

== Setup per Project ==

=== Compilation ===
==== Preparation ====
(all the following steps happen in Visual Studio Code)
# Open the folder containing your project - eg: /opt/toolchains/dc/kos/examples/dreamcast/2ndmix:
##If you are using WSL:
###"F1" - "Connect To WSL"
##Menu: File-Open Folder...
# (if you are using Profiles) Make sure that the "Dreamcast" profile is selected (Menu: File-Preferences-Profiles)
#If you are using WSL, check that the C/C++ extension is correctly installed for WSL - if you get a warning like "install in WSL: Ubuntu", do so.
# Create a new subfolder ".vscode"
# insert the following files in the '''".vscode" subfolder''':

* '''kos_environ.sh'''
<syntaxhighlight lang="bash">
#!/bin/bash

#set the KOS environtment variables
source /opt/toolchains/dc/kos/environ.sh
</syntaxhighlight>

* '''kos_make.sh'''
<syntaxhighlight lang="json">
#!/bin/bash

#set the KOS environtment variables
source /opt/toolchains/dc/kos/environ.sh

make

exit
</syntaxhighlight>

* '''settings.json'''
<syntaxhighlight lang="json">
{
"C_Cpp.default.includePath": [
"${workspaceFolder}/**",
"/opt/toolchains/dc/kos/include/**",
"/opt/toolchains/dc/kos/kernel/arch/dreamcast/include/**",
"/opt/toolchains/dc/kos/addons/include/**",
"/opt/toolchains/dc/kos-ports/include/**",
"/opt/toolchains/dc/kos-ports/*/include/**"
],
"C_Cpp.default.defines": [
"_arch_dreamcast"
],
"C_Cpp.default.compilerPath": "/opt/toolchains/dc/sh-elf/bin/sh-elf-gcc",
"C_Cpp.default.cStandard": "c11",
"C_Cpp.default.cppStandard": "c++17",
"C_Cpp.default.intelliSenseMode": "",

"terminal.integrated.defaultProfile.linux": "kos-bash",
"terminal.integrated.profiles.linux": {
"kos-bash": {
"path": "/usr/bin/bash",
"args": ["--init-file", "${workspaceFolder}/.vscode/kos_environ.sh" ],
"overrideName": true
}
}
}
</syntaxhighlight>

(TODO: to be tested for Mac/OSX: probably needs the 2 lines terminal.integrated.*.linux replaced with terminal.integrated.*.osx)

* '''tasks.json'''
<syntaxhighlight lang="json">
{
"version": "2.0.0",
"tasks": [
{
"label": "Build",
"type": "process",
"command": "bash",
"args": [
"--init-file", "${workspaceFolder}/.vscode/kos_make.sh"
],
"group": {
"kind": "build",
"isDefault": true
},
},
]
}
</syntaxhighlight>

The result should look like this:
{|
| [[File:Vscode cfg files.png|thumb]]
|}

At this point, you should be able to compile applications for the Dreamcast!

==== Compilation ====
You can compile via 2 ways:
# via the VSCode [https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette Command Palette] - "Tasks: Run Build Task", or
# by opening a "kos-bash" terminal (Menu: View-Terminal if not visible yet, then click on the "+" to see the terminals to choose from, and select "kos-bash"), and typing "make"
In both cases, the compilation should generate an executable file, ending with .elf

Note: "kos-bash" is a bash shell with the "source /opt/toolchains/dc/kos/environ.sh" already executed for you. It should be your default shell in VSCode as long as you used the settings.json mentioned above.

==== Running a program ====
For this, we will use the "make run" command that you can find in many (all?) Makefiles of the KallistiOs project, to send and run the program on a real dreamcast:

* Typically, one of the following tools is used to run a program for the Dreamcast:
# on a real Dreamcast:
##via an ethernet cable & a [https://dreamcast.wiki/Broadband_adapter Broadband] (BBA) or [https://dreamcast.wiki/LAN_adapter LAN] adapter: '''[https://dreamcast.wiki/Dcload-ip dcload-ip]'''
## via a [https://dreamcast.wiki/Coder%27s_cable coder's cable] & the serial port of the Dreamcast: '''[https://dreamcast.wiki/Dcload-serial dcload-serial]'''
# on an emulator, like lxdream-nitro

* Make sure that the '''KOS_LOADER''' variable in '''/opt/toolchains/dc/kos/environ.sh''' is configured correctly:

# for '''dcload-ip''' (example if the IP of the Dreamcast is 192.168.1.210):
<syntaxhighlight lang="bash">
export KOS_LOADER="dc-tool-ip -t 192.168.1.210 -x"
</syntaxhighlight>

# for '''dcload-serial''' (example if the Dreamcast is on serial port /dev/ttyS0):
<syntaxhighlight lang="bash">
export KOS_LOADER="dc-tool-ser -t /dev/ttyS0 -x"
</syntaxhighlight>

# for '''the emulator''' (example with lxdream-nitro):
<syntaxhighlight lang="bash">
export KOS_LOADER="/opt/toolchains/dc/lxdream-nitro/builddir/lxdream-nitro -e"
</syntaxhighlight>

* If want to run it on a real Dreamcast, power it on with the dcload disc loaded, and wait for the blue screen
* Open a "kos-bash" terminal, and type: make run
* The program will be running on your Dreamcast or on the emulator !
* (If you ran the 2ndmix example, you can press the START button on the Dreamcast pad to exit)
* Note: be sure to not have a gdb_init(); line added in your code when you only want to run a program & not debug it.

=== Debugging ===
==== Preparation ====
* Make sure that you compiled gdb for the Dreamcast, ie '''/opt/toolchains/dc/sh-elf/bin/sh-elf-gdb''' should exist (cfr prerequisites)
* Debugging in Visual Studio Code is configured in a '''.vscode/launch.json''' file. You can add as many debugging configurations as you want inside that launch.json file, eg 1 for debugging on a dreamcast, 1 for debugging on an emulator, ...

# insert the following files in the '''".vscode" subfolder''':

* '''launch.json''' (example with the IP of the Dreamcast = 192.168.1.210 for the BBA/LAN or /dev/ttyS0 for the serial cable):
<syntaxhighlight lang="json">
{
"version": "0.2.0",
"configurations": [
{
"name": "BBA_LAN",
"type": "cppdbg",
"request": "launch",
"preLaunchTask": "Build",
"cwd": "${workspaceFolder}",
"program": "${workspaceFolder}/${workspaceFolderBasename}.elf",
//"program": "${workspaceFolder}/2ndmix.elf",
"MIMode": "gdb",
"miDebuggerPath": "/opt/toolchains/dc/sh-elf/bin/sh-elf-gdb",
"miDebuggerServerAddress":"localhost:2159",//common misconception: we connect to the gdb server offered by dc-tool-ip, NOT to the Dreamcast directly !
"debugServerPath":"/opt/toolchains/dc/bin/dc-tool-ip",
"debugServerArgs": "-g -t 192.168.1.210 -x ${workspaceFolder}/${workspaceFolderBasename}.elf",
//"debugServerArgs": "-g -t 192.168.1.210 -x ${workspaceFolder}/2ndmix.elf",
//"stopAtEntry": true,
"externalConsole": false,
"avoidWindowsConsoleRedirection": false,
"internalConsoleOptions": "openOnSessionStart",
},
{
"name": "SERIAL",
"type": "cppdbg",
"request": "launch",
"preLaunchTask": "Build",
"cwd": "${workspaceFolder}",
"program": "${workspaceFolder}/${workspaceFolderBasename}.elf",
//"program": "${workspaceFolder}/2ndmix.elf",
"MIMode": "gdb",
"miDebuggerPath": "/opt/toolchains/dc/sh-elf/bin/sh-elf-gdb",
"miDebuggerServerAddress":"localhost:2159",//common misconception: we connect to the gdb server offered by dc-tool-ser, NOT to the Dreamcast directly !
"debugServerPath":"/opt/toolchains/dc/bin/dc-tool-ser",
"debugServerArgs": "-g -t /dev/ttyS0 -x ${workspaceFolder}/${workspaceFolderBasename}.elf",
//"debugServerArgs": "-g -t /dev/ttyS0 -x ${workspaceFolder}/2ndmix.elf",
//"stopAtEntry": true,
"externalConsole": false,
"avoidWindowsConsoleRedirection": false,
"internalConsoleOptions": "openOnSessionStart",
},
{
"name": "LXDream",
"type": "cppdbg",
"request": "launch",
"preLaunchTask": "Build",
"cwd": "${workspaceRoot}",
"program": "${workspaceFolder}/${workspaceFolderBasename}.elf",
//"program": "${workspaceFolder}/2ndmix.elf",
"miDebuggerPath": "/opt/toolchains/dc/sh-elf/bin/sh-elf-gdb",
"setupCommands": [{
"text": "set architecture sh",
"description": "Set GDB Arch to SuperH",
"ignoreFailures" : false,
}],
"miDebuggerServerAddress": ":9999",
// path to lxdream-nitro
"debugServerPath": "PATH_TO_LXDREAM",
// lxdream-nitro flags
"debugServerArgs": "--log=DEBUG --gdb-sh4=9999 -A null -e ${workspaceRoot}/${workspaceFolderBasename}.elf -n",
//"debugServerArgs": "--log=DEBUG --gdb-sh4=9999 -A null -e ${workspaceRoot}/2ndmix.elf -n",
"filterStdout": true,
"filterStderr": true,
// run on connect
"stopAtConnect": false,
// stop at main
"stopAtEntry": true,
"externalConsole": false,
"avoidWindowsConsoleRedirection": false,
"internalConsoleOptions": "openOnSessionStart",
"launchCompleteCommand": "exec-run",
"serverStarted": "SH4 GDB server running on port",
"useExtendedRemote": true
}
]
}
</syntaxhighlight>

Note that for the 3 launch configurations above, you have 2 lines for
"program" and "debugServerArgs", one of which is commented out.
${workspaceFolderBasename} is the name of your project directory (eg: 2ndmix), and if that matches the name of your target .elf file (eg: 2ndmix.elf), then you can use ${workspaceFolderBasename}.
If not, you can just use the other line by replacing ${workspaceFolderBasename} with the real .elf filename.

You'll also need to replace "PATH_TO_LXDREAM" with the path to the emulator installed on your pc.

==== Launching a Debug session ====
{|
| [[File:Vscode debugging.png|thumb|alt=Vscode debugging|Vscode debugging]]
|}
* put a line to initialize gdb in your code (1):
<syntaxhighlight lang="c">
gdb_init();
</syntaxhighlight>

If using lxdream-nitro, a gdb server is already provided and so gdb_init() should ```not``` be called.

TODO: conditional include
* insert a breakpoint '''AFTER''' this gdb_init(); line (1). You can't put a breakpoint before or on this line !
* If want to run it on a real Dreamcast, power it on with the dcload disc loaded, and wait for the blue screen
* Click on the "Debugger" icon (2) on the left
* Select the configuration you want to launch (BBA_LAN, SERIAL, or LXDream)(3)
* Click on the green arrow ("Start Debugging" - F5)(4)

==== Tips ====
* If you want to print out the value of a variable to the console (Terminal) on the pc, add a line like this to your code:
<syntaxhighlight lang="c">
dbglog(DBG_INFO, "value is: 0x%08X\n", variable);
</syntaxhighlight>

==== Troubleshooting Tips ====
* If the dc-tool app does not seem to react anymore:
<syntaxhighlight lang="bash">
sudo netstat -ap | grep :2159
sudo kill <pid>
</syntaxhighlight>

== Sources ==
[https://forums.sonicretro.org/index.php?threads/setting-up-gdb-with-redream-in-linux.38824/ netstat tip source]

[https://dcemulation.org/phpBB/viewtopic.php?t=105596&start=20 Original VSCode topic on dcemulation.org]

Dreamcast emulators

2024-09-10T06:17:31Z

Voxel:

Emulators can be very handy when you want to test code quickly, but can't be totally relied on. Some emulator are closer to the original console while some will run your game even if a real Dreamcast can't.

==Reicast ==
*Official page: [https://reicast.com]
*Developed by: skmp, others. Derived from nullDC.
*Status: Active, Under rewrite
*Platform: Android, Windows, Linux, macOS, html5
===Supported features===
===Known issues===
*Extremely buggy

==Redream==
*Official page: [https://redream.io]
*Developed by: inolen
*Status: Active
*Platform: Android, Windows, Linux, macOS
===Supported feature===
===Known issues===
*No sound support for homebrew with HLE bios

==NullDC==
*Official page: [https://github.com/skmp/nulldc]
*Developed by: skmp, ZeZu, PsyMan
*Status: Inactive
*Platform: Windows
===Supported feature===
===Known issues===

==lxdream==
*Official page: [http://www.lxdream.org/news/]
*Developed by: nkeynes
*Status: Inactive
*Platform: Linux and macOS
===Supported feature===
-'''DEV''' Console support (printf)
===Known issues===

==lxdream-nitro==
*Official page: [https://gitlab.com/simulant/community/lxdream-nitro]
*Platform: Linux and macOS
*A community-improved version of lxdream
===Known issues===
*No KOS cd access when using bundled HLE bios

==Demul==
*Official page: [http://demul.emulation64.com/]
*Developed by: Wind, CaH4e3, ajax16384, DreamZzz, MetalliC
*Status: Inactive
*Platform: Windows
===Supported feature===
*MMU, Naomi 2
===Known issues===

==WashingtonDC==
*Official page: [http://washemu.org/]
*Developed by: snickerbockers
*Status: Active
*Platform: Linux, Windows
===Supported feature===
*Console support (printf) via serial port
*remote GDB debugging
===Known issues===
*game compatibility
*Z-Fighting

==MAME==
*Official page: [http://mamedev.org/]
*Developed by: MAME community
*Status: Active
*Platform: Linux, Windows
===Supported feature===
===Known issues===
*game compatibility
*speed

==Other older emulators==
These emulators are listed mostly for historical/archival reasons.
===Chankast===
*Chankast is a Dreamcast emulator for Windows. Released on May 29th, 2004, Chankast was the first publicly-released Dreamcast emulator to play commercial games playably. It is now considered outdated.
*Authors: baktery, unai and garrofi
*[http://www.chanka.org/ Homepage]
*Latest version: Alpha 0.25, 07/07/2004
===Makaron===
*Makaron
[[File:Swirly.jpg|thumb|Swirly running Megan Potter's Stars demo]]
===DreamEmu===
[[File:Dreamemu-01.jpg|thumb|DreamEmu running DC Space Invaders]]
* Developed by Lord Cheese, DreamEmu is an early Dreamcast emulator that can only run some tech demos and homebrew, last released on 10/28/02.
* Downloads: [https://files.dcemulation.org/software/dcemulators/dreamemu/dreamemu-0.0.4.1-bin-rel.zip 0.0.4.1], [https://files.dcemulation.org/software/dcemulators/dreamemu/dreamemu-003.zip v0.03 - 08/03/01], [https://files.dcemulation.org/software/dcemulators/dreamemu/dreamemu-002.zip v0.02], [https://files.dcemulation.org/software/dcemulators/dreamemu/dreamemu_001a.zip v0.01a]
* [http://www.dreamemu.net/ Homepage]

===Dreamer===
*Developed by ElSemi in late 2000 into mid-2001, Dreamer was the first working and released Dreamcast emulator for PC.
*Latest version: Alpha 0.25 - Download [https://files.dcemulation.org/software/dcemulators/dreamer/dreamer002.zip v0.02]
*[Dreamer](http://emulatronia.com/dcemu.htm)
*SH4: All opcodes is emulated (100% have not been proven) interprets. Those of movements of data to memory and jumps are emulated using dynamic recompilación.

*FPU: All opcodes emulated for want of the 2 specific instructions of the Dreamcast. > uses the interpreter - Slow.

*PowerVR: The basic part of the hardware 2d works (Framebuffer correctly and control registries). It lacks the way of video 555. We are at the moment looking for information on the hardware 3d and display lists.

*JoyPad: Emulated completely.

*Maple Bus: The control registries have been identified and will be working shortly.

*Sound: Nothing yet.

*CDROM: Almost emulated.

*DEBUGGER: The emulator takes integrated to debugger (that is a little patatero but it plays his role). Executing debugger implies that the execution of the program is much more slow. The handling keys are the following ones:

*F5: Go (uninterrupted Execution) 
*F7: Draw up Into (to execute entering the subroutines) 
*F8: Step Over (To execute without entering the subroutines, does not work to 100%)

*Commandos: The commandos are written in the inferior part of the window of the code: 
**G (Just as F5) 
**G direction (Executes until that direcci¢n. in hex) 
**D direction (shows the memory of the specified direction. in hex) 
**D registry (it shows the memory of the direction loaded in the chosen registry) 
**And direction data (writes in the direction the specified data. 0-FF in hex) 
**R registry value (loads the value in the registry. 0-FFFFFFFF in hex) 
**S (it stops the single emulation works in Go way) 
**F (it draws framebuffer) 
**X (to leave) 
**Z (reset, cracks, not to use) 
**WD 0|1 (oculta|muestra window of data) 
**WR 0|1 (oculta|muestra window of registries) 
**WM 0|1 (oculta|muestra window of messages) 
**WC 0|1 (oculta|muestra code window, nor is happened to you, but where you write)

===Swirly===
*[Swirly](http://swirly.sourceforge.net/)