Às vezes, você quer usar uma biblioteca que só está disponível como código C ou C++. Tradicionalmente, é aqui que você desiste. Não mais, porque agora temos o Emscripten e o WebAssembly (ou Wasm).
O conjunto de ferramentas
Defini como meta descobrir como compilar um código C para Wasm. Tem havido algum barulho em torno do back-end Wasm do LLVM, então comecei a pesquisar sobre isso. Embora seja possível compilar programas simples dessa forma, no momento em que você quiser usar a biblioteca padrão do C ou até mesmo compilar vários arquivos, provavelmente vai ter problemas. Isso me levou à principal lição que aprendi:
Embora o Emscripten costumasse ser um compilador de C para asm.js, ele amadureceu para segmentar o Wasm e está em processo de mudança para o back-end oficial do LLVM internamente. O Emscripten também fornece uma implementação compatível com Wasm da biblioteca padrão do C. Use o Emscripten. Ele realiza muito trabalho oculto, emula um sistema de arquivos, fornece gerenciamento de memória, envolve o OpenGL com o WebGL — muitas coisas que você realmente não precisa desenvolver por conta própria.
Embora isso possa parecer que você precisa se preocupar com o excesso de dados, o compilador Emscripten remove tudo o que não é necessário. Nos meus experimentos, os módulos Wasm resultantes têm o tamanho adequado para a lógica que contêm, e as equipes do Emscripten e do WebAssembly estão trabalhando para reduzi-los ainda mais no futuro.
Para instalar o Emscripten, siga as instruções no site (link em inglês) ou use o Homebrew. Se você gosta de comandos dockerizados como eu e não quer instalar coisas no seu sistema só para testar o WebAssembly, há uma imagem Docker bem mantida que pode ser usada:
$ docker pull trzeci/emscripten
$ docker run --rm -v $(pwd):/src trzeci/emscripten emcc <emcc options here>
Compilar algo simples
Vamos usar o exemplo quase canônico de escrever uma função em C que calcula o n-th número de Fibonacci:
#include <emscripten.h>
EMSCRIPTEN_KEEPALIVE
int fib(int n) {
if(n <= 0){
return 0;
}
int i, t, a = 0, b = 1;
for (i = 1; i < n; i++) {
t = a + b;
a = b;
b = t;
}
return b;
}
Se você conhece C, a função em si não deve ser muito surpreendente. Mesmo que você não conheça C, mas conheça JavaScript, esperamos que consiga entender o que está acontecendo aqui.
emscripten.h é um arquivo principal fornecido pelo Emscripten. Precisamos dele apenas para
ter acesso à macro EMSCRIPTEN_KEEPALIVE, mas ele
oferece muito mais funcionalidades.
Essa macro informa ao compilador para não remover uma função, mesmo que ela pareça
não utilizada. Se omitíssemos essa macro, o compilador otimizaria a função,
já que ninguém a está usando.
Vamos salvar tudo isso em um arquivo chamado fib.c. Para transformá-lo em um arquivo .wasm, precisamos
usar o comando do compilador do Emscripten emcc:
$ emcc -O3 -s WASM=1 -s EXTRA_EXPORTED_RUNTIME_METHODS='["cwrap"]' fib.c
Vamos analisar esse comando. emcc é o compilador do Emscripten. fib.c é nosso arquivo
C. Até aqui, tudo bem. -s WASM=1 instrui o Emscripten a fornecer um arquivo Wasm
em vez de um arquivo asm.js.
-s EXTRA_EXPORTED_RUNTIME_METHODS='["cwrap"]' instrui o compilador a deixar a
função cwrap() disponível no arquivo JavaScript. Vamos falar mais sobre essa função
mais adiante. -O3 instrui o compilador a otimizar de forma agressiva. Você pode escolher números menores
para diminuir o tempo de build, mas isso também vai aumentar os pacotes resultantes,
já que o compilador pode não remover o código não utilizado.
Depois de executar o comando, você terá um arquivo JavaScript chamado
a.out.js e um arquivo WebAssembly chamado a.out.wasm. O arquivo Wasm (ou
"módulo") contém nosso código C compilado e deve ser bem pequeno. O arquivo JavaScript cuida do carregamento e da inicialização do módulo Wasm e fornece uma API mais agradável. Se necessário, ele também vai configurar a
pilha, o heap e outras funcionalidades que o sistema operacional
geralmente fornece ao escrever código C. Por isso, o arquivo JavaScript é um pouco
maior, com 19 KB (cerca de 5 KB compactados com gzip).
Executar algo simples
A maneira mais fácil de carregar e executar o módulo é usar o arquivo JavaScript
gerado. Depois de carregar esse arquivo, você terá um
Module global
à sua disposição. Use
cwrap
para criar uma função nativa do JavaScript que converta parâmetros
em algo compatível com C e invoque a função encapsulada. cwrap usa o
nome da função, o tipo de retorno e os tipos de argumento como argumentos, nessa ordem:
<script src="a.out.js"></script>
<script>
Module.onRuntimeInitialized = _ => {
const fib = Module.cwrap('fib', 'number', ['number']);
console.log(fib(12));
};
</script>
Se você executar esse código, vai aparecer "144" no console, que é o 12º número de Fibonacci.
O Santo Graal: compilar uma biblioteca C
Até agora, o código C que escrevemos foi escrito com o Wasm em mente. No entanto, um caso de uso principal do WebAssembly é usar o ecossistema atual de bibliotecas C e permitir que os desenvolvedores as usem na Web. Essas bibliotecas geralmente dependem da biblioteca padrão do C, de um sistema operacional, de um sistema de arquivos e de outras coisas. O Emscripten oferece a maioria desses recursos, embora haja algumas limitações.
Vamos voltar ao meu objetivo original: compilar um codificador para WebP para Wasm. A origem do codec WebP é escrita em C e está disponível no GitHub, assim como uma extensa documentação da API. Esse é um bom ponto de partida.
$ git clone https://github.com/webmproject/libwebp
Para começar de forma simples, vamos tentar expor WebPGetEncoderVersion() de
encode.h para JavaScript escrevendo um arquivo C chamado webp.c:
#include "emscripten.h"
#include "src/webp/encode.h"
EMSCRIPTEN_KEEPALIVE
int version() {
return WebPGetEncoderVersion();
}
Esse é um bom programa simples para testar se podemos compilar o código-fonte da libwebp, já que não precisamos de parâmetros ou estruturas de dados complexas para invocar essa função.
Para compilar esse programa, precisamos informar ao compilador onde ele pode encontrar
os arquivos principais da libwebp usando a flag -I e também transmitir todos os arquivos C da
libwebp necessários. Vou ser sincero: eu só forneci todos os arquivos C
que encontrei e confiei no compilador para remover tudo o que era
desnecessário. Parece que funcionou muito bem!
$ emcc -O3 -s WASM=1 -s EXTRA_EXPORTED_RUNTIME_METHODS='["cwrap"]' \
-I libwebp \
webp.c \
libwebp/src/{dec,dsp,demux,enc,mux,utils}/*.c
Agora, só precisamos de um pouco de HTML e JavaScript para carregar nosso novo módulo:
<script src="/a.out.js"></script>
<script>
Module.onRuntimeInitialized = async (_) => {
const api = {
version: Module.cwrap('version', 'number', []),
};
console.log(api.version());
};
</script>
O número da versão de correção vai aparecer na saída:
Transferir uma imagem do JavaScript para o Wasm
Conseguir o número da versão do codificador é ótimo, mas codificar uma imagem real seria mais impressionante, certo? Vamos fazer isso, então.
A primeira pergunta que precisamos responder é: como colocar a imagem no ambiente do Wasm?
Analisando a
API de codificação da libwebp, ela espera
uma matriz de bytes em RGB, RGBA, BGR ou BGRA. Felizmente, a API Canvas tem
getImageData(),
que nos dá um
Uint8ClampedArray
contendo os dados da imagem em RGBA:
async function loadImage(src) {
// Load image
const imgBlob = await fetch(src).then((resp) => resp.blob());
const img = await createImageBitmap(imgBlob);
// Make canvas same size as image
const canvas = document.createElement('canvas');
canvas.width = img.width;
canvas.height = img.height;
// Draw image onto canvas
const ctx = canvas.getContext('2d');
ctx.drawImage(img, 0, 0);
return ctx.getImageData(0, 0, img.width, img.height);
}
Agora, é "apenas" uma questão de copiar os dados do JavaScript para o Wasm. Para isso, precisamos expor mais duas funções. Uma que aloca memória para a imagem dentro do Wasm e outra que a libera novamente:
EMSCRIPTEN_KEEPALIVE
uint8_t* create_buffer(int width, int height) {
return malloc(width * height * 4 * sizeof(uint8_t));
}
EMSCRIPTEN_KEEPALIVE
void destroy_buffer(uint8_t* p) {
free(p);
}
create_buffer aloca um buffer para a imagem RGBA, ou seja, 4 bytes por pixel.
O ponteiro retornado por malloc() é o endereço da primeira célula de memória desse buffer. Quando o ponteiro é retornado ao ambiente do JavaScript, ele é tratado como
um número. Depois de expor a função ao JavaScript usando cwrap, podemos
usar esse número para encontrar o início do buffer e copiar os dados da imagem.
const api = {
version: Module.cwrap('version', 'number', []),
create_buffer: Module.cwrap('create_buffer', 'number', ['number', 'number']),
destroy_buffer: Module.cwrap('destroy_buffer', '', ['number']),
};
const image = await loadImage('/image.jpg');
const p = api.create_buffer(image.width, image.height);
Module.HEAP8.set(image.data, p);
// ... call encoder ...
api.destroy_buffer(p);
Grande final: codificar a imagem
A imagem agora está disponível no Wasm. É hora de chamar o codificador WebP para
fazer o trabalho dele. Analisando a
documentação do WebP, o WebPEncodeRGBA
parece ser uma opção perfeita. A função usa um ponteiro para a imagem de entrada e
as dimensões dela, além de uma opção de qualidade entre 0 e 100. Ele também aloca
um buffer de saída para nós, que precisamos liberar usando WebPFree() quando
terminarmos de usar a imagem WebP.
O resultado da operação de codificação é um buffer de saída e o comprimento dele. Como as funções em C não podem ter matrizes como tipos de retorno (a menos que aloquemos memória dinamicamente), usei uma matriz global estática. Eu sei, não é C limpo (na verdade, ele depende do fato de que os ponteiros do Wasm têm 32 bits de largura), mas, para simplificar, acho que esse é um atalho justo.
int result[2];
EMSCRIPTEN_KEEPALIVE
void encode(uint8_t* img_in, int width, int height, float quality) {
uint8_t* img_out;
size_t size;
size = WebPEncodeRGBA(img_in, width, height, width * 4, quality, &img_out);
result[0] = (int)img_out;
result[1] = size;
}
EMSCRIPTEN_KEEPALIVE
void free_result(uint8_t* result) {
WebPFree(result);
}
EMSCRIPTEN_KEEPALIVE
int get_result_pointer() {
return result[0];
}
EMSCRIPTEN_KEEPALIVE
int get_result_size() {
return result[1];
}
Agora, com tudo isso definido, podemos chamar a função de codificação, pegar o ponteiro e o tamanho da imagem, colocá-los em um buffer próprio do JavaScript e liberar todos os buffers do Wasm que alocamos no processo.
api.encode(p, image.width, image.height, 100);
const resultPointer = api.get_result_pointer();
const resultSize = api.get_result_size();
const resultView = new Uint8Array(Module.HEAP8.buffer, resultPointer, resultSize);
const result = new Uint8Array(resultView);
api.free_result(resultPointer);
Dependendo do tamanho da imagem, pode ocorrer um erro em que o Wasm não consegue aumentar a memória o suficiente para acomodar as imagens de entrada e saída:
Felizmente, a solução para esse problema está na mensagem de erro. Basta adicionar -s ALLOW_MEMORY_GROWTH=1 ao comando de compilação.
Pronto! Compilamos um codificador WebP e transcodificamos uma imagem JPEG para
WebP. Para provar que funcionou, podemos transformar nosso buffer de resultado em um blob e usá-lo
em um elemento <img>:
const blob = new Blob([result], { type: 'image/webp' });
const blobURL = URL.createObjectURL(blob);
const img = document.createElement('img');
img.src = blobURL;
document.body.appendChild(img);
Contemple a glória de uma nova imagem WebP!
Conclusão
Não é fácil fazer uma biblioteca C funcionar no navegador, mas, depois que você entende o processo geral e como o fluxo de dados funciona, fica mais fácil, e os resultados podem ser incríveis.
O WebAssembly abre muitas possibilidades novas na Web para processamento, processamento de números e jogos. O Wasm não é uma solução mágica que deve ser aplicada a tudo, mas, quando você se depara com um desses gargalos, ele pode ser uma ferramenta incrivelmente útil.
Conteúdo bônus: como executar algo simples de maneira difícil
Se você quiser tentar evitar o arquivo JavaScript gerado, talvez seja possível. Vamos voltar ao exemplo de Fibonacci. Para carregar e executar o modelo, podemos fazer o seguinte:
<!DOCTYPE html>
<script>
(async function () {
const imports = {
env: {
memory: new WebAssembly.Memory({ initial: 1 }),
STACKTOP: 0,
},
};
const { instance } = await WebAssembly.instantiateStreaming(
fetch('/a.out.wasm'),
imports,
);
console.log(instance.exports._fib(12));
})();
</script>
Os módulos WebAssembly criados pelo Emscripten não têm memória para trabalhar,
a menos que você forneça memória a eles. Para fornecer qualquer coisa a um módulo Wasm,
use o objeto imports, o segundo parâmetro da
função instantiateStreaming. O módulo Wasm pode acessar tudo dentro
do objeto de importações, mas nada fora dele. Por convenção, os módulos
compilados pelo Emscripting esperam algumas coisas do ambiente de carregamento
do JavaScript:
- Primeiro, há o
env.memory. O módulo Wasm não tem conhecimento do mundo externo, por assim dizer, então ele precisa de memória para funcionar. DigiteWebAssembly.Memory. Ele representa uma parte da memória linear (que pode ser expandida). Os parâmetros de dimensionamento estão em "unidades de páginas do WebAssembly", o que significa que o código acima aloca uma página de memória, com cada página tendo um tamanho de 64 KiB. Sem fornecer uma opçãomaximum, a memória teoricamente não tem limite de crescimento (o Chrome atualmente tem um limite rígido de 2 GB). A maioria dos módulos do WebAssembly não precisa definir um máximo. env.STACKTOPdefine onde a pilha deve começar a crescer. A pilha é necessária para fazer chamadas de função e alocar memória para variáveis locais. Como não fazemos nenhuma travessura de gerenciamento de memória dinâmica em nosso pequeno programa Fibonacci, podemos usar toda a memória como uma pilha, daíSTACKTOP = 0.