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 conforme o esperado no navegador Chrome, com etapas claras para resolver os problemas, quando possível.

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

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

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

Isso pode ocorrer devido a um destes motivos. Confira os seguintes na ordem específica:

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

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

    • Forneça seu código localmente em http://localhost ou http://127.0.0.1 com um destes comandos: npx http-server ou python3 -m http.server.

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

    • Instale o Node.js e execute npx servez --ssl para disponibilizar a pasta em https com um certificado falso. Você ainda vai receber um aviso no Chrome, mas pode ignorá-lo clicando em "Avançado" e depois em "Continuar para".

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

O adaptador de GPU é nulo

Confira a seguir um exemplo de erro de JavaScript que pode ocorrer 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 seguintes motivos. Confira os seguintes na ordem específica:

  1. A WebGPU fica 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. O WebGPU ainda não é compatível com essa plataforma. Ative a flag chrome://flags/#enable-unsafe-webgpu e reinicie o Chrome. Para o suporte experimental do Linux, também é necessário ativar a flag chrome://flags/#enable-vulkan. Confira o suporte ao WebGPU no Chrome sem cabeça para saber mais.

  3. O hardware da GPU foi especificamente incluído na lista de bloqueio. Se a mensagem "O WebGPU foi desativado pela lista de bloqueio ou pela linha de comando" aparecer em chrome://gpu, você poderá desativar a lista de bloqueio dos adaptadores do WebGPU ativando a flag chrome://flags/#enable-unsafe-webgpu e reiniciando o Chrome.

  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 requer uma GPU (hardware ou emulada por software). Para verificar se o Chrome detecta uma GPU, acesse chrome://gpu.

  6. O processo da GPU falhou várias vezes. Atualize a página ou reinicie o Chrome. Confira as práticas recomendadas para perda de dispositivo da WebGPU para saber mais.

A WebGPU é mais lenta que a WebGL

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

  2. A tradução direta de conceitos do WebGL para o WebGPU pode não aproveitar totalmente as otimizações exclusivas do WebGPU. Confira Da WebGL para a WebGPU para saber mais sobre algumas das diferenças.

Limitações específicas do Windows

Observe as 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 problema chromium:329211593.

  • O Chrome sempre usa o mesmo adaptador de GPU alocado para outras cargas de trabalho do Chrome, que, no caso de laptops, geralmente é a placa de vídeo integrada, devido ao aspecto de uso de energia (por exemplo, economia de energia). Isso significa que a opção powerPreference não tem nenhum impacto ao chamar requestAdapter(). É possível forçar o uso da GPU de alto desempenho, se disponível, ativando a flag chrome://flags/#force-high-performance-gpu e reiniciando o Chrome.