CommunityProgramación y desarrollogithub.com

mobile-gpu-profiling

Skill de codificación. Lee lo que la GPU del teléfono realmente está haciendo desde sus contadores de hardware, para que las correcciones apunten al límite real. Compatible con Arm Mali (mediante Arm Performance Studio) y Qualcomm Adreno (mediante Snapdragon Profiler / Android GPU Inspector). Incluye scripts que capturan contadores Mali a través de adb y los convierten en diagnósticos.

¿Qué es mobile-gpu-profiling?

Este skill permite a un agente de IA (como Claude Code) analizar el rendimiento de la GPU en teléfonos móviles a nivel de hardware, identificando cuellos de botella precisos (píxeles, vértices, texturas, ancho de banda, operaciones ALU) en lugar de confiar en conjeturas. Es una herramienta de escalado, no el primer paso: se usa cuando las métricas de alto nivel (FPS, memoria, temperatura) no son suficientes o el rendimiento no mejora al reducir la carga gráfica. Soporta GPUs Arm Mali (a través de Arm Performance Studio: captura headless con Streamline, análisis con Performance Advisor y Mali Offline Compiler) y Qualcomm Adreno (con Snapdragon Profiler o Android GPU Inspector en Android 11+). El skill proporciona scripts listos para usar que automatizan la captura de contadores vía adb, los analizan y generan un informe detallado con un veredicto claro (limitado por fragmentos, geometría, CPU, etc.) y recomendaciones de corrección. También incluye herramientas para encontrar shaders costosos mediante compilación offline (malioc) y extracción de shaders de Godot, Unity, three.js y Bevy. Finalmente, siempre se debe verificar con `device_probe.py` y comparar las métricas antes y después de aplicar cambios.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/P0r0ro/mobile-gpu-profiling-skill/tree/HEAD/mobile-gpu-profiling

Installed? Explore more Programación y desarrollo skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Perfilado de GPU móvil (contadores de hardware Mali y Adreno)

mobile-3d-rendering mide desde fuera: fps, memoria, temperatura y contadores del motor. Este skill abre la GPU y lee sus contadores de hardware. Responde: ¿es realmente la GPU el límite, y si lo es, se trata de píxeles, vértices, texturas, ancho de banda o matemáticas de shaders? Cada uno necesita una corrección diferente, así que adivinar desperdicia días.

Cuándo usarlo (escalado, no el primer paso):

  • El triaje de mobile-3d-rendering muestra fps por debajo del objetivo con recuentos de draw calls dentro del presupuesto, o el fps no se mueve al reducir draws y triángulos;
  • Decidir si un efecto de nivel alto (mapas de normales, MSAA 4x, halo bloom, más luces) cabe en el presupuesto en el teléfono de referencia;
  • Encontrar qué shader o material es caro;
  • Calor sin causa obvia (el ancho de banda se manifiesta aquí);
  • Rarezas del lado de la GPU en un proveedor.

Siempre termina volviendo a medir con mobile-3d-rendering/scripts/device_probe.py en el dispositivo (fps, p95, pendiente de memoria, térmicas). Los contadores explican; la sonda confirma.

0. Detectar la GPU y elegir el camino

S=~/.claude/skills/mobile-gpu-profiling/scripts
python3 $S/gpu_profile.py detect          # proveedor, GPU, driver, versión de Android, tamaño de pantalla
GPUCaptura de contadoresCoste de shaderCaptura de fotogramas
Arm Mali / Immortalisgpu_profile.py mali-capture (Streamline, headless)malioc_batch.py (Mali Offline Compiler)Frame Advisor, RenderDoc para GPUs Arm
Qualcomm AdrenoSnapdragon Profiler Realtime/Trace (GUI), o AGI en dispositivos compatibles con Android 11+Compilador offline de Adreno (si está disponible) o estadísticas de shaders de SDPSnapdragon Profiler Snapshot, perfilador de fotogramas AGI
otros (PowerVR, Xclipse)herramienta del proveedor / AGI; gpu_profile.py gpu-busy—RenderDoc / AGI

Notas de instalación para cada herramienta: references/arm-performance-studio.md, references/adreno.md. La aplicación debe ser una compilación depurable (Godot: exportación de depuración; Unity: Development Build; android:debuggable="true").

