Documentation VISION (VAPI) : Raster Index Interface

		Documentation VISION (VAPI)		Dernière mise à jour : 04/01/02
Télécharger la doc		RASTER INTERFACE

Résumé
Préfixe de l'interface	Ra
Nombre de fonctions	16
Description	Ensemble de fonctions permettant de manipuler des rasters image sous différents formats (bit-plan, True Color, formats ATARI, spécifique, standard...).

Prototype	void cdecl RaImgWhite(MFDB *img)
Paramètres	[IN/OUT] img : pointeur sur l'image à traiter
Retour	Aucun
Description	Initialise un raster image avec la couleur blanche. Le format attendu est le format ATARI. En mode palette (img->fd_nplanes <= 8), le raster est initialisé avec des bits mis à 0 (index TOS/VDI = 0), l'indice 0 de la palette est généralement positionné sur la couleur blanche.
Remarques	Cette fonction effectue la transformation "sur place".
Version VAPI	1.00 ou supérieure

Prototype	long cdecl RaIs15Bits(void)
Paramètres	Aucun
Retour	0 : Format True Color sur 16 bits ou nombre de bits de la résolution graphique différent de 16 1 : Nombre de plans de la résolution graphique sur 16 bits mais codage des pixels sur 15 bits (5 par composante)
Description	Indique si le codage True Color de la résolution graphique courante est sur 15 ou 16 bits
Remarques	Au cas où il est important de savoir si le nombre de bits de codage de la composante verte est sur 5 ou 6 bits, on peut par cette fonction savoir si tous les 16 bits du mode True Color sur 16 plans sont utilisés (la composante verte est alors codée sur 6 bits au lieu de 5 et RaIs15Bits renvoie 0) ou si seuls 15 bits sont utiles (la composante verte est alors codée sur 5 bits et RaIs15Bits renvoie 1)
Version VAPI	1.00 ou supérieure

Prototype	void cdecl RaTCConvert(MFDB *img)
Paramètres	[IN/OUT] img : pointeur sur l'image à traiter
Retour	Aucun
Description	Transforme un raster True Color au format spécifique de la carte graphique en un raster True Color au format ATARI
Remarques	Cette fonction effectue la transformation "sur place". Si VISION se rend compte que le format spécifique de la machine est le format ATARI, la fonction rend immédiatement la main, sans effectuer de traitement. Cette fonction est l'inverse de RaTCInvConvert
Version VAPI	1.00 ou supérieure

Prototype	void cdecl RaTCInvConvert(MFDB *img)
Paramètres	[IN/OUT] img : pointeur sur l'image à traiter
Retour	Aucun
Description	Transforme un raster True Color au format ATARI en un raster True Color au format spécifique de la carte graphique
Remarques	Cette fonction effectue la transformation "sur place". Si VISION se rend compte que le format spécifique de la machine est le format ATARI, la fonction rend immédiatement la main, sans effectuer de traitement. Cette fonction est l'inverse de RaTCInvConvert
Version VAPI	1.00 ou supérieure

Prototype	void cdecl RaInd2RasterInit(MFDB *img, long width)
Paramètres	[IN/OUT] img : pointeur sur l'image à traiter [IN] width : largeur (en pixels) maximale à ne pas dépasser. width ne peut dépasser 32767. Le codage sur un entier 32 bits ne sert qu'à assurer la compatibilité avec les compilateurs 32 bits.
Retour	Aucun
Description	Prépare des opérations de transfert d'index vers un raster image au format ATARI.
Remarques	Le paramètre width peut paraître redondant avec img->fd_w mais il est là parce que VISION positionne toujours img->fd_w à un multiple de 16 (optimisations internes). width permet donc de ne pas être limité à une largeur multiple de 16 pixels. Intéressant : si width est multiple de 16, la fonction RaInd2Raster sera bien plus rapide !
Version VAPI	1.00 ou supérieure

Prototype	void cdecl RaInd2Raster(unsigned char*indexes, long nb_indexes)
Paramètres	[IN] indexes : pointeur sur le tableau d'indices TOS à converir vers le raster précédemment initialisé avec la fonction RaInd2RasterInit [IN] nb_indexes : Nombre d'index dans le tableau pointé par indexes
Retour	Aucun
Description	Convertit les indices TOS en données bit-plan du raster
Remarques	Une fois l'initialisation faite par la fonction RaInd2RasterInit, on peut appeler cette fonction autant de fois qu'on le veut afin de transformer le flux de données (indices TOS) vers le raster image. VAPI mémorise la dernière position atteinte dans le raster. Par exemple : Vapi->RaInd2RasterInit( img, wished_width ) ; for ( y = 0; y < img->fd_h; y++ ) { GetTosIndexes( y, tab_indexes, &nb_indexes ) ; /* Recupere les indices TOS pour la ligne y / Vapi->RaInd2Raster( tab_indexes, nb_indexes ) ; / Envoi vers le raster au format ATARI bit-plan */ }
Version VAPI	1.00 ou supérieure

