WebGPU: dicas de solução de problemas e correções

François Beaufort
François Beaufort
GitHub

Este documento explica por que a WebGPU pode não funcionar ou não funcionar como esperado no navegador Chrome, com etapas claras para resolver os problemas sempre que possível.

O exemplo a seguir mostra um erro de JavaScript que pode ocorrer quando gpu não está disponível no navigator:

const adapter = await navigator.gpu.requestAdapter();

cancel Uncaught TypeError: Cannot read properties of undefined (reading 'requestAdapter')

Isso pode ocorrer devido a um dos motivos a seguir. Confira nesta ordem específica:

  1. A WebGPU exige o Chrome 113 ou mais recente no ChromeOS, macOS, Windows e Chrome 121 ou mais recente no Android. Verifique sua versão em chrome://version e atualize, se necessário.

  2. A WebGPU só pode ser acessada para contextos seguros. Se você disponibilizar seu código por um protocolo não seguro (por exemplo, http: ou file:), use o protocolo https: seguro ou resolva isso durante o desenvolvimento do app da Web de uma das seguintes maneiras:

    • Disponibilize seu código localmente no http://localhost ou no http://127.0.0.1 com um destes comandos: npx http-server ou python3 -m http.server.

    • Adicionar a origem a "Origens não seguras tratadas como seguras" lista de chrome://flags/#unsafely-treat-insecure-origin-as-secure e reinicie o Chrome.

    • Instale o Node.js e execute npx servez --ssl para exibir a pasta por HTTPS com um certificado falso. Você ainda vai receber um aviso no Chrome que pode ser ignorado clicando em "Avançado" e em "Continuar para...".

    • Exponha seu servidor da Web local à Internet com o ngrok.

O adaptador da GPU é nulo

Confira a seguir um exemplo de erro de JavaScript que pode aparecer quando o adaptador recebido ao chamar requestAdapter() é nulo:

const adapter = await navigator.gpu.requestAdapter();
const device = await adapter.requestDevice();

cancel Uncaught TypeError: Cannot read properties of undefined (reading requestDevice)

Isso acontece por um dos motivos abaixo. Confira nesta ordem específica:

  1. A WebGPU é desativada quando o usuário desativa a opção "Usar aceleração gráfica quando disponível" em chrome://settings/system. Verifique se essa configuração está desativada e ative-a novamente

  2. Ainda não há suporte para a WebGPU nesta plataforma. É possível ativar a sinalização chrome://flags/#enable-unsafe-webgpu e reiniciar o Chrome. Para oferecer suporte experimental do Linux, também é necessário ativar a flag chrome://flags/#enable-vulkan. Confira o suporte para WebGPU no Headless Chrome para saber mais.

  3. O hardware da GPU foi incluído na lista de bloqueio. Se aparecer a mensagem "A WebGPU foi desativada por meio da lista de bloqueio ou da linha de comando" em chrome://gpu, ative a sinalização chrome://flags/#enable-unsafe-webgpu e reinicie o Chrome para desativar a lista de bloqueio de adaptadores da WebGPU.

  4. Não há adaptador de GPU correspondente para as opções transmitidas em requestAdapter(). Tente chamar requestAdapter() com opções diferentes.

  5. A WebGPU exige uma GPU (com emulação de hardware ou software). Para verificar se o Chrome detecta uma GPU, acesse chrome://gpu.

A WebGPU é mais lenta que a WebGL

  1. Abra chrome://gpu e confira se você consegue ler "WebGPU: Hardware Accelerated". Se você ler "WebGPU: Somente software, aceleração de hardware indisponível", talvez seja necessário atualizar os drivers da GPU.

  2. A tradução direta dos conceitos do WebGL para a WebGPU pode não estar aproveitando ao máximo as otimizações exclusivas da WebGPU. Consulte De WebGL para WebGPU para conhecer algumas das diferenças.

Limitações específicas do Windows

Esteja ciente das seguintes limitações ao usar a WebGPU em dispositivos Windows:

  • O Chrome não oferece suporte ao uso de vários adaptadores de GPU simultaneamente. Consulte issue chromium:329211593.

  • O Chrome sempre usa o mesmo adaptador de GPU alocado para outras cargas de trabalho do Chrome. Para laptops, geralmente é a placa de vídeo integrada, devido ao aspecto do uso de energia (ou seja, economia de energia). Isso significa que a opção powerPreference não tem nenhum impacto ao chamar requestAdapter().