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 estar inoperante 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 abaixo. Confira-os 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. No momento, a WebGPU não pode ser acessada de um service worker ou um worker compartilhado. Se estiver usando um service worker ou um worker compartilhado, mova o código da WebGPU para um worker dedicado ou o contexto da janela global.

  3. A WebGPU só pode ser acessada por contextos seguros. Se você disponibilizar o código usando 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 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" do chrome://flags/#unsafely-treat-insecure-origin-as-secure e reinicie o Chrome.

    • Instale o Node.js e execute npx servez --ssl para disponibilizar sua pasta por https com um certificado falso. Você ainda receberá um aviso no Chrome, que pode ser ignorado 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 abaixo 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 motivos a seguir. Confira-os 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. A WebGPU ainda não é compatível com esta plataforma. Você pode ativar a sinalização chrome://flags/#enable-unsafe-webgpu e reiniciar o Chrome. Para suporte experimental do Linux, também será necessário ativar a flag chrome://flags/#enable-vulkan. Confira o suporte da WebGPU no Headless Chrome para saber mais.

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

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

  5. A WebGPU exige uma GPU (emulada por hardware ou software). Acesse chrome://gpu para verificar se o Chrome detecta uma GPU.

A WebGPU é mais lenta que a WebGL

  1. Abra chrome://gpu e confira se você consegue ler "WebGPU: Hardware acelerada". 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 de conceitos WebGL para a WebGPU pode não estar aproveitando ao máximo as otimizações exclusivas da WebGPU. Acesse Do WebGL para a WebGPU para aprender 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 o problema 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().