Dr.Vince
11/09/2006, 12h24
GBFS: Le tutoriel
Auteur: xFlash
I-Introduction
-Qu'est-ce-que GBFS?
GBFS est un système d'accès a des fichiers sur votre Gameboy. En effet la GBA ne possède pas de FileSystem(FS) et on n'accède à la mémoire de nos cartouches que sous la forme d'un énorme bloc mémoire accessible depuis 0x08000000h
-Pourquoi utiliser un système de fichiers?
Utiliser un tel système possède plein d'avantages dans le developemment sur GBA. Cela evites les transformations ou convertions de bon nombre des ressources (gfx/sfx/map/dialogue/...) necessaires au projet, car on les inclut directement, tel quel, sans changement. Adieu les bin2h, bin2obj ,...
Cela implique aussi des gains de temps dans les phases de compilation, car on evite les conversions/transformations de ses ressources lorsqu'on les modifie.
-Qui a écrit GBFS?
L'auteur de GBFS est Damian Yerrick-
Site internet : PinEight[ (http://www.pineight.com/gba/)
-Ou peut-on récupérer ces outils?
Ici : http://www.pineight.com/gba/gbfs.zip
ou ici : Mirroir PA (http://ouaper2k.free.fr/PAtuto/GBA/gbfs.zip)
II-Comment ca marche?
Chaque fichier de données que vous désirez inclure à votre ROM est ajouté à la fin de votre ROM compilé. On accède à ces fichiers à l'aide de fonctions C présentes dans l'API de Damian.
Si on regrade en detail le resultat d'une ROM dans lequel est inclus GBFS et 2 fichiers par exemple, l'on obtiendrait ceci :
http://ouaper2k.free.fr/PAtuto/GBA/gbfs.png
La "ROM compilé" est le resultat produit le linker d'un compilo, le fichier .bin ou .gba de votre projet.
Le "Header GBFS" est un fichier produit par l'outil (GBFS.exe fournit dans l'archive) qui decrit les entrées, noms et tailles de chaque fichiers inclus
Les Fichiers "TXT01.DLG" et "TXT02.DLG" sont les fichiers de ressources désirés
III-Comment l'inclure dans mon projet?
- Exemple
Imaginons que tel l'exemple précédent, vous ayez besoin d'inclure des fichiers de dialogues à longueur évidemment variable dans le temps et pour lequels, vous voulez y accéder depuis votre code.
Attention ceci est une exemple, vous pourrez tout aussi bien le faire avec des fichiers d'images, sons, map, etc.
- Procédure
Il faut ordonner a Make, plusieurs operations supplementaires :
Generer le fichier .GBFS(le Header GBFS precedemment decrit + les fichiers désirés)
Aligner la ROM a un pas de 256
Inclure les fichiers de ressources
Que vous utilisez HAM ou non, la procedure est la meme. Je partirais d'un makefile issu d'un projet de HAM, car je vous sais nombreux à l'utiliser. Pour les autres, vous connaissez certainement très bien votre makefile et son langage, donc la modif ne devrait pas vous poser de soucis.
- Les modifications du makefile
Dans votre makefile, vous aviez avant une entrée du style:
all : $(PROGNAME).$(EXT)
Avec GBFS, Make ne doit pas s'arréter une fois la cible $(PROGNAME).$(EXT) générée.
Aussi on éditera le makefile ainsi:
OFILES += $(GBFS_HOME)\libgbfs.o
INCDIR += $(GBFS_HOME)
DAT_FILES = dlg\TXT02.DLG dlg\TXT02.DLG
$(PROGNAME).gbfs:
@$(GBFS_HOME)\tools\gbfs.exe $(PROGNAME).gbfs $(DAT_FILES)
$(PROGNAME)_GBFS.$(EXT): $(PROGNAME).$(EXT) $(PROGNAME).gbfs
@$(GBFS_HOME)\tools\padbin 256 $(PROGNAME).$(EXT)
@copy /b $(PROGNAME).$(EXT)+$(PROGNAME).gbfs $(PROGNAME)_GBFS.$(EXT)
all : $(PROGNAME)_GBFS.$(EXT)
Vous remarquerez plusieurs choses:
- GBFS_HOME est une variable d'environnement contenant le chemin d'acces à votre distribution de GBFS décompressé.
- On rajoutes aux aobjet a compiler et a linker la librairie de gbfs
- GBFS.exe est l'outil qui vous générera un fichier .gbfs dans le repertoir de votre projet contenant une entete GBFS et les 2 fichiers de datas désirés. C'est ce qui est encadré en gris dans mon exemple plus haut.
- PADBIN.exe est un outil permettant d'aligner votre ROM a une valeur multiple de 2. Ils remplit le trou restant avec des 00. Ceci etant necessaire car le code de GBFS scanne la ROM de manière optimale avec une plage a 256. Explication de l'auteur :
Note that this does a slow linear search at 256-byte strides, so make sure that your files are aligned to 256-byte boundaries and that you pass a start location close to (but not past) the beginning of the GBFS file.
De plus cette operation peut etre faite avec d'autres outils. Personnellement j'utilise GBAFIX de DarkFader permettant en plus de fixer le nom de la ROM dans la meme operation.
- La copie binaire concatène simplement la ROM et le fichier GBFS ensemble dans un nouveau fichier
- Ne pas oublier d'inclure
- Utilisation de GBFS dans le code
Une fois dans votre code, l'utilisation de GBFS est assez simple. La complexité réside plus dans ce que vous allez faire de la ressource incluse, ex: Décompression, lecture de BMP/JPG, ...
Aussi voici un exemple de ce que vous pouvez faire avec l'exe^mple precedent.
#include <gbfs.h>
#define GBFS_ENTRY_NAME_LGMAX 24
/**
Variables globales
**/
//pointeurs sur données de texte
static const char* pTxt1 = NULL;
static const char* pTxt2 = NULL;
//pointeur sur la premiere structure GBFS trouvée
static GBFS_FILE* pGBFSFile=NULL;
int main()
{
/**
Variables locales
**/
u32 uFileSize, uNbFiles;
char pFileName[GBFS_ENTRY_NAME_LGMAX];
//init
uFileSize = 0;
//on recupere un pointeur sur la structure GBFS cherchée
pGBFSFile = find_first_gbfs_file(find_first_gbfs_file);
//Attention:
// la subtilité ici est d'indiquer a GBFS de commencer sa recherche de la structure
// GBFS ajoutée à la ROM au plus proche de la ou elle pourrait etre.
// on pourrait tout a fait remplacer la ligne par :
// pGBFSFile = find_first_gbfs_file(0);
// auquel cas, GBFS commencerait a chercher depuis le debut de la Memoire
// ce qui pourrait etre très très lent...
// aussi on lui donne l'adresse de la fonction find_first_gbfs_file qui en memoire
// est l'une des derniere ajoutées a la ROM compilé donc une bonne estimation du
// plus proche endroit de la structure recherchée...
//on peut recuperer le nombre de fichiers presents
uNbFiles = gbfs_count_objs(pGBFSFile);
//recuperation pointeur sur le premier fichier par son nom
pTxt1 = gbfs_get_obj(pGBFSFile, "TXT01.DLG", &uFileSize);
// on peut recuperer le 2eme fichier par son ordre dans la structure
pTxt2 = gbfs_get_nth_obj(pGBFSFile, 1, pFileName, &uFileSize);
//On peut a partir de la manipuler les données de notre fichier comme on le désire
//...
return 0;
}
IV-Autres choses?
Ne pas oubliez avec GBFS:
Le padding de la ROM a 256
Inclure libgfs.o en tout dernier lieu dans la chaine du linker
Les sources de GBFS sont fournies!! N'hesitez pas a y jeter un oeil. C'est assez instructif
Remercier l'auteur Damian Yerrick
Poser des questions ici, si vous avez des doutes.
Auteur: xFlash
I-Introduction
-Qu'est-ce-que GBFS?
GBFS est un système d'accès a des fichiers sur votre Gameboy. En effet la GBA ne possède pas de FileSystem(FS) et on n'accède à la mémoire de nos cartouches que sous la forme d'un énorme bloc mémoire accessible depuis 0x08000000h
-Pourquoi utiliser un système de fichiers?
Utiliser un tel système possède plein d'avantages dans le developemment sur GBA. Cela evites les transformations ou convertions de bon nombre des ressources (gfx/sfx/map/dialogue/...) necessaires au projet, car on les inclut directement, tel quel, sans changement. Adieu les bin2h, bin2obj ,...
Cela implique aussi des gains de temps dans les phases de compilation, car on evite les conversions/transformations de ses ressources lorsqu'on les modifie.
-Qui a écrit GBFS?
L'auteur de GBFS est Damian Yerrick-
Site internet : PinEight[ (http://www.pineight.com/gba/)
-Ou peut-on récupérer ces outils?
Ici : http://www.pineight.com/gba/gbfs.zip
ou ici : Mirroir PA (http://ouaper2k.free.fr/PAtuto/GBA/gbfs.zip)
II-Comment ca marche?
Chaque fichier de données que vous désirez inclure à votre ROM est ajouté à la fin de votre ROM compilé. On accède à ces fichiers à l'aide de fonctions C présentes dans l'API de Damian.
Si on regrade en detail le resultat d'une ROM dans lequel est inclus GBFS et 2 fichiers par exemple, l'on obtiendrait ceci :
http://ouaper2k.free.fr/PAtuto/GBA/gbfs.png
La "ROM compilé" est le resultat produit le linker d'un compilo, le fichier .bin ou .gba de votre projet.
Le "Header GBFS" est un fichier produit par l'outil (GBFS.exe fournit dans l'archive) qui decrit les entrées, noms et tailles de chaque fichiers inclus
Les Fichiers "TXT01.DLG" et "TXT02.DLG" sont les fichiers de ressources désirés
III-Comment l'inclure dans mon projet?
- Exemple
Imaginons que tel l'exemple précédent, vous ayez besoin d'inclure des fichiers de dialogues à longueur évidemment variable dans le temps et pour lequels, vous voulez y accéder depuis votre code.
Attention ceci est une exemple, vous pourrez tout aussi bien le faire avec des fichiers d'images, sons, map, etc.
- Procédure
Il faut ordonner a Make, plusieurs operations supplementaires :
Generer le fichier .GBFS(le Header GBFS precedemment decrit + les fichiers désirés)
Aligner la ROM a un pas de 256
Inclure les fichiers de ressources
Que vous utilisez HAM ou non, la procedure est la meme. Je partirais d'un makefile issu d'un projet de HAM, car je vous sais nombreux à l'utiliser. Pour les autres, vous connaissez certainement très bien votre makefile et son langage, donc la modif ne devrait pas vous poser de soucis.
- Les modifications du makefile
Dans votre makefile, vous aviez avant une entrée du style:
all : $(PROGNAME).$(EXT)
Avec GBFS, Make ne doit pas s'arréter une fois la cible $(PROGNAME).$(EXT) générée.
Aussi on éditera le makefile ainsi:
OFILES += $(GBFS_HOME)\libgbfs.o
INCDIR += $(GBFS_HOME)
DAT_FILES = dlg\TXT02.DLG dlg\TXT02.DLG
$(PROGNAME).gbfs:
@$(GBFS_HOME)\tools\gbfs.exe $(PROGNAME).gbfs $(DAT_FILES)
$(PROGNAME)_GBFS.$(EXT): $(PROGNAME).$(EXT) $(PROGNAME).gbfs
@$(GBFS_HOME)\tools\padbin 256 $(PROGNAME).$(EXT)
@copy /b $(PROGNAME).$(EXT)+$(PROGNAME).gbfs $(PROGNAME)_GBFS.$(EXT)
all : $(PROGNAME)_GBFS.$(EXT)
Vous remarquerez plusieurs choses:
- GBFS_HOME est une variable d'environnement contenant le chemin d'acces à votre distribution de GBFS décompressé.
- On rajoutes aux aobjet a compiler et a linker la librairie de gbfs
- GBFS.exe est l'outil qui vous générera un fichier .gbfs dans le repertoir de votre projet contenant une entete GBFS et les 2 fichiers de datas désirés. C'est ce qui est encadré en gris dans mon exemple plus haut.
- PADBIN.exe est un outil permettant d'aligner votre ROM a une valeur multiple de 2. Ils remplit le trou restant avec des 00. Ceci etant necessaire car le code de GBFS scanne la ROM de manière optimale avec une plage a 256. Explication de l'auteur :
Note that this does a slow linear search at 256-byte strides, so make sure that your files are aligned to 256-byte boundaries and that you pass a start location close to (but not past) the beginning of the GBFS file.
De plus cette operation peut etre faite avec d'autres outils. Personnellement j'utilise GBAFIX de DarkFader permettant en plus de fixer le nom de la ROM dans la meme operation.
- La copie binaire concatène simplement la ROM et le fichier GBFS ensemble dans un nouveau fichier
- Ne pas oublier d'inclure
- Utilisation de GBFS dans le code
Une fois dans votre code, l'utilisation de GBFS est assez simple. La complexité réside plus dans ce que vous allez faire de la ressource incluse, ex: Décompression, lecture de BMP/JPG, ...
Aussi voici un exemple de ce que vous pouvez faire avec l'exe^mple precedent.
#include <gbfs.h>
#define GBFS_ENTRY_NAME_LGMAX 24
/**
Variables globales
**/
//pointeurs sur données de texte
static const char* pTxt1 = NULL;
static const char* pTxt2 = NULL;
//pointeur sur la premiere structure GBFS trouvée
static GBFS_FILE* pGBFSFile=NULL;
int main()
{
/**
Variables locales
**/
u32 uFileSize, uNbFiles;
char pFileName[GBFS_ENTRY_NAME_LGMAX];
//init
uFileSize = 0;
//on recupere un pointeur sur la structure GBFS cherchée
pGBFSFile = find_first_gbfs_file(find_first_gbfs_file);
//Attention:
// la subtilité ici est d'indiquer a GBFS de commencer sa recherche de la structure
// GBFS ajoutée à la ROM au plus proche de la ou elle pourrait etre.
// on pourrait tout a fait remplacer la ligne par :
// pGBFSFile = find_first_gbfs_file(0);
// auquel cas, GBFS commencerait a chercher depuis le debut de la Memoire
// ce qui pourrait etre très très lent...
// aussi on lui donne l'adresse de la fonction find_first_gbfs_file qui en memoire
// est l'une des derniere ajoutées a la ROM compilé donc une bonne estimation du
// plus proche endroit de la structure recherchée...
//on peut recuperer le nombre de fichiers presents
uNbFiles = gbfs_count_objs(pGBFSFile);
//recuperation pointeur sur le premier fichier par son nom
pTxt1 = gbfs_get_obj(pGBFSFile, "TXT01.DLG", &uFileSize);
// on peut recuperer le 2eme fichier par son ordre dans la structure
pTxt2 = gbfs_get_nth_obj(pGBFSFile, 1, pFileName, &uFileSize);
//On peut a partir de la manipuler les données de notre fichier comme on le désire
//...
return 0;
}
IV-Autres choses?
Ne pas oubliez avec GBFS:
Le padding de la ROM a 256
Inclure libgfs.o en tout dernier lieu dans la chaine du linker
Les sources de GBFS sont fournies!! N'hesitez pas a y jeter un oeil. C'est assez instructif
Remercier l'auteur Damian Yerrick
Poser des questions ici, si vous avez des doutes.