A diferença entre baixar bytes da rede e decodificar em pixels na memória — trocas visuais em 0ms sem engasgo ou tela piscando.
Um arquivo de imagem comprimido (WebP, JPG ou PNG) chega da rede como uma “mala fechada”. Antes de exibi-la sem travar a animação, o navegador precisa abrir o arquivo e decodificar cada pixel na memória de vídeo (RAM/VRAM). Pré-carregar significa fazer o download e o image.decode() nos bastidores, antes do visitante precisar ver a imagem.
O ciclo de uma imagem perfeita segue 4 etapas: 1. Baixar (os bytes comprimidos viajam pela rede) → 2. Decodificar (o método assíncrono image.decode() descompacta a matriz de pixels fora da thread principal) → 3. Guardar (os pixels prontos ficam guardados na memória) → 4. Exibir (a substituição visual acontece em 0ms, sem layout shift nem congelamento de tela).
O arquivo comprimido (ex: 120 KB WebP) atravessa a rede.
image.decode() descompacta a matriz em pixels RGBA.
Os pixels prontos ficam alocados em memória de vídeo.
A troca visual acontece em 0ms sem nenhuma piscada.
<!--
O navegador não desenha arquivos comprimidos diretamente:
01. Baixar (Rede) -> 02. Decodificar (decode()) -> 03. Guardar (RAM) -> 04. Exibir (0ms)
--><!-- Comparação real de carregamento: na hora vs nos bastidores com decode() -->
<script>
// 1. Sem pré-carregar: cria e insere direto na hora
const imgDireta = new Image();
imgDireta.src = 'foto.webp';
palco.replaceChildren(imgDireta);
// 2. Com pré-carregamento real:
const imgPronta = await SWMotion.preloadImage('foto.webp');
palco.replaceChildren(imgPronta); // Troca instantânea em 0ms!
</script><!-- Pré-carregamento de múltiplos recursos com acompanhamento em tempo real -->
<button type="button" class="sw-btn sw-btn-pri" id="btn-batch">Pré-carregar Galeria</button>
<script>
const fotos = [
'amber-chair.webp',
'architecture.webp',
'chrome-desert.webp'
];
await SWMotion.preloadImages(fotos, (loaded, total, url, img) => {
const porcento = Math.round((loaded / total) * 100);
console.log(porcento + '% (' + loaded + '/' + total + ')');
});
</script>Veja por que não devemos pré-carregar dezenas de fotos de uma vez só:
<!--
Cálculo de consumo real na memória de vídeo:
Largura (px) × Altura (px) × 4 bytes (RGBA)
Exemplo: 1920 × 1080 × 4 = 8.294.400 bytes (~8.29 MB de RAM)
-->// Template completo com fallback se o download ou decode falhar
try {
const img = await SWMotion.preloadImage('hero-banner.webp', 'Banner Principal');
document.getElementById('palco-hero').replaceChildren(img);
} catch (error) {
console.warn('Falha no pré-carregamento:', error);
// Fallback: mostra imagem estática básica ou cor de fundo
}Nenhum.
Comparador Lado a LadoCarregamento em LoteCalculadora de MemóriaNenhum.
SWMotion.preloadImage(src, alt)image.decode(), retornando uma Promise com o elemento <img> pronto para exibição instantânea.SWMotion.preloadImages(urls, onProgress)loaded, total, url, img).image.decode() é suportado nativamente em todos os navegadores modernos (Chrome, Firefox, Safari, Edge). O SWCore possui fallback automático caso o método não esteja disponível.