Prototype	void cdecl RaRaster2Ind(short pt_bitplan, long nb_pts, long nb_planes, unsigned char tos_indexes)
Paramètres	[IN] pt_bitplan : pointeur sur le début des données raster à convertir (démarrage sur un multiple de 16 pixels) [IN] nb_pts : Nombre de points à convertir [IN] nb_planes : Nombre de plans du raster image. nb_planes ne peut prendre que les valeurs 1, 2, 4, ou 8. Le codage sur un entier 32 bits ne sert qu'à assurer la compatibilité avec les compilateurs 32 bits. [OUT] tos_indexes : pointeur vers le tableau d'indices TOS recevant les données (doit être dimensionné à nb_pts octets)
Retour	Aucun
Description	Convertit des données bit-plan du raster en indices TOS
Remarques	Fonction réciproque de RaInd2Raster. Attention ! A cause des optimisations internes de la fonction, nb_pts DOIT être multiple de 16, sinon vous n'aurez pas les derneiers points (si vous spécifiez 35 points, vous n'en n'aurez que 32 en retour). Il vous faut donc ajuster nb_pts avant l'appel et sur-dimensionner de 16 points votre buffer tos_indexes de réception pour être tranquille...
Version VAPI	1.00 ou supérieure

Prototype	unsigned char cdecl RaGetTOS2VDIArray*(long nb_planes)
Paramètres	[IN] nb_planes : Nombre de plans. nb_planes ne peut prendre que les valeurs 1, 2, 4, ou 8. Le codage sur un entier 32 bits ne sert qu'à assurer la compatibilité avec les compilateurs 32 bits.
Retour	Pointeur sur le tableau de converion index TOS --> index VDI
Description	Récupérer le tableau de correspondance entre les indices TOS et VDI, pour un nombre de plans donné
Remarques	Fonction réciproque de RaGetVDI2TOSArray
Version VAPI	1.00 ou supérieure

Prototype	unsigned char cdecl RaGetVDI2TOSArray*(long nb_planes)
Paramètres	[IN] nb_planes : Nombre de plans. nb_planes ne peut prendre que les valeurs 1, 2, 4, ou 8. Le codage sur un entier 32 bits ne sert qu'à assurer la compatibilité avec les compilateurs 32 bits.
Retour	Pointeur sur le tableau de converion index VDI --> index TOS
Description	Récupérer le tableau de correspondance entre les indices VDI et TOS, pour un nombre de plans donné
Remarques	Fonction réciproque de RaGetTOS2VDIArray
Version VAPI	1.00 ou supérieure

Prototype	unsigned long cdecl RaGetImgSize*(long width, long height, long nplanes)
Paramètres	[IN] width : Largeur de l'image en nombre de pixels [IN] height : Hauteur de l'image en nombre de pixels [IN] nplanes : Nombre de plans pour coder un pixel Le codage sur un entier 32 bits ne sert qu'à assurer la compatibilité avec les compilateurs 32 bits.
Retour	La taille mémoire nécessaire (en octets) pour contenir une telle image.
Description	Permet de connaitre la taille d'une image compte tenu des contraintes d'alignement VDI sur 16 pixels.
Remarques
Version VAPI	1.02 ou supérieure

Prototype	long cdecl RaRasterAlloc(MFDB *raster)
Paramètres	[IN/OUT] raster : Structure VDI décrivant une image
Retour	0 : OK, l'image a été allouée (pointé par le champ fd_addr de la structure MFDB) != 0 : Erreur (mémoire)
Description	Alloue une image d'après les champs fd_w, fd_h et fd_nplanes de la strucuture MFDB.
Remarques	Si succès le champ fd_addr pointe vers les données image (non initialisées), sinon fd_addr vaut NULL fd_wdwidth est aussi mis à jour. Les autres champs restent inchangés.
Version VAPI	1.02 ou supérieure

Prototype	void cdecl RaRasterFree(MFDB *raster)
Paramètres	[IN/OUT] raster : Structure VDI décrivant une image
Retour	Aucun
Description	Libère une image précédemment allouée par RaRasterAlloc
Remarques	Tous les champs de la structure MFDB sont remis à zéro après libération.
Version VAPI	1.02 ou supérieure

Prototype	void cdecl RaTC15RemapColors(REMAP_COLORS *rc)
Paramètres	[IN] rc : Pointeur sur une structure de type REMAP_COLORS définissant la table de redéfinition des couleurs élémentaires, le début du buffer à modifier et le nombre de points
Retour	Aucun
Description	Modifie la répartition actuelle des couleurs d'une suite de points en True Color 15 bits. Les champs red, green et blue de la structure REMAP_COLORS doivent pointer sur des tableaux de 32 (32 = 2^5) éléments, chaque élément du tableau devant définir la valeur à substituer à l'indice de ce tableau, par exemple la formule: red[i] = i ; (0 <= i < 32) ne change rien pour la table de la composante rouge (i sera remplacé par i). Attention ! La nouvelle valeur substitué doit appartenir à l'intervalle [0,31]. Exemple tout bête : augmenter la luminosité de 100% sur toutes les composantes: new_val = i * 2 ; if ( new_val > 31) new_val = 31 ; /* Important ! */ red[i] = green[i] = blue[i] = new_val ;
Remarques	Cette fonction travaille sur le format spécifique de la machine ! Inutile donc de passer par les fonctions RaTCConvert et RaTCInvConvert.
Version VAPI	1.03 ou supérieure

