====== libGDX : Viewport i resolucions ======

Referències: [[jocs_libgdx]]

**libGDX és multiplataforma** i podrem compilar el mateix codi per a diferents dispositius. És un gran avantatge però **ens planteja un problema: la resolució de les pantalles pot ser diferent en cada dispositiu**.

De forma nadiua libGDX treballa en píxels, però no ho podem fer així si volem obtenir el mateix resultat en diferents dispositius. Necessitarem unes "coordenades virtuals" i que després es tradueixi a cada plataforma (i dispositiu) adientment.

Per a aquest propòsit disposem de 2 eines fonamentals: ''Viewport'' i ''OrtographicCamera''. En anteriors versions variava una mica la configuració d'aquests objectes. Ara, la ''OrtographicCamera'' ja va dintre del ''Viewport'', i això ens facilita la tasca.

Hi ha diferents [[https://libgdx.com/wiki/graphics/viewports|tipus de Viewports]]. Farem l'exemple bàsic amb ''FitViewport'', que manté la relació d'aspecte entre els diferents dispositius omplint amb fons negre les parts que excedeixin per tal d'acomplir aquesta relació d'aspecte.

\\

===== Configuració Viewport bàsica =====

El codi mínim que ens quedaria per a una aplicació amb ''FitViewport'' seria la següent, amb una configuració d'aspecte de 8x5 unitats d'amplada per alçada. Aquestes "unitats" les podríem considerar "metres", però és una "resolució virtual" que ens convé a nosaltres. En altres ocasions podrien ser kilòmetres, per exemple si mostréssim un mapa.

Al ser unitats divisibles caldrà emprar //floats//, i no //integers// com es podria fer servir pels píxels.

<file java Joc.java>
// Exemple amb ApplicationAdapter, però podria ser una Screen
public class Joc extends ApplicationAdapter {
    private SpriteBatch batch;
    public FitViewport viewport;

    @Override
    public void create() {
        batch = new SpriteBatch();
        viewport = new FitViewport(8, 5); // 8x5 unitats (amplada x alçada)
    }

    @Override
    public void render() {
        // pintem background de color
        ScreenUtils.clear(0.15f, 0.15f, 0.2f, 1f);
        
        // PUNT CLAU: ajustem càmera per traduir resolucions quan pintem
        viewport.apply();
        batch.setProjectionMatrix(viewport.getCamera().combined);
        
        // pintem!
        batch.begin();
        // ...instruccions de dibuix amb "coordenades virtuals"...
        batch.end();
    }

    // SUPER IMPORTANT, sense resize no funciona el Viewport
    // és un error típic oblidar aquest mètode, esteu avisats
    @Override
    public void resize(int width, int height) {
        viewport.update(width, height, true);
    }

    @Override
    public void dispose() {
        batch.dispose();
    }
}
</file>

==== Desktop ====

Si volem que la pantalla de l'aplicació Desktop coincideixi amb la relació d'aspecte definit al joc, convindrà redefinir-la a l'arxiu ''Lwjgl3Launcher.java'':

<file java Lwjgl3Launcher.java>
public class Lwjgl3Launcher {
    // ...
    private static Lwjgl3ApplicationConfiguration getDefaultConfiguration() {
        // ...
        
        // configurem 800x500 px però podria ser altra resolució que compleixi amb la relació d'aspecte
        configuration.setWindowedMode(800, 500);
        // ...
    }
}
</file>

\\

===== Dibuixem! =====

Definicions:
  * ''SpriteBatch'': "pinzell" que dibuixa sobre la pantalla.
  * ''Texture'': imatge.
  * ''TextureRegion'': imatge retallada.
  * ''Sprite'': objecte que conté la ''Texture'' i les coordenades per renderitzar.

Dibuixarem un cercle a la posició (2,2) de les nostres "coordenades virtuals". Ho farà el ''batch'' a cada iteració a la funció ''render()''.

El ''batch'' necessitarà una ''Texture'' per poder renderitzar la forma dibuixada. La podem crear així:

<code java>
public class Joc extends ApplicationAdapter {
    // ...
    
    // Texture és l'objecte adequat per a pintar al batch
    // es pot crear a partir d'imatges o de formes dibuixades
    Texture pilotaTexture;

    @Override
    public void create() {
        // ...
        
        // Creem la Texture de la pilota (format en pixels! , de moment)
        Pixmap pilotaPixmap = new Pixmap(100,100,Pixmap.Format.RGBA8888);
        pilotaPixmap.setColor(Color.RED);
        pilotaPixmap.fillCircle(50,50,50); // posx, posy, radi
        pilotaTexture = new Texture(pilotaPixmap);
    }
    
    public void render() {
        // ... background, projection matrix, etc.
        
        // pintem!
        batch.begin();
        // Tant fa l'amplada i alçada en píxels que tingui la Texture
        // A pintar la redefinim (textura, posx, posy, amplada, alçada)
        batch.draw(pilotaTexture,2f,2f,1f,1f);
        batch.end();
    }

    // ...
}
</code>

\\

===== Movem l'objecte =====

Per moure l'objecte haurem de definir les posicions x i y, i també la velocitat a la que volem moure l'objecte.

Recordem que el loop típic dels jocs consisteix en:
  - Inputs: processar controls de l'usuari (joystick, tecles, etc.)
  - Calcular objectes
  - Pintar objectes

<code java>
public class Joc extends ApplicationAdapter {
    // ...

    // les dades mínimes son posició i velocitat de la pilota
    float posx, posy, velx, vely;

    @Override
    public void create() {
        // ...

        posx = posy = 0f;
        velx = vely = 1f; // velocitat d'1 m/s
    }

    @Override
    public void render() {
        // 1- INPUTS (controls usuari)...

        // 2- CALCULEM
        // primera prova: increment 0.01mts per iteració
        posx = posx + 0.01;

        // 3- PINTEM
        // projecció viewport, background, etc...
        batch.begin();
        batch.draw(pilotaTexture,posx,posy,1f,1f); // tamany pilota = 1x1
        batch.end();
    }

}
</code>

Si proves el codi veuràs que la pilota avança poc a poc.

Però no hem fet servir la velocitat real ''velx''. Prova de canviar el 0.01 per ''velx'':
<code java>
posx = posx + velx;
</code>

Què succeeix?

Si ho feu així veureu que la pilota no avança a 1 m/s, sinó que avança 1 metre per iteració. I els ajustos habituals solen ser de 30 FPS, per tant, la velocitat que ara estem executant és de 30 m/s, segurament ni l'heu vist passar !!!

Perquè la pilota avanci a 1 m/s de veritat (hauria de trigar 8 segons en travessar la pantalla) hauríem de fer el següent:

<code java>
    public void render() {
        // 1- INPUTS (controls usuari)...

        // 2- CALCULEM
        float delta = Gdx.graphics.getDeltaTime();
        posx = posx + velx * delta;
        
        // ...
    }
</code>

<WRAP info>
**En termes físics**

En termes de física, les sumes han de ser de la mateixa magnitud, és a dir, a la posició x [metres] no podem sumar-li una velocitat [m/s], sinó que cal sumar-li un desplaçament també en [metres].

  posx = posx + velx;

{{mdi>close-circle?color=red&size=22}} <del>[m] + [m/s]</del>

Quant és el desplaçament que cal aplicar-li a posx? Doncs dependrà del temps que hagi passat. Podriem calcular-ho en base als FPS, però tenim una manera millor encara, demanar-li a libGDX que ens digui el temps que ha passat des del darrer ''render()''. Això ho fem amb la instrucció:<code>
float delta = Gdx.graphics.getDeltaTime();
</code>

Ara podrem calcular el desplaçament:
  posx = posx + velx * delta;

Que en magnituds serà:

{{mdi>check-circle?color=green&size=22}} posx[m] + velx[m/s] * delta[s]  =>  [m] + [m/s] * [s] = [m]

Ara sí!
</WRAP>

\\

===== Rebots =====

Per poder fer rebotar la pilota a les parets, caldrà tenir descomposta la velocitat en les components X i Y : ''posx'' i ''posy''. Per fer els rebots:
  * Canviem el signe (multiplicar per -1) de ''velx'' quan arribem als extrems laterals.
  * Canviem el signe (multiplicar per -1) de ''vely'' quan arribem al "sostre" o el "terra".

ULL: aquest gràfic té la coordenada Y invertida (moltes interfícies gràfiques tenen l'origen (0,0) a l'extrem superior esquerra, però libGDX ho té a l'extrem inferior esquerre):

{{Pilota-rebots.png}}


<WRAP todo>
Fes els següents exercicis:
  - Actualitza també el valor de ''vely'' perquè la pilota es mogui per tota la pantalla.
  - Implementa els rebots: introdueix codi per controlar els límits i inverteix el signe de les velocitats x i y com s'ha explicat.
  - Rebota bé en els límits? Fes els ajustos adequats perquè reboti de forma correcta.

Potser t'interessarà saber que l'objecte ''Viewport'' té diversos mètodes per conèixer la resolució real de la pantalla i altre dades, en particular les que ens interessen per saber l'amplada i alçada de la pantalla en termes de "coordenades virtuals":
  viewport.getWorldWidth()
  viewport.getWorldHeight()

</WRAP>