Skip to content

Commit ac167a2

Browse files
jcarr71jcarr71
authored
Add onscreen interactive keypad overlay support (#92)
* Add stb_image implementation file This commit introduces the implementation of stb_image functions in a new source file, stb_image_impl.c. This file includes the necessary definitions to enable the functionality provided by the stb_image library. Only one C file should define STB_IMAGE_IMPLEMENTATION to avoid multiple definitions. * Update binary libraries for various architectures * feat: Implement in-game file browser for FreeIntv - Added comprehensive technical overview and visual reference documentation for the file browser feature. - Added support for various platforms, ensuring consistent behavior across Windows, Linux, macOS, Android, Switch, and Vita. - Included error handling strategies and performance considerations for efficient operation. - Updated build configurations to include new source files for different architectures (arm64-v8a, armeabi-v7a, riscv64, x86, x86_64). * feat: Add initial libretro info file for FreeIntvTSOverlay * Add object dependency files for FreeIntvTSOverlay source files - Created dependency files for various source files including cart.c, controller.c, cp1610.c, and others. - Updated dependencies for libretro-common components such as compat_posix_string.c, compat_snprintf.c, and file_path.c. - Included necessary headers for each source file to ensure proper compilation. - Enhanced project structure by organizing object files and their dependencies for better build management. * feat: Update documentation and code for FreeIntvTSOverlay touchscreen support * Enhance README with images and contributor details Added images and updated contributors section in README. * docs: Enhance README with details on touchscreen and mouse input for overlays * Implement code changes to enhance functionality and improve performance * Add Ko-fi username for funding Added Ko-fi username for funding support. * chore: Prepare for upcoming feature enhancements and optimizations * chore: Update documentation for clarity and consistency * Refactor code structure for improved readability and maintainability * Checked compile on Android, Windows, and Linux * Refactor code structure for improved readability and maintainability * Implement feature X to enhance user experience and fix bug Y in module Z * chore: Update README for clarity and consistency * Fix: Revert valid_extensions from 'intv' to 'int' to restore ZIP file loading * chore: Update .gitignore to exclude build artifacts and IDE files * chore: Remove build artifacts tracked by git (now in .gitignore) * refactor: Rename asset folder from FreeIntvTS_Overlays to freeIntv_image_assets * Removed utility buttons and added logo banner, prepping for change to a 'core option'. * Changed naming entries to FreeIntv without the TS Overlay to prepare for change to core option from separate core * Incorporate PNG files into the code to alleviate need for external files * corrected overlay loading code, and fixed keypad transparency * updated documentation and screenshots * Enhance user documentation with installation steps and dual-screen display instructions * Update FreeIntv_libretro.info for improved clarity and accuracy in display name, supported extensions, and description * Add dual-screen touchscreen and overlay support to FreeIntv core - Implement side-by-side dual-screen rendering (1074×600 workspace) - Add touchscreen hotspot input detection for 12 keypad buttons - Support ROM-specific PNG overlays (370×600 pixels) - Add cross-platform input handling (Android, Windows, Linux) - Include screen swap functionality - Update documentation with setup and usage instructions - Update core metadata and info file - Remove debug logging infrastructure - Maintain full backward compatibility * Update FreeIntv_libretro.info, README.md, and USER_GUIDE.md for enhanced onscreen interactive keypad overlays and improved versioning * fix: Correct corename typo in FreeIntv_libretro.info * Corrected multi-screen core option menu item. Fixed onscreen keypad in default single screen mode. * Updated wording for the new core option to specify restart and touchscreen/mouse are required. * Add step to mark repo as safe in workflow * Updated readme and user guide --------- Co-authored-by: Jason Carr <[email protected]>
1 parent 1b51f41 commit ac167a2

33 files changed

+85439
-46
lines changed

‎.github/FUNDING.yml‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# These are supported funding model platforms
2+
3+
github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
4+
patreon: # Replace with a single Patreon username
5+
open_collective: # Replace with a single Open Collective username
6+
ko_fi: jcarr71
7+
tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
8+
community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
9+
liberapay: # Replace with a single Liberapay username
10+
issuehunt: # Replace with a single IssueHunt username
11+
lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
12+
polar: # Replace with a single Polar username
13+
buy_me_a_coffee: # Replace with a single Buy Me a Coffee username
14+
thanks_dev: # Replace with a single thanks.dev username
15+
custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

‎.github/copilot-instructions.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# FreeIntv with Android Touchscreen Support - AI Agent Instructions
2+
3+
## Project Overview
4+
5+
FreeIntv is a libretro emulation core for the Mattel Intellivision, recently enhanced with Android touchscreen support. The codebase is a C-based emulator that runs on the libretro framework, supporting multiple platforms (Linux, Windows, macOS, Nintendo Switch, PS Vita, etc.).
6+
7+
**Key Architecture**: Libretro plugin core → RetroArch frontend. The core handles CPU emulation, graphics, audio, controllers, and now dual-screen rendering with an integrated touchscreen keypad UI.
8+
9+
## Core Components & Data Flows
10+
11+
### 1. **Emulation Engine** (`src/intv.c`, `src/cp1610.c`, `src/stic.c`, `src/psg.c`)
12+
- **CP1610**: 16-bit CPU emulator with cycle-accurate instruction execution
13+
- **STIC**: Graphics chip that renders 352×224 pixels to frame buffer (`extern unsigned int frame[352*224]`)
14+
- **PSG/Intellivoice**: Audio subsystem
15+
- **Memory**: 16-bit address space (0x10000 addresses), with BIOS ROM, cartridge ROM, and RAM
16+
17+
**Pattern**: Each subsystem has serialization functions (`CP1610Serialize`, `STICSerialize`, etc.) for save states.
18+
19+
### 2. **Dual-Screen Rendering System** (`src/libretro.c: render_dual_screen()`)
20+
The new touchscreen feature uses a horizontal layout:
21+
```
22+
[Game Screen (704×448)] [Keypad UI (370×600)]
23+
└─ 2x scaled 352×224 └─ 12 buttons + indicators
24+
[Utility Buttons (704×100)]
25+
```
26+
**Workspace**: 1074×600 pixels total. Display can swap positions via `display_swap` flag.
27+
28+
### 3. **Controller Mapping** (`src/controller.c`, `src/controller.h`)
29+
- **RetroPad input** (from RetroArch joypad array) → Intellivision controller codes
30+
- **Keypad codes**: 12 buttons (1-9, 0, *, #) with specific bit patterns (e.g., `K_1=0x81`, `K_5=0x42`)
31+
- **Disc**: 16-way analog stick mapping for directional control
32+
- **Action buttons**: Top/Left/Right buttons mapped via bit masks
33+
- **Controller swap**: `controllerSwap` toggles left/right controller mapping (needed because different games expect different controller on player 1)
34+
35+
### 4. **Touchscreen Integration** (Android-specific in `src/libretro.c`)
36+
- **Input**: RetroArch pointer callbacks → touches converted to coordinates
37+
- **Hotspots**: Keypad and utility buttons defined as rectangles; touch within rectangle triggers action
38+
- **Keypad hotspots**: 12 buttons at 70px spacing, positioned right of game screen
39+
- **Utility buttons**: Menu, Quit, Swap Screen, Save/Load/Screenshot (partially implemented)
40+
- **Button hold**: Touches kept active for 3 frames after release (`BUTTON_HOLD_FRAMES`)
41+
42+
## Developer Workflows
43+
44+
### Building
45+
```bash
46+
# Linux/Mac (standard libretro build)
47+
make platform=unix
48+
49+
# Windows (MinGW)
50+
make platform=win
51+
52+
# Android NDK
53+
ndk-build -C jni/
54+
55+
# View all platform targets in Makefile
56+
```
57+
58+
### Testing Workflow
59+
1. Build core for platform
60+
2. Load in RetroArch with appropriate BIOS files (`exec.bin`, `grom.bin`) in system folder
61+
3. Launch Intellivision ROM to test controller input and rendering
62+
4. On Android: touch keypad area to test pointer input handling
63+
64+
### Critical Libretro Callbacks (in `retro_run()`)
65+
- `Run()` - Main emulation loop per frame
66+
- `getControllerState()` - Convert RetroPad joypad array to Intellivision bits
67+
- `setControllerInput()` - Write controller state to memory (addresses 0x1FE, 0x1FF)
68+
- `render_dual_screen()` - Build composite frame buffer for display
69+
- `Video(frame_buffer, width, height, pitch)` - Push frame to RetroArch
70+
71+
## Project-Specific Patterns & Conventions
72+
73+
### Memory-Mapped I/O
74+
Controller input is written to specific memory addresses:
75+
- `Memory[0x1FE + player]` = controller state (XORed with 0xFF for libretro compatibility)
76+
- Reading/writing memory uses `readMem(adr)` and `writeMem(adr, val)`
77+
- **Gotcha**: Controller values are inverted (XOR 0xFF), so button press = 0 bit set
78+
79+
### Keypad State Encoding
80+
Keypad buttons use non-obvious bit patterns. **Never hardcode button values**—always reference constants in `controller.h`:
81+
```c
82+
#define K_1 0x81 // Keypad 1
83+
#define K_5 0x42 // Keypad 5
84+
#define K_C 0x88 // Keypad * (Clear)
85+
#define K_E 0x28 // Keypad # (Enter)
86+
```
87+
Combine with bitwise OR: `state |= K_5 | D_N` for "keypad 5 + North direction"
88+
89+
### Libretro Integration Points
90+
- **Core options**: Defined in `libretro_core_options.h`; read via `Environ(RETRO_ENVIRONMENT_GET_VARIABLE, &var)`
91+
- **Video refresh**: Call `Video(frame_ptr, width, height, pitch)` at end of `retro_run()`
92+
- **Audio sample**: Call `Audio(left_sample, right_sample)` for 16-bit PCM at 44.1kHz
93+
- **Serialization**: Save/load state uses versioned struct (version 0x4f544702)
94+
95+
### Coordinate System for Touchscreen
96+
- Origin (0,0) at top-left
97+
- Utility buttons positioned below game screen: Y starts at 448
98+
- Keypad positioned right of game screen: X starts at 704
99+
- When `display_swap=true`, keypad moves to X=0 and game to X=370
100+
101+
### Frame Buffer Format
102+
- Resolution: 352×224 pixels (native Intellivision)
103+
- Format: `unsigned int frame[352*224]` (RGBA, 32-bit per pixel)
104+
- Rendered 2x for display (704×448 after scaling)
105+
106+
## Critical Files for Common Tasks
107+
108+
| Task | Key Files |
109+
|------|-----------|
110+
| Add new controller input | `controller.c`, `controller.h` |
111+
| Fix emulation bugs | `cp1610.c` (CPU), `stic.c` (graphics), `psg.c` (audio) |
112+
| Implement UI features | `libretro.c` (rendering, touch handling) |
113+
| Modify save states | `libretro.c` (serialization structs) |
114+
| Change build system | `Makefile`, `Makefile.common` |
115+
| Add platform support | `Makefile` (platform detection), `jni/` (Android) |
116+
117+
## Known Gotchas & Limitations
118+
119+
1. **ECS (Entertainment Computer System)**: Not currently supported; contributions welcome
120+
2. **Button images**: Utility button graphics loading is partially implemented (placeholders); only "Swap Screen" button is fully functional
121+
3. **Audio**: PSG audio works; Intellivoice support was added but needs testing with specific games
122+
4. **Android NDK**: Uses Application.mk and Android.mk for build; requires NDK toolchain setup
123+
5. **Serialization version**: Change 0x4f544702 if save state struct changes, or old saves will fail to load
124+
125+
## Build & Deploy
126+
127+
- **Libretro repository**: Changes should track with upstream libretro/FreeIntv
128+
- **Core release**: Plugin compiled to `FreeIntv_libretro.{so,dll,dylib}` depending on platform
129+
- **Android APK**: Built via RetroArch Android app; FreeIntv core loads as plugin
130+
131+
---
132+
133+
**Last Updated**: October 2025 | **Touchscreen Feature**: Added October 2025

‎.github/workflows/compilation.yml‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,9 @@ jobs:
1414
- name: Install dependencies
1515
run: |
1616
apk add build-base git zip
17+
18+
- name: Mark repo as safe
19+
run: git config --global --add safe.directory $GITHUB_WORKSPACE
1720

1821
- uses: actions/checkout@v2
1922
- run: |
@@ -29,7 +32,7 @@ jobs:
2932

3033
- name: Upload artifacts
3134
if: ${{ success() }}
32-
uses: actions/upload-artifact@v2
35+
uses: actions/upload-artifact@v4
3336
with:
3437
name: freeintv_libretro_ps2-${{ steps.slug.outputs.sha8 }}
3538
path: freeintv_libretro_ps2.a

‎.gitignore‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,38 @@
11
*.o
22
*.dylib
3+
*.dll
4+
*.so
5+
*.a
6+
*.exe
7+
*.out
38

9+
# Build directories and artifacts
10+
obj/
11+
build/
12+
dist/
13+
bin/
14+
15+
# Dependency files
16+
*.d
17+
*.o.d
18+
19+
# Android NDK specific
20+
libs/arm64-v8a/
21+
libs/armeabi-v7a/
22+
libs/x86/
23+
libs/x86_64/
24+
jni/obj/
25+
26+
# IDE and editor files
27+
.vscode/
28+
.idea/
29+
*.swp
30+
*.swo
31+
*~
32+
.DS_Store
33+
34+
# Temporary and log files
35+
*.tmp
36+
*.temp
37+
*.log
38+
Assets/Thumbs.db

‎Assets/Overlays.zip‎

20.3 MB
Binary file not shown.

0 commit comments

Comments
 (0)