weaver_api_en.tex

\input tex/epsf.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{The Weaver API}
\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.}

\secao{1. Introduction}

\subsecao{1.1. File Organization}

When a user types \monoespaco{weaver PROJECT} at command line, a
directory with a new Weaver project is created. Inside the directory,
the file with the main loop is in \monoespaco{src/game.c} and inside
them we find:

\alinhaverbatim
#include "game.h"

void main_loop(void){ // The game main loop
 LOOP_INIT: // Initialization code 

 LOOP_BODY: // Code executed each iteration
    if(W.keyboard[W_ANY])
        Wexit_loop();
 LOOP_END: // Code executed at finalization
    return;
}

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

And inside \monoespaco{src/game.h}, we find:

\alinhaverbatim
#ifndef _game_h_
#define _game_h_

#include "weaver/weaver.h"
#include "includes.h"

struct _game_struct{
  // You can customise this structure declaring variables here.
  // But don't change it's name. And access it by its pointer: W.game
  int whatever; // <- This variable is here to prevent compiler errors
} _game;

void main_loop(void);

#endif
\alinhanormal

In this file there's an struct which can be customized by the user and
which is where variables with global states should be declared. The
variables declared here are also variables which will be saved in a
player's save file and which will be sent over a network to inform
clients about the game state. This struct should be referenced by the
variable \monoespaco{W.game}. This also gives us information that the
API will be organized in a way that will exist a \monoespaco{struct}
called \monoespaco{W} where the API resources will be centralized.

The file \monoespaco{includes.h} is just a header which includes in
the project all the other headers of modules created by the user (each
module is a C source file and a header).

All the API code shall be present or be included by macros in the
files \monoespaco{weaver.c} and \monoespaco{weaver.h}. The
\monoespaco{weaver.h} organization is:

