PME2: GPU-rendered description tooltip for Pie Menu

[Pluglug]

Summary

Add GPU-rendered description tooltips for Pie Menu items - a long-requested PME1 feature finally coming to PME2.

Background

Users have requested the ability to show descriptive text for pie menu items on hover. This is a signature PME2 feature that will enhance usability.

---

Phase 1: Pie Menu Tooltip (This Issue)

Goal

• GPU-rendered tooltip showing pmi.description on hover
• Pie Menu only (PMENU mode)
• Simple text display near the hovered item

Technical Approach

Architecture:

┌─────────────────────────────────────────────────┐
│ Blender Standard UI                              │
│   wm.popup_menu_pie() → _draw_pm()              │
│   (UILayout-based, existing behavior)            │
└─────────────────────────────────────────────────┘
                    ▼
┌─────────────────────────────────────────────────┐
│ GPU Overlay (NEW)                                │
│   POST_PIXEL draw_handler                        │
│   - Detect hovered item                          │
│   - Render description tooltip                   │
└─────────────────────────────────────────────────┘

Key Components:

1. Mouse tracking: Get cursor position during pie menu display
2. Hit test: Calculate which slot (0-9) is hovered based on angle/distance
3. Tooltip rendering: gpu (rect) + blf (text) modules
4. Positioning: Near cursor or item, avoiding screen edge

Key Files:

• operators/__init__.py:1137 - WM_OT_pme_user_pie_menu_call
• operators/__init__.py:1372 - _draw_pm() method
• infra/overlay.py - Existing overlay infrastructure

---

Future Phases (Out of Scope)

Phase 2: Always-Visible Hover UI

• Mini Qt-like widget system
• Persistent panels that don't auto-close
• GPU widget framework (pme.gfx package)

Phase 3: Full Widget Editor

• Visual pie menu editor
• Drag & drop slot arrangement
• Live preview

---

Implementation Considerations

GPU/BLF Constraints (from analysis)

1. Drawing target: Existing Area/Region only (SpaceView3D, etc.)
2. Input handling: All via modal operator
3. Theme/scaling: Manual calculation required (HiDPI, pixel_size)
4. API stability: GPU/BLF signatures change between versions - need adapter layer

Blender API Notes

• blf.size() changed in 4.0 (dpi argument removed)
• gpu.shader.from_builtin() may change
• Recommend isolating GPU calls in pme.gfx or infra/gpu_utils.py

Recommended Architecture

# infra/gpu_utils.py - Adapter layer for Blender version compatibility
def draw_text(x, y, text, size, color): ...
def draw_rect(x, y, w, h, color): ...

# ui/tooltip.py - Tooltip logic
class PieTooltipRenderer:
    def __init__(self, pm): ...
    def draw(self, context): ...
    def get_hovered_slot(self, mouse_x, mouse_y): ...

---

Related Resources

Internal Documents

• _docs/design/user_pie_menu_call_analysis.md - Full operator analysis
• _docs/design/PME2_FEATURE_REQUESTS.md - User feature requests

Design Decision: Operator Decomposition

Benefits of decomposing WM_OT_pme_user_pie_menu_call:

Feature Request	Current Problem	After Decomposition
Custom styling (#3)	200-line _draw_item, changes hard to trace	ui/item_style.py isolates style logic
Modal operator enhancement (#8)	524-line state machine	operators/modal/state_machine.py
Context-aware menus (#5)	poll/draw tightly coupled	core/context_rules.py

Recommendation: Consider _draw_item separation (Phase WM-1) before or alongside tooltip implementation.

---

JSON Schema v2 Integration

{
  "items": [
    {
      "text": "Add Cube",
      "description": "Add a cube primitive to the scene",
      "description_expr": "'Objects: ' + str(len(C.scene.objects))"
    }
  ]
}

• description: Static text (i18n-translatable)
• description_expr: Python expression for dynamic text

See: #81 (description/description_expr implementation)

---

🎉 Milestone Issue #100 - A signature feature for PME2!

[Pluglug]

Technical Feasibility Report

Summary

Direct tooltip implementation is feasible without operator decomposition.

The existing WM_OT_pme_user_pie_menu_call can be extended with GPU overlay without modifying its core invoke/modal logic.

---

Architecture Overview

execute_menu() flow:
  ┌─────────────────────────────────┐
  │ Before popup_menu_pie()         │
  │   → Register draw_handler       │
  │     (POST_PIXEL)                │
  └─────────────────────────────────┘
              ↓
  ┌─────────────────────────────────┐
  │ wm.popup_menu_pie()             │
  │   (Blender standard)            │
  └─────────────────────────────────┘
              ↓
  ┌─────────────────────────────────┐
  │ User interacts with pie menu    │
  │   → draw_handler renders        │
  │     tooltip on each frame       │
  └─────────────────────────────────┘
              ↓
  ┌─────────────────────────────────┐
  │ Menu closed (modal_stop)        │
  │   → Remove draw_handler         │
  └─────────────────────────────────┘

---

Existing Infrastructure

infra/overlay.py already provides:

• BLF text rendering (blf.size, blf.position, blf.color, blf.draw)
• Shadow rendering (blf.SHADOW, blf.shadow_offset)
• draw_handler registration patterns
• Timer-based fade effects

This can be reused or extended for tooltip rendering.

---

Hit Testing Requirements

Blender's Pie Menu does not expose internal state (hovered slot). We must implement our own hit testing:

# Blender Pie Menu slot layout:
#        1 (N)
#     6       2
#   5   center  3
#     4       0
#        7 (S)
#
# Extra slots 8, 9 are positioned center-top and center-bottom

def get_hovered_slot(mouse_x, mouse_y, center_x, center_y, radius, threshold):
    dx = mouse_x - center_x
    dy = mouse_y - center_y
    distance = sqrt(dx*dx + dy*dy)
    
    if distance < threshold:
        return None  # center (no selection)
    
    angle = atan2(dy, dx)  # -π to π
    # Map angle to slot number (8 sectors)
    # slot 0 = East (0°), slot 1 = North (90°), etc.

Complexity: Extra slots 8/9 require special handling (center column, above/below main pie).

---

Risk Assessment

Area	Risk	Reason
Existing code impact	Low	Only adds draw_handler, doesn't touch invoke/modal
Rendering accuracy	Low	BLF is mature, proven in infra/overlay.py
Hit testing	Medium	Extra slots 8/9 have non-standard positions
Performance	Low	BLF is lightweight, per-frame is fine
Blender version compat	Low	BLF API stable since 4.0 (dpi arg removed)

---

Proposed Implementation

1. New module: infra/pie_tooltip.py

   • PieTooltipOverlay class (draw_handler lifecycle)
   • Hit test function for slot detection
   • BLF tooltip rendering

2. Minimal changes to execute_menu:

   • Register overlay before popup_menu_pie() (PMENU only)
   • Unregister on modal_stop

3. Schema: description field already designed in JSON Schema v2

---

Alternative: Operator Decomposition First

The analysis document (_docs/design/user_pie_menu_call_analysis.md) proposes separating _draw_item (200 lines) to ui/item_drawing.py. This would:

• Resolve layer violations (editors → operators, ui → operators)
• Improve testability
• Make future enhancements cleaner

However, this is NOT required for tooltip implementation. The tooltip overlay is independent of the drawing logic.

---

Next Step

Before implementation, we need to decide on UI/UX design:

• When to show tooltip (hover delay? immediate?)
• Position (near slot? fixed location? follow cursor?)
• Content (static description? dynamic info? slot index?)
• Animation (fade in/out? slide?)

This technical report is provided as reference for UX decision-making.