How obaraemmanuel/nes works
Main Components
a. Core Emulator Engine (Native C code)
• CPU6502 module (cpu6502.c/.h)
• PPU module (ppu.c/.h)
• APU module (apu.c/.h)
• MMU & Mapper subsystem (mmu.c/.h + src/mappers/*.c)
• Graphics & Audio output helpers (gfx.c/.h, biquad.c/.h)
• Input handlers (controller.c/.h, touchpad.c/.h, gamepad.c/.h)
• Utility & debug modules (utils.c/.h, debugtools.c/.h, trace.c)
• Main orchestrator (main.c, emulator.c/.h)
b. Native Library & Build System
• CMakeLists.txt (defines how native code builds into libnes.so)
• external/SDL & external/SDL_ttf (third-party libraries)
c. SDL / JNI Bridge
• org.libsdl.app package (SDL.java, SDLActivity.java, SDLSurface, etc.)
• Provides JNI glue:
– JNI calls from Java → native engine entry point
– Framebuffer render via SDL_Surface → Android Surface
– Audio callback wiring via SDLAudioManager
– Input events forwarded to native (HIDDeviceManager → controller.c)
d. Android Front-End App
• Gradle build (android/app/build.gradle, settings.gradle)
• UI Activities:
– MainActivity (ROM browser UI, RecyclerView with NESItemAdapter)
– EmulatorActivity (launches SDLActivity behind the scenes to run emulation)
• UI Layouts & Resources (res/layout/*.xml, drawable/, values/, mipmap/)
• Asset management (assets folder for bundled items)
Relationships & Data Flows
• ROM Selection Flow:
MainActivity UI → user taps a ROM → Java filepicker → path passed to EmulatorActivity.
• Emulation Startup:
EmulatorActivity → invokes SDLActivity (native SDL) → JNI init → native main.c reads ROM.
• Input Flow:
Android touch/gamepad events (EmulatorActivity → SDLInputConnection/HIDDeviceManager) → controller.c.
• Rendering & Audio Flow:
native PPU generates pixel buffer → SDL_Surface → SDLSurface → Android SurfaceView.
native APU audio buffer → SDLAudioManager → Android AudioTrack.
• Mapper & Memory:
CPU & PPU request memory reads/writes → MMU routes to ROM/RAM or mapper logic.
Architectural Patterns & Principles
• Layered Architecture: clear separation between Core Engine, SDL Bridge, and Android UI.
• Modular C design: one module per hardware component (CPU, PPU, APU, MMU, Mappers).
• Externalization of platform specifics: SDL abstracts cross-platform I/O.
• Build-time separation: CMake for native, Gradle for Android, coordinated via Android NDK plugin.