# Android Emulator GPU Troubleshooting Guide

## Overview

This guide helps resolve GPU binding issues when running Android emulators on Linux systems with NVIDIA graphics cards. The most common issue is when the emulator detects the NVIDIA GPU for Vulkan but still binds OpenGL rendering to the Intel iGPU.

## Problem Diagnosis

### GPU Binding Issues

#### Symptoms
- Emulator runs but feels sluggish
- NVIDIA GPU shows low utilization in `nvidia-smi`
- Emulator banner shows Intel graphics in OpenGL renderer:
  ```
  OpenGL Renderer=[Android Emulator OpenGL ES Translator (Mesa Intel(R) Graphics (RPL-S))]
  ```
- Vulkan detection works but OpenGL compositing uses Intel

#### Root Cause
The emulator detects your NVIDIA GPU for Vulkan (`Selecting Vulkan device: NVIDIA GeForce RTX 4060...`) but the window/compositor path still binds to your Intel iGPU. Frames get decoded via gfxstream/Vulkan but final GL presentation rides the Intel driver.

### Network Connectivity Issues

#### Symptoms
- Play Services ANRs and timeouts
- "API failed to connect while resuming" errors
- `GmsClientSupervisor ... Timeout...` messages
- `Phenotype registration failed` errors
- NetworkMonitor shows hard failures:
  - `ECONNREFUSED` on DNS lookups
  - `UnknownHostException` for `www.google.com` / `connectivitycheck.gstatic.com`
  - `[100 WIFI] validation failed`

#### Root Cause
The emulator has no working internet/DNS connectivity, causing Google apps to stall and ANR. This is often caused by:
- DNS resolution failures
- VPN/killswitch blocking emulator traffic
- Firewall rules blocking outbound connections
- Corrupted network state from previous sessions

## Solution Strategies

### 1. Network Connectivity Fixes (Priority)

If experiencing ANRs and Play Services failures, address network issues first:

#### Quick Network Fix
```bash
cd test-apps
./launch-emulator-network-fix.sh
```

#### Verify Network Status
```bash
cd test-apps
./verify-emulator-network.sh
```

#### Manual Network Verification
```bash
# Check airplane mode
adb -e shell settings get global airplane_mode_on

# Check network interfaces
adb -e shell ip addr; adb -e shell ip route

# Test DNS resolution
adb -e shell ping -c1 8.8.8.8
adb -e shell ping -c1 connectivitycheck.gstatic.com
```

#### Clear Play Services Cache
```bash
adb -e shell pm clear com.google.android.gms
adb -e shell pm clear com.android.vending
```

### 2. GPU Binding Solutions

Use the enhanced launch script with all NVIDIA offloading variables:

```bash
cd test-apps
./launch-emulator-gpu.sh
```

**What each variable does:**
- `__NV_PRIME_RENDER_OFFLOAD=1` + `__GLX_VENDOR_LIBRARY_NAME=nvidia`: Offload GL to NVIDIA
- `__VK_LAYER_NV_optimus=NVIDIA_only` + `VK_ICD_FILENAMES=...nvidia_icd.json`: Make Vulkan loader pick NVIDIA
- `DRI_PRIME=1`: Belt-and-suspenders in mixed Mesa/NVIDIA setups
- `QT_QPA_PLATFORM=xcb`: Avoids Wayland/Qt oddities
- `-no-snapshot-load`: Prevents flaky snapshots from different configs

### 2. Alternative GPU Modes

If the primary solution still binds to Intel, try these alternatives:

#### Pure OpenGL Mode
```bash
cd test-apps
./launch-emulator-opengl.sh
```
- Removes `-feature Vulkan` to avoid mixed VK+GL path
- Forces pure OpenGL rendering on NVIDIA
- Good when Vulkan+OpenGL mixed mode causes issues

#### ANGLE Mode
```bash
cd test-apps
./launch-emulator-angle.sh
```
- Uses ANGLE (Almost Native Graphics Layer Engine)
- Better NVIDIA compatibility on Linux
- More stable rendering pipeline

#### Mesa Fallback
```bash
cd test-apps
./launch-emulator-mesa.sh
```
- Software rendering as last resort
- Use only for stability testing
- More CPU intensive but very stable

### 3. Manual Launch Commands

If scripts don't work, use these manual commands:

#### Enhanced GPU Launch
```bash
QT_QPA_PLATFORM=xcb \
__NV_PRIME_RENDER_OFFLOAD=1 \
__GLX_VENDOR_LIBRARY_NAME=nvidia \
__VK_LAYER_NV_optimus=NVIDIA_only \
VK_ICD_FILENAMES=/usr/share/vulkan/icd.d/nvidia_icd.json \
DRI_PRIME=1 \
emulator -avd TimeSafari_Emulator \
  -gpu host \
  -feature Vulkan \
  -accel on \
  -no-boot-anim \
  -no-snapshot-load
```

