Investigate and fix missing icons in the emenu radial menu. Ensure all icon resources are properly loaded, rendered, and accessible across X11 and Wayland configurations without breaking existing functionality.

Analysis

Based on project documentation (llm.md), the following hypotheses apply:

Icons likely loaded via external textures or font-based rendering in OpenGL context
main.go handles window initialization and likely UI rendering loop
Render pipeline passes through gl_legacy.go for OpenGL bindings
Touch input handling may affect icon display on Wayland (via touch_wayland.so)
Icon assets may reside alongside executable or be loaded from specific paths

Missing Information Assumptions:

Project has an assets/ or icons/ directory for static resources
Icons rendered using either texture atlas or individual OpenGL textures
Command parsing likely reads JSON in format: [{"name": "Label", "exec": "..."}] with optional "icon" field

Potential Causes of Missing Icons:

Icon loading not initialized before render loop
Texture context failures (no asset path)
Wayland specific resource resolution issues
CLI flag to specify icon assets not implemented

Implementation Steps

STEP-01: Locate and inspect current rendering code for icon support in main.go
- Actions:
  1. Search main.go for icon/load/texture-related strings (case-insensitive)
  2. Identify any existing icon asset paths or loading functions
  3. Check for icon field parsing in command JSON structure
  4. Document findings: files, function names, and current implementation state
- Prerequisites: Repository access to main.go in emenu root
- Verification: File search returns matches; analysis log notes any missing icon loading paths or broken asset references
STEP-02: Review gl_legacy.go for texture/context initialization
- Actions:
  1. Check OpenGL context creation for texture binding functions
  2. Verify whether texture loading succeeds before draw loop begins
  3. Identify any conditional icon rendering flags (e.g., -no-icons)
  4. Log texture loading results using the same pattern as other resources in gl_legacy.go
- Prerequisites: STEP-01 analysis complete; gl_legacy.go accessible
- Verification: Texture context functions identified; loading errors or missing binding points logged
STEP-03: Create icon asset directory and populate with default icons
- Actions:
  1. Create assets/icons/ at project root (or update existing assets directory)
  2. Include sample PNG/SVG for common categories: search, settings, system, applications
  3. Define minimum size requirements (16x16 to 24x24 scaled to resolution)
  4. Add .gitignore entry if this wasn't already handled
- Prerequisites: Project directory layout known; STEP-02 confirms texture loading path
- Verification: Asset directory exists with icon files committed or listed in git status
STEP-04: Implement icon loading helper function
- Actions:
  1. Create new file icon_loader.go (or extend existing asset loader)
  2. Function signature example: func LoadIcons(ctx *glLegacyContext, path string) error
  3. Handle missing textures with graceful fallback (e.g., blank or default icon)
  4. Return error codes: invalid path, texture load failure, empty asset response
- Prerequisites: STEP-02 identified texture functions; Go module dependency check complete
- Verification: Function compiles without errors; signature matches renderer expectations
STEP-05: Wire icon loading into main.go render preparation
- Actions:
  1. Add icon loading call after context creation in main.go
  2. Ensure icon assets are validated before entering the menu draw loop (avoid runtime failure)
  3. Pass icon paths from config or static list
  4. Handle load errors by logging and proceeding with blank placeholders
- Prerequisites: STEP-04 function complete; render loop location identified in main.go
- Verification: Code compiles; icon loading occurs before first frame; error logs appear on intentional asset removal
STEP-06: Update command JSON schema to support optional icon field
- Actions:
  1. Modify command parsing logic for "icon" field in each menu entry
  2. Allow icon as either filename reference or embedded base64 (if using texture atlas)
  3. Default to no-icon if missing (no breaking existing behavior)
  4. Add validation to catch duplicate/icon-too-large entries at startup
- Prerequisites: main.go command parsing structure understood; STEP-05 complete
- Verification: JSON example validates; command with icon shows rendered graphic; command without icon works normally
STEP-07: Test icon rendering on X11 (default build)
- Actions:
  1. Build using make build (X11 defaults)
  2. Launch emenu with -debug flag to verify texture status
  3. Confirm icons display for sample commands with and without icons
  4. Verify fallback behavior when icon file is missing or invalid path