Prototype	void cdecl RaTC16RemapColors(REMAP_COLORS *rc)
Paramètres	[IN] rc : Pointeur sur une structure de type REMAP_COLORS définissant la table de redéfinition des couleurs élémentaires, le début du buffer à modifier et le nombre de points
Retour	Aucun
Description	Modifie la répartition actuelle des couleurs d'une suite de points en True Color 16 bits. Les champs red, green et blue de la structure REMAP_COLORS doivent pointer sur des tableaux de 32 (32 = 2^5) éléments pour red et blue, et 64 (64=2^6) pour green, chaque élément du tableau devant définir la valeur à substituer à l'indice de ce tableau, par exemple la formule: red[i] = i ; (0 <= i < 32) ne change rien pour la table de la composante rouge (i sera remplacé par i). Attention ! La nouvelle valeur substitué doit appartenir à l'intervalle [0,31] pour red et blue et [0,63] pour green. Exemple tout bête : augmenter la luminosité de 100% sur la composante verte: new_val = i * 2 ; if ( new_val > 63) new_val = 63 ; /* Important ! / green[i] = new_val ; / Pour 0 <= i < 64) */
Remarques	Cette fonction travaille sur le format spécifique de la machine ! Inutile donc de passer par les fonctions RaTCConvert et RaTCInvConvert.
Version VAPI	1.03 ou supérieure

Prototype	void cdecl RaTC32RemapColors(REMAP_COLORS *rc)
Paramètres	[IN] rc : Pointeur sur une structure de type REMAP_COLORS définissant la table de redéfinition des couleurs élémentaires, le début du buffer à modifier et le nombre de points
Retour	Aucun
Description	Modifie la répartition actuelle des couleurs d'une suite de points en True Color 32 bits. Les champs red, green et blue de la structure REMAP_COLORS doivent pointer sur des tableaux de 256 (256=2^8) éléments, chaque élément du tableau devant définir la valeur à substituer à l'indice de ce tableau, par exemple la formule: red[i] = i ; (0 <= i < 256) ne change rien pour la table de la composante rouge (i sera remplacé par i). Attention ! La nouvelle valeur substitué doit appartenir à l'intervalle [0,255]. Exemple tout bête : baisser la luminosité de 20% sur toutes les composantes: new_val = (80 * i) / 100 ; /* Notons que on retombe forcément dans la plage [0;255] .../ red[i] = green[i] = blue[i] = new_val ; / Pour 0 <= i < 256) */
Remarques	Cette fonction travaille sur le format spécifique de la machine ! Inutile donc de passer par les fonctions RaTCConvert et RaTCInvConvert.
Version VAPI	1.03 ou supérieure

Prototype	void cdecl RaRasterRotateGetDstMFDB(MFDB in, MFDB out, long angle)
Paramètres	[IN] in : MFDB décrivant l'image dont on veut effectuer la rotation [OUT]out : MFDB de destination [IN] angle : angle en degrés de la rotation
Retour	Aucun
Description	Permet de connaitre la taille de l'image après rotation en vue d'une allocation par exemple. tous les champs du MFDB out sont mis à jour SAUF fd_addr car l'image destination n'est pas allouée.
Remarques	Généralement, cette fonction est appelée avant la fonction suivante
Version VAPI	1.03 ou supérieure

Prototype	long cdecl RaRasterRotate(MFDB in, MFDB out, long angle, long flags)
Paramètres	[IN] in : MFDB décrivant l'image dont on veut effectuer la rotation [OUT]out : MFDB de destination [IN] angle : angle en degrés de la rotation [IN] flags : drapeau dont les bits ont la signification suivante: Bit 0 positionné : Demande à VAPI d'afficher une barre de progression
Retour	ELDV_NOERROR : tout va bien ELDV_NOTENOUGHMEMORY : pas assez de mémoire ELDV_CANCELLED : (possible seulement si la progression a été demandée) ELDV_GENERALFAILURE : erreur inconnue
Description	Efectue la rotation d'angle spécifié su le MFDB source. Le MFDB destination doit avoir été alloué, sinon la fonction l'allouera. Notez que cette dernière solution est un peu dangereuse car c'est maintenant au LDV de gérer sa libération par RaRasterFree. La bonne nouvelle c'est que VAPI se charge de prendre en compte le format VDI standard si nécessaire !
Remarques	Si l'angle est multiple de 90°, des routines spéciales sont appelées afin d'éviter des calculs approximatifs et inutiles de sinus et cosinus.
Version VAPI	1.03 ou supérieure

		Documentation VISION (VAPI)		Dernière mise à jour : 04/01/02
Télécharger la doc		RASTER INTERFACE