1. Mali: capturar y leer los contadores

python3 $S/gpu_profile.py mali-capture -p <package> -s 30 -o gpu-profile-<nombre>
#   la primera ejecución construye una configuración de contadores a partir de la plantilla de Arm para esa GPU (almacenada en caché en ~/.cache/mobile-gpu-profiling)
#   el script inicia la aplicación; reproduce la escena que quieres medir (peor caso: multitudes, combate, noche)
python3 $S/gpu_profile.py mali-analyze gpu-profile-<nombre>/capture.apc --fps 60   # releer más tarde

Escribe report.md + metrics.json. Lee el veredicto al principio, luego los números:

MétricaSaludable en un teléfono medioSi no
gpu_util< 75–80% al fps objetivo (margen térmico)> 85%: limitado por GPU, lee las siguientes filas. < 60% con fps bajo: limitado por CPU, así que perfiliza la CPU
fragment_queue_util vs non_fragment_queue_util / tiler_util—El que esté cerca del 100% es el límite: fragment = coste por píxel; non-fragment/tiler = vértices, triángulos, proyectores de sombras
fragments_per_screen_pixel< 2.0 (todos los pases)Sobredibujado, mapas de sombras, pases de render extra (ver render_passes_per_frame)
alu_instr_per_fragment< 20–30 en BifrostShaders de fragmento pesados → §2
tex_compressed_share / tex_mipmapped_sharealta para texturas de escenaTexturas sin comprimir/sin mipmap desperdician ancho de banda y caché (los mapas de sombras y los render targets nunca están comprimidos, así que verifica qué texturas dominan)
late_zs_test_share< 10%Descartar/prueba alfa, o escrituras de profundidad en shaders, deshabilitan early-Z
early_zs_kill_rate, fpk_occluding_sharealta es buenaOrdenar opacos de adelante a atrás; evitar descartes en superficies grandes
bandwidth_mb_per_frame< ~30–40 MB a 60 fps en teléfonos de 2018–2020Render targets, texturas sin comprimir, resoluciones MSAA → calor
facing_culled_share~40–50% para mallas cerradasMateriales de dos caras duplican trabajo de vértices
fp16_varying_sharealtaVaryings mediump reducen a la mitad el coste de interpolación

La referencia completa de contador a corrección, con fórmulas, está en references/mali-counters.md.

Marcadores de fotogramas: el informe HTML por fotograma de Performance Advisor necesita límites de fotograma de la capa de Arm. Arm es compatible con Android 11+. En Android 10 (probado en un Galaxy Note 9) los contadores funcionan pero los fotogramas de la capa nunca llegaron a gatord, por lo que el script recurre a contadores por segundo × el fps que mide de SurfaceFlinger durante la captura.

2. Encontrar el shader caro (cualquier motor, modelo de coste Mali)

