Documentation de la bibliothèque libBMP 1.0

Présentation de libBMP

Une histoire de bitmaps

La bibliothèque libBMP a été créer pour permettre facilement la manipulation des fichiers bitmap simples (.bmp). Elle permet par exemple :

De charger des fichiers bitmaps dans la mémoire ;
De les afficher et modifier ;
De les transformer en sprites classiques ;
De les exporter en fichier .bmp dans le système de fichiers.

Avantages et inconvénients

Les sprites classiques, stockés dans des tableaux d'unsigned char fonctionne parfaitement, mais ont pour défaut d'encombrer le code, et la mémoire de la machine s'ils sont déclarés en variables globales. Les fichiers bitmaps externes n'ont pas cet inconvénient. En revanche, ils ont un header de minimum 62 octets, c'est pourquoi il est déconseillé de les utiliser pour de petits sprites et plutôt de stocker directement des tilesets.

Utiliser libBMP

Pour utiliser libBMP, il vous suffit d'en télécharger les sources (que vous avez normalement déjà) ici et d'extraire le code source et le fichier d'en-tête dans les données de votre projet. Ensuite, il vous suffit d'ajouter le fichier source LibBMP.c à votre projet en passant par la fenêtre Files in project du SDK et à inclure le fichier d'en-tête LibBMP.h au début de tous les fichiers de code qui utilisent libBMP.

Liste des fonctions

L'objet `Bitmap`

struct Bitmap
{
  int width, height;
  int depth;
  unsigned char *data;
}

WIDTH	Représente la largeur en pixels du bitmap.
HEIGHT	Représente la hauteur en pixels du bitmap.
DEPTH	Indique le nombre de bits utilisés pour coder une couleur du bitmap.
DATA	Contient les données brutes du bitmap. Celles-ci sont différentes de sprites classiques.

Manipulation de l'objet `Bitmap`

Bitmap *BMP_Load(const char *adresse, int *err);// Prototype
Bitmap *monBitmap = BMP_Load(~~"\\\\fls0\\BITMAP.bmp"~~, NULL);// Exemple

DESCRIPTION	Charge le fichier bitmap à l'adresse adresse. L'extension est libre. S'il se produit une erreur, un code d'erreur standard sera affecté à l'adresse err si la paramètre est non nul.
RETOUR	Retourne un pointeur de type `Bitmap` alloué dynamiquement contenant les données du bitmap si le chargement a réussi, un pointeur `NULL` sinon.
DEPENDANCES	`malloc()`, `calloc()`, `sizeof()`, `free()`, `Bfile_OpenFile(), Bfile_ReadFile(), Bfile_CloseFile()`
NOTA BENE	N'oubliez pas de libérer le pointeur après utilisation.

void *BMP_Draw(Bitmap *bmp, int xb, int yb, int m);// Prototype
BMP_Draw(monBitmap, 84, 34, BMP_OR);// Exemple

DESCRIPTION	Dessine le bitmap bmp aux coordonnées (`xb`;`yb`) dans le mode de dessin m. Le mode peut prendre trois valeurs différentes : `BMP_AND`, `BMP_OR` ou `BMP_XOR`.
RETOUR	Ne retourne rien.
DEPENDANCES	`Bdisp_SetPoint_VRAM()`

int BMP_GetPixel(Bitmap *bmp, int x, int y);// Prototype
int x = BMP_GetPixel(monBitmap, 0, 0);// Exemple

DESCRIPTION	Renvoie la couleur du pixel du bitmap bmp aux coordonées (x;y).
RETOUR	Retourne `0` si le pixel est blanc, `1` s'il est noir.

void BMP_SetPixel(Bitmap *bmp, int x, int y, int v);// Prototype
BMP_SetPixel(monBitmap, 10, 12, 0);// Exemple

DESCRIPTION	Affecte la couleur v au pixel aux coordonnées (x;y) du bitmap bmp.
RETOUR	Ne retourne rien.

Avec les sprites classiques

void *BMP_GetData(Bitmap *bmp, int *err);// Prototype
void *sprite = BMP_GetData(monBitmap, NULL);// Exemple

DESCRIPTION	Retourne les données du bitmap bmp sous une forme classique, lisible par exemple par Monochrome Lib. Un code d'erreur standard est écrit à l'adresse err si celle-ci est non nulle.
RETOUR	Retourne le pointeur alloué sur les données si l'opération a réussi, `NULL` sinon.
DEPENDANCES	`malloc()`

Bitmap *BMP_Create(void *data, int w, int h, int *err);// Prototype
Bitmap *monSprite = BMP_Create(unSprite, 16, 16, NULL);// Exemple

DESCRIPTION	Crée un Bitmap monochrome à partir d'un sprite classique data et de ses largeur et hauteur w et h. Un code d'erreur standard est écrit à l'adresse err si celle-ci est non nulle.
RETOUR	Retourne un pointeur sur le nouveau bitmap si l'opération a réussi, NULL sinon.
DEPENDANCES	`malloc()`
NOTA BENE	N'oubliez pas de libérer le pointeur avec `free()` après utilisation pour éviter les fuites de mémoire.

