MosisService/ARCHITECTURE.md

MosisService Architecture

Overview

MosisService is an Android application that combines Kotlin UI components with native C++ libraries for UI rendering and system interaction. The architecture is built around a service-oriented design using Android's Binder system and integrates with RmlUi for rich UI rendering.

Core Components

1. Service Layer (mosis-service)

• Purpose: Main Android Binder service implementation
• Interface: Implements IMosisService.aidl
• Functionality:
  • Touch event processing (onTouchDown, onTouchMove, onTouchUp)
  • Service initialization and listener management
  • Integration with kernel-based rendering system
  • Asset loading through Android AssetManager

2. Rendering Layer (mosis-test)

• Purpose: UI rendering and testing infrastructure
• Interface: Implements IMosisListener.aidl
• Functionality:
  • OpenGL ES 2.0 rendering pipeline using GLAD
  • Multi-threaded rendering with EGL context management
  • Surface and buffer handling for Android native windows
  • Task queue management for asynchronous rendering operations
  • Hardware buffer management and processing

3. Core Engine (Kernel)

• Purpose: Central rendering and event processing engine
• Components:
  • RmlUi-based UI rendering engine
  • EGL context creation and management
  • Render target handling
  • Touch event processing and UI updates
  • Multi-threaded execution using std::thread

4. Supporting Libraries

• AssetsManager: Asset loading from Android AssetManager
• Logger: Cross-platform logging system
• EGL Context: OpenGL ES context management
• Render Target: Framebuffer and buffer management
• Shader: OpenGL shader program handling
• External Texture: Hardware buffer texture creation

System Architecture

Android Binder Integration

• Uses AIDL (Android Interface Definition Language) for cross-process communication
• Service exposes IMosisService interface for touch events and initialization
• Listener pattern with IMosisListener for rendering callbacks
• Binds to Java/Kotlin components through JNI

Multi-threading Model

• Service layer runs in main thread for event handling
• Rendering loop runs in dedicated thread managed by Kernel
• Async task processing for UI updates
• Thread-safe communication between components

Rendering Pipeline

1. Initialization: Service connects to test layer, creates EGL context
2. Buffer Management: Hardware buffers allocated and shared between layers
3. Event Processing: Touch events processed and forwarded to Kernel
4. Rendering Loop: Continuous rendering with frame synchronization
5. UI Updates: RmlUi engine updates UI based on events and data

Data Flow

User Touch Events → IMosisService.onTouch* → Kernel.process → RmlUi UI Updates
Service Initialized → IMosisListener.onServiceInitialized → Rendering Setup
Buffer Available → IMosisListener.onBufferAvailable → Texture Creation
Frame Available → IMosisListener.onFrameAvailable → Frame Rendering

Key Technologies

• Android NDK: Native development with C++23
• CMake: Build system for native libraries
• RmlUi: UI rendering engine with HTML/CSS-like markup
• OpenGL ES 2.0: Graphics rendering
• GLAD: OpenGL loader library
• AIDL: Inter-process communication
• Binder: Android's IPC mechanism

File Structure

• mosis-service.cpp: Main service implementation
• mosis-test.cpp: Test/rendering implementation
• kernel.cpp: Core rendering engine and event processing
• assets_manager.cpp: Asset loading utilities
• egl_context.cpp: EGL context management
• render_target.cpp: Framebuffer handling
• logger.cpp: Cross-platform logging

Code Standards

• Modern C++23 with smart pointers and RAII
• Thread-safe operations using std::mutex
• Resource management with proper cleanup
• Use of std::span, std::format for modern features
• Cross-platform compatibility through Android NDK