- Prerequisites: Asset directory populated with test icons; STEP-05 change committed
- Verification: X11 build succeeds; debug output logs texture load status; UI renders with expected icons
STEP-08: Test icon rendering on Wayland
- Actions:
  1. Build using make build-wayland (or equivalent target)
  2. Launch emenu in Wayland session
  3. Verify touch input does not interfere with icon display
  4. Check for any EGL/texture context initialization differences
- Prerequisites: -tags wayland build tag understood; STEP-07 complete (X11 verified)
- Verification: Wayland build succeeds; icons appear correctly under compositor; debug logs show touchscreen detection status separately from texture state
STEP-09: Add CLI flag to control icon loading behavior
- Actions:
  1. Implement -no-icons or --icon-mode flag for toggling/offloading icon rendering
  2. Provide help entry in main.go's usage function
  3. Ensure the flag does not break existing command execution without icons
- Prerequisites: Icon loading integration complete; CLI flags documented in llm.md review
- Verification: Build succeeds with flag option; usage output shows flag description; toggling works without crashes
STEP-10: Commit changes and draft CHANGELOG entry
- Actions:
  1. Create commit with summary referencing "Add missing icon rendering support and fixes"
  2. Add entries to CHANGELOG.md following existing format (next minor/beta version)
  3. Verify no unintended files modified in repository root or CI configuration
  4. Push to remote branch ready for code review
- Prerequisites: All testing complete (X11 + Wayland); human reviewer ready to merge; assets committed
- Verification: Git diff shows expected changes only; CHANGELOG entry added correctly; push succeeds

Acceptance Criteria

After all steps complete:

✅ Emenu renders icons for commands that specify them in JSON configuration
✅ Missing icon files result in graceful fallback (blank/default placeholder) rather than crash or missing target
✅ X11 and Wayland builds both display icons correctly after startup
✅ Debug flag shows texture load status and does not interfere with normal operation
✅ Existing commands without icons continue to work unchanged
✅ Optional -no-icons flag disables icon rendering if needed (for performance cases)

Risks/Notes

Risk	Impact	Mitigation
Texture loading fails on some compositors	Icons don't show	Log error; user can adjust compositor settings via `-debug` flag
Wayland EGL context differs from X11 OpenGL defaults	Icon rendering inconsistent	Test both builds; handle platform-specific texture initialization paths in `touch_wayland.so` if needed
Icon assets directory grows large	Git bloat, CI build time increases	Consider git-lfs for images or host assets externally and load by URL path (future decision)
Touch detection code could conflict with texture loads on Wayland	UI rendering corrupted	Verify input backend initialization order does not impact OpenGL context availability

Build Instructions:

# X11 (default)
make build

# Wayland
make build-wayland

Debug Mode:

./emenu -commands "[{\"label\":\"Test\",\"exec\":\"echo hello\",\"icon\":\"assets/icons/search.png\"}]" -debug

Questions for Human Reviewers:

Does the existing project use a specific icon font (Material Icons, Noto Color Emoji) or PNG assets? If fonts, where are they configured?
Are there any texture resource limits per GL context that we need to check before batch-loading icons?
Should icon configuration be moved to a separate config file rather than JSON command array (future extensibility)?

This runbook provides actionable steps for the developer agent to implement icon rendering fixes in one invocation per step. Each step has stable verification and prerequisites ensuring repository coherence.

