weaver_api.tex

\font\sixteen=cmbx16
\font\twelve=cmr12
\font\fonteautor=cmbx12
\font\fonteemail=cmtt10
\font\twelvenegit=cmbxti12
\font\twelvebold=cmbx12
\font\trezebold=cmbx13
\font\twelveit=cmsl12
\font\monodoze=cmtt12
\font\it=cmti12
\voffset=0,959994cm % 3,5cm de margem superior e 2,5cm inferior
\parskip=6pt

\def\titulo#1{{\noindent\sixteen\hbox to\hsize{\hfill#1\hfill}}}
\def\autor#1{{\noindent\fonteautor\hbox to\hsize{\hfill#1\hfill}}}
\def\email#1{{\noindent\fonteemail\hbox to\hsize{\hfill#1\hfill}}}
\def\negrito#1{{\twelvebold#1}}
\def\italico#1{{\twelveit#1}}
\def\monoespaco#1{{\monodoze#1}}
\def\iniciocodigo{\lineskip=0pt\parskip=0pt}
\def\fimcodigo{\twelve\parskip=0pt plus 1pt\lineskip=1pt}

\long\def\abstract#1{\parshape 10 0.8cm 13.4cm 0.8cm 13.4cm
0.8cm 13.4cm 0.8cm 13.4cm 0.8cm 13.4cm 0.8cm 13.4cm 0.8cm 13.4cm
0.8cm 13.4cm 0.8cm 13.4cm 0.8cm 13.4cm
\noindent{{\twelvenegit Abstract: }\twelveit #1}}

\def\resumo#1{\parshape  10 0.8cm 13.4cm 0.8cm 13.4cm
0.8cm 13.4cm 0.8cm 13.4cm 0.8cm 13.4cm 0.8cm 13.4cm 0.8cm 13.4cm
0.8cm 13.4cm 0.8cm 13.4cm 0.8cm 13.4cm
\noindent{{\twelvenegit Resumo: }\twelveit #1}}

\def\secao#1{\vskip12pt\noindent{\trezebold#1}\parshape 1 0cm 15cm}
\def\subsecao#1{\vskip12pt\noindent{\twelvebold#1}}
\def\referencia#1{\vskip6pt\parshape 5 0cm 15cm 0.5cm 14.5cm 0.5cm 14.5cm
0.5cm 14.5cm 0.5cm 14.5cm {\twelve\noindent#1}}

%@* .

\twelve
\vskip12pt
\titulo{A API Weaver}
\vskip12pt
\autor{Thiago Leucz Astrizi}
\vskip6pt
\email{thiago@@bitbitbit.com.br}
\vskip6pt

\abstract{This article describes using literary programming the
  Weaver API. Weaver is a game engine and this API are how programmers
  interact with the engine in their game projects. Besides the API,
  this article also covers how the configuration file is interpreted
  and how game loops should be managed in a game project. The API is
  portable code which should work under OpenBSD, Linux, Windows and
  Web Assembly environments.}

\vskip 0.5cm plus 3pt minus 3pt

\resumo{Este artigo utiliza programação literária para descrever a
API Weaver. Weaver é um motor de jogos e esta API é como os
programadores interagem com ela em seus projetos. Além da API, este
artigo também cobre como o arquivo de configuração é interpretado e
como os laços de execução do jogo devem ser organizados. A API é
código portável que deve funcionar sob ambientes OpenBSD, Linux,
Windows e Web Assembly.}

\secao{1. Introdução}

\subsecao{1.1. Organização de Arquivos}

Quando um usuário digita \monoespaco{weaver PROJETO} na linha de
comando, um diretório com um novo projeto Weaver e criado. Dentro
deste diretório, o arquivo que contém o loop principal está
em \monoespaco{src/game.c} e nele encontramos:

\alinhaverbatim
#include "game.h"

void main_loop(void){ // Um laço principal do jogo
 LOOP_INIT: // Código de inicialização 

 LOOP_BODY: // Código executado a cada iteração
    if(W.keyboard[W_ANY])
        Wexit_loop();
 LOOP_END: // Código executado na finalização
    return;
}

int main(void){
  Winit(); // Initializes Weaver
  Wloop(main_loop); // Enter a new game loop
  return 0;
}
\alinhanormal

E dentro de \monoespaco{src/game.h}, nós encontramos:

\linha
\alinhaverbatim
#ifndef _game_h_
#define _game_h_

#include "weaver/weaver.h"

#include "includes.h"

struct _game_struct{
  // Você pode personalizar esta estrutura declarando variáveis aqui.
  // Mas não mude seu nome. E acesse ela por meioda variável W.game
  int whatever; // <- Variável só pra prevenir erro em certo compilador
} _game;

void main_loop(void);

#endif
\alinhanormal
\linha

Notar que neste arquivo existe uma estrutura que pode ser
personalizada pelo usuário e cumpre o papel de centralizar algumas
variáveis com estados globais. O tipo de coisa que para um jogo deve
ser preservada ao salvarmos o progresso de um jogador. Ou que deve ser
acessível para plugins. Ou ainda que deve ser transmitida para
informar o estado do jogo a clientes conectados à rede. Segundo o
comentário acima, esta estrutura deve ser referenciada pela
variável \monoespaco{W.game}, o que já nos indica que a API será
organizada de modo a fornecer um \monoespaco{struct}
chamado \monoespaco{W} onde serão centralizados os recursos da API.

O arquivo \monoespaco{includes.h} é apenas um cabeçalho que inclui em
um projeto todos os cabeçalho de módulos criados pelo usuário (cada
módulo é um arquivo de código C e um cabeçalho).

Todo o código da API deve então estar presente ou ser incluída por
macros dentro dos arquivos \monoespaco{weaver.c}
e \monoespaco{weaver.h}. A organização do \monoespaco{weaver.h} é:

\iniciocodigo
@(project/src/weaver/weaver.h@>=
#ifndef _weaver_h_
#define _weaver_h_
#ifdef __cplusplus
  extern "C" {
#endif
@<Inclui Cabeçalhos (weaver.h)@>
@<Estruturas de Dados (weaver.h)@>
@<Declaração de Função (weaver.h)@>
@<Variáveis Externas (weaver.h)@>
@<Macros (weaver.h)@>
#ifdef __cplusplus
  }
#endif
#endif
@
\fimcodigo

A parte em vermelho no código acima representa código que ainda será
definido. Por exemplo, na região reservada para incluirmos cabeçalhos
gerais, será importante incluirmos o
cabeçalho \monoespaco{sys/param.h} em alguns casos. No BSD isso é
essencial para podermos checar por meio da macro se estamos sendo
compilados para um sistema BSD. No Linux inserir tal cabeçalho não tem
problema algum. Mas o Windows não possui tal cabeçalho. Por outro
lado, no caso do Windows certamente iremos quierer inserir
o \monoespaco{windows.h}. Então podemos inserir condicionalmente
cabeçalhos se estamos ou não no Windows por meio do código abaixo:

\iniciocodigo
@<Inclui Cabeçalhos (weaver.h)@>=
#if !defined(_WIN32)
#include <sys/param.h>
#else
#include <windows.h>
#endif
@
\fimcodigo

Mais tarde, podemos querer inserir mais cabeçalhos à medida que eles
forem necessários. Por exemplo, o cabeçalho de entrada e saída padrão,
e da biblioteca padrão. Já o \monoespaco{stdint.h} também é útil para
quando queremos definir inteiros com um tamanho fixo de bits enquanto
o \monoespaco{stdbool.h} nos permite declarar e usar variáveis
booleanas:

\iniciocodigo
@<Inclui Cabeçalhos (weaver.h)@>+=
#include <stdio.h>
#include <stdlib.h>
#include <stdint.h>
#include <stdbool.h>
@
\fimcodigo

Também iremos definir aqui a estrutura geral do
arquivo \monoespaco{weaver.c} de nossa API:

\iniciocodigo
@(project/src/weaver/weaver.c@>=
#include "weaver.h"
#include "../game.h"
@<Cabeçalhos Locais (weaver.c)@>
@<Macros Locais (weaver.c)@>
@<Variáveis Globais (weaver.c)@>
@<Variáveis Estáticas (weaver.c)@>
@<Definição de Função (weaver.c)@>
@<Definição de Funções da API (weaver.c)@>
@
\fimcodigo

Como exemplo de macros locais, vamos definir macros que serão formas
portáveis de declarar e usar mutex, independente do sistema
operacional:

\iniciocodigo
@<Macros Locais (weaver.c)@>=
#if defined(__linux__) || defined(BSD)
#define STATIC_MUTEX_DECLARATION(mutex) static pthread_mutex_t mutex
#define MUTEX_INIT(mutex) pthread_mutex_init(mutex, NULL)
#define MUTEX_DESTROY(mutex) pthread_mutex_destroy(mutex);
#define MUTEX_WAIT(mutex) pthread_mutex_lock(mutex);
#define MUTEX_SIGNAL(mutex) pthread_mutex_unlock(mutex);
#elif defined(_WIN32)
#define STATIC_MUTEX_DECLARATION(mutex) static CRITICAL_SECTION mutex
#define MUTEX_INIT(mutex) InitializeCriticalSection(mutex)
#define MUTEX_DESTROY(mutex) DeleteCriticalSection(mutex);
#define MUTEX_WAIT(mutex) EnterCriticalSection(mutex);
#define MUTEX_SIGNAL(mutex) LeaveCriticalSection(mutex);
#elif defined(__EMSCRIPTEN__)
#define STATIC_MUTEX_DECLARATION(mutex)
#define MUTEX_INIT(mutex)
#define MUTEX_DESTROY(mutex)
#define MUTEX_WAIT(mutex)
#define MUTEX_SIGNAL(mutex)
#endif
@
\fimcodigo

Ao longo deste documento iremos expandir todas as outras partes em
vermelho apresentando o código que será inserido nelas. E assim a
nossa API será definida.

\subsecao{1.2. A Estrutura W}

A principal estrutura de dados que definiremos será
um \monoespaco{struct} chamado \monoespaco{W}. Esta estrutura
basicamente será um espaço de nomes (``namespace'') onde iremos
colocar as variáveis e funções oficiais de nossa API. Podemos então
começar a definir tal estrutura:

\iniciocodigo
@<Estruturas de Dados (weaver.h)@>=
// Esta estrutura conterá todas as variáveis e funções definidas pela
// API Weaver:
extern struct _weaver_struct{
  struct _game_struct *game;
  @<Namespace de Variáveis@>
  @<Namespace de Funções@>
} W;
@
\fimcodigo

Notar que além de \monoespaco{W.game}, existirão outras variáveis
presentes dentro desta estrutura. Basicamente iremos centralizar
dentro dela todas as funções públicas da nossa API. Só não estarão
nela funções que começam com ``\_'', e que são consideradas internas e
não deveriam ser usadas por programadores utilizando a API. Desta
forma deixamos bem delimitado o que faz parte da API e também evitamos
poluir com nomes o ``namespace'' global de programas em C.

Colocaremos então esse nosso namespace como uma variável global:

\iniciocodigo
@<Variáveis Globais (weaver.c)@>=
struct _weaver_struct W;
@
\fimcodigo

\subsecao{1.3. Funções de Inicialização e Finalização}

Uma das coisas que a função de inicialização faz é inicializar os
valores da estrutura \monoespaco{W}. Justamente por isso, ela é uma
das poucas funções externas ao nosso namespace:

\iniciocodigo
@<Declaração de Função (weaver.h)@>=
void Winit(void);
@
\fimcodigo

\iniciocodigo
@<Definição de Funções da API (weaver.c)@>=
void Winit(void){
  W.game = &_game;
  @<API Weaver: Inicialização@>
}
@
\fimcodigo

A função de finalização deve desalocar qualquer memória pendente,
finalizar o uso de recursos, e deve também fechar o programa
informando que tudo correu bem se assim realmente ocorreu. Notar que a
memória deve ser a última coisa finalizada.

\iniciocodigo
@<Declaração de Função (weaver.h)@>=
void Wexit(void);
@
\fimcodigo

\iniciocodigo
@<Definição de Funções da API (weaver.c)@>=
void Wexit(void){
  @<API Weaver: Finalização@>
  @<API Weaver: Memória: Finalização@>
  exit(0);
}
@
\fimcodigo


\secao{2. Contagem de Tempo}

Weaver mede o tempo em microssegundos ($10^{-6}$s) e armazena a sua
contagem de tempo em pelo menos 64 bits de memória. Weaver serve para
criar programas que executam dentro de um laço principal. Então além
do tempo total em microssegundos desde que o programa inicializou,
também armazenamos a diferença de tempo entre a iteração atual do
programa e a última.

Então para começar devemos ter um lugar onde devemos armazenar a
última medida de tempo que fizemos. Usaremos para isso uma variável
global. No Windows usamos um dos tipos específicos para representar
inteiros grandes (e incluimos o cabeçalho necessário para usá-lo)
e nos demais sistemas usamos uma estrutura de valor de tempo de
alta resolução.

Nossa variável global é declarada aqui:

\iniciocodigo
@<Variáveis Externas (weaver.h)@>=
#if defined(_WIN32)
extern LARGE_INTEGER _last_time;
#else
extern struct timeval _last_time;
#endif
@
\fimcodigo

E aqui:

\iniciocodigo
@<Variáveis Globais (weaver.c)@>=
#if defined(_WIN32)
LARGE_INTEGER _last_time;
#else
struct timeval _last_time;
#endif
@
\fimcodigo

Já o cabeçalho para usá-la pode ser colocado aqui:

\iniciocodigo
@<Inclui Cabeçalhos (weaver.h)@>=
#if !defined(_WIN32)
#include <sys/time.h>
#endif
@
\fimcodigo

A ideia é que esta variável armazene sempre a última medida de
tempo. Ela é inicializada com a primeira medida de tempo na
inicialização:

\iniciocodigo
@<API Weaver: Inicialização@>=
#if defined(_WIN32)
QueryPerformanceCounter(&_last_time);
#else
gettimeofday(&_last_time, NULL);
#endif
@
\fimcodigo

Após a inicialização, todas as outras atualizações desta variável
deverão ser feitas por meio da função declarada abaixo:

\iniciocodigo
@<Declaração de Função (weaver.h)@>+=
unsigned long _update_time(void);
@
\fimcodigo

Tal função irá ler o tempo atual e armazenar na variável. Ela irá
sempre retornar a diferença de tempo em microssegundos entre a leitura
atual e a última. Em sistemas Unix faremos isso exatamente da maneira
recomendada pelo manual da GNU Glbc de modo a tornar a subtração de
tempo mais portável e funcional mesmo que os elementos da
estrutura \monoespaco{timeval} sejam armazenadas como ``unsigned''.  A
desvantagem é que o código se torna menos claro. O código fica sendo:

\iniciocodigo
@<Definição de Função (weaver.c)@>=
#if !defined(_WIN32)
unsigned long _update_time(void){
  int nsec;
  unsigned long result;
  struct timeval _current_time;
  gettimeofday(&_current_time, NULL);
  // Aqui temos algo equivalente ao "vai um" do algoritmo da subtração:
  if(_current_time.tv_usec < _last_time.tv_usec){
    nsec = (_last_time.tv_usec - _current_time.tv_usec) / 1000000 + 1;
    _last_time.tv_usec -= 1000000 * nsec;
    _last_time.tv_sec += nsec;
  }
  if(_current_time.tv_usec - _last_time.tv_usec > 1000000){
    nsec = (_current_time.tv_usec - _last_time.tv_usec) / 1000000;
    _last_time.tv_usec += 1000000 * nsec;
    _last_time.tv_sec -= nsec;
  }
  if(_current_time.tv_sec < _last_time.tv_sec){
    // Overflow
    result = (_current_time.tv_sec - _last_time.tv_sec) * (-1000000);
    // Sempre positivo:
    result += (_current_time.tv_usec - _last_time.tv_usec);
  }
  else{
    result = (_current_time.tv_sec - _last_time.tv_sec) * 1000000;
    result += (_current_time.tv_usec - _last_time.tv_usec);
  }
  _last_time.tv_sec = _current_time.tv_sec;
  _last_time.tv_usec = _current_time.tv_usec;
  return result;
}
#endif
@
\fimcodigo

Em sistema Windows, já existe uma função que trata o tempo como sendo
em microssegundos. Por causa disso, a função se torna muito mais
simples:

\iniciocodigo
@<Definição de Função (weaver.c)@>+=
#if defined(_WIN32)
unsigned long _update_time(void){
  LARGE_INTEGER prev;
  prev.QuadPart = _last_time.QuadPart;
  QueryPerformanceCounter(&_last_time);
  return (_last_time.QuadPart - prev.QuadPart);
}
#endif
@
\fimcodigo

\secao{3. Os loops principais.}

Todos os jogos são organizados dentro de loops, ou laços
principais. Eles são basicamente um código que fica iterando
indefinidamente até que uma condição nos leve a outro loop principal,
ou então ao fim do programa.

Como foi mostrado no código inicial do \monoespaco{game.c}, um loop
principal deve ser declarado como:

\alinhaverbatim
void nome\_do\_loop(void){
 LOOP\_INIT: // Código executado na inicialização

 LOOP\_BODY: // Código executado a cada iteração
    if(W.keyboard[W\_ANY])
        Wexit\_loop();
 LOOP\_END: // Código executado na finalização
    return;
}
\alinhanormal

Antes de entendermos como devemos entrar em um loop principal
corretamente, é importante descrever como este loop é
executado. Nota-se que ele possui uma região de inicialização, de
execução e finalização demarcada por rótulos escritos em letras
maiúsculas.

Interpretar isso é bastante simples. É perfeitamente possível
interpretar o código acima como:

\alinhaverbatim
void nome\_do\_loop(void){
  // LOOP\_INIT
  for(;;){
    // LOOP\_BODY
    if(W.keyboard[W\_ANY])
        Wexit\_loop();
  }
  // LOOP\_END
}
\alinhanormal

Mas embora esta interpretação seja suficientemente adequada em certos
contextos, não é assim que este código será traduzido. Não é em todos
os ambientes em que é possível executar um loop infinito sem fazer com
que a interface do jogo trave. Um exemplo é o ambiente Web Assembly de
um navegador de Internet, onde os laços principais de um programa só
podem ser executados se forem corretamente declarados como tais e a
execução deles ocorre não por meio de um laço infinito, mas pela
contínua chamada de uma função de laço principal.

Por causa disso, para tornar o código mais portável devemos encarar
toda execução de um loop principal como no código abaixo:

\alinhaverbatim
for(;;)
  nome\_do\_loop();
\alinhanormal

E dentro da função de loop principal nós não colocamos um laço
explícito. Ao invés disso, nós decidimos qual parte da função deve ser
executada com ajuda dos rótulos inseridos, os quais na verdade são
macros com lógica adicional embutida junto a alguns
comandos \monoespaco{goto} que decidem o que será executado a cada vez
que a função é chamada.

Uma consequência disso é que não é possível lidar com variáveis
declaradas dentro da inicialização de um loop principal. Elas ,só
teriam um valor correto dentro da inicialização, e dentro do corpo do
loop principal seu valor seria indefinido. Por exemplo, o seguinte
código terá resultado indefinido e talvez não imprima nada na tela:

\alinhaverbatim
// ERRADO
void loop(void){
LOOP\_INIT:
  int var = 5;
LOOP\_BODY:
  if(var == 5)
    printf("var == 5\\n");
LOOP\_END:
}
\alinhanormal

Já o seguinte código iria imprimir na saída padrão a cada iteração do
loop:

\alinhaverbatim
// CERTO
static int var;

void loop(void){
LOOP\_INIT:
  var = 5;
LOOP\_BODY:
  if(var == 5)
    printf("var == 5\\n");
LOOP\_END:
}
\alinhanormal

Outra coisa que deve ser levada em conta é que as macros utilizadas
escondem outro detalhe importante: não é apenas um laço principal que
executamos, mas existem dois simultâneos. Um laço principal executa
com uma frequência fixa: o laço que cuida da física e da lógica do
jogo. Outro laço, nós apenas fazemos executar o mais rápido que der no
hardware atual: o laço responsável por renderizar coisas na tela.

Idealmente para cada iteração do laço de física e lógica executamos uma
ou mais iterações de nosso laço de renderização. Isso significa que
podemos renderizar com uma frequência maior que executamos a iteração
responsável por realmente mover objetos, detectar colisões e ler
entrada do usuário. Para que a cada vez nós não renderizemos
exatamente a mesma imagem, o que derrotaria o propósito de fazermos
isso, nós interpolamos a posição dos objetos da tela de acordo com
seus valores de aceleração, velocidade e posição.

Garantindo que a nossa física e lógica do jogo execute sempre em
intervalos constantes, nós garantimos o determinismo necessário para
podermos sincronizar partidas por meio de redes como a Internet. E
renderizando os objetos na tela o mais rápido que podemos com ajuda de
interpolação nos dá a experiência visual mais suave e natural que for
possível.

Uma referência e maiores detalhes de como implementar isso pode ser
encontrado em [Fiedler 2004]. Nossa implementação será como mostrado
na referência, com exceção de que nosso código será muito menos
transparente por ter que estar contido dentro de macros sem usar loops
explícitos.

Vamos agora definir nas subseções seguintes o que exatamente deverá
existir em cada uma das macros que devem estar presentes em todo laço
principal.

\subsecao{3.1. Inicialização do Loop.}

Isso é o que fará a macro \monoespaco{LOOP\_INIT}:

Primeiro devemos checar variáveis que determinam se devemos encerrar o
laço. Se estivermos, mas ainda houverem recursos sendo carregados
(imagens, vídeos, shaders, sons), apenas retornamos da função. Se não
houver nada sendo carregado, mas ainda não executamos a finalização
deste laço, pulamos para executar a finalização. Se não há nada a ser
carregado e já executamos a finalização, aí sim encerramos de vez o
laço. Depois checamos se esta função está sendo chamada pela primeira
vez. Em caso afirmativo, apenas continuamos a execução. Em caso
negativo, fazemos um desvio incondicional para não termos que executar
novamente o código de inicialização. Por fim, se não fizemos o desvio,
faremos com que a variável |W.loop_name| passe a ser uma string com o
nome do laço principal atual.

Saber se devemos continuar executando ou não um laço é algo que pode
ser controlado por uma variável global, não sendo nem necessário se
preocupar com semáforos. Afinal, somente um laço irá executar em um
dado momento. O mesmo pode ser feito com a variável que determina se
estamos na primeira execução de um laço (ou o começo de um laço) e se
já executamos a finalização. Vamos declarar essas variáveis no
cabeçalho:

\iniciocodigo
@<Variáveis Externas (weaver.h)@>+=
extern bool _running_loop, _loop_begin, _loop_finalized;
@
\fimcodigo

E também no arquivo com as definições:

\iniciocodigo
@<Variáveis Globais (weaver.c)@>+=
bool _running_loop, _loop_begin, _loop_finalized;
@
\fimcodigo

Vamos também inicializar elas:

\iniciocodigo
@<API Weaver: Inicialização@>+=
_running_loop = false;
_loop_begin = false;
_loop_finalized = false;
@
\fimcodigo

Saber se ainda estamos carregando arquivos (ou melhor, quantos
arquivos pendentes ainda estamos carregando) ou o nome do laço em que
estamos são duas informações que são úteis não só para a lógica
interna do motor, mas também para o seu usuário. Saber se o laço ainda
não terminou de carregar é útil para fornecer uma tela de
carregamento. Saber durante a execução o nome do laço em que estamos é
útil tanto para depuração como para podermos carregar recursos
diferentes dependendo do laço em que estamos. Por causa disso, ambas
as variáveis devem ser declaradas na estrutura |W|. O tamanho máximo
de nome de um laço que podemos armazenar pode ser personalizado com a
macro \monoespaco{W\_MAX\_LOOP\_NAME}.

\iniciocodigo
@<Namespace de Variáveis@>+=
// Dentro da estrutura W:
#if !defined(W_MAX_LOOP_NAME)
#define W_MAX_LOOP_NAME 64
#endif
unsigned pending_files;
char loop_name[W_MAX_LOOP_NAME];
@
\fimcodigo

Na inicialização ajustamos tais variáveis como 0 e |NULL|
respectivamente:

\iniciocodigo
@<API Weaver: Inicialização@>+=
W.pending_files = 0;
W.loop_name[0] = '\0';
@
\fimcodigo

A função que usaremos para sair do laço será esta:

\iniciocodigo
@<Declaração de Função (weaver.h)@>+=
#if !defined(_MSC_VER)
void _exit_loop(void) __attribute__ ((noreturn));
#else
__declspec(noreturn) void _exit_loop(void);
#endif
@
\fimcodigo

Mas não iremos definir ela ainda. Pelo cabeçalho nota-se que é uma
função que nunca retorna, tendo isso especificado tanto pela convenção
do GCC e Clang como pela convenção do Visual Studio. Isso porque o que
ela fará é apenas chamar o código do laço anterior, ou sair do
programa dependendo do caso.

Após descrever tudo isso, podemos enfim definir a macro de início de
laço:

\iniciocodigo
@<Macros (weaver.h)@>+=
#define LOOP_INIT                                                   \
  if(!_running_loop){                                               \
    if(W.pending_files)                                             \
      return;                                                       \
    if(!_loop_finalized){                                           \
      _loop_finalized = true;                                       \
      goto _LOOP_FINALIZATION;                                      \
    }                                                              \
    _exit_loop();                                                   \
  }                                                                 \
  if(!_loop_begin)                                                   \
    goto _END_LOOP_INITIALIZATION;                                   \
  snprintf(W.loop_name, W_MAX_LOOP_NAME, "%s", __func__);            \
  _BEGIN_LOOP_INITIALIZATION
@
\fimcodigo

Terminamos com o
identificador \monoespaco{\_BEGIN\_LOOP\_INITIALIZATION}, o qual será
o verdadeiro nome do rótulo que existirá por trás de nossa macro.

\subsecao{3.2. Corpo do Loop.}

Isso é o que fará a macro \monoespaco{LOOP\_BODY}:

Ao chega nesta macro, devemos ajustar como falsa a informação de que é
nossa primeira execução do laço, pois assim não iremos executar a
inicialização novamente. Em seguida, aproveitamos para colocar um
desvio incondicional por trás de um \monoespaco{if} que garanta que
ele nunca seja executado para o rótulo que termina a macro
anterior. Esse desvio nunca irá ocorrer, mas isso previne que o
compilador reclame que o rótulo que encerra a última macro não é
usado. Em seguida, crimaos o verdadeiro rótulo que marca o fim da
inicialização e o começo da execução do corpo do laço. Neste começo de
corpo do laço nós medimos o tempo que passou desde o último laço e
armazenamos em um acumulador. Se este acumulador tiver um valor maior
que o período de tempo entre execuções do código de física e lógica,
então executamos o código presente no laço e o código associado à
física. Caso contrário, só ignoramos tudo e vamos para a finalização
onde apenas renderizamos na tela.  Caso tenha passado um longo tempo
entre cada iteração de laço, executamos mais de uma vez o código do
corpo do laço.

O acumulador que usamos para saber se devemos executar a lógica e a
física do jogo será chamado de \monoespaco{\_lag}. Declaramos ele
globalmente:

\iniciocodigo
@<Variáveis Externas (weaver.h)@>+=
extern unsigned long _lag;
@
\fimcodigo

\iniciocodigo
@<Variáveis Globais (weaver.c)@>+=
unsigned long _lag;
@
\fimcodigo

E o inicializamos:

\iniciocodigo
@<API Weaver: Inicialização@>+=
_lag = 0;
@
\fimcodigo

Existirão variáveis que poderão ser lidas pelo usuário com informações
de tempo. Uma delas (\monoespaco{W.t}) conterá a quantidade de
microssegundos desde que o jogo inicializou. Outra delas
(\monoespaco{W.dt}) conterá o intervalo entre execuções do motor de
física e da lógica do jogo. Ambas as variáveis precisam ser declaradas
na estrutura \monoespaco{W}:

\iniciocodigo
@<Namespace de Variáveis@>+=
unsigned long long t;
unsigned long dt;
@
\fimcodigo

A primeira das variáveis, obviamente deve ser inicializada como
zero. A segunda deve ser inicializada como tendo o mesmo valor que uma
macro \monoespaco{W\_TIMESTEP} que pode ser definida pelo usuário para
que assim ele controle a granularidade de execução do código mais
pesado do motor de física e lógica do jogo. Se esta macro não for
definida, iremos assumir um valor de 40000 microssegundos. Isso
significa uma freuência de 25 Hz de execução do motor de física (25
vezes por segundo).

\iniciocodigo
@<API Weaver: Inicialização@>+=
#if !defined(W_TIMESTEP)
#define W_TIMESTEP 40000
#endif
W.dt = W_TIMESTEP;
W.t = 0;
@
\fimcodigo

O código da engine de física e lógica interna do jogo deve ficar
encapsulado em uma função chamada \monoespaco{\_update}:

\iniciocodigo
@<Declaração de Função (weaver.h)@>+=
void _update(void);
@
\fimcodigo

Por hora ainda não iremos definir o código a ser executado nesta
função:

\iniciocodigo
@<Definição de Função (weaver.c)@>+=
void _update(void){
  @<Código a executar todo loop@>
}
@
\fimcodigo

Mas com as definições que fizemos já podemos definir a nossa macro que
marca o começo do código do laço principal:

\iniciocodigo
@<Macros (weaver.h)@>+=
#define LOOP_BODY                                            \
  _loop_begin =  false;                                      \
  if(_loop_begin)                                            \
    goto _BEGIN_LOOP_INITIALIZATION;                         \
_END_LOOP_INITIALIZATION:                                    \
  _lag += _update_time();                                    \
  while(_lag >= W.dt){                                       \
    _update();                                               \
_LABEL_0
@
\fimcodigo

Notar que a macro acima abre um laço com um \monoespaco{while}, mas
não o encerra. Ele deverá ser encerrado pelo código inserido pela
macro que delimita o fim do corpo do laço principal. A qual também
deverá decrementar a variável \monoespaco{\_lag} para que este não
seja um laço infinito.

\subsecao{3.3. Finalização do Loop.}

Isso é o que fará a macro \monoespaco{LOOP\_END}:

Primeiro para fornecer uma condição de parada para o laço começado na
macro anterior, decrementaremos de \monoespaco{\_lag} o valor
de \monoespaco{W.dt}. Em seguida, incrementaremos \monoespaco{W.t} com
tal quantidade de microssegundos. Só então encerramos o bloco do laço
dentro do qual estávamos. Fora deste laço, seguimos realizando aquilo
que deve ser feito independente de estarmos executando o motor de
física e de lógica de jogo ou não. Como são sempre atividades
relacionadas à renderização na tela, isso estará dentro de uma função
chamada \monoespaco{\_render}. Em seguida, simplesmente retornamos. Se
estamos executando o código aqui, é porque estávamos terminando de
executar o corpo do link. Depois do retorno colocamos um desvio para
um rótulo que nunca será executado e apenas nos protege de aviso do
compilador. E enfim colocamos um rótulo imediatamente antes da
finalização e que pode ser atingido somente por um desvio se
detectarmos que o laço acabou e precisamos rodar a finalização.

A única coisa nova que temos aqui então é a função de renderização:

\iniciocodigo
@<Declaração de Função (weaver.h)@>+=
void _render(void);
@
\fimcodigo

Por hora ainda não iremos definir o código a ser executado nesta
função:

\iniciocodigo
@<Definição de Função (weaver.c)@>+=
void _render(void){
  @<Código de renderização@>
}
@
\fimcodigo

E agora colocamos o código da macro:

\iniciocodigo
@<Macros (weaver.h)@>+=
#define LOOP_END                                           \
    _lag -=  40000;                                        \
    W.t +=  40000;                                         \
  }                                                        \
  _render();                                               \
  return;                                                  \
  goto _LABEL_0;                                           \
_LOOP_FINALIZATION
@
\fimcodigo

\subsecao{3.4. Entrando em Laço Principal.}

Frequentemente estaremos trocando de laços principais ao longo de um
jogo. Mas nem sempre isso significa uma substituição completa. Alguns
laços principais ocorrem dentro de outros laços principais. Por
exemplo, quando acessamos um menu de configurações durante um jogo. Ou
quando em um RPG clássico por turnos mudamos para o modo de combate
após um encontro aleatório.

Podemos então formar uma pilha de laços principais, onde ao sairmos do
último laço voltamos para o que está empilhado imediatamente abaixo
dele ao invés de sairmos do jogo.

Sendo assim, existem duas formas de entrar em um laço principal. Uma
delas, por meio da função que definiremos chamada \monoespaco{Wloop} e
a segunda por meio da \monoespaco{Wsubloop}. A primeira envolve
substituirmos o laço principal atual por um novo. A segunda enolve
apenas criar um laço principal dentro do laço atual. A primeira é algo
que só poderemos fazer se não houverem arquivos pendentes sendo
carregados (possivelmente haverá uma tela de carregamento neste
caso). Por isso apenas nos asseguramos disso por mieo de um truque com
macros:

\iniciocodigo
@<Declaração de Função (weaver.h)@>+=
#if !defined(_MSC_VER)
void _Wloop(void (*f)(void)) __attribute__ ((noreturn));
void Wsubloop(void (*f)(void)) __attribute__ ((noreturn));
#else
__declspec(noreturn) void _Wloop(void (*f)(void));
__declspec(noreturn) void Wsubloop(void (*f)(void));
#endif
#define Wloop(a) ((W.pending_files)?(false):(_Wloop(a)))
@
\fimcodigo

Nenhum dos dois tipos de função irá retornar jamais. Então
especificamos isso tanto na convenção de compiladores como Clang e GCC
como na do Visual Studio.

Vamos precisar de uma pilha de laços principais, que representaremos
por meio de uma sequência de ponteiros para funções. Essa nossa
sequência será um vetor com \monoespaco{W\_MAX\_SUBLOOP}
posições. Esta macro poderá ser controlada pelo usuário, mas se não
estiver definida, assumiremos que será 3. Além da pilha, vamos
precisar de uma variável para nos informar em qual profundidade da
pilha estamos no momento (\monoespaco{\_number\_of\_loops}).

A declaração destas duas variáveis será:

\iniciocodigo
@<Variáveis Externas (weaver.h)@>+=
#if !defined(W_MAX_SUBLOOP)
#define W_MAX_SUBLOOP 3
#endif
extern int _number_of_loops;
extern void (*_loop_stack[W_MAX_SUBLOOP]) (void);
@
\fimcodigo

\iniciocodigo
@<Variáveis Globais (weaver.c)@>+=
int _number_of_loops;
void (*_loop_stack[W_MAX_SUBLOOP]) (void);
@
\fimcodigo


E inicializamos a contagem do número de laços como zero:

\iniciocodigo
@<API Weaver: Inicialização@>+=
_number_of_loops = 0;
@
\fimcodigo

Entrar em um novo laço principal por meio de \monoespaco{Wloop}
envolve verificar se já estamos antes em um laço. Se for o caso,
cancelamos ele. Em seguida, carregamos o novo laço para a pilha e
ajustamos o valor da contagem de laços em execução. Atualizamos o
nosso valor de contagem de tempo e finalmente executamos o laço. Em
ambiente Web Assembly em navegador de Internet isso envolve chamar
diretamente uma função que estabelece nossa função escolhida como laço
principal. Nos demais, basta executar a função em
um \monoespaco{while} comum:

\iniciocodigo
@<Definição de Função (weaver.c)@>+=
void _Wloop(void (*f)(void)){
  if(_number_of_loops > 0){
    @<Cancela Loop Principal@>
    @<Ajuste de Memória Após Cancelar Loop@>
    _number_of_loops --;
  }
  @<Código antes de Loop e Subloop@>
  @<Código antes de Loop, não de Subloop@>
  @<Ajuste de Memória antes de Loop e Subloop@>
  _loop_stack[_number_of_loops] = f;
  _number_of_loops ++;
#if defined(__EMSCRIPTEN__)
  emscripten_set_main_loop(f, 0, 1);
#else
  while(1)
    f();
#endif
}
@
\fimcodigo

Lembrando que se estivermos executando em ambiente Web Assembly em
navegador precisamos do cabeçalho adequado:

\iniciocodigo
@<Inclui Cabeçalhos (weaver.h)@>+=
#if defined(__EMSCRIPTEN__)
#include <emscripten.h>
#endif
@
\fimcodigo

Cancelar um laço principal já existente envolve caso estejamos
executando em ambiente Web Assembly invocar a função que interrompe o
laço atual:

\iniciocodigo
@<Cancela Loop Principal@>=
#if defined(__EMSCRIPTEN__)
emscripten_cancel_main_loop();
#endif
@
\fimcodigo

Iniciar um novo subloop, ou sublaço, é bastante semelhante. Mas
tratamos de maneira diferente o nosso contador de laços, já que ele
realmente precisa ser incrementado. E também temos que checar se
tivemos um estouro na nossa pilha de laços:

\iniciocodigo
@<Definição de Função (weaver.c)@>+=
void Wsubloop(void (*f)(void)){
#if defined(__EMSCRIPTEN__)
    emscripten_cancel_main_loop();
#endif
  @<Código antes de Loop e Subloop@>
  @<Código antes de Subloop, não de Loop@>
  if(_number_of_loops >= W_MAX_SUBLOOP){
    fprintf(stderr, "Error: Max number of subloops achieved.\n");
    fprintf(stderr, "Please, increase W_MAX_SUBLOOP in conf/conf.h"
            " to a value bigger than %d.\n", W_MAX_SUBLOOP);
    exit(1);
  }
  _loop_stack[_number_of_loops] = f;
  _number_of_loops ++;
#if defined(__EMSCRIPTEN__)
  emscripten_set_main_loop(f, 0, 1);
#else
  while(1)
    f();
#endif
}
@
\fimcodigo

Uma coisa que faremos tanto antes de um laço como de um sublaço é
atualizar a variável \monoespaco{\_running\_loop} que avisa ao motor
que realmente estamos executando um laço ao invés de tentar sair dele,
ajustamos a variável que diz que estamos entrando no começo de um laço
e que portanto precisaremos executar o código de inicialização, a
variável que informa que a finalização do laço ainda não foi
executada. Estas são as variáveis que controlam o fluxo de execução do
laço. Também atualizamos nosso contador de tempo:

\iniciocodigo
@<Código antes de Loop e Subloop@>=
_running_loop = true;
_loop_begin = true;
_loop_finalized = false;
_update_time();
@
\fimcodigo

\subsecao{3.5. Saindo do Laço Principal.}

Assim como existem duas funções para entrar em laços principais,
existitão duas funções para sair. Uma delas apenas sai do laço
principal atual, voltando para o próximo laço principal da pilha se
existir. A outra sai de todos os laços existentes e encerra o
programa.

A que sai de todos os laços já foi parcialmente definida e é
a \monoespaco{Wexit}.

Sair de um laço atual já existente envolve ajustar a variável global
que diz que estamos executando o laço para um valor que significa que
queremos sair do laço:

\iniciocodigo
@<Macros (weaver.h)@>+=
#define Wexit_loop() (_running_loop = false)
@
\fimcodigo

Se você verificar novamente o código inserido pelas macros presentes
em laços principais, verá que se esta variável for falsa e não existir
nenhum recurso ou arquivo ainda sendo carregado, então será chamada a
função \monoespaco{\_exit\_loop}.

Já o código desta função envolve cancelar o laço atual e checar se
existe outro na pilha. Se não existir, o programa se encerra. Se
existir, executa código de entrada no novo laço:

\iniciocodigo
@<Definição de Função (weaver.c)@>+=
void _exit_loop(void){
  if(_number_of_loops <= 1){
    Wexit();
    exit(1); // Esta linha apenas previne aviso na compilação
  }
  else{
    @<Código após sairmos de Subloop@>
    _number_of_loops --;
    @<Código antes de Loop e Subloop@>
#if defined(__EMSCRIPTEN__)
    emscripten_cancel_main_loop();
    emscripten_set_main_loop(_loop_stack[_number_of_loops - 1], 0, 1);
#else
    while(1)
      _loop_stack[_number_of_loops - 1]();
#endif
  }
}
@
\fimcodigo

\secao{4. Gerenciamento de Memória}

O gerenciamento de memória utiliza um subsistema próprio que fornece
suas próprias funções de alocação e gerenciamento de memória. Uma das
diferenças do subsistema utilizado e do gerenciamento tradicional por
meio das funções \monoespaco{malloc} e \monoespaco{free} é que nele
somos obrigados a informar com antecedência qual a quantidade máxima
de memória que iremos precisar.

A quantidade máxima deve ser pensada de acordo com as especificações
de um projeto. Um jogo feito para um console pode usar como quantidade
máxima a quantidade de RAM da especificação do console. Um projeto
escrito para rodar em computadores pode começar com um valor pequeno,
talvez potência de dois que sempre irá dobrar à medida que o projeto
vai sendo escrito e a quantidade inicial não é mais o suficiente,
sempre cuidando para que o valor não se torne maior que o suportado
pelas máquinas na qual espera-se rodar o programa após ser finalizado.

Espera-se que o usuário informe qual a quantidade máxima de memória
definindo a macro \monoespaco{W\_MAX\_MEMORY}
em \monoespaco{conf/conf.h}. Se esta macro não estiver definida, vamos
deliberadamente escolher o valor pequeno de 4 KiB, o qual forçará o
usuário a ter que explicitar um valor mais adequado exceto nos
menores e mais triviais dos projetos:

\iniciocodigo
@<Macros (weaver.h)@>+=
#ifndef W_MAX_MEMORY
#define W_MAX_MEMORY 4096
#endif
@
\fimcodigo

Essa quantidade máxima de memória será alocada durante a inicialização
e armazenaremos o endereço para ela na variável abaixo:

\iniciocodigo
@<Variáveis Estáticas (weaver.c)@>=
static void *memory_arena;
@
\fimcodigo

Para podermos usar as funções de nosso subsistema de memória,
incluimos o cabeçalho:

\iniciocodigo
@<Cabeçalhos Locais (weaver.c)@>=
#include "memory.h"
@
\fimcodigo

E durante a inicialização nós alocamos em nossa arena de memória
interna toda a memória que iremos precisar ao longo da execução de
nosso projeto:

\iniciocodigo
@<API Weaver: Inicialização@>+=
memory_arena = _Wcreate_arena(W_MAX_MEMORY);
@
\fimcodigo

Na finalização nós desalocamos toda a memória obtida na inicialização
ou que ainda esteja alocada na pilha temporária. A invocação para a
função \monoespaco{\_Wtrash} faz isso: desaloca tudo da pilha da
esquerda permanente e direita temporária passando respectivamente
argumento 0 e 1:

\iniciocodigo
@<API Weaver: Memória: Finalização@>=
_Wtrash(memory_arena, 0);
_Wtrash(memory_arena, 1);
_Wdestroy_arena(memory_arena);
@
\fimcodigo

Antes de entrar em cada laço principal, usamos a
função \monoespaco{\_Wmempoint}. Esta função salva o estado atual da
memória para podermos voltar até ele depois. Fazendo isso, depois para
desalocarmos de uma só vez tudo que foi alocado durante o laço
principal torna-se fácil: é só restaurar a arena de memória para o
estado salvo.

Como salvar o estado atual requer escrever na memória, vamos precisar
saber qual o alinhamento de bytes recomendado para o nosso CPU. Weaver
obtém este valor da macro \monoespaco{W\_MEMORY\_ALIGNMENT} que pode
ser definida em \monoespaco{conf/conf.h}. Se ela não estiver definida,
nós usamos por padrão o tamanho de um \monoespaco{unsigned long} como
palpite.

\iniciocodigo
@<Macros (weaver.h)@>+=
#ifndef W_MEMORY_ALIGNMENT
#define W_MEMORY_ALIGNMENT (sizeof(unsigned long))
#endif
@
\fimcodigo

Com isso podemos salvar o estado da pilha esquerda de nossa arena de
memória, onde guardamos as coisas mais permanentes:

\iniciocodigo
@<Ajuste de Memória antes de Loop e Subloop@>=
_Wmempoint(memory_arena, W_MEMORY_ALIGNMENT, 0);
@
\fimcodigo

Isso significa que assim que sairmos de um laço, devemos restaurar o
estado da arena de memória para como estava quando entramos nele, no
que concerne a pilha de memória da esquerda:

\iniciocodigo
@<Ajuste de Memória Após Cancelar Loop@>=
_Wtrash(memory_arena, 0);
@
\fimcodigo

E isso basicamente será o coletor de lixo de nosso projeto. Vamos
agora definir uma função para que o usuário possa usar nossa função de
alocação de memória. Todas as alocações permanentes feitas pelo
usuário devem ser da pilha esquerda da memória, usando o alinhamento
padrão:

\iniciocodigo
@<Definição de Função (weaver.c)@>+=
static void *_alloc(size_t size){
  return _Walloc(memory_arena, W_MEMORY_ALIGNMENT, 0, size);
}
@
\fimcodigo

Para alocações temporárias, que poderão não permanecer alocadas em
memória mais que uma iteração de nosso laço principal, usa-se a função
abaixo:

\iniciocodigo
@<Definição de Função (weaver.c)@>+=
static void *_talloc(size_t size){
  return _Walloc(memory_arena, W_MEMORY_ALIGNMENT, 1, size);
}
@
\fimcodigo


Vamos declarar ponteiros para estas funções dentro da
estrutura \monoespaco{W} para que as funções possam ser invocada
como \monoespaco{W.alloc()} e \monoespaco{W.talloc()}:

\iniciocodigo
@<Namespace de Funções@>=
void *(*alloc)(size_t);
void *(*talloc)(size_t);
@
\fimcodigo

E a função estará pronta para ser usada após a inicialização:

\iniciocodigo
@<API Weaver: Inicialização@>+=
W.alloc = _alloc;
W.talloc = _talloc;
@
\fimcodigo

Tudo o que for alocado com a alocação permanente será automaticamente
desalocado quando o laço principal em que ocorrer a alocação deixar de
existir. Já o que foi alocado com a alocação temporária, será
desalocado a cada laço principal, a menos que estejamos carregando
algum arquivo ou recurso, momento no qual precisamos manter alocações
temporárias por mais atempo até que isso termine:

\iniciocodigo
@<Código a executar todo loop@>+=
if(W.pending_files == 0)
  _Wtrash(memory_arena, 1);
@
\fimcodigo

\secao{5. Gerador de Números Randômicos}

Primeiro temos que inserir o cabeçalho para o subsistema de geração de
números pseudo-randômicos:

\iniciocodigo
@<Cabeçalhos Locais (weaver.c)@>+=
#include "random.h"
@
\fimcodigo

Em seguida, vamos declara o ponteiro para a estrutura de nosso
gerador:

\iniciocodigo
@<Variáveis Estáticas (weaver.c)@>+=
static struct _Wrng *rng;
@
\fimcodigo

Se o usuário da API Weaver passar uma semente pré-definida por meio da
macro \monoespaco{W_RNG_SEED}, usaremos tal semente para inicializar
nosso gerador:

\iniciocodigo
@<API Weaver: Inicialização@>+=
#if defined(W_RNG_SEED)
{
  uint64_t seed[] = W_RNG_SEED;
  rng = _Wcreate_rng(_alloc, sizeof(seed)/sizeof(uint64_t), seed);
}
#endif
@
\fimcodigo

Se não existir uma semente pré-definida, iremos gerar uma semente
obtida aleatória e uniformemente. Nossa semente será formada por
quatro números aleatórios de 64 bits, pois isso é o suficiente para
garantir a qualidade de qualquer gerador. Ao invés de escolher o
método mais simples de usar o horário atual como semente, iremos gerar
ela da maneira mais aleatória e imprevisível possível. Espera-se que
isso aumente a qualidade dos números aleatórios gerados. Mas gerar
sementes tão aleatórias desta forma em alguns sistemas envolve o uso
de uma API criptográfica.

No Linux podemos usar a chamada de sistema \monoespaco{getrandom}. O
primeiro argumento de sua função em C é um buffer a ser preenchido, o
segundo argumento é o tamanho do buffer em bytes e o terceiro são
flags que mudam o comportamento padrão. A função retorna quantos bytes
realmente foram preenchidos (pode ser menos que o pedido se a chamada
de sistema for interrompida por um sinal):

\iniciocodigo
@<API Weaver: Inicialização@>+=
#if !defined(W_RNG_SEED) && defined(__linux__)
{
  ssize_t ret;
  uint64_t buffer[4];
  do{
    ret = getrandom(buffer, 4 * 8, 0);
  }while(ret != 4 * 8);
  rng = _Wcreate_rng(_alloc, 4, buffer);
}
#endif
@
\fimcodigo

Mas isso requer que adicionemos o cabeçalho para chamar esta função:

\iniciocodigo
@<Cabeçalhos Locais (weaver.c)@>+=
#if !defined(W_RNG_SEED) && defined(__linux__)
#include <sys/random.h>
#endif
@
\fimcodigo

Sistemas baseados em BSD, incluindo Mac OS podem obter valores
aleatórios iniciais usando a função \monoespaco{arc4random\_buf}. A
função já é fornecida no cabeçalho da biblioteca padrão e não falha em
nenhum caso:

\iniciocodigo
@<API Weaver: Inicialização@>+=
#if !defined(W_RNG_SEED) && defined(BSD)
{
  uint64_t buffer[4];
  arc4random_buf(buffer, 4 * 8);
  rng = _Wcreate_rng(_alloc, 4, buffer);
}
#endif
@
\fimcodigo

No Windows, geradores de números aleatórios criptograficametne seguros
podem ser chamadas pela assim cahamada ``API de Criptografia: Próxima
Geração'' (CNG). Para preencher a semente com valores imprevisíveis
chamamos a função abaixo. O primeiro argumento é nulo porque o último
argumento é uma flag que indica que o algoritmo a ser usado deve ser o
que quer que seja recomendado pelo sistema. Sem esta flag, o primeiro
argumento deveria indicar o algoritmo escolhido. Os outros dois
parâmetros da função é o buffer a ser preenchido e o tamanho em bytes.

Como a documentação não lista todas as causas possíveis que podem
levar esta função à falhar, não temos como garantir que qualquer falha
que tenhamos é sempre temporária (como no caso do Linux em que elas
podem ser causadas por algum sinal enviado) ou pode ser
permanente. Sendo assim, o que faremos é tentar novamente um número
finito de vezes caso não tenhamos sucesso ao preencher nosso
vetor. Tentamos um total de 16 vezes, mas o esperado é que não hajam
problemas e que a primeira tentativa seja bem-sucedida.

\iniciocodigo
@<API Weaver: Inicialização@>+=
#if !defined(W_RNG_SEED) && defined(_WIN32)
{
  uint64_t buffer[4];
  NTSTATUS ret;
  int count = 0;
  do{
    ret = BCryptGenRandom(NULL, (unsigned char *) &buffer, 8 * 4,
                          BCRYPT_USE_SYSTEM_PREFERRED_RNG);
    count ++;
  } while(ret != 0 && count < 16);
  if(ret != 0){
    fprintf(stderr, "ERROR: I could not initialize the RNG.\n");
    exit(1);
  }
  rng = _Wcreate_rng(_alloc, 4, buffer);
}
#endif
@
\fimcodigo

Para usar a API CNG do Windows nós primeiro precisamos inserir este
cabeçalho:

\iniciocodigo
@<Cabeçalhos Locais (weaver.c)@>+=
#if !defined(W_RNG_SEED) && defined(_WIN32)
#include <bcrypt.h>
#endif
@
\fimcodigo

Se estamos executando código Web Assembly no ambiente de um navegador
de Internet, para inicializar uma semente com valores imprevisíveis,
nós podemos executar código Javascript e obter assim acesso à API
criptográfica do navegador de Internet. Podemos
usar \monoespaco{EM\_ASM\_INT} para executar código Javascript e obter
um inteiro como retorno após cada execução (que para o Emscripten
sempre tem 32 bits). Compondo 8 números de 32 bits nós podemos formar
4 números de 64 bits:

\iniciocodigo
@<API Weaver: Inicialização@>+=
#if !defined(W_RNG_SEED) && defined(__EMSCRIPTEN__)
{
  uint64_t buffer[4];
  int i;
  for(i = 0; i < 4; i ++){
    buffer[i] = EM_ASM_INT({
      var array = new Uint32Array(1);
      window.crypto.getRandomValues(array);
      return array[0];
    });
    buffer[i] = buffer[i] << 32;
    buffer[i] += EM_ASM_INT({
      var array = new Uint32Array(1);
      window.crypto.getRandomValues(array);
      return array[0];
    });
  }
  rng = _Wcreate_rng(_alloc, 4, buffer);
}
#endif
@
\fimcodigo

Se inicializamos o nosso gerador de números aleatórios durante a
inicialização da API Weaver, vamos finalizar ele durante a finalização
da API. O código para isso é:

\iniciocodigo
@<API Weaver: Finalização@>=
_Wdestroy_rng(NULL, rng);
@
\fimcodigo

Precisamos agora de uma função que apenas retorne um número aleatório
de 64 bits, sem precisar passar como argumento o próprio
gerador.Podemos construir tal função assim:

\iniciocodigo
@<Definição de Função (weaver.c)@>+=
static uint64_t _rand(void){
  return _Wrand(rng);
}
@
\fimcodigo

Para permitir que ela seja usada externamente como parte de nossa API,
declaramos um ponteiro para ela na estrutura \monoespaco{W}:

\iniciocodigo
@<Namespace de Funções@>=
uint64_t (*rand)(void);
@
\fimcodigo

E o ponteiro pode ser invocado como função após a seguinte
inicialização:

\iniciocodigo
@<API Weaver: Inicialização@>+=
W.rand = _rand;
@
\fimcodigo

\secao{6. Criação de Janelas e Gerenciamento de Entrada}

Todo o gerenciamento de janelas será feito invocando as funções do
subsistema de janela e somente isso. Para podermos usar o subsistema,
inserimos o seu cabeçalho, o qual deve também ser visdível para o
usuário:

\iniciocodigo
@<Inclui Cabeçalhos (weaver.h)@>+=
#include "window.h"
@
\fimcodigo

Para obter a estrutura de teclado e mouse, necessárias para criar a
nossa janela, vamos deixar um espaço para a estrutura deles na
estrutura \monoespaco{W}:

\iniciocodigo
@<Namespace de Variáveis@>+=
long *keyboard;
struct _Wmouse mouse;
@
\fimcodigo

A estrutura completa do teclado será declarada aqui:

\iniciocodigo
@<Variáveis Estáticas (weaver.c)@>+=
static struct _Wkeyboard keyboard;
@
\fimcodigo

E inicializamos o ponteiro do teclado para apontar para a região certa
criada pelo subsistema de janela:

\iniciocodigo
@<API Weaver: Inicialização@>+=
W.keyboard = keyboard.key;
@
\fimcodigo

Para termos uma janela, precisamos criar ela na inicialização do nosso
programa. Iremos criar sempre uma única janela e só iremos fechá-la
durante a finalização:

\iniciocodigo
@<API Weaver: Inicialização@>+=
_Wcreate_window(&keyboard, &W.mouse);
@
\fimcodigo

\iniciocodigo
@<API Weaver: Finalização@>+=
_Wdestroy_window();
@
\fimcodigo

E iremos renderizar na tela dentro do nosso laço principal, no momento
de renderização, o que significa que faremos isso com a maior
frequência possível:

\iniciocodigo
@<Código de renderização@>=
_Wrender_window();
@
\fimcodigo


O teclado e mouse precisam ser lidos periodicamente, toda iteração:

\iniciocodigo
@<Código a executar todo loop@>=
_Wget_window_input(W.t, &keyboard, &W.mouse);
@
\fimcodigo

E ao inicar qualquer loop ou subloop, precisamos limpar e reiniciar o
teclado e mouse:

\iniciocodigo
@<Código antes de Loop e Subloop@>+=
_Wflush_window_input(&keyboard, &W.mouse);
@
\fimcodigo

Por fim, vamos fornecer ao usuário algumas informações sobre o
ambiente em que estamos executando. As informações relevantes aqui,
além do estado do mouse e teclado que já tratamos, será a resolução da
tela e também de nossa janela. Mas há um pequeno detalhe: se a
macro \monoespaco{W\_FORCE\_LANDSCAPE} estiver definida e se além
disso a altura da janela for maior que a largura, então
devemos trocar ambos os valores, pois a tela deverá ser rotacionada
pelo usuário. Por causa disso, o código que armazena tais dados deverá
levar isso em conta.

Vamos então usar a seguinte variável global só para saber se estamos
com a tela rotacionada ou não:

\iniciocodigo
@<Variáveis Estáticas (weaver.c)@>+=
#if defined(W_FORCE_LANDSCAPE)
static bool rotated_screen = false;
#endif
@
\fimcodigo

E agora, durante a inicialização, iremos preencher as seguintes
variáveis que armazenarão a resolução da tela e tamanho da janela:

\iniciocodigo
@<Namespace de Variáveis@>+=
int width, height, resolution_x, resolution_y;
@
\fimcodigo

Aqui os valores são preenchidos:

\iniciocodigo
@<API Weaver: Inicialização@>+=
_Wget_screen_resolution(&W.resolution_x, &W.resolution_y);
_Wget_window_size(&W.width, &W.height);
#if defined(W_FORCE_LANDSCAPE)
if(W.height > W.width){
  int tmp;
  tmp = W.resolution_y;
  W.resolution_y = W.resolution_x;
  W.resolution_x = tmp;
  tmp = W.width;
  W.width = W.height;
  W.height = tmp;
  rotated_screen = true;
}
#endif
@
\fimcodigo

\secao{7. Interface de Usuário}

Para usar a API de interface de usuário, inserimos o cabeçalho:

\iniciocodigo
@<Inclui Cabeçalhos (weaver.h)@>+=
#include "interface.h"
@
\fimcodigo

Antes de inicializar nossa API de interface de usuário, temos que
decidir o que deve ser feito por ela imediatamente antes de começar a
carregar texturas e dados para uma interface e o que deve ser feito
depois. A API Weaver deve sempre manter dados corretos sobre o número
de recursos que estão sendo carregados ou não por meio da
variável \monoespaco{W.pending\_files}. Então, quando vamos carregar
dados de uma interface, devemos incrementar esta variável. E quando
terminarmos de carregar os dados, devemos decrementá-la
novamente. Fazer isso garante que não iremos abandonar um laço
principal antes de carregar todos os seus recursos, o que garante que
uma thread de carregamento de dados não vai continuar escrevendo
coisas em memória que pode já ter sido desalocada e alocada para outro
laço principal.

Como podemos esperar que texturas e recursos para as interfaces sejam
carregadas por threads, isso significa que vamos precisar de um mutex
para incrementar e decrementar a variável. Além disso, queremos também
que em um dado momento exista somente uma thread lendo arquivos e
carregando recursos para evitar uma explosão de gasto de memória. Para
isso usaremos duas variáveis de mutex. Vamos armazenar eles como
variáveis estáticas:

\iniciocodigo
@<Variáveis Estáticas (weaver.c)@>+=
STATIC_MUTEX_DECLARATION(pending_files_mutex);
STATIC_MUTEX_DECLARATION(loading_files);
@
\fimcodigo

O mutex é inicializado durante a inicialização:

\iniciocodigo
@<API Weaver: Inicialização@>+=
MUTEX_INIT(&pending_files_mutex);
MUTEX_INIT(&loading_files);
@
\fimdodigo

E é finalizado na finalização:

\iniciocodigo
@<API Weaver: Finalização@>+=
MUTEX_DESTROY(&pending_files_mutex);
MUTEX_DESTROY(&loading_files);
@
\fimcodigo

Com o mutex, podemos enfim declarar uma função que deve ser executada
antes de carregar cada recurso de interface e outra depois de carregar
os recursos. As funções, por meio de mutex, irão garantir a contagem
adequada de recursos sendo carregados, garantirão que haja só uma
thread carregando recursos enquanto as outras esperam, mas além disso
também irão inicialmente criar uma marcação na pilha direita de nosso
gerenciador de memórias e depois do carregamento irão apagar tudo que
foi alocado nessa região de memória. Fazer isso irá limpar toda a
memória temporária alocada durante o carregamento.

\iniciocodigo
@<Definição de Função (weaver.c)@>+=
void before_loading_resources(void){
  MUTEX_WAIT(&pending_files_mutex);
  W.pending_files ++;
  MUTEX_SIGNAL(&pending_files_mutex);
  MUTEX_WAIT(&loading_files);
  _Wmempoint(memory_arena, W_MEMORY_ALIGNMENT, 1);
}
void after_loading_resources(void){
  _Wtrash(memory_arena, 1);
  MUTEX_SIGNAL(&loading_files);
  MUTEX_WAIT(&pending_files_mutex);
  W.pending_files --;
  MUTEX_SIGNAL(&pending_files_mutex);
}
@
\fimcodigo

A nossa API de interface de usuário é inicializada com:

\iniciocodigo
@<API Weaver: Inicialização@>+=
{
  int *window_width = &W.width, *window_height = &W.height;
#if defined(W_FORCE_LANDSCAPE)
  if(rotated_screen){
    *window_width = &W.height;
    *window_height = &W.width;
  }
#endif
  _Winit_interface(window_width, window_height, _alloc, NULL,
                   _talloc, NULL, before_loading_resources,
                   after_loading_resources, NULL);
}
@
\fimcodigo

Na inicialização informamos a API de interface do tamanho verdadeiro
da janela (não o tamanho rotacionado caso estejamos em modo paisagem e
esperamos que o usuário rotacione seu telefone para usar o programa),
como a memória deve ser alocada, que a API não deve tentar desalocar
sozinha memória e as duas funções definidas acima do quê fazer antes e
depois de carregar recursos de arquivos.

Finalizamos o código com:

\iniciocodigo
@<API Weaver: Finalização@>+=
_Wfinish_interface();
@
\fimcodigo

Uma coisa que temos que fazer também é salvar a lista de interfaces
que temos no momento e colocar em uma pilha toda vez que entramos em
um laço principal ao mesmo tempo que após salvar marcamos como
não-ativas todas as interfaces. Se sairmos de um laço principal,
devemos restaurar a nossa lista de interfaces ativa para o último
estado salvo na pilha e removê-lo da pilha. Dessa forma toda interface
terá como escopo o laço em que é criada e sua alocação e desalocação
obedecerá a mesma odem e lógica dos laços principais.

Para isso basta chamarmos as funções adequadas no momento
certo. Antes de entrar em novo loop e subloop devemos salvar o estado
das interfaces na pilha e marcar todas elas como inativas:

\iniciocodigo
@<Código antes de Loop e Subloop@>+=
_Wmark_history_interface();
@
\fimcodigo

E quando estivermos cancelando um loop principal no qual estamos,
devemos apagar as interfaces criadas dentro dela e restaurar o último
estado salvo na pilha, removendo-o da pilha:

\iniciocodigo
@<Cancela Loop Principal@>+=
_Wrestore_history_interface();
@
\fimcodigo

During the game physics loop, we can interact with the interfaces:

\iniciocodigo
@<Código a executar todo loop@>+=
_Winteract_interface(W.mouse.x, W.mouse.y,
                     W.mouse.button[W_MOUSE_LEFT] > 0,
                     W.mouse.button[W_MOUSE_MIDDLE] > 0,
                     W.mouse.button[W_MOUSE_RIGHT] > 0);
@
\fimcodigo

Assim como devemos renderizar as interfaces em cada laço de
renderização:

\iniciocodigo
@<Código de renderização@>+=
_Wrender_interface(W.t);
@
\fimcodigo

Mas para poder renderizar ou tornar interfaces ativas, precisamos
criar novas interfaces. Para isso devemos passar como argumento um
arquivo onde está seu código-fonte de shader e sua textura. Ambos
podem ser \monoespaco{NULL} para usar o valor padrão.

Mas ao invés de esperar que usuários passem caminhos absolutos para
tais arquivos, queremos que o usuário digite apenas o seu nome e nós
os buscaremos no diretório adequado. Código-fonte de shaders devem ser
colocados no diretório \monoespaco{shaders} e texturas com imagens
devem estar no diretório \monoespaco{images}. Ambos os diretórios
devem estar no diretório indicado pela macro \monoespaco{W\_DATA\_DIR}
se ela estiver definida. Caso contrário, eles serão buscados no
diretório atual. A ideia é que esta macro seja definida somente quando
uma versão do jogo estiver sendo compilada para instalação.

O modo então de gerar novas interfaces será por meio da seguinte
função:

\iniciocodigo
@<Definição de Função (weaver.c)@>+=
static struct user_interface *new_interface(char *shader, char *texture,
                                            float x, float y, float z,
                                            float width, float height){
  char path_shader[512], path_texture[512];
  int dir_len, shader_len, texture_len;
  if(shader != NULL){
    shader_len = strlen(shader);
    path_shader[0] = '.';
    path_shader[1] = '\0';
    dir_len = 1;
#if defined(W_DATA_DIR)
    dir_len = strlen(W_DATA_DIR);
    memcpy(path_shader, W_DATA_DIR, dir_len + 1);
#endif
    memcpy(&path_shader[dir_len], "/shaders/", 10);
    dir_len += 9;
    memcpy(&path_shader[dir_len], shader, shader_len + 1);
  }
  if(texture != NULL){
    texture_len = strlen(texture);
    path_texture[0] = '.';
    path_texture[1] = '\0';
    dir_len = 1;
#if defined(W_DATA_DIR)
    dir_len = strlen(W_DATA_DIR);
    memcpy(path_texture, W_DATA_DIR, dir_len + 1);
#endif
    memcpy(&path_texture[dir_len], "/images/", 9);
    dir_len += 8;
    memcpy(&path_texture[dir_len], texture, texture_len + 1);
  }  
  return _Wnew_interface((texture == NULL)?(NULL):(path_texture),
                         (shader == NULL)?(NULL):(path_shader),
                         x, y, z, width, height);
}
@
\fimcodigo

Isso requer que usemos o canbeçalho de strings:

\iniciocodigo
@<Cabeçalhos Locais (weaver.c)@>+=
#include <string.h>
@
\fimcodigo

E colocamos esta função no namespace da API Weaver:

\iniciocodigo
@<Namespace de Funções@>+=
struct user_interface *(*new_interface)(char *, char *, float, float,
                                        float, float, float);
@
\fimcodigo

As outras funções da API de interface de usuário serão usadas tal qual
elas estão definidas no submódulo de interfaces. Por isso, só
precisaremos declará-las no namespace:

\iniciocodigo
@<Namespace de Funções@>+=
struct user_interface *(*link_interface)(struct user_interface *);
void (*rotate_interface)(struct user_interface *, float);
void (*resize_interface)(struct user_interface *, float, float);
void (*move_interface)(struct user_interface *, float, float, float);
@
\fimcodigo

Todas as funções precisam então ser preparadas para serem usadas após
a inicialização:

\iniciocodigo
@<API Weaver: Inicialização@>+=
W.new_interface = new_interface;
W.link_interface = _Wlink_interface;
W.rotate_interface = _Wrotate_interface;
W.resize_interface = _Wresize_interface;
W.move_interface = _Wmove_interface;
@
\fimcodigo


\secao{Definições Vazias}

As seguintes definições ainda estão em branco e estão aqui para manter
o projeto compilando com sucesso. Esta parte não existirá na versão
final deste documento e as partes que aparecem aqui vazias estarão
posteriormente preenchidas e melhor explicadas.

\iniciocodigo
@<Código antes de Subloop, não de Loop@>=
@
\fimcodigo

\iniciocodigo
@<Código após sairmos de Subloop@>=
@
\fimcodigo



\iniciocodigo
@<Código antes de Loop, não de Subloop@>=
@
\fimcodigo



\secao{Referências}

\referencia{Fiedler, G. (2004) ``Fix Your Timestep!'', acessado em 2020
em:\\
\monoespaco{https://gafferongames.com/post/fix\_your\_timestep/}}


\fim