void BMP_Save(const char *adresse, Bitmap *bmp, int *err);// Prototype
BMP_Save(~~"\\\\fls0\\SPRITE.bmp"~~, monSprite, NULL);// Exemple

DESCRIPTION	Crée un fichier bitmap `.bmp` à l'adresse adresse à partir de la structure bmp. Un code d'erreur standard est écrit à l'adresse err si celle-ci est non nulle.
RETOUR	Ne retourne rien.
DEPENDANCES	`calloc()`, `free()`, `Bfile_DeleteFile()`, `Bfile_CreateFile()`, `Bfile_OpenFile`, `Bfile_WriteFile()`, `Bfile_CloseFile()`

Autre documentation

Les codes d'erreur standard

Les fonctions de Bfile utilisent des codes d'erreur définis pour indiquer quelle erreur se produit lorsqu'une fonction de manipulation de la mémoire se termine de manière inattendue. LibBMP utilise également des codes d'erreur pour signaler d'autres raisons pour que la fonction ait échouée. Ceux-ci sont positifs alors que ceux de Bfile sont négatifs.
Voici la liste des codes que vous pouvez obtenir ainsi que la raison de l'erreur associée.

CODE D'ERREUR	RAISON DE L'ERREUR
3	Bitmap compressed
2	Not black and white
1	Not enough RAM
0	No error
-1	Entry not found
-2	Illegal parameter
-3	Illegal path
-4	Device full
-5	Illegal device
-6	Illegal filesystem
-7	Illegal system
-8	Access denyed
-9	Already locked
-10	Illegal task ID
-11	Permission error
-12	Entry full
-13	Already exist entrys
-14	Read-only file
-15	Illegal filter
-16	Enumrate end
-17	Device changed
-18	Not record file (not used)
-19	Illegal seek position
-20	Illegal block file
-21	Device not exist (not used)
-22	End of file (not used)
-23	Not mount device
-24	Not unmount device
-25	Cannot lock system
-26	Record not found
-27	Not dual record file (not used)
-28	Not alarm support
-29	Cannot add alarm
-30	File find used
-31	Device error
-32	System not locked
-33	Device not found
-34	File type mismatch
-35	Not empty
-36	Broken system data
-37	Media not ready
-38	Too many alarm item
-39	Same alarm exist
-40	Access SWAP area
-41	Multimedia card
-42	Copy protection
-43	Illegal file data

Tutoriel d'utilisation

Présentation

Cette partie ne fait pas vraiment partie de la documentation. Il s'agit d'un tutoriel présentant le fonctionnement basique de libBMP. Il permet de prendre en main facilement la bibliothèque.

Ouvrir un bitmap

La démarche est très simple.

Bitmap *monBitmap = BMP_Load(~~"\\\\fls0\\BITMAP.bmp"~~, NULL);

Ce code chargera le bitmap à l'adresse donnée dans la structure. Notez que le deuxième paramètre attendu est un int * qui recevra le code d'erreur au retour de la fonction.

Une fois que vous avez fini avec le bitmap, n'oubliez pas de libérer la mémoire :

BMP_Free(monBitmap);

Afficher des bitmaps

Là encore, la démarche est prévue pour être simple d'utilisation. Une fois votre bitmap chargé avec BMP_Load(), vous pouvez l'afficher simplement en utilisant la fonction BMP_Draw()

BMP_Draw(monBitmap, 10, 20, BMP_OR);

Très intuitivement, les paramètres sont dans l'ordre le bitmap à afficher, les coordonnées en x puis en y de la position à laquelle il doit être affiché et le mode d'affichage. Ce dernier peut prendre trois valeurs : BMP_AND, BMP_OR ou BMP_XOR.

Exporter des bitmaps

Pour exporter un bitmap, vous devez disposer d'une structure de type Bitmap *. Nous allons donc la créer à partit du code d'un sprite avec la fonction BMP_Create.

const unsigned char sprite[8] = { 60,126,102,36,126,102,66,60 };
Bitmap *monBitmap = BMP_Create(sprite, 8, 8, NULL);

Comme d'habitude, on a d'abord la largeur puis la hauteur, et enfin le pointeur sur le code d'erreur (ici ignoré).

Une fois ceci fait, si monBitmap n'est pas nul, il contient le code du sprite formaté pour être enregistré. Il ne nous reste donc plus qu'à utiliser la fonction BMP_Save() :

if(monBitmap) BMP_Save(~~"\\\\fls0\\MYSPRITE.bmp"~~, monBitmap, NULL);

Si aucune erreur ne s'est produite, un fichier .bmp lisible par votre ordinateur a été créé dans la mémoire de la calculatrice.

Documentation