\iniciocodigo
@(project/src/weaver/weaver.h@>=
#ifndef _weaver_h_
#define _weaver_h_
#ifdef __cplusplus
  extern "C" {
#endif
@<Include Headers (weaver.h)@>
@<Data Structures (weaver.h)@>
@<Function Declaration (weaver.h)@>
@<Extern Variables (weaver.h)@>
@<Macros (weaver.h)@>
#ifdef __cplusplus
  }
#endif
#endif
@
\fimcodigo

The test in red above represents code that still was not defined. For
example, in the ``Include Headers'' part, it is useful to include the
header \monoespaco{sys/param.h} to check if we are compiling the
program on some BSD system. However, Windows do not have such header,
but if we are on Windows, we will want to
include \monoespaco{windows.h}.. Because of this, we can include
different headers if we are  on Windows or not with the conditional
inclusion below:

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

After we could want to include more headers in this part. For example,
the header for standard input/output and the standard library
header. The header \monoespaco{stdint.h} is also useful to define
integers with a fixed size of bits and \monoespaco{stdbool.h} is
useful to declare and use boolean variables:

\iniciocodigo
@<Include Headers (weaver.h)@>+=
#include <stdio.h>
#include <stdlib.h>
#include <stdint.h>
#include <stdbool.h>
@
\fimcodigo

We also will define here the general structure of
file \monoespaco{weaver.c} from our API:

\iniciocodigo
@(project/src/weaver/weaver.c@>=
#include "weaver.h"
#include "../game.h"
@<Local Headers (weaver.c)@>
@<Local Macros (weaver.c)@>
@<Global Variables (weaver.c)@>
@<Static Variables (weaver.c)@>
@<Function Definition (weaver.c)@>
@<Defining API Functions (weaver.c)@>
@
\fimcodigo

As an example of local macros that we will use in this document, the
macros below give us a portable way of declaring mutex and using them
independent of the operating system:

\iniciocodigo
@<Local Macros (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

In this document we will expand all the other parts in red in the two
files (\monoespaco{weaver.c} and \monoespaco{weaver.h}) showing the
code that should be inserted there. ANd this is how our API will be
defined.

\subsecao{1.2. The W Structure}

The main data structure that we will define is a
\monoespaco{struct} called \monoespaco{W}. This structure
basically will be a namespace where we will define our API public
functions and variables. Now we can start to define this structure:

\iniciocodigo
@<Data Structures (weaver.h)@>=
// This structure will contain all the variables and functions
// defined at Weaver API:
extern struct _weaver_struct{
  struct _game_struct *game;
  @<Variables Namespace@>
  @<Functions Namespace@>
} W;
@
\fimcodigo

Besides \monoespaco{W.game}, there will be other variables in this
structure. We basically will centralize all the public functions of
our API here. Only private functions whose names starts with ``\_''
and some initialization and finalization functions won't be inside
the \monoespaco{W} structure. In this way we prevent the pollution of
the global namespace.

We declare this namespace as a global variable:

\iniciocodigo
@<Global Variables (weaver.c)@>=
struct _weaver_struct W;
@
\fimcodigo

\subsecao{1.3. Initialization and Finalization Functions}

One thing that the initialization function must do is initialize the
values inside the \monoespaco{W} structure. Because of this, it is one
of the few functions outside our namespace:

\iniciocodigo
@<Function Declaration (weaver.h)@>=
void Winit(void);
@
\fimcodigo

\iniciocodigo
@<Defining API Functions (weaver.c)@>=
void Winit(void){
  W.game = &_game;
  @<Weaver API: Initialization@>
}
@
\fimcodigo

The finalization function shall deallocate any pending memory, end
resource usage and close the program informing if everything happened
as expected. Note that the memory should be the last thing to be
finalized.

\iniciocodigo
@<Function Declaration (weaver.h)@>=
void Wexit(void);
@
\fimcodigo

\iniciocodigo
@<Defining API Functions (weaver.c)@>=
void Wexit(void){
  @<Weaver API: Finalization@>
  @<Weaver API: Memory: Finalization@>
  exit(0);
}
@
\fimcodigo


\secao{2. Time Counting}

Weaver measeures elapsed time in microseconds ($10^{-6}$s) and stores
the time counting in at least 64 bits of memory. Besides the total
elapsed time since the program initialization, we also store the time
difference between the current iteration in the main loop and the
previous one.

First we neet a place to store our last time measure and we use a
global variable. In Windows we use a specific type to store large
integers (\monoespaco{LARGE\_INTEGER}) and in other systems we use a
\monoespaco{timeval} structure to store the time measure at high
resolution.

Our global variable is declared here:

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

And here:

\iniciocodigo
@<Global Variables (weaver.c)@>=
#if defined(_WIN32)
LARGE_INTEGER _last_time;
#else
struct timeval _last_time;
#endif
@
\fimcodigo

The header to use it can be placed here:

\iniciocodigo
@<Include Headers (weaver.h)@>=
#if !defined(_WIN32)
#include <sys/time.h>
#endif
@
\fimcodigo

The idea is store in this variable always the last time measure. It's
initialized with our first time measure at initialization:

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

After initialization, all other updates in this variable will happen
using the following declared function:

\iniciocodigo
@<Function Declaration (weaver.h)@>+=
unsigned long _update_time(void);
@
\fimcodigo

This function will read the current time and store the variable. It
will always return the difference in microseconds between the last two
measures. In Unix systems we compute the time difference using the
method recommended in the GNU C Library manual. This subtraction
method is more portable and works even if the \monoespaco{timeval}
elements are stored as ``unsigned''. The disadvantage is that the code
is less clear and intuitive. The code is:


\iniciocodigo
@<Function Definition (weaver.c)@>=
#if !defined(_WIN32)
unsigned long _update_time(void){
  int nsec;
  unsigned long result;
  struct timeval _current_time;
  gettimeofday(&_current_time, NULL);
  // Performing the carry:
  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);
    // This is always positive:
    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

At Windows systems, there's already a function that measure time in
microseconds. So the function becames much simpler:

\iniciocodigo
@<Function Definition (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. The main loops.}

All games are organized inside main loops. They are code which
iterates indefinitelly until some condition send the program for
another main loop or terminate the program.

As shown in the initial code at \monoespaco{game.c}, a main loop
should be declared as:

\alinhaverbatim
void nome\_do\_loop(void){
 LOOP\_INIT: // Code executed at initialization

 LOOP\_BODY: // Code executed in each iteration
    if(W.keyboard[W\_ANY])
        Wexit\_loop();
 LOOP\_END: // Code executed at finalization
    return;
}
\alinhanormal

Before understanding how we should enter correctly in a main loop,
it's important to describe how the loop is executed. Note that it has
an initialization section, an execution section and a finalization
section. These sections are delimited by labels in upper case.

Interpreting this is very simple. You can see the code above as:

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

While this interpretation is suitable in some contexts, this is not
how the main loop code is translated. We can't run an infinite loop in
all environments without blocking tha game interface. In Web Assembly
environments, a game loop can be executed only if they are correctly
declared as such and these functions shouldn't have an infinite loop,
instead they are called successively.

Because of such differences, to create more portable code, we should
interpret a main loop execution as:

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

Inside the main loop function, we don't put an explicit loop. Instead,
we decide which section of the function we should execute with the
help of the labels inserted. Such labels are in fact macros with
aditional logic inside and with some \monoespaco{goto} to decide which
section should be executed.

Because of this, we can't declare variables in a main loop
initialization. If so, they would have the correct value only during
the first iteration, not in the others. For example, the following
code would have an undefinded result and perhaps it wouldn't print
anything in the screen:

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

But the following code is correct and print in the screen in all
iterations because the variable is declared outside the function:

\alinhaverbatim
// CORRECT
static int var;

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

Other thing that should be considered is that in fact there's not just
one main loop being executed in a given moment, but two of them. One
of the loops execute in a fixed frequency: the loop handling physics
and game logic. The other main loop runs as fast as it: the loop
rendering graphics in the screen.

Ideally in each physics and logic loop iteration, we execute one or
more iterations of rendering loop. It means that we can render with a
frequency greater than we move objects, detect collisions and read
user input. And in each of the rendering loop iteration, we need to
render different images, otherwise there's no point in running this
loop faster than the physics loop. So in the rendering loop we also
interpolate the objects positions, knowing their current speed,
acceleration and position.

And ensuring that our game physics and logic runs always in a fixed
interval, we ensure the necessary determinism for synchronizing games
in networks like the Internet. And at same time, rendering as fast as
we can with interpolation gives us a more pleasant and natural
experience.

For more details of how to implement thism you can check [Fiedler
2004]. Our implementation swill be like in this reference, except that
our code will be much less explicit because it will be hiden by macros
without explicit loops.

Let's define in the following subsections what exactly we will put in
the macros present in every main loop.

\subsecao{3.1. Loop Initialization.}

This is what the macro \monoespaco{LOOP\_INIT} does:

First it checks variables to determine if we should finish the
loop. If so, but we still have resources being loaded (images, videos,
shaders, sounds), we just return from the function. If we have nothing
being loaded but we still didn't executed the finalization section, we
use \monoespaco{goto} and go to the finalization section. If there's
nothing being loaded and we already ran the finalization, we finally
stop the loop.

If we don't need to finish the loop, but this function is being called
for the first time, we just continue the execution. Otherwise, we use
a \monoespaco{goto} to avoid executing more than once the
initialization section. Finally, if we are still here, it's because we
are running the function for the first time. So we make the variable
|W.loop_name| represents a string with the name of current main loop.

How do we know if we should keep executing the loop? We use a global
variable. As there's only one main loop, we don't need to protect it
with semaphores. The same can be done to know if we are executing a
main loop for the first time, if we are in the beginning of a loop of
if we already executed the finalization. Let's declare the variables
in the header:

\iniciocodigo
@<Extern Variables (weaver.h)@>+=
extern bool _running_loop, _loop_begin, _loop_finalized;
@
\fimcodigo

And in the main file:

\iniciocodigo
@<Global Variables (weaver.c)@>+=
bool _running_loop, _loop_begin, _loop_finalized;
@
\fimcodigo

And let's initialize them:

\iniciocodigo
@<Weaver API: Initialization@>+=
_running_loop = false;
_loop_begin = false;
_loop_finalized = false;
@
\fimcodigo

Know if we are still loading resources (usually reading files) or the
name of the current loop is useful not only for the engine's internal
logic, but also for the user. Knowing if we are still loading files
permits showing a loading screen. Knowing the current loop name is
useful for debugging and for loading different resources depending of
the loop. Because of this, both variables shall be declared in |W|
structure. The maximum loop name which we can store can be setted with
the macro \monoespaco{W\_MAX\_LOOP\_NAME}.

\iniciocodigo
@<Variables Namespace@>+=
// Inside W structure:
#if !defined(W_MAX_LOOP_NAME)
#define W_MAX_LOOP_NAME 64
#endif
unsigned pending_files;
char loop_name[W_MAX_LOOP_NAME];
@
\fimcodigo

During initialization we set these variables as 0 and |NULL|
respectivelly:

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

The function which exits the loop is:

\iniciocodigo
@<Function Declaration (weaver.h)@>+=
#if !defined(_MSC_VER)
void _exit_loop(void) __attribute__ ((noreturn));
#else
__declspec(noreturn) void _exit_loop(void);
#endif
@
\fimcodigo

But we still won't define it. By the header, this is a function which
never returns, specified as such in the above code using notation from
GCC and Clang and from Visual Studio. It's so because when it exists,
it just calls previous main loop which never returns, or it just
exists the program, depending of the case.

After describing thism we can finally define the loop initialization
macro:

\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

We end with th identifier \monoespaco{\_BEGIN\_LOOP\_INITIALIZATION},
which is the true label name from this macro (remember, this macro is
always invoked as ``\monoespaco{LOOP\_INIT:}'' with ``:'' )  .

\subsecao{3.2. Loop Body.}    
     
This is what the macro \monoespaco{LOOP\_BODY} does:

When we are in this macro, we shall set as false the information that
this is our first loop execution avoiding to re-execute the
initialization again. Then, we put an \monoespaco{goto} after
a \monoespaco{if} which never will be executed. This is done just so
we can use the label \monoespaco{\_BEGIN\_LOOP\_INITIALIZATION} with
no compiler warnings of unused label. We mark with the
label \monoespaco{\_END\_LOOP\_INITIALIZATION} the real beginning of
our loop body. We then measure the elapsed time since the last loop
and store in an accumulator. If this accumulator holds a value bigger
than the time expected between execution of physics code and logic
code, we execute thee code. Otherwise, we just ignore these code and
jump for finalization where we just render in the screen. If a lot of
time passed since last loop execution, we could run more than once
this loop body code.

The accumulator which determines if we should run physics code or
logic code will be called \monoespaco{\_lag}. It is a global variable:

\iniciocodigo
@<Extern Variables (weaver.h)@>+=
unsigned long _lag;
@
\fimcodigo

\iniciocodigo
@<Global Variables (weaver.c)@>+=
unsigned long _lag;
@
\fimcodigo


This is ts initialization:

\iniciocodigo
@<Weaver API: Initialization@>+=
_lag = 0;
@
\fimcodigo

We need some variables which could be read by an user with information
about time. One of them (\monoespaco{W.t}) will store the elapsed
microseconds since the game initialization. Another one
(\monoespaco{W.dt}) will hold the interval between executions of our
physics engine and game logic. Both variables needs to be declared
inside \monoespaco{W} struct:

\iniciocodigo
@<Variables Namespace@>+=
unsigned long long t;
unsigned long dt;
@
\fimcodigo

The first variable obviously shall be initialized as zero.  The second
one shall be initialized with the same value than
macro \monoespaco{W\_TIMESTEP}, which could be defined by the user to
cntrol the granularity of code execution in physics and logic. If this
macro is not defined, we assume 40000 microsecons. This ensures a
frequency of 25 Hz for the execution of physics engine.

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

The code of physics engine and internal logic shall be encapsuled in a
function called \monoespaco{\_update}:

\iniciocodigo
@<Function Declaration (weaver.h)@>+=
void _update(void);
@
\fimcodigo

We won't at this moment define the code in this function:

\iniciocodigo
@<Function Definition (weaver.c)@>+=
void _update(void){
  @<Code to execute every loop@>
}
@
\fimcodigo

With all these definitions, we already can define our macro which
marks the beginning of the main loop:

\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

Notice that the previous macro opens a \monoespaco{while} loop, but
don't close it. It should be closed by the code inserter by our macro
which delimits the end of loop body. This macro also should decrement
the variable \monoespaco{\_lag} to prevent an infinite loop.

\subsecao{3.3. Loop Finalization.}

This is what our macro \monoespaco{LOOP\_END} will do:

First to ensure that the loop from last macro ends, we decrement from
\monoespaco{\_lag} the value of \monoespaco{W.dt}. Next we increment
\monoespaco{W.t} with that ammount of microseconds. And next we end
the block of the loop. Outside the loop we keep doing activities not
related with the physics engine and game logic. As these activities
are tipically about rendering, we put them in a function called 
\monoespaco{\_render}. Next we return. After the return we put a
\monoespaco{goto} to a label which never will be executed to protect us
from compiler warnings. Finally, we put a label signaling the
beginning of finalization.

The only new thing here is the rendering function:

\iniciocodigo
@<Function Declaration (weaver.h)@>+=
void _render(void);
@
\fimcodigo

For now we are not defining the code inside this function:

\iniciocodigo
@<Function Definition (weaver.c)@>+=
void _render(void){
  @<Render Code@>
}
@
\fimcodigo

And now we define the macro code:

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

\subsecao{3.4. Entering in a main loop.}

Frequently we will change which main loop we will execute during the
game execution. But not always this means a complete
substitution. Some main loops runs inside other main loops. For
example, when we enter a configuration menu during the game. Or when
in a classic turn-based japanese RPG we enter in the combat loop after
a random encounter.

We can use a stack of main loops, where when we exit the last main
loop, we enter the next loop in the stack.

So exists two forms of entering a main loop. In one of them, using a
function which we will call \monoespaco{Wloop} and the other with the
second function \monoespaco{Wsubloop}. In the first we substitute one
loop for another, and we can doo this only if there are no pending
files being loaded (in this case, usually we will be in a loading
screen, but not necessarily). We can ensure this using tricks with
macros:

\iniciocodigo
@<Function Declaration (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

The two functions to enter main loops never will return. We specified
this above using both Clang and GCC conventions and also Visual Studio
convention.

We also need a stack of main loops, which will be stored as an array
of pointers for functions. The array will
have \monoespaco{W\_MAX\_SUBLOOP} positions.This macro will be
controlled by the user, but if it is not defined, we will assume
3. The choice is completely arbitrary. Besides the stack, we need a
variable to store the depth of main loop stack:
(\monoespaco{\_number\_of\_loops}).

We declare these variables as:

\iniciocodigo
@<Extern Variables (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
@<Global Variables (weaver.c)@>+=
int _number_of_loops;
void (*_loop_stack[W_MAX_SUBLOOP]) (void);
@
\fimcodigo

And initialize the counting of number of loops as zero:

\iniciocodigo
@<Weaver API: Initialization@>+=
_number_of_loops = 0;
@
\fimcodigo

Entering in a main loop using \monoespaco{Wloop} means verifying if we
are already in a main loop or not. If we are, we cancel the previous
loop. Next, we load he next loop to the stack and adjust the counting
of main loops. We also update our time measuring and finally run the
loop. In Web Assembly running in web browsers, this means calling
directly a function which determines the program main loop. In other
environments, we just run the function in a um \monoespaco{while}:

\iniciocodigo
@<Function Definition (weaver.c)@>+=
void _Wloop(void (*f)(void)){
  if(_number_of_loops > 0){
    @<Cancel Main Loop@>
    @<Memory Adjustment when Canceling Main Loop@>
    _number_of_loops --;
  }
  @<Code Before Loop and Subloop@>
  @<Code before Loop, not Subloop@>
  @<Memory Adjustment Before Loop and 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

But we must remember that if we are running in a Web Assembly
environment in the browser, we need to include the correct header for
this:

\iniciocodigo
@<Include Headers (weaver.h)@>+=
#if defined(__EMSCRIPTEN__)
#include <emscripten.h>
#endif
@
\fimcodigo


Cancelling a main loop involves calling a function if we are running
in Web Assembly environment:

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

Start a new subloop is similar. But we update differently our main
loop counter, as it needs to be incremented. And we also need to check
for stack overflows:

\iniciocodigo
@<Function Definition (weaver.c)@>+=
void Wsubloop(void (*f)(void)){
#if defined(__EMSCRIPTEN__)
    emscripten_cancel_main_loop();
#endif
  @<Code Before Loop and Subloop@>
  @<Code before Subloop, not 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


One necessary update before entering a main loop updating
\monoespaco{\_running\_loop}, variable which tells the game engine
that we should run the current game loop, not exit it. We also update
a variable which stores if we are in the beginning of loop, and so
needs to run initialization code. And also the variable which stores
that we never executed this loop finalization. These are variables
which control the main loop flow. We also update our time measure.

\iniciocodigo
@<Code Before Loop and Subloop@>=
_running_loop = true;
_loop_begin = true;
_loop_finalized = false;
_update_time();
@
\fimcodigo

\subsecao{3.5. Exit from Main Loop.}

As there are two functions to enter in a main loop, there are two
functions to exit. One of them exits the current main loop returning
to the previous in the stack if it exists. The other exits all the
main loops and stops the program.

The function to exit from all main loops was already partially defined
and is the \monoespaco{Wexit} function.

Exit from a main loop involves adjust the global variable which stores
if we should execute the current main loop or exits from it:

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

If you check again the code inserted by macros in main loops, you will
notice that if this variable is false, if there are no pending files
being loaded, then the function \monoespaco{\_exit\_loop} is called.

The code of this function involves cancelling the current main loop
and checking if there is another main loop in the stack. If not, the
program exits.  If exists, we run again the initialization code in
that main loop and start running it:

\iniciocodigo
@<Function Definition (weaver.c)@>+=
void _exit_loop(void){
  if(_number_of_loops <= 1){
    Wexit();
    exit(1); // This line prevents compiler warnings
  }
  else{
    @<Code after Exiting Subloop@>
    _number_of_loops --;
    @<Code Before Loop and 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. Memory Management}

The memory management will use our subsystem with its own allocation
and management functions. One difference between our subsystem and the
traditional memory management with functions \monoespaco{malloc}
and \monoespaco{free} is that here we need to inform the maximum
ammount of memory that we will need.

The maximum numbe of memory used will change according with the
project. A game mede to a video-game console could just use the
maximum quantity of available memory. A project made to run in a PC
could begin in the development with a small quantity and this quantity
could be doubled each time th project grows and require more memory,
until achieving a maximum quantity, where the developers will try to
decrease the memory consumption. The maximum memory in a PC game will
be the expected specifications for target consumer machines when the
game is finished.

We expect that the user will inform the maximum quantity of memory
using the macro \monoespaco{W\_MAX\_MEMORY}
in \monoespaco{conf/conf.h}. If the macro is not defined, we choose
the small value of 4 KiB. This will force the user to specify a more
realistic value after some time, except in the most trivial projects.

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

The maximum quantity of informed memory will be allocated during
initialization and we will return the address to the pointer below:

\iniciocodigo
@<Static Variables (weaver.c)@>=
static void *memory_arena;
@
\fimcodigo

To use the functions in the memory subsystem, we include the header:

\iniciocodigo
@<Local Headers (weaver.c)@>=
#include "memory.h"
@
\fimcodigo

And during the initialization we allocate in our internal memory arena
all the memory that we will need along the project execution:

\iniciocodigo
@<Weaver API: Initialization@>+=
memory_arena = _Wcreate_arena(W_MAX_MEMORY);
@
\fimcodigo

During the finalization we free the allocated memory obtained during
the initialization and any temporary allocation that could still
exist.  We invoke function \monoespaco{\_Wtrash} to do this: free
everything in the left (allocated during initialization) and right
(temporary) memory stack passing respectively argument 0 and 1:

\iniciocodigo
@<Weaver API: Memory: Finalization@>=
_Wtrash(memory_arena, 0);
_Wtrash(memory_arena, 1);
_Wdestroy_arena(memory_arena);
@
\fimcodigo

Before entering in a main loop, we use the
function \monoespaco{\_Wmempoint}. This function saves the state of
our memory so that in the future we can return to this state. Doing
this we can disallocate at once everything that will be allocated
during the main loop.

As saving the state require knowing the memory byte alignment
recommended in our environment. Weaver will get this value from
macro \monoespaco{W\_MEMORY\_ALIGNMENT} that can be defined explicitly
in \monoespaco{conf/conf.h}. If this macro is not defined, we use as
default the size of a \monoespaco{unsigned long} as a guess.

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

Knowing this we can save the state in our memory (the left stack,
where we put the more permanent allocations):

\iniciocodigo
@<Memory Adjustment Before Loop and Subloop@>=
_Wmempoint(memory_arena, W_MEMORY_ALIGNMENT, 0);
@
\fimcodigo

This means that when we exit from this loop, we will restore the
memory state to how it was before entering in the loop in the left
stack:

\iniciocodigo
@<Memory Adjustment when Canceling Main Loop@>=
_Wtrash(memory_arena, 0);
@
\fimcodigo

This basicly willl be the garbage collector in our project. We will
define now a function to the user use our memory allocation. All
permanent user allocations will be done in the left stack using the
default byte alignment:

\iniciocodigo
@<Function Definition (weaver.c)@>+=
static void *_alloc(size_t size){
  return _Walloc(memory_arena, W_MEMORY_ALIGNMENT, 0, size);
}
@
\fimcodigo

For temporary allocations that should not be kept after a single
iteration in our main loop, we can use the following function:

\iniciocodigo
@<Function Definition (weaver.c)@>+=
static void *_talloc(size_t size){
  return _Walloc(memory_arena, W_MEMORY_ALIGNMENT, 1, size);
}
@
\fimcodigo


We will declare a pointer for both functions in struct \monoespaco{W}
and these function will be invoked as \monoespaco{W.alloc()} and
\monoespaco{W.talloc()} respectivelly:

\iniciocodigo
@<Functions Namespace@>=
void *(*alloc)(size_t);
void *(*talloc)(size_t);
@
\fimcodigo

And this function will be ready to be used after the initialization:

\iniciocodigo
@<Weaver API: Initialization@>+=
W.alloc = _alloc;
W.talloc = _talloc;
@
\fimcodigo

Everything allocated with the permanent function will be kept while
the main loop where the allocation happened exist. After the loop
ends, these allocations are automatically disallocated. What is
allocated with the temporary function will be kept only during the
current iteration in the main loop, but will be disallocated after it,
except if we are loading things from files, which requires us to keep
temporary allocation for more time:

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

\secao{5. Random Number Generator}

First we need to insert the header for our pseudo-random number
generation subsystem:

\iniciocodigo
@<Local Headers (weaver.c)@>+=
#include "random.h"
@
\fimcodigo

Next we will declare a ponter to our generator struct:

\iniciocodigo
@<Static Variables (weaver.c)@>+=
static struct _Wrng *rng;
@
\fimcodigo

If the user of this API pass a predefined seed using
macro \monoespaco{W_RNG_SEED}, we will use such seed to initialize the
generator:

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

If a predefined seed does not exist, we will generate a seed uniformly
at random. Our seed will be four random 64-bit numbers. This is
sufficient to ensure the quality for any generator. Instead of using
simpler methods like choosing the current time as a seed, our seed
will be the most random and unpredictable possible. This is expected
to produce better quality results. But to generate seeds in this way,
in some systems we need to use some underlying cryptographic API.

In Linux we can use the syscall \monoespaco{getrandom}. The first
argument for its corresponding C function is the buffer to be filled,
the second is the size in bytes and the third are flags to change the
default behaviour. The function returns the number of random bytes
filled (can be less than asked if the system call is interrupted by a
signal):

\iniciocodigo
@<Weaver API: Initialization@>+=
#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

But this requires that the following header be added:

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

Systems based on BSD, including Mac OS can obtain initial random
values using the function \monoespaco{arc4random\_buf}. The function
already is included in the standard library and never fails:

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

In Windows, secure cryptographic random number generators can be
accessed using the so called ``Cryptography API: Next Generation''
(CNG). To fill our initial seed with impredictable seed we call the
function responsible for generating random numbers in the API. The
first argument is NULL because the last argument is a flag indicating
that the system preferred RNG should be used. Without this flag we
should indicate explicitly the preferred algorithm. The other
arguments are the buffer to be filled and the size.

The documentation do not list all possible failures for the Windows
cryptographic random number generator. Therefore, we cannot be sure if
some error that prevent its usage is temporary (as in the Linux case
where a signal can make the syscall \monoespaco{getrandom} fail) or if
something can cause a permanent error. To prevent infinite loops in
case of error, if we fail at filling the buffer with a random seed
after 16 tries, we give up. But the expected is that this function
succeed in the first try:

\iniciocodigo
@<Weaver API: Initialization@>+=
#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

To use WIndows CNG API we first need to include this header:

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

If we are running a Web Assembly code in a browser environment, to
initialize a seed with unpredictable values, we can run Javascript
code to access the Crypto API in the Browser. We can
use \monoespaco{EM\_ASM\_INT} to run Javascript code and get an
integer (that for Emscripten always have 32 bits). Composing 8 numbers
with 32 bits we get 4 numbers with 64 bits as in the other
environments:

\iniciocodigo
@<Weaver API: Initialization@>+=
#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

If we initialized our random number generation during Weaver
initialization, then we need to finalize it during the
finalization. The code for this is:

\iniciocodigo
@<Weaver API: Finalization@>=
_Wdestroy_rng(NULL, rng);
@
\fimcodigo

Now we need a function to use the random number generator without
needing to pass the generator as an argument. We can build such
function as:

\iniciocodigo
@<Function Definition (weaver.c)@>+=
static uint64_t _rand(void){
  return _Wrand(rng);
}
@
\fimcodigo

To allow usage of this function in our API we declare a pointer to in
in our \monoespaco{W} struct:

\iniciocodigo
@<Functions Namespace@>+=
uint64_t (*rand)(void);
@
\fimcodigo

And the pointer can be invoked after this initialization:

\iniciocodigo
@<Weaver API: Initialization@>+=
W.rand = _rand;
@
\fimcodigo

\secao{6. Creating the Window and Managing User Input}

We manage the window and its input using only the functions from
window subsystem. To use the subsystem, we include its header, which
should also be visible to the user:

\iniciocodigo
@<Include Headers (weaver.h)@>+=
#include "window.h"
@
\fimcodigo

To get a mouse and keyboard struct, necessary to create our window, we
will have pointer for the keyboard and the entire mouse struct
in \monoespaco{W} struct:

\iniciocodigo
@<Variables Namespace@>+=
long *keyboard;
struct _Wmouse mouse;
@
\fimcodigo

The complete keyboard struct will be declared here:

\iniciocodigo
@<Static Variables (weaver.c)@>+=
static struct _Wkeyboard keyboard;
@
\fimcodigo

We initialize the keyboard pointer during initialization, pointing the
keyboard directly to the key array:

\iniciocodigo
@<Weaver API: Initialization@>+=
W.keyboard = keyboard.key;
@
\fimcodigo

We will create our window during the program initialization and close
it during the finalization. We never will create more than one window
in our program.

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

\iniciocodigo
@<Weaver API: Finalization@>+=
_Wdestroy_window();
@
\fimcodigo

We will render in the screen during the rendering step in the main
loop, which means that we will do it as fast as we can:

\iniciocodigo
@<Render Code@>=
_Wrender_window();
@
\fimcodigo

We need to read input in the mouse and keyboard periodically, in each
iteration:

\iniciocodigo
@<Code to execute every loop@>=
_Wget_window_input(W.t, &keyboard, &W.mouse);
@
\fimcodigo

And when we enter in a new loop or subloop, we need to clean all user
input and restart the mouse and keyboard structs:

\iniciocodigo
@<Code Before Loop and Subloop@>+=
_Wflush_window_input(&keyboard, &W.mouse);
@
\fimcodigo

Finally, we should give to the user information about the running
environment. Besides information about mouse and keyboard, which we
already provided, we also will give information about screen
resolution and window size. But there is an important detail: if the
macro \monoespaco{W\_FORCE\_LANDSCAPE} is defined and the window
height is greater than the window width, we swap the horizontal and
vertical values, because we assume that the user will rotate its
screen.

We will use the following global variable to know if our screen is
rotated or not:

\iniciocodigo
@<Static Variables (weaver.c)@>+=
#if defined(W_FORCE_LANDSCAPE)
static bool rotated_screen;
#endif
@
\fimcodigo

And during initialization, we will set the correct values in the
following variables to store the screen resolution and window size:

\iniciocodigo
@<Variables Namespace@>+=
int width, height, resolution_x, resolution_y;
@
\fimcodigo

And here we set the values:

\iniciocodigo
@<Weaver API: Initialization@>+=
_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. User Interface}

To use our user interface API, we include the header:

\iniciocodigo
@<Include Headers (weaver.h)@>+=
#include "interface.h"
@
\fimcodigo

Before initializing our user intrface API, we need to decide what
should be done before and after loading each interface resources (like
their texture). Recall that Weaver API must keep in
variable \monoespaco{W.pending\_files} the number of files and
resources that we are currently loading. Therefore, before loading a
new resource, this variable must be incremented and after loading, it
should be decremented. Doing this is important because ensures that we
will not exit a main loop before loading its resources, which prevents
errors where the loading threads keep writting and loading resources
in memory areas that were already freed and allocated to other game
loop.

As we expect that textures and resources could be loaded by threads,
we need a mutex to ensure that only one thread increment or decrement
the variable. We also want to forbid to have more than one thread
loading resources from files to avoid increasing too much the memory
consumption. For this we will need two mutex variables. We will store
them as static variables:

\iniciocodigo
@<Static Variables (weaver.c)@>+=
STATIC_MUTEX_DECLARATION(pending_files_mutex);
STATIC_MUTEX_DECLARATION(loading_files);
@
\fimcodigo


The mutex is initialized during the initialization:

\iniciocodigo
@<Weaver API: Initialization@>+=
MUTEX_INIT(&pending_files_mutex);
MUTEX_INIT(&loading_files);
@
\fimdodigo

And finalized in the finalization:

\iniciocodigo
@<Weaver API: Finalization@>+=
MUTEX_DESTROY(&pending_files_mutex);
MUTEX_DESTROY(&loading_files);
@
\fimcodigo

With all the mutex, we can then declare a function that runs before
and after each loading.The functions will use the mutex to ensure that
we are counting correctly the loading resources, and that only one
thread will load resources while other threads will just wait. Besides
this, before loading we mark the memory region in the right stack of
our memory manager and after loading everything we clean the temporary
allocated memory after the loading.

\iniciocodigo
@<Function Definition (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


We initialize the API it with:

\iniciocodigo
@<Weaver API: Initialization@>+=
{
  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

In the initialization we inform the user interface API the real size
of our window (not the rotated size if the user is using a mobile
device and is expected to rotate the screen), how the memory should be
allocated, that the API should not try to disallocate memory, and the
two functions above that should be called before and after loading
resources from files.

We finalize the code with:

\iniciocodigo
@<Weaver API: Finalization@>+=
_Wfinish_interface();
@
\fimcodigo

Another necessary thing is that we need to save the list of active
interfaces and piut in a stack in the beginning of each main loop
while marking as non-active all interfaces. When we exit a main loop,
we should restore our list of active interfaces for the last state
saven in the stack and remove it from the stack. Doing this, all
interfaces will have as scope the loop in where it is created and its
allocation and disaloccation will follow the same order and logic than
the main loop ordering.

For this we need to call some adequate functions in the right
places. Before entering a new loop or subloop we save the state of our
interfaces in the stack and mark all them as inactive:

\iniciocodigo
@<Code Before Loop and Subloop@>+=
_Wmark_history_interface();
@
\fimcodigo

And when we cancel the current main loop, we should erase all
interfaces created in that loop and restore the last saved state in
the stack, removing it from the stack:

\iniciocodigo
@<Cancel Main Loop@>+=
_Wrestore_history_interface();
@
\fimcodigo

We can interact with the interfaces using the mouse in each loop of
our physics engine:

\iniciocodigo
@<Code to execute every 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

And in each rendering loop we should render all our visible
interfaces:

\iniciocodigo
@<Render Code@>+=
_Wrender_interface(W.t);
@
\fimcodigo

To render and turn interfaces active, we need first to create
them. The interface API expect that we pass to the function that
creates them a path for the shader source code and for the file with
the texture. Both values can also be \monoespaco{NULL} to use default
shader or texture.

But instead of expecting users to give full file paths, Weaver Engine
expect the user to just give the filename and this file will be taken
from the correct directory. Shader source-codes should be in
the \monoespaco{shader} directory and image files with texture should
be in the \monoespaco{images} directory. Both directories will be
searched on \monoespaco{W\_DATA\_DIR} if this macro is
defined. Otherwise, they are searched on the current directory. This
macro probably will be defined only when the game is being compiled to
be installed.

Therefore, new interfaces will be created by the following function:

\iniciocodigo
@<Function Definition (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

This requires the string header:

\iniciocodigo
@<Local Headers (weaver.c)@>+=
#include <string.h>
@
\fimcodigo

We place this new function in our API namespace:

\iniciocodigo
@<Functions Namespace@>+=
struct user_interface *(*new_interface)(char *, char *, float, float,
                                        float, float, float);
@
\fimcodigo

The other functions from our user interface submodule will be used
exactly as they are defined. Therefore, we just declare them in our
namespace:

\iniciocodigo
@<Functions Namespace@>+=
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

All functions need to be prepared to be used after the initialization:

\iniciocodigo
@<Weaver API: Initialization@>+=
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{Empty Definitions}

The following section and definitions are intentionally blank and are
here to ensure correct compilation of the project. This part won't
exist in the final version of this document and the currently blank
parts after will be written and better explained.

\iniciocodigo
@<Code before Subloop, not Loop@>= @
\fimcodigo

\iniciocodigo
@<Code after Exiting Subloop@>= @
\fimcodigo

\iniciocodigo
@<Code before Loop, not Subloop@>= @
\fimcodigo



\secao{References}

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


\fim