# Godot (Compatibility/GLES3): volcar el GLSL ES que realmente compila el juego, mediante Mesa en el escritorio
HEADLESS=1 $S/godot_dump_shaders.sh <proyecto_godot> dump/ 20 [res://test_scene.tscn]
python3 $S/malioc_batch.py --core Mali-G72 dump/ --label-src <proyecto_godot>/shaders --top 15
  • La clasificación lista los ciclos por píxel (o por vértice) y qué pipeline lo limita (A aritmética, LS load/store, V varying, T textura). Las etiquetas nombran tu archivo de shader; "engine" significa un material integrado.
  • Banderas: occ50 significa más de 32 registros de trabajo, por lo que la mitad de los hilos están en vuelo (latencia oculta peor); SPILL significa desbordamiento de pila; lateZS significa descarte; fp16:0% significa que no hay matemáticas de 16 bits.
  • Coste de un shader ≈ ciclos × píxeles que cubre. Un shader de 38 ciclos en el suelo y los edificios importa más que uno de 60 ciclos en un letrero pequeño.
  • Extracción de shaders de Unity, three.js y Bevy: references/shader-cost.md.

El script de volcado ejecuta el juego contra una copia desechable de sus datos de usuario, por lo que los guardados y la configuración no se tocan y la caché de shaders de Godot no oculta las compilaciones. Visita las áreas que te interesan durante la ejecución (o pasa una escena de prueba). Godot compila las variantes de forma perezosa.

3. Adreno (Qualcomm)

Usa Snapdragon Profiler: Realtime para métricas en vivo, Trace para una línea de tiempo, Snapshot para un fotograma con estadísticas por draw. Lee las mismas preguntas de sus métricas: % Shaders Busy, % Time Shading Fragments vs Vertices, Avg Bytes / Fragment, % Texture Fetch Stall, % Texture L1 Miss, ALU / Fragment, % Prims Trivially Rejected, Read/Write Total. La tabla de métrica a corrección está en references/adreno.md.

En dispositivos con Android 11+ compatibles con AGI, Android GPU Inspector proporciona contadores neutrales al proveedor más un perfilador de fotogramas. Para una lectura rápida de utilización sin herramientas, gpu_profile.py gpu-busy -s 30 lee el nodo busy del kernel donde la compilación lo permite.

4. De los contadores a los cambios (luego verificar)

  1. Corrige el limitador más grande que nombra el informe. Haz un cambio a la vez.

  2. Asignaciones típicas:

    LímiteCorrecciones
    limitado por fragmentosmapas de sombras más pequeños/menos y menor distancia de sombras, menos sobredibujado transparente, shaders más baratos en superficies grandes (mover matemáticas al vertex shader, eliminar ruido/niebla/especular por píxel en Bajo/Medio, mediump), texturas comprimidas+con mipmap, resolución interna más baja solo donde se demuestre seguro (Mali-G72 perdía memoria con escalado de render)
    limitado por geometría/tilerLOD y rangos de visibilidad, menos proyectores de sombras, culling de caras traseras activado, skinning más simple en multitudes
    ancho de banda/calortexturas comprimidas, menos render targets/pases, MSAA en lugar de post AA, sin post a pantalla completa
    limitado por CPU (GPU < 60% ocupada)draw calls, scripts, animación, física (performance-optimization)
  3. Vuelve a capturar la misma escena y compara metrics.json antes/después (ms de GPU por fotograma, la participación del limitador).

  4. Confirma en el dispositivo con device_probe.py durante al menos 60 s (fps, p95, pendiente de memoria, térmicas). Una victoria de contador que calienta el teléfono o pierde memoria no es una victoria.

  5. Registra el hallazgo en las notas del proyecto (qué estaba limitado, qué lo corrigió, números antes/después).

Reglas ganadas con esfuerzo (de capturas reales)

  • Genera la configuración de contadores a partir de la plantilla de la GPU, y mantén solo contadores de GPU por defecto. Los contadores PMU de CPU hicieron que el hijo de captura fallara al inicio en un kernel Samsung Android 10.
  • adb por Wi-Fi funciona, pero el id del dispositivo es ip:puerto. Pásalo en todas partes (los scripts lo hacen).
  • Una captura bloqueada puede dejar agentes gatord vivos dentro del sandbox de la aplicación. Bloquean los sockets de la siguiente captura ("Address already in use") y la acortan. El script los mata por PID (run-as <pkg> pkill no funcionó).
  • Forzar la detención de la aplicación justo antes de una captura puede terminarla después de un segundo. El script espera a que las cosas se estabilicen.
  • Streamline-cli -generate-config necesita -template <name> antes del objetivo, a pesar de su texto de -help.
  • Godot mantiene una caché de shaders GLES en user://shader_cache, por lo que una segunda ejecución en escritorio no compila nada. Usa un XDG_DATA_HOME nuevo (el script de volcado lo hace).
  • Ejecutar el juego real en el escritorio para auditorías escribe su autoguardado. Aísla el directorio de datos de usuario.

Referencias

ArchivoLeer cuando
references/arm-performance-studio.mdinstalar/usar Streamline, Performance Advisor, Frame Advisor, RenderDoc para Arm, malioc; detalles del pipeline headless
references/mali-counters.mdqué significa cada métrica de Mali, fórmulas, umbrales, Bifrost vs Valhall vs 5ª generación
references/adreno.mdconfiguración de Snapdragon Profiler / AGI y tabla de métrica a corrección para Adreno
references/shader-cost.mdobtener shaders compilados de Godot/Unity/three.js/Bevy y leer la salida de malioc

Skills relacionados