jptiz / libgba-cpp

C++ Library for Game Boy Advance Development

LibGBA - CPP

What is it?

It's a C++ library for GBA homebrew development. Focused on better API and abstraction, so programmers can focus more on game logic and call functions for effects instead of thinking in a too low-level way.

Requirements

A lot of statements are being written with C++11/14/17 features, so, the requirements are:

• Toolchain: DevKitPro (to compile for GBA ARMv4 ISA and ARM7TDMI processor).
• Compiler: GCC 7.1 or above;
• Build-system: Meson

Examples

• AlphaBlending (BG Layers)
• Generated Tilemaps
• Interrupts
• Mode5
• Mosaic
• Sound
• Tilemap
• Windowing

Building

To build this project, after installing the Requirements and cloning this repository, enter the cloned repository's directory and run:

$ meson build --cross-file cross_file.ini

If you want to build examples as well, add -Dbuild-tests=true to the command:

$ meson build -Dbuild-tests=true

Running examples

After building the examples (see Building), you'll need a GBA emulator. My personal recommendations are:

• MGBA: an open-source fully-featured GBA emulator with a lot of cool debugging tools. Can also link with GDB for a professional in-depth debugging.
• Visual Boy Advance-M: continuation of the almighty legendary VisualBoyAdvance.

Examples are compiled into the build/tests directory. So to run, say, alphablend example, you should open build/tests/alphablend.gba with your emulator.

Documentation

• API Documentation

To-Do's

Check issues.

Bibliography

There are two main contributions for the knowledge necessary to make this library: one is the greatly well explained tutorials TONC by J Vijn (which I really want to thank him for making it), and the other is the great GBA Techical Manual by Martin Korth.

libgba-cpp's Issues

Move away from makefiles

Currently the system use a very handmade Makefile structure as a build system. Using cmake (EDIT: or meson!) could be a good choice.

To set the ARMv7TDMI compiler, this CMAKE line could be useful:

set(CMAKE_CXX_COMPILER <something>)

In meson, it would be through a cross-file.

Add DMA support

Scenery

DMA (Direct Memory Access) helps transfering huge amounts of data while leaving CPU alone to do other things. This is necessary for playing music in proper ways, and for some cool visual effects. There's currently no DMA implementation nor sketch.

Where to start

Try to follow TONC's DMA tutorial.

Investigate GBA memory access issues

In a recent pong game development, I noticed sometimes memory-mapped register access does not work as expected in runtime.

Running mgba-qt with console logs enabled, the following is shown ("ERRO DO JOGO" = "Game error"):

ERRO DO JOGO] GBA I/O: Write to read-only I/O register: 006
[ERRO DO JOGO] GBA Video: Invalid video register: 0x056
[ERRO DO JOGO] GBA DMA: Invalid DMA source address: 0x00000000
[ERRO DO JOGO] GBA DMA: Invalid DMA source address: 0x00000000
[ERRO DO JOGO] GBA DMA: Invalid DMA source address: 0x00000000
[ERRO DO JOGO] GBA DMA: Invalid DMA source address: 0x00000000

Which might point out to the cause.

Possible solution

To not "reinvent the wheel" and spend to much time figuring out what's wrong in the memory access, it would be better to just build the API as a thin wrapper to https://github.com/devkitPro/libgba.

Add SFX and Music support

Scenery

Currently there's no working SFX implementation. There are some tests on a specific branch. For music, #6 will be needed.

Where to start

One could read about sound register in the technical manual to implement a simple API to access them, and then read about Interrupt Control to make audio play using interrupts. With those two, plus DMA transfer, audio frequencies may be transferred to each channel's FIFO and then music should play.

Hints

These may help:

• Sound on the Gameboy Advance - Deku's Tree of Art;
• Audio Programming on the GameBoy Advance Part 1 - gamedev.net;
• Writing a Game Boy Advance Game - reinterpretcast;
• The Audio Advance.

screenshots of samples

Hello I have compiled the samples but I see some red lines, is this expected?

It would be nice to have screenshots of samples so I can compare against my build.

Fix Mosaic effects

Scenery

There is a Mosaic-effect implementation with a test game. Currently they're not working (TODO: describe what is not working).

Where to start

See codes linked above and read about Mosaic in the technical manual.