#### Pure OpenGL
```bash
QT_QPA_PLATFORM=xcb \
__NV_PRIME_RENDER_OFFLOAD=1 \
__GLX_VENDOR_LIBRARY_NAME=nvidia \
DRI_PRIME=1 \
emulator -avd TimeSafari_Emulator \
  -gpu host \
  -accel on \
  -no-boot-anim
```

#### ANGLE Mode
```bash
QT_QPA_PLATFORM=xcb \
__NV_PRIME_RENDER_OFFLOAD=1 \
__GLX_VENDOR_LIBRARY_NAME=nvidia \
DRI_PRIME=1 \
emulator -avd TimeSafari_Emulator \
  -gpu angle_indirect \
  -accel on \
  -no-boot-anim
```

## Verification

### Check GPU Binding
After launching, check the emulator banner for:
- ✅ **Good**: `OpenGL Vendor=Google (NVIDIA)` or GL translator running atop NVIDIA
- ❌ **Bad**: `(Mesa Intel)` or Intel graphics in renderer

### Monitor GPU Usage
```bash
# Real-time GPU utilization
nvidia-smi dmon -s u

# Check emulator process specifically
watch -n1 "nvidia-smi --query-compute-apps=pid,process_name,used_memory --format=csv,noheader | grep qemu"
```

You should see non-zero GPU utilization/memory for the emulator process.

## Additional Optimizations

### Clean Snapshots
Snapshots made with different configs can cause issues:
```bash
# Delete snapshots for clean state
rm -rf ~/.android/avd/TimeSafari_Emulator.avd/snapshots/
```

### Fix ADB Issues
"Device offline" after boot is common with snapshots:
```bash
adb kill-server && adb start-server
adb -e wait-for-device
```

### Disable Unnecessary Features
Save CPU, reduce log spam, and prevent hangs:
```bash
emulator -avd TimeSafari_Emulator \
  -gpu host -accel on -no-boot-anim \
  -feature -Bluetooth -camera-back none -camera-front none -no-audio
```

**Key Benefits:**
- `-feature -Bluetooth`: Prevents Bluetooth-related hangs and ANRs
- `-camera-back none -camera-front none`: Disables camera hardware
- `-no-audio`: Disables audio system (saves resources)

### CPU/RAM Configuration
Keep your existing settings:
```bash
emulator -avd TimeSafari_Emulator \
  -cores 6 -memory 4096 \
  -gpu host -accel on -no-boot-anim
```

## Troubleshooting Checklist

### Before Launch
- [ ] NVIDIA drivers installed and working
- [ ] Vulkan ICD file exists: `/usr/share/vulkan/icd.d/nvidia_icd.json`
- [ ] AVD exists and is properly configured
- [ ] Android SDK and emulator in PATH

### After Launch
- [ ] Check emulator banner for correct GPU binding
- [ ] Monitor `nvidia-smi` for GPU utilization
- [ ] Verify ADB connection with `adb devices`
- [ ] Test app installation and functionality

### If Still Having Issues
- [ ] Try different GPU modes (OpenGL, ANGLE, Mesa)
- [ ] Clean snapshots and restart
- [ ] Check system logs for GPU errors
- [ ] Verify NVIDIA driver compatibility
- [ ] Consider software rendering for stability testing

## Performance Expectations

### Hardware Acceleration (NVIDIA)
- **GPU Utilization**: 20-60% during normal use
- **Memory Usage**: 500MB-2GB GPU memory
- **UI Responsiveness**: Smooth, 60fps target
- **Startup Time**: 30-60 seconds

### Software Rendering (Mesa)
- **CPU Usage**: 50-80% on all cores
- **Memory Usage**: 1-4GB system RAM
- **UI Responsiveness**: Slower, 30fps typical
- **Startup Time**: 60-120 seconds

## System Requirements

### Minimum
- **CPU**: 4 cores, 2.5GHz+
- **RAM**: 8GB system, 4GB for emulator
- **GPU**: Any with OpenGL 3.0+ support
- **Storage**: 10GB free space

### Recommended
- **CPU**: 6+ cores, 3.0GHz+
- **RAM**: 16GB system, 6GB for emulator
- **GPU**: NVIDIA GTX 1060+ or equivalent
- **Storage**: 20GB free space, SSD preferred

## Support

If you continue experiencing issues:
1. Check the [Android Emulator documentation](https://developer.android.com/studio/run/emulator)
2. Review [NVIDIA Linux driver documentation](https://docs.nvidia.com/driver/)
3. Test with different AVD configurations
4. Consider using physical Android devices for testing