How phenom64/openxmb works
1. What this repository is
OpenXMB is a C++23 desktop UI shell that reimagines the PlayStation-style XMB. The runtime is not a general-purpose app framework; it is a single interactive front-end that coordinates menus, overlays, media viewers, and optional modules inside one Vulkan-rendered interface.
2. Top-level execution path
src/main.cpp is the entry point. Startup flows into the application/shell layer (src/app/shell.cpp, src/app/module.cppm), which initializes configuration, localization, rendering, and input, then hands control to the main navigation loop.
3. Core platform boundary
SDL2 is the platform-facing layer for window creation, input, and likely audio/event plumbing. Vulkan is the graphics API. The actual renderer is delegated to AuroreEngine (built on dreamrender), so OpenXMB sits above the engine rather than managing raw Vulkan frame logic everywhere.
4. Rendering architecture
Rendering is split into a dedicated src/render subtree. It contains shader management plus render components for the XMB look and effects: wave background, original-style renderer, and particle variants. Shader sources live in shaders/, including compute passes for blur/downsample/upsample and YUV decoding, which indicates a GPU-heavy pipeline with postprocessing and media decode support.
5. UI composition model
The visible interface is built from reusable components in src/app/components and layered effects in src/app/layers. Examples include startup, progress, message, and choice overlays, plus a blur layer. This suggests a composited UI model where the shell is always present and transient overlays are stacked above the main navigation state.
6. Navigation and menu subsystem
The menu tree lives under src/menu/ and is divided into domain-specific menus: applications, files, settings, and users. This is the main user-navigation boundary. The menus likely feed content into the shell rather than owning rendering themselves, keeping content selection separate from presentation.
7. Programs / content viewers
src/programs/ contains built-in viewers for images, text, and video. These are treated as sub-apps opened from the shell rather than independent executables. The video path is notable because the README says it uses FFmpeg plus GPU-accelerated YUV decoding, so media decoding is a distinct pipeline from normal menu rendering.
8. Optional feature modules
src/modules/ holds optional alpha integrations: browser, disc media, and libretro. These are feature boundaries that can be compiled out. Architecturally, they extend the shell with specialized content sources without changing the core navigation or renderer.
9. Config, constants, and utilities
Runtime behavior is driven by config.json through src/config.*, with shared constants and helpers in src/constants.cppm and src/utils.*. Config affects visual theme, font choices, date/time display, controller behavior, and render quality. The runtime resolves config from environment and app-local/user locations, so deployment layout matters.
10. Assets and localization
The repository includes packaged asset trees under interfaceFX/ for graphics, audio, and typefaces, plus gettext catalogs in po/. The launcher/build scripts set asset and locale directories at runtime, so the app expects a structured install layout rather than baking everything into code only.
11. Build and packaging topology
This repo is organized as a CMake/Ninja project with C++ modules and resource embedding (resources.qrc, embedded shader/resource paths). The build is designed to run across Linux/SynOS, macOS with MoltenVK, and Windows via vcpkg/LLVM. CI and smoke scripts validate not just compilation but staged install layout, launcher startup, and presence of key assets.
12. External dependency boundaries
The important external boundaries are: SDL2 for platform I/O, Vulkan/MoltenVK for graphics, AuroreEngine/dreamrender for rendering infrastructure, FFmpeg for video, gettext for localization, and optionally CEF/libretro/disc tooling for alpha features. OpenXMB is essentially the orchestration layer that ties these services into a single XMB-style shell.
Main entry points: shell.cpp Shell · main_menu.cpp Main Menu · module.cppm Render Module · base.cppm Menus
Components 34
Runtime
Entry, shell, config, and app coordination
- Main · Program entry and startup handoff
src/main.cpp - Shell · Initializes and runs the interactive XMB shell
src/app/shell.cpp - App Module · Top-level app module boundary
src/app/module.cppm - Config · Loads user and environment-driven settings
src/config.cpp - Constants · Common compile-time/runtime constants
src/constants.cppm
UI Shell
Composable overlays and menu navigation
- Overlays · Reusable transient UI components
src/app/components/main_menu.cpp - Startup · Boot and startup status layer
src/app/components/startup_overlay.cpp - Progress · Progress feedback layer
src/app/components/progress_overlay.cpp - Message · Status and error message layer
src/app/components/message_overlay.cpp - Choice · User choice and confirmation layer
src/app/components/choice_overlay.cpp - Blur Layer · Backdrop blur compositing layer
src/app/layers/blur_layer.cpp - Main Menu · Primary shell menu composition
src/app/components/main_menu.cpp - Menus · Domain menus for shell navigation
src/menu/base.cppm - Apps Menu · Application launcher navigation
src/menu/applications_menu.cpp - Files Menu · File browsing navigation
src/menu/files_menu.cpp - Settings · Settings navigation and options
src/menu/settings_menu.cpp - Users · User/profile navigation
src/menu/users_menu.cpp
Content
Built-in viewers and optional feature modules
- Programs · Built-in viewers opened from the shell
src/programs.cpp - Image Viewer · Image viewing sub-app
src/programs/image_viewer.cppm - Text Viewer · Text viewing sub-app
src/programs/text_viewer.cppm - Video Player · Video playback pipeline and sub-app
src/programs/video_player.cppm - Optional Modules · Compile-time optional integrations
src/modules/browser.cppm - Browser · Browser integration boundary
src/modules/browser.cppm - Disc Media · Disc/media integration boundary
src/modules/disc.cppm - Libretro · Retro content integration boundary
src/modules/libretro.cppm
Rendering
GPU rendering, shader management, and visual effects
- Render Module · Connects shell UI to the rendering subsystem
src/render/module.cppm - Shaders · Shader loading and shader pipeline management
src/render/shaders.cpp - Wave Renderer · XMB wave background renderer
src/render/components/wave_renderer.cppm - Original Renderer · Original-style XMB renderer
src/render/components/original_renderer.cppm - Particles · Particle effect variant renderer
src/render/components/original_particles.cppm
Support
Assets, localization, build, and external integration boundaries
- Assets · Packaged graphics, audio, and typefaces
interfaceFX/GraphicsServer/HomeMenu - Localization · Translated message catalogs
po/en.po - QML UI · Supplementary QML frontend entrypoint
qml/main.qml - Build · CMake build, presets, and install layout
CMakeLists.txt
Connections 32
- Main → Shell: starts · Program entry hands off to shell startup
- Shell → Config: loads · Shell initializes runtime configuration
- Shell → App Module: initializes · Shell enters the application module boundary
- Shell → Render Module: binds · Shell connects UI state to renderer
- Shell → Menus: drives · Shell owns the main navigation loop
- Shell → Programs: opens · Shell launches built-in viewers
- Shell → Optional Modules: extends · Optional integrations are attached through modules
- App Module → Main Menu: composes · Application module composes the visible shell UI
- Main Menu → Startup: layers · Startup overlay appears above the main shell
- Main Menu → Progress: layers · Progress overlay appears during loading
- Main Menu → Message: layers · Message overlay provides status and errors
- Main Menu → Choice: layers · Choice overlay handles confirmations
- Main Menu → Blur Layer: effects · Blur layer provides background compositing
- Menus → Apps Menu: includes · Menu tree includes application navigation
- Menus → Files Menu: includes · Menu tree includes file browsing
- Menus → Settings: includes · Menu tree includes settings navigation
- Menus → Users: includes · Menu tree includes user navigation
- Programs → Image Viewer: contains · Built-in image viewer sub-app
- Programs → Text Viewer: contains · Built-in text viewer sub-app
- Programs → Video Player: contains · Built-in video player sub-app
- Optional Modules → Browser: contains · Optional browser integration
- Optional Modules → Disc Media: contains · Optional disc-media integration
- Optional Modules → Libretro: contains · Optional libretro integration
- Render Module → Shaders: manages · Renderer module manages shader pipeline assets
- Render Module → Wave Renderer: routes · Wave background renderer is selected through render module
- Render Module → Original Renderer: routes · Original XMB renderer is selected through render module
- Render Module → Particles: routes · Particle variant is part of the visual effect set
- Video Player → Shaders: uses · Video playback depends on GPU decode shaders
- Shell → Assets: uses · Shell consumes packaged interface assets
- Shell → Localization: uses · Shell loads translated text resources
- Build → Render Module: builds · Build system assembles the render subsystem
- Build → QML UI: packages · Build includes auxiliary QML UI resources