Efeitos São Páginas Web

Os efeitos no SignalRGB, conhecidos como Lightscripts, são essencialmente páginas web que interagem com a API do SignalRGB, e devem seguir algumas regras simples para funcionar corretamente. Todo Lightscript requer três tags HTML essenciais: <head>, <body> e <script>.

<head>

Esta seção deve conter quaisquer tags <meta> necessárias. Como detalhado na seção “Referência da API”, essas tags podem criar campos de entrada do usuário (como sliders de matiz, seletores numéricos, etc.) ou acessar a API do SignalRGB para obter entrada visual do seu aplicativo principal. Além disso, uma tag <title> nesta seção atribuirá um rótulo ao seu efeito dentro do aplicativo Signal.

Vamos revisitar o exemplo anterior para um entendimento mais claro:

<head>
    <title>Hue Cycle</title>
    <meta description="Stock hue cycle."/>
    <meta publisher="WhirlwindFX" />
    <meta property="speed" label="Cycle Speed" type="number" min="1" max="10" default="2">
</head>

Este cabeçalho inclui quatro tags: uma tag <title> e três tags <meta>, que cobrem a descrição, o publicador e um slider numérico básico. Enquanto os cabeçalhos de efeitos estáticos costumam ser pequenos, efeitos que respondem a ações na tela podem envolver dezenas de medidores, cada um com múltiplas configurações de resolução. É importante manter a organização e seguir boas convenções de nomenclatura.

<head>

<body>

O body contém apenas um elemento — a tag <canvas>. Os atributos essenciais dessa tag são id, usado para buscar o canvas no script, e width e height. As dimensões padrão para o SignalRGB são 320px de largura e 200px de altura.

<body style="margin: 0; padding: 0;">
    <canvas id="exCanvas" width="320" height="200"></canvas>
</body>

<body>

<script>

É aqui que a mágica acontece. Existem três seções básicas neste script, além de duas funções que devem ser consideradas PADRÃO para desenvolvedores de Lightscript: update e window.requestAnimationFrame.

Declarações de Variáveis

Todas as variáveis de escopo do script devem ser declaradas juntas para simplificar o processo de desenvolvimento. No futuro, isso também incluirá declarações de medidores, mas por enquanto temos uma seleção simples.

var c: Usado para buscar a tag canvas declarada anteriormente.
var ctx: O contexto 2D do elemento canvas, que é a área editável do seu efeito.
height, width e hue: São declarados aqui para simplificar o processo.

Chamada Inicial de Update

Na parte inferior do bloco de código, há a referência a window.requestAnimationFrame(update). “Update” é o nome da função que lida com os detalhes da animação. O estado atualizado em cada frame cria a ilusão de movimento para os espectadores.

O método usado aqui é fundamental: como cada operação na sua função update leva um pequeno tempo para executar, chamar update() diretamente pode causar atrasos nas animações. Por exemplo, o primeiro callback pode pensar que 100ms passaram, o próximo 110ms, e assim por diante.

Ao usar window.requestAnimationFrame, o timestamp atual é passado para a função de callback e seus callbacks aninhados, preservando o estado da animação apesar das pequenas lacunas de execução.

Resumindo, use o método window.requestAnimationFrame(callback) para atualizar sua animação!

A Função Update

Esta função é central para um Lightscript funcional e precisa ser o mais simples e enxuta possível, pois é executada a cada frame. Após o carregamento inicial do script e a chamada da função, update continuará em execução por meio de sua chamada interna a window.requestAnimationFrame.

Neste exemplo, cada frame realiza quatro operações principais:

Define o estilo de preenchimento do canvas com ctx.fillStyle. Pode ser uma cor, padrão ou gradiente, e persistirá até ser substituído pela próxima chamada de ctx.fillStyle.
Cria um retângulo (com o estilo de preenchimento previamente definido) com ctx.fillRect(x, y, width, height). Neste caso, o retângulo representa todo o canvas.
Incrementa o hue por speed, a variável de entrada do usuário localizada no cabeçalho.
Limita o hue ao intervalo 0-360 para se encaixar no padrão HSL (matiz, saturação, luminosidade).

<script>
    // Variable Declarations -------------------------
    // Get the canvas element from the DOM
    var c = document.getElementById("exCanvas");
    var ctx = c.getContext("2d");
    var width = 320;
    var height = 200;
    var hue = 0;

    // Update function --------------------------------
    function update()
    {
      // 1
      ctx.fillStyle = 'hsl('+ hue + ', 100%, 50%)';
      // 2
      ctx.fillRect(0, 0, width , height);
      // 3
      hue+=(speed / 4);
      // 4
      if (hue > 360) { hue = hue % 360; }
      // Re-call the function
      window.requestAnimationFrame(update);
    }

    // Initial update call ----------------------------
    window.requestAnimationFrame(update);
</script>

Este padrão geral (definir preenchimento, desenhar forma, editar variáveis) é o padrão para animações em canvas.

Se a cor estiver errada, você esqueceu um preenchimento de estilo.
Se a forma estiver errada, você esqueceu um preenchimento de forma.
Se nada mudar ao longo do tempo, você não editou suas variáveis.

Para mais detalhes e dicas de solução de problemas, confira nossa próxima página sobre HTML5 + JS.

<script>