Utilitaires

CMSXImg

Table des matières

Exemple
Options
Déscription

CMSXImg 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 : CMSXimg 1.9.1

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 :

> CMSXImg -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 :

Code C :

// Data table
const unsigned char myYellowCar[] =
{
// Sprite[0] (offset:0)
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 
    0x00, 0x00, 0x04, 0x04, 0x04, 0x10, 0x21, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 
    0x6D, 0x49, 0x04, 0x21, 0x04, 0xFB, 0x21, 0x21, 0x91, 0x92, 0xBC, 0x6D, 0x00, 
    ...
};

Options

Code TEXT :

 
Usage: CMSXimg <filename> [options]
Options:
   inputFile       Inuput file name. Can be 8/16/24/32 bits image
                   Supported format: BMP, JPEG, PCX, PNG, TGA, PSD, GIF, etc.
   -out outFile    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)
   -gap x y        Gap between blocks in pixels
   -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)
      2               2-bit index in 4 colors palette
      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)
   -idx            Add images index table (default: false)
   -copy (file)    Add copyright information from text file
                   If file name is empty, search for <inputFile>.txt
   -head           Add a header table contening input parameters (default: false)
   -font x y f l   Add font header (default: false)
                   x/y: Font width/heigt in pixels
                   f/l: ASCII code of the first/last character to export
                        Can be character (like: &) or hexadecimal value (0xFF format)
   -def            Add defines for each table (default: false)
   -notitle        Remove the ASCII-art title in top of exported text file
   -help           Display this help

Déscription

Fichier source

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

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 de sélectionner 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).