STATUS: DONE # Runbook: Icon Rendering Fix for emenu Circular Launcher --- ## Goal Investigate and fix missing icons in the emenu radial menu. Ensure all icon resources are properly loaded, rendered, and accessible across X11 and Wayland configurations without breaking existing functionality. --- ## Analysis Based on project documentation (`llm.md`), the following hypotheses apply: - Icons likely loaded via external textures or font-based rendering in OpenGL context - `main.go` handles window initialization and likely UI rendering loop - Render pipeline passes through `gl_legacy.go` for OpenGL bindings - Touch input handling may affect icon display on Wayland (via `touch_wayland.so`) - Icon assets may reside alongside executable or be loaded from specific paths **Missing Information Assumptions:** 1. Project has an `assets/` or `icons/` directory for static resources 2. Icons rendered using either texture atlas or individual OpenGL textures 3. Command parsing likely reads JSON in format: `[{"name": "Label", "exec": "..."}]` with optional `"icon"` field **Potential Causes of Missing Icons:** - Icon loading not initialized before render loop - Texture context failures (no asset path) - Wayland specific resource resolution issues - CLI flag to specify icon assets not implemented --- ## Implementation Steps - [ ] **STEP-01: Locate and inspect current rendering code for icon support in main.go** - **Actions:** 1. Search `main.go` for icon/load/texture-related strings (case-insensitive) 2. Identify any existing icon asset paths or loading functions 3. Check for icon field parsing in command JSON structure 4. Document findings: files, function names, and current implementation state - **Prerequisites:** Repository access to `main.go` in emenu root - **Verification:** File search returns matches; analysis log notes any missing icon loading paths or broken asset references - [ ] **STEP-02: Review gl_legacy.go for texture/context initialization** - **Actions:** 1. Check OpenGL context creation for texture binding functions 2. Verify whether texture loading succeeds before draw loop begins 3. Identify any conditional icon rendering flags (e.g., `-no-icons`) 4. Log texture loading results using the same pattern as other resources in gl_legacy.go - **Prerequisites:** STEP-01 analysis complete; `gl_legacy.go` accessible - **Verification:** Texture context functions identified; loading errors or missing binding points logged - [ ] **STEP-03: Create icon asset directory and populate with default icons** - **Actions:** 1. Create `assets/icons/` at project root (or update existing assets directory) 2. Include sample PNG/SVG for common categories: search, settings, system, applications 3. Define minimum size requirements (`16x16` to `24x24` scaled to resolution) 4. Add `.gitignore` entry if this wasn't already handled - **Prerequisites:** Project directory layout known; STEP-02 confirms texture loading path - **Verification:** Asset directory exists with icon files committed or listed in git status - [ ] **STEP-04: Implement icon loading helper function** - **Actions:** 1. Create new file `icon_loader.go` (or extend existing asset loader) 2. Function signature example: `func LoadIcons(ctx *glLegacyContext, path string) error` 3. Handle missing textures with graceful fallback (e.g., blank or default icon) 4. Return error codes: invalid path, texture load failure, empty asset response - **Prerequisites:** STEP-02 identified texture functions; Go module dependency check complete - **Verification:** Function compiles without errors; signature matches renderer expectations - [ ] **STEP-05: Wire icon loading into main.go render preparation** - **Actions:** 1. Add icon loading call after context creation in `main.go` 2. Ensure icon assets are validated before entering the menu draw loop (avoid runtime failure) 3. Pass icon paths from config or static list 4. Handle load errors by logging and proceeding with blank placeholders - **Prerequisites:** STEP-04 function complete; render loop location identified in main.go - **Verification:** Code compiles; icon loading occurs before first frame; error logs appear on intentional asset removal - [ ] **STEP-06: Update command JSON schema to support optional icon field** - **Actions:** 1. Modify command parsing logic for `"icon"` field in each menu entry 2. Allow icon as either filename reference or embedded base64 (if using texture atlas) 3. Default to no-icon if missing (no breaking existing behavior) 4. Add validation to catch duplicate/icon-too-large entries at startup - **Prerequisites:** main.go command parsing structure understood; STEP-05 complete - **Verification:** JSON example validates; command with icon shows rendered graphic; command without icon works normally - [ ] **STEP-07: Test icon rendering on X11 (default build)** - **Actions:** 1. Build using `make build` (X11 defaults) 2. Launch emenu with `-debug` flag to verify texture status 3. Confirm icons display for sample commands with and without icons 4. Verify fallback behavior when icon file is missing or invalid path - **Prerequisites:** Asset directory populated with test icons; STEP-05 change committed - **Verification:** X11 build succeeds; debug output logs texture load status; UI renders with expected icons - [ ] **STEP-08: Test icon rendering on Wayland** - **Actions:** 1. Build using `make build-wayland` (or equivalent target) 2. Launch emenu in Wayland session 3. Verify touch input does not interfere with icon display 4. Check for any EGL/texture context initialization differences - **Prerequisites:** `-tags wayland` build tag understood; STEP-07 complete (X11 verified) - **Verification:** Wayland build succeeds; icons appear correctly under compositor; debug logs show touchscreen detection status separately from texture state - [ ] **STEP-09: Add CLI flag to control icon loading behavior** - **Actions:** 1. Implement `-no-icons` or `--icon-mode` flag for toggling/offloading icon rendering 2. Provide help entry in main.go's usage function 3. Ensure the flag does not break existing command execution without icons - **Prerequisites:** Icon loading integration complete; CLI flags documented in llm.md review - **Verification:** Build succeeds with flag option; usage output shows flag description; toggling works without crashes - [ ] **STEP-10: Commit changes and draft CHANGELOG entry** - **Actions:** 1. Create commit with summary referencing "Add missing icon rendering support and fixes" 2. Add entries to `CHANGELOG.md` following existing format (next minor/beta version) 3. Verify no unintended files modified in repository root or CI configuration 4. Push to remote branch ready for code review - **Prerequisites:** All testing complete (X11 + Wayland); human reviewer ready to merge; assets committed - **Verification:** Git diff shows expected changes only; CHANGELOG entry added correctly; push succeeds --- ## Acceptance Criteria After all steps complete: - ✅ Emenu renders icons for commands that specify them in JSON configuration - ✅ Missing icon files result in graceful fallback (blank/default placeholder) rather than crash or missing target - ✅ X11 and Wayland builds both display icons correctly after startup - ✅ Debug flag shows texture load status and does not interfere with normal operation - ✅ Existing commands without icons continue to work unchanged - ✅ Optional `-no-icons` flag disables icon rendering if needed (for performance cases) --- ## Risks/Notes | Risk | Impact | Mitigation | |------|--------|------------| | Texture loading fails on some compositors | Icons don't show | Log error; user can adjust compositor settings via `-debug` flag | | Wayland EGL context differs from X11 OpenGL defaults | Icon rendering inconsistent | Test both builds; handle platform-specific texture initialization paths in `touch_wayland.so` if needed | | Icon assets directory grows large | Git bloat, CI build time increases | Consider git-lfs for images or host assets externally and load by URL path (future decision) | | Touch detection code could conflict with texture loads on Wayland | UI rendering corrupted | Verify input backend initialization order does not impact OpenGL context availability | **Build Instructions:** ```bash # X11 (default) make build # Wayland make build-wayland ``` **Debug Mode:** ```bash ./emenu -commands "[{\"label\":\"Test\",\"exec\":\"echo hello\",\"icon\":\"assets/icons/search.png\"}]" -debug ``` **Questions for Human Reviewers:** 1. Does the existing project use a specific icon font (Material Icons, Noto Color Emoji) or PNG assets? If fonts, where are they configured? 2. Are there any texture resource limits per GL context that we need to check before batch-loading icons? 3. Should icon configuration be moved to a separate config file rather than JSON command array (future extensibility)? --- This runbook provides actionable steps for the developer agent to implement icon rendering fixes in one invocation per step. Each step has stable verification and prerequisites ensuring repository coherence.

debesielis removed the

wip

label

2026-08-25 11:13:40 +03:00

debesielis referenced this issue from a commit

2026-08-25 11:13:40 +03:00

issue #1: plan and project docs

zordsdavini commented

2026-08-25 11:27:42 +03:00

Author

Owner

wrong project - ups 🗡️