Utilisation

Dans ce chapitre, nous allons voir comment créer un nouveau projet en utilisant cette librairie. Ceci suppose toutefois que vous vous êtes déjà un peu familiarisé avec le PSPSDK (utilisation basique de cygwin et compilation d'un projet simple). Je sais bien qu'il est plutôt ennuyeux à utiliser lorsqu'on est habitué à la simplicité de Windows, mais une fois que vous l'aurez pris en main, tout ira mieux ;-)

Tout d'abord, créez un nouveau répertoire, qui contiendra les fichiers de votre projet. Dans ce répertoire, nous allons créer un makefile (c'est un fichier texte qui décrit votre projet, de manière à savoir quel compilateur appeler, quels fichiers compiler, quelles librairies utiliser, quel fichier produire au final, etc.).

Le Makefile est donc un fichier qui s'appelle Makefile (sans extension). Voici un exemple du texte qu'il pourrait contenir (utilisez ceci pour débuter):

TARGET = test
OBJS = test.o
YOURLIBS=

INCDIR =
CFLAGS = -G4 -Wall -O2
CXXFLAGS = $(CFLAGS) -fno-exceptions -fno-rtti
ASFLAGS = $(CFLAGS)

LIBDIR =
LDFLAGS =
STDLIBS= -losl -lpng -lz \
		-lpspsdk -lpspctrl -lpspumd -lpsprtc -lpsppower -lpspgu -lpspaudiolib -lpspaudio -lm
LIBS=$(STDLIBS)$(YOURLIBS)

EXTRA_TARGETS = EBOOT.PBP
PSP_EBOOT_TITLE = OSL Sample

PSPSDK=$(shell psp-config --pspsdk-path)
include $(PSPSDK)/lib/build.mak

Passons en revue les sections qui constituent ce fichier. Tout d'abord il y a la ligne TARGET = test. C'est en réalité le nom de notre projet. Ensuite, il y a OBJS = test.o. Ceci indique les fichiers objets à produire, c'est-à-dire simplement les fichiers à compiler. Les fichiers à produire ont l'extension .o (c'est le résultat de la compilation des fichiers .c ou .cpp), c'est pourquoi j'ai mis test.o et non test.c.
La ligne YOURLIBS= permet de définir ses propres librairies à ajouter au projet. PSP_EBOOT_TITLE est le nom qui apparaîtra au menu de sélection des jeux de la PSP. Pour les autres lignes, vous n'avez pas besoin de les toucher, sauf si vous voulez utiliser une autre librairie (dans ce cas-là, référez-vous à la documentation de la librairie en question).

Si vous voulez simplement ajouter OSLib à un projet qui existe déjà, il suffit d'ajouter -losl à vos librairies, toutefois vous devez vous assurer que toutes les librairies système dont OSLib dépend sont incluses, et placées dans cet ordre (sinon vous aurez des erreurs):

-losl -lpng -lz -lpspsdk -lpspctrl -lpspumd -lpsprtc -lpspgu -lpspaudiolib -lpspaudio -lm

Pour compiler le projet, démarrez cygwin, déplacez-vous dans le répertoire en question et tapez "make". Pour toute information complémentaire, voyez la documentation officielle sur les makefiles.

Prêt à coder?

Maintenant que la librairie est correctement incluse à votre projet, vous devriez pouvoir l'utiliser sans problème. Voyons d'abord le squelette d'un projet créé avec OSLib.

#include <oslib/oslib.h>

PSP_MODULE_INFO("Module name", 0, 1, 1);
PSP_MAIN_THREAD_ATTR(THREAD_ATTR_USER | THREAD_ATTR_VFPU);

int main(int argc, char* argv[])
{
	//Initialise les différentes parties de la librairie
	oslInit(0);
	oslInitGfx(OSL_PF_8888, 1);
	oslInitConsole();
	
	//Boucle principale
	while (!osl_quit)
	{
		//Code d'affichage
		oslStartDrawing();
		//Ecran rouge
		oslClearScreen(RGB(255,0,0));
		//Fin de l'affichage
		oslEndDrawing();
		//Synchronisation
		oslSyncFrame();
	}

	//Terminé
	oslEndGfx();
	oslQuit();
	return 0;
}

Si vous êtes expérimenté, vous pouvez modifier les lignes PSP_MODULE_INFO et PSP_MAIN_THREAD_ATTR, mais les attributs THREAD_ATTR_USER et THREAD_ATTR_VFPU doivent toujours être présents dans les attributs du thread. Si vous débutez, n'y touchez pas, sachez juste qu'elles sont requises par le PSPSDK (donc rien à voir avec OSLib).
Notez également que OSLib vous fait grâce de l'initialisation des callbacks, pour autant que la valeur 0 est passée à oslInit. Si vous voulez utiliser vos propres callbacks (si vous ne savez pas ce que c'est, n'y touchez pas, évidemment), passez 1.

Utilisation générale

Tout d'abord, il faut initialiser la librairie. Les différentes parties de la librairie (comme le son, les graphiques, etc.) sont initialisées séparément histoire de pouvoir limiter au maximum les ressources inutiles. Mais avant d'initialiser les parties, il faut initialiser la librairie elle-même. C'est réalisé par un appel à oslInit, à laquelle vous passez zéro par défaut.

void oslInit(int useOwnCallbacks);

Ensuite, vous pouvez initialiser la partie graphique, en spécifiant quelle pixelformat vous utilisez pour l'écran, ainsi que si vous souhaitez utiliser le double buffering. Nous verrons plus tard ce que sont les pixelFormats, pour le moment passez simplement OSL_PF_8888 pour du 32 bits, OSL_PF_5650 pour du 16 bits comme premier argument.

void oslInitGfx(int pixelFormat, int bDoubleBuffer);

Le double buffering permet d'avoir deux écrans, l'un sur lequel vous dessinez et l'autre qui est celui affiché à l'écran. Vous dessinez sur un écran pendant que l'autre est affiché, ainsi l'utilisateur ne verra rien jusqu'à ce que vous échangez les écrans, ainsi il a directement l'écran tout fait, et pas de clignotement qui arrive si vous effacez l'écran et redessinez tout par dessus. Le changement des buffers se fait avec la fonction oslSwapBuffers, ou simplement oslSyncFrame qui attend également la VSync et s'occupe du frameskip.

Important: l'appel à oslInitGfx réinitialise le système graphique, et toutes les images en VRAM seront également réinitialisées par la même occasion!

Il reste à initialiser la console, pour pouvoir dessiner du texte (la fonte standard est chargée à ce moment-là). Pour cela, appelez simplement:

void oslInitConsole();

Finalement, pour initialiser le système audio:

void oslInitAudio();

Mais on verra cela plus tard.

Pour commencer à dessiner, quelque chose d'important est qu'il faut appeler oslStartDrawing(), et oslEndDrawing() lorsque vous avez fini, comme dans l'exemple plus haut. Si vous tentez de dessiner sans avoir appelé oslStartDrawing, cela ne fonctionnera pas. Pour le reste, c'est relativement simple, suivez les pages suivantes du guide et c'est parti!