documentation links to itself

your "API docs" contain pretty much the same as the readme and the link to the "API docs" inside it link to the same page again.

Master is broken

Okay, after MONTHS without touching this thing properly I realized master branch is broken, which is unnacceptible. Who in hell made this?

$ git blame src/arch/display/video.cpp
40891023 src/drivers/display/video.cpp (João Paulo Taylor Ienczak Zanette 2018-07-17 12:56:27 -0300  1) #include <libgba-cpp/arch/display/video.h>
f9070b92 src/drivers/display/video.cpp (João Paulo Taylor Ienczak Zanette 2018-07-17 13:11:19 -0300  2) #include <libgba-cpp/utils/general.h>
ba7f6d3a src/drivers/display/video.cpp (João Paulo Taylor Ienczak Zanette 2017-09-23 21:39:36 -0300  3) 
ba7f6d3a src/drivers/display/video.cpp (João Paulo Taylor Ienczak Zanette 2017-09-23 21:39:36 -0300  4) namespace {
ba7f6d3a src/drivers/display/video.cpp (João Paulo Taylor Ienczak Zanette 2017-09-23 21:39:36 -0300  5) 
972fdf7e src/drivers/display/video.cpp (João Paulo Taylor Ienczak Zanette 2017-11-02 02:09:17 -0200  6) using gba::display::Page;
1c0993f5 src/drivers/display/video.cpp (João Paulo Taylor Ienczak Zanette 2017-09-26 12:02:43 -0300  7) using gba::display::Color;
f8101474 src/arch/display/video.cpp    (João Paulo Taylor Ienczak Zanette 2018-07-26 19:26:57 -0300  8) using gba::display::RawPalette;
ba7f6d3a src/drivers/display/video.cpp (João Paulo Taylor Ienczak Zanette 2017-09-23 21:39:36 -0300  9) using gba::display::VRAMData;
ba7f6d3a src/drivers/display/video.cpp (João Paulo Taylor Ienczak Zanette 2017-09-23 21:39:36 -0300 10) 
ba7f6d3a src/drivers/display/video.cpp (João Paulo Taylor Ienczak Zanette 2017-09-23 21:39:36 -0300 11) static auto& vram_data = *new (reinterpret_cast<void*>(0x0600'0000)) std::array<VRAMData, 0x18000 / 2>{};
ba7f6d3a src/drivers/display/video.cpp (João Paulo Taylor Ienczak Zanette 2017-09-23 21:39:36 -0300 12) 
972fdf7e src/drivers/display/video.cpp (João Paulo Taylor Ienczak Zanette 2017-11-02 02:09:17 -0200 13) static auto page = Page::PAGE1;
972fdf7e src/drivers/display/video.cpp (João Paulo Taylor Ienczak Zanette 2017-11-02 02:09:17 -0200 14) 
ba7f6d3a src/drivers/display/video.cpp (João Paulo Taylor Ienczak Zanette 2017-09-23 21:39:36 -0300 15) }
ba7f6d3a src/drivers/display/video.cpp (João Paulo Taylor Ienczak Zanette 2017-09-23 21:39:36 -0300 16) 
ba7f6d3a src/drivers/display/video.cpp (João Paulo Taylor Ienczak Zanette 2017-09-23 21:39:36 -0300 17) std::array<VRAMData, 0x18000 / 2>& gba::display::vram_data() {
ba7f6d3a src/drivers/display/video.cpp (João Paulo Taylor Ienczak Zanette 2017-09-23 21:39:36 -0300 18)     return ::vram_data;
ba7f6d3a src/drivers/display/video.cpp (João Paulo Taylor Ienczak Zanette 2017-09-23 21:39:36 -0300 19) }
ba7f6d3a src/drivers/display/video.cpp (João Paulo Taylor Ienczak Zanette 2017-09-23 21:39:36 -0300 20) 
972fdf7e src/drivers/display/video.cpp (João Paulo Taylor Ienczak Zanette 2017-11-02 02:09:17 -0200 21) Color& gba::display::mode5::vram(int x, int y) {
972fdf7e src/drivers/display/video.cpp (João Paulo Taylor Ienczak Zanette 2017-11-02 02:09:17 -0200 22)     return vram(x  + screen_width * y);
972fdf7e src/drivers/display/video.cpp (João Paulo Taylor Ienczak Zanette 2017-11-02 02:09:17 -0200 23) }
972fdf7e src/drivers/display/video.cpp (João Paulo Taylor Ienczak Zanette 2017-11-02 02:09:17 -0200 24) 
972fdf7e src/drivers/display/video.cpp (João Paulo Taylor Ienczak Zanette 2017-11-02 02:09:17 -0200 25) Color& gba::display::mode5::vram(int index) {
972fdf7e src/drivers/display/video.cpp (João Paulo Taylor Ienczak Zanette 2017-11-02 02:09:17 -0200 26)     return vram_data()[index + utils::value_of(::page) * screen_width * screen_height].color;
972fdf7e src/drivers/display/video.cpp (João Paulo Taylor Ienczak Zanette 2017-11-02 02:09:17 -0200 27) }
972fdf7e src/drivers/display/video.cpp (João Paulo Taylor Ienczak Zanette 2017-11-02 02:09:17 -0200 28) 
972fdf7e src/drivers/display/video.cpp (João Paulo Taylor Ienczak Zanette 2017-11-02 02:09:17 -0200 29) Page gba::display::mode5::page() {
972fdf7e src/drivers/display/video.cpp (João Paulo Taylor Ienczak Zanette 2017-11-02 02:09:17 -0200 30)     return ::page;
972fdf7e src/drivers/display/video.cpp (João Paulo Taylor Ienczak Zanette 2017-11-02 02:09:17 -0200 31) }
972fdf7e src/drivers/display/video.cpp (João Paulo Taylor Ienczak Zanette 2017-11-02 02:09:17 -0200 32) 
972fdf7e src/drivers/display/video.cpp (João Paulo Taylor Ienczak Zanette 2017-11-02 02:09:17 -0200 33) void gba::display::mode5::flip_pages() {
972fdf7e src/drivers/display/video.cpp (João Paulo Taylor Ienczak Zanette 2017-11-02 02:09:17 -0200 34)     select_page(::page);
f8101474 src/arch/display/video.cpp    (João Paulo Taylor Ienczak Zanette 2018-07-26 19:26:57 -0300 35) 
f8101474 src/arch/display/video.cpp    (João Paulo Taylor Ienczak Zanette 2018-07-26 19:26:57 -0300 36)     constexpr auto PAGE0 = Page::PAGE0;
f8101474 src/arch/display/video.cpp    (João Paulo Taylor Ienczak Zanette 2018-07-26 19:26:57 -0300 37)     constexpr auto PAGE1 = Page::PAGE1;
f8101474 src/arch/display/video.cpp    (João Paulo Taylor Ienczak Zanette 2018-07-26 19:26:57 -0300 38)     ::page = ::page == PAGE0 ? PAGE1 : PAGE0;
972fdf7e src/drivers/display/video.cpp (João Paulo Taylor Ienczak Zanette 2017-11-02 02:09:17 -0200 39) }

Oh damn, it was me. Every line.

I'm sorry everyone, I shall fix this. ASAP.

Fix interrupt handling

Scenery

There is currently an implementation of Interrupt handling:

• include/libgba-cpp/arch/cpu/interrupts.h;
• include/libgba-cpp/arch/cpu/interrupts.cpp.

TODO: describe what is not working.

Make writable graphics API

Scenary

Currently all data must bem const to be placed in ROM. This is done this way because there is only 32KB in SRAM (+256KB in DRAM), and graphics potentially use much more than that (and there still need space for game data while playing).

Ideas

No idea from where to start, actually. Maybe with palette?

Make setup.sh an actual setup (or switch to a `make` subcommand)

Currently, setup.sh exists just to a quick workshop I lectured years ago and everything it does is...

#!/usr/bin/bash
export LIBGBA=$(pwd)

...pretty self-explanatory. It would be nice to make it actually do something useful - or even remove it or switch into make commands.

Documentation: add tutorials for the library API usage

Even I find myself lost when I'm going to use this API after a long time without usage. Having small tutorials with simple tasks will not only be very cute and help teaching GBA mechanics, but also improve the usability of this library a lot.

Documentation: add build instructions

A newcomer might get completely lost in this repo. Having at least a simple and small how-to-build section in Readme would help a lot.