CMSXImg

MSXImage est un outil Windows en ligne de commande permettant d'extraire des sprites d'une image et de les convertir dans un format MSX intégrable dans un programme C ou Assembleur, ou directement en binaire.

Version actuelle : MSXImage 1.7

Exemple

Prenons l'image suivante :


Elle est constitué de 4 rangées (une par voiture) de 16 sprites d'une taille de 13x11 pixels.
Imaginons qu'on souhaite extraire les 16 sprites de la 2e voiture (la jaune) vers un fichier my_sprites.h pour être intégré dans un programme C.
Cela permet d'avoir les images directement intégré au programme sans avoir à les charger à la main (très utile pour les programme destiné aux ROMs).
Nous utiliserons la commande :

> MSXImage -in my_image.png -out my_sprites.h -pos 0 11 -size 13 11 -num 16 1 -name myYellowCar -trans 0xE300E3 -bpc 8

-pos 0 11 : donne la position de départ de la zone à extraire dans l'image source.
-size 13 11 : donne la taille des blocks à extraire.
-num 16 1 : donne le nombre de blocks à extraire.
-name myYellowCar : donne le nom de la structure à créer (dans le cas d'un fichier texte).
-trans 0xE300E3 : donne la couleur de fond qui va permettre de déterminer les zones transparentes.
-bpc 8 : détermine le nombre de couleur des sprites. Ici, on utilise le mode 8-bits du Screen 8 et ses 256 couleurs.

Dans ce cas, l'outil va générer un fichier texte qu'on va pouvoir ensuite inclure dans un programme C qui va ressembler à ça :

Options

[code=text]Usage: MSXImage [options]
Usage: MSXImage -in <filename> -out <filename> [options]
Options:
-in fileName Inuput file name. Can be 8/16/24/32 bits image
Supported format: BMP, JPEG, PCX, PNG, TGA, PSD, GIF, etc.
-out fileName Output file name
-format ? Output format
auto Auto-detected using output file extension (default)
c C header file output
asm Assembler header file output
bin Raw binary data image
-name name Name of the table to generate
-pos x y Start position in the input image
-size x y Width/height of a block to export (if 0, use image size)
-num x y Number of block to export (columns/rows number)
-trans color Transparency color (in RGB 24 bits format : 0xFFFFFF)
-bpc ? Number of bits per color for the output image (support 1, 4 and 8-bits)
1 1-bit black & white (0: tranparency or black, 1: other colors)
4 4-bits index in 16 colors palette
8 8 bits RGB 256 colors (format: [G:3|R:3|B2]; default)
-pal Palette to use for 16 colors mode
msx1 Use default MSX1 palette
custom Generate a custom palette and add it to the output file
-palcount n Number of color in the custom palette to create (default: 15)
-compress ?
none No compression (default)
crop16 Crop image to non transparent area (4-bits, max size 16x16)
cropline16 Crop image to non transparent area (4-bits per line, max size 16x16)
crop32 Crop image to non transparent area (5-bits, max size 32x32)
cropline32 Crop image to non transparent area (5-bits per line, max size 32x32)
crop256 Crop image to non transparent area (8-bits, max size 256x256)
cropline256 Crop image to non transparent area (8-bits per line, max size 256x256)
rle0 Run-length encoding of transparent blocs (7-bits for block length)
rle4 Run-length encoding for all colors (4-bits for block length)
rle8 Run-length encoding for all colors (8-bits for block length)
auto Determine a good compression method according to parameters
best Search for best compressor according to input parameters (smallest data)
-dither ? Dithering method (for 1-bit color only)
none No dithering (default)
floyd Floyd & Steinberg error diffusion algorithm
bayer4 Bayer ordered dispersed dot dithering(order 2 – 4x4 - dithering matrix)
bayer8 Bayer ordered dispersed dot dithering(order 3 – 8x8 - dithering matrix)
bayer16 Bayer ordered dispersed dot dithering(order 4 – 16x16 dithering matrix)
cluster6 Ordered clustered dot dithering(order 3 - 6x6 matrix)
cluster8 Ordered clustered dot dithering(order 4 - 8x8 matrix)
cluster16 Ordered clustered dot dithering(order 8 - 16x16 matrix)
-data ? Text format for numbers
dec Decimal data (c & asm)
hexa Default hexadecimal data (depend on langage; default)
hexa0x Hexadecimal data (0xFF; c & asm)
hexaH Hexadecimal data (0FFh; asm only)
hexa$ Hexadecimal data ($FF; asm only)
hexa# Hexadecimal data (#FF; asm only)
bin Binary data (11001100b; asm only)
-skip Skip empty sprites (default: false)
-head Add a header table contening input parameters (default: false)
-help Display this help

Déscription

Fichier source

-in path\fileName

Le chemin et le nom du fichier source d'où les images vont être extraites.
MSXImage utilise la libraire FreeImage et supporte donc de très nombreux formats d'image (BMP, JPEG, PCX, PNG, TGA, PSD, GIF, etc.) et de nombreux format de couleur (8, 16, 24 ou 32-bits).

Fichier destination

-out path\fileName

Le chemin et le nom du fichier de destination.
Si le paramètre format (voir si dessous) est mode automatique ( -format auto ), c'est l'extension du fichier de destination qui déterminera le format des données à exporter.

-format auto | c | asm | bin

Détermine le format d'export.
c : Créer un fichier texte avec une table au format C
asm : Créer un fichier texte avec une table au format assembleur
bin : Créer un fichier binaire

-name tableName

Pour les formats texte, détermine le nom de la structure à créer.

-data dec | hexa | hexa0x | hexaH | hexa$ | hexa# | bin

Pour les formats texte, détermine la façon d'écrire les chiffres (123, 0x12, $12, 12h, etc.).

Découpage des sprites

-pos x y

Position de départ de la zone à extraire dans l'image source (en pixels).

-size x y

Taille des blocks à extraire (en pixels).

-num x y

Nombre de blocks à extraire.

-skip

Ne pas exporter les blocks ne contenant que des pixels transparents.

Couleurs

-trans color

La couleur de l'image qui permettra de déterminer les zones transparentes.
Elle doit être donnée sous forme hexadécimal selon le format 0xRRGGBB (8-bits pour chaque canal).

-bpc 1 | 4 | 8

Nombre de bits-par-couleurs (BPC).
1-bit : Monochrome (2 couleurs). Si une couleur de transparence est donnée, les pixels transparents vaudront 0 et tous les autres 1. Sinon, les pixels de couleur noir "pur" (0x000000) vaudront 0 et tous les autres 1.
4-bits : Index sur une palette de 16 couleurs.
8-bits : Valeur GBR au format [G:3|R:3|B2]

-pal msx1 | custom

Dans le cas du format 4-bits-par-couleur (16 couleurs), permet de choisir entre la palette par défaut du MSX (fixe) ou bien demander au programme de créer une palette spécifique en fonction des couleurs de l'image de source.

-palcount n

Dans le cas de l'utilisation d'une palette custom , permet de déterminer le nombre de couleurs maximum qu'elle peut utiliser.

-dither none | floyd | bayer4 | bayer8 | bayer16 | cluster6 | cluster8 | cluster16

Différent méthode de tramage (dithering) pour le mode 1-bit-par-couleur.

Compression

-compress none | crop16 | cropline16 | crop32 | cropline32 | crop256 | cropline256 | rle0 | rle4 | rle8

Différent mode de compression sans perte pour réduire la taille des données exportées.
Les méthodes de compression Crop16/32/256, CropLine16/32/256 et RLE0 n'ont de sens que si une couleur de transparence est spécifiée.

Crop

Permet de réduite la zone exporté en taillant (crop) les bordures transparentes du sprite.
Pour chaque sprite, l'algorithme détermine la position X et Y minimal et maximal des pixels non-transparents.
Par ex., si dans un sprite 16x16, aucun pixel non-transparents n'apparait avant la colonne 3 et aucun après la colonne 10, le programme n'exportera le sprite qu'entre ces deux colonnes.
Au début de chaque sprite, un header détermine les valeurs min/max en X et Y pour que les données puissent être décompressé correctement.

Il existe 3 versions de l'algorithme :

Nom	Taille max	Entête	Remarque
Crop16	16x16 px	2 bytes : [minX:4|maxX:4] [minY:4|maxY:4]
Crop32	32x32 px	2 bytes : [minX:3|maxX:5] [minY:3|maxY:5]	La valeur minimum de X et Y n'étant codé que sur 3-bits (valeurs 0 à 7), la zone transparente "taillé" ne peut excéder cette taille même s'il n'y a pas de pixel non-transparent au delà
Crop256	256x256 px	4 bytes : [minX] [maxX] [minY] [maxY]

Exemple d'organisation des données en Crop16 :

CropLine

Comme pour la compression Crop, il s'agit de réduite la zone exporté en taillant les bordures transparentes du sprite. La particularité de cet algorithme, c'est qu'il "taille" le sprite ligne par ligne.
Il détermine d'abord les valeurs min/max des pixels non-transparents sur l'axe Y et les écrits dans le header du sprite.
Ensuite, ligne par ligne, il détermine min/max des pixels non-transparents de la ligne, les écrits dans le header de la ligne puis écrits les couleurs comprises dans cet intervalle.

Il existe également 3 versions de l'algorithme :

Nom	Taille max	Entête sprite	Entête ligne	Remarque
CropLine16	16x16 px	1 byte : [minY:4|maxY:4]	1 byte : [minX:4|maxX:4]
CropLine32	32x32 px	1 byte : [minY:3|maxY:5]	1 byte : [minX:3|maxX:5]	La valeur minimum de X et Y n'étant codé que sur 3-bits (valeurs 0 à 7), la zone transparente "taillé" ne peut excéder cette taille même s'il n'y a pas de pixel non-transparent au delà
CropLine256	256x256 px	2 bytes : [minY] [maxY]	2 bytes : [minX] [maxX]

Exemple d'organisation des données en CropLine16 :

RLE

La compression RLE rassemble tous les pixels consécutif d'une même couleur et les stock sous la forme de 2 infos : la couleur en question et le nombre d'itération.

Il existe 2 versions de l'algorithme :

Nom	Longueur max	Encodage
RLE4	16	1 byte : [length:4|color:4]
RLE8	256	2 bytes : [length] [color]

Exemple d'organisation des données en RLE4 :


Exemple d'organisation des données en RLE8 :

RLE0

La compression RLE0 est optimisée pour la compression de sprite partiellement transparent.
Contrairement aux autres algorithmes RLE, le RLE0 ne rassemble que les pixels transparents. Toutes les autres couleurs sont stockés ensembles.

Chaque block commence par un entête de 1 byte : [trans:1|length:7]

Longueur maximale par block : 127 pixels.
Si le bit "trans" est à 1, le block représente la couleur transparente.
Si le bit "trans" est à 0, le block représente les autres couleurs. Dans ce cas, le header est suivi de la liste des couleurs du block.

Exemple d'organisation des données en RLE0 :

Auto

Le programme essaye sélectionne un mode de compression standard en fonction des paramètres d'entrée (en fonction de la taille des sprites et de mode couleur 1/4/8-bits).

Best

Le programme génère les données dans tous les modes de compression possibles, puis sélectionne le meilleur (celui qui génère les données les plus petites).