Documentation de la bibliothèque MLV-0.5

Définition de type | Fonctions

Référence du fichier MLV_animation.h

Ce fichier définit les prototypes des fonctions permettant de mettre en oeuvre des animations. Plus de détails...

Aller au code source de ce fichier.

Définition de type

typedef struct
_MLV_Animation_sequence 
MLV_Animation_sequence
 Définit le type Animation qui code une animation dans la librairie MLV.
typedef struct _MLV_Animation MLV_Animation
 Définit le type d'un animateur dans la librairie MLV.
typedef struct _MLV_Animation_book MLV_Animation_book
 Définit le type Animation_bbook qui code un livre contenant de nombreuses animations.

Fonctions

MLV_Animation_sequenceMLV_create_animation_sequence (unsigned int nb_frames, unsigned int nb_layers, unsigned int nb_channels)
 Créé une séquence d'animation comportant un nombre d'image donné.
void MLV_free_animation_sequence (MLV_Animation_sequence *animation)
 Libère les données alloué pour l'animation.
void MLV_change_frame_in_animation_sequence (MLV_Image **array_of_images, MLV_Sound **array_of_sounds, unsigned int delay, MLV_Animation_sequence *animation, unsigned int position)
 Change un animation en remplacant une image et son temps d'affichage associé. L'image concerné est repéré à l'aide de son index et de l'index de la couche où elle appartient.
void MLV_change_frame_image_in_animation_sequence (MLV_Image *image, MLV_Animation_sequence *animation, unsigned int position, unsigned int layer)
 Change un animation en remplacant uniquement une image. L'image concerné est repéré à l'aide de son index et de de l'index de sa couche.
void MLV_change_frame_sound_in_animation_sequence (MLV_Sound *sound, MLV_Animation_sequence *animation, unsigned int position, unsigned int channel)
 Change un animation en remplacant uniquement un bruitage. Le son image concerné est repéré à l'aide de son index et de de l'index de son canaul.
void MLV_change_frame_delay_in_animation_sequence (unsigned int delay, MLV_Animation_sequence *animation, unsigned int position)
 Change le temps d'affichage d'une image donnée d'une animation.
void MLV_get_frame_from_animation_sequence (MLV_Animation_sequence *animation, unsigned int position, unsigned int layer, MLV_Image **image, unsigned int *delay)
 Recupère l'image et le temps présents à une position et une couche donnée d'une animation.
int MLV_get_frame_delay_from_animation_sequence (MLV_Animation_sequence *animation, unsigned int position)
 Renvoie le temps d'affichage de l'image présente à une position donnée d'une animation donnée.
MLV_ImageMLV_get_frame_image_from_animation_sequence (MLV_Animation_sequence *animation, unsigned int position, unsigned int layer)
 Renvoie l'image présente à une position et une couche donnée d'une animation donnée.
MLV_AnimationMLV_create_animation (MLV_Animation_sequence *animation)
 Cree un animateur et l'initialise avec une animation donnée en paramètre.
void MLV_free_animation (MLV_Animation *animation)
 Libère l'espace mémoire alloué pour un animateur donné.
void MLV_play_animation (MLV_Animation *animation)
 Demare la lecture de l'animation lu par l'animateur.
void MLV_play_revert_animation (MLV_Animation *animation)
 Demande à un animateur donné de jouer l'animation à l'envers.
void MLV_stop_animation (MLV_Animation *animation)
 Met en pause la lecture d'un animateur donné.
void MLV_rewind_animation (MLV_Animation *animation)
 Demande à l'animateur de reprendre la lecture de l'animation depuis le début.
void MLV_next_frame (MLV_Animation *animation)
 Force l'animateur à passer à l'image suivante.
void MLV_previous_frame (MLV_Animation *animation)
 Force l'animateur à revenir sur l'image précédente.
void MLV_update_animation (MLV_Animation *animation)
 Met a jour l'animateur.
void MLV_change_sound_volume_on_animation (MLV_Animation *animation, unsigned int channel, float volume)
 Change le volume sonore d'un bruitage.
void MLV_turn_on_sound_on_animation (MLV_Animation *animation, unsigned int channel)
 Active le son du canal d'une animation donnée.
void MLV_turn_off_sound_on_animation (MLV_Animation *animation, unsigned int channel)
 Désactive le son du canal d'une animation donnée.
void MLV_draw_animation (MLV_Animation *animation, unsigned int layer, int x, int y)
 Dessine à une position donnée l'image actuellement lue par l'animateur. Cette image est situè à une couche donnée en paramètre.
void MLV_draw_partial_animation (MLV_Animation *animation, unsigned int layer, int source_x, int source_y, int source_width, int source_height, MLV_Image *image, int x, int y)
 Dessine à l'écran à une position donnée, une portion de l'image actuellement lue par l'animateur et extraite de la couche spécifiée en paramètre.
void MLV_draw_animation_on_image (MLV_Animation *animation, unsigned int layer, MLV_Image *image, int x, int y)
 Dessine sur une image donnée à une position donnée l'image actuellement lue par l'animateur et située à une couche donnée.
void MLV_draw_partial_animation_on_image (MLV_Animation *animation, unsigned int layer, int source_x, int source_y, int source_width, int source_height, MLV_Image *image, int x, int y)
 Dessine sur une image donnée à une position donnée une portion de l'image actuellement lue par l'animateur et située à une couche donnée.
MLV_Animation_bookMLV_load_animation_book (const char *xml_file, const char *image_directory, const char *sound_directory)
 Charge en memoire un livre contenant une multitude d'animations.
void MLV_free_animation_book (MLV_Animation_book *animation_book)
 Libère la memoire contenue par le livre d'animation.
int MLV_get_number_of_animation_sequences (MLV_Animation_book *animation_book)
 Détermine le nombre d'animations contenus par le livre d'animation.
MLV_Animation_sequenceMLV_get_animation_from_id (MLV_Animation_book *animation_book, int id)
 Renvoie une animation donnée contenue dans le livre d'animation.
MLV_Animation_sequenceMLV_get_animation_from_name (MLV_Animation_book *animation_book, const char *name)
 Renvoie une animation donnée contenue dans le livre d'animation.
const char * MLV_get_name_from_id_animation (MLV_Animation_book *animation_book, int id_animation)
 Renvoie le nom d'un animation à partir de son identifiant dans le livre d'animation.
void MLV_add_frame_in_animation_sequence (MLV_Image **array_of_images, MLV_Sound **array_of_sounds, unsigned int delay, MLV_Animation_sequence *animation_sequence)
 Ajoute un image dans la séquence d'animation. Cette fonction ne peux pas augmenter le nombre d'image d'une animation.

Description détaillée

Ce fichier définit les prototypes des fonctions permettant de mettre en oeuvre des animations.

Auteur:
Adrien Boussicault
Marc Zipstein

Cette interface est inspiré du tutoriel : http://www.gnurou.org/writing/linuxmag/sdl/partie3


Documentation des définitions de type

typedef struct _MLV_Animation MLV_Animation

Définit le type d'un animateur dans la librairie MLV.

Un animateur est un objet qui garde contient les informations suivante:

  • un pointeur vers une animation
  • la position de l'image courante de l'animation
  • une horloge interne ( dons le temps est différent du temps courant )

Un animateur permet d'animer une animation. Pour cela, l'animateur possède une horloge dont l'aiguille avance d'une unité à chaque appel de la fonction update. Les animations sont alors jouée en fonction de l'évolution du temps de chaque animateur. Ainsi, deux animateurs différents peuvent avoir une courbe du temps différente.

La bonne façon d'utiliser des animateurs est de mettre a jour tous les animateurs en même temps à un intervalle de temps régulier. Pour cela vous pouvez utiliser la fonction framerate qui endort le programme de façon a assurer l'execution d'un tour de boucle à une fréquence donnée

 MLV_Image* creature1 = MLV_load_image("creature1.png");
 MLV_Image* creature2 = MLV_load_image("creature2.png");

 MLV_Animation_sequence* animation_seq;
 animation_seq = MLV_create_animation_sequence( 2 );
 MLV_change_frame_in_animation_sequence( creature1, 1, animation_seq, 0 );
 MLV_change_frame_in_animation_sequence( creature2, 1, animation_seq, 0 );

 MLV_Animation* animation; 
 animation = MLV_create_animation( animation );

 int frequence = 24; // nombre d'images par secondes
 MLV_change_frame_rate( frequence );
 while( 1 ){ 
     MLV_animation_update( animation );
     MLV_draw_animation(animation, 0, 0);
     MLV_frame_rate_delay();
 }

Documentation des fonctions

void MLV_add_frame_in_animation_sequence ( MLV_Image **  array_of_images,
MLV_Sound **  array_of_sounds,
unsigned int  delay,
MLV_Animation_sequence animation_sequence 
)

Ajoute un image dans la séquence d'animation. Cette fonction ne peux pas augmenter le nombre d'image d'une animation.

Paramètres:
array_of_images Liste d'image à ajouter. Il s'agit de toutes les images assiciée à toutes les couches correspondnant de l'animation.
array_of_sounds Liste de sons à ajouter. Il s'agit de toutes les sons assiciées à tous les cannaux correspondnant de l'animation.
delay le temps d'afficahge d'une image.
animation_sequence La sequence d'animation à moifier.
Exemples:
advanced/9_animation.c.
void MLV_change_frame_delay_in_animation_sequence ( unsigned int  delay,
MLV_Animation_sequence animation,
unsigned int  position 
)

Change le temps d'affichage d'une image donnée d'une animation.

Paramètres:
delay temps d'affichage de l'image
animation Animation à modifier
position position de l'image dans l'animation
void MLV_change_frame_image_in_animation_sequence ( MLV_Image image,
MLV_Animation_sequence animation,
unsigned int  position,
unsigned int  layer 
)

Change un animation en remplacant uniquement une image. L'image concerné est repéré à l'aide de son index et de de l'index de sa couche.

Paramètres:
image image a ajouter dans l'animation
animation Animation à modifier
position position de l'image dans l'animation
layer Couche de l'image.
void MLV_change_frame_in_animation_sequence ( MLV_Image **  array_of_images,
MLV_Sound **  array_of_sounds,
unsigned int  delay,
MLV_Animation_sequence animation,
unsigned int  position 
)

Change un animation en remplacant une image et son temps d'affichage associé. L'image concerné est repéré à l'aide de son index et de l'index de la couche où elle appartient.

Paramètres:
array_of_images Un tableau d'adresse contenant les addresses de images correspondat aux différentes couches d'une animation.
array_of_sounds Un tableau d'adresse contenant les addresses de sons correspondant aux différentes canaux d'une animation.
delay temps d'affichage de l'image
animation Animation à modifier
position position de l'image dans l'animation
void MLV_change_frame_sound_in_animation_sequence ( MLV_Sound sound,
MLV_Animation_sequence animation,
unsigned int  position,
unsigned int  channel 
)

Change un animation en remplacant uniquement un bruitage. Le son image concerné est repéré à l'aide de son index et de de l'index de son canaul.

Paramètres:
sound son a ajouter dans l'animation
animation Animation à modifier
position position de l'image dans l'animation
channel Canal du son.
void MLV_change_sound_volume_on_animation ( MLV_Animation animation,
unsigned int  channel,
float  volume 
)

Change le volume sonore d'un bruitage.

Paramètres:
animation L'animateur dans lequel se trouve le son.
channel Le canal concerné.
volume le nouveau volume sonore.
Exemples:
advanced/11_animation_book.c, et advanced/9_animation.c.
MLV_Animation* MLV_create_animation ( MLV_Animation_sequence animation  ) 

Cree un animateur et l'initialise avec une animation donnée en paramètre.

Paramètres:
animation L'animation que devra animer l'animateur.
Renvoie:
L'animateur créé.
Exemples:
advanced/11_animation_book.c, et advanced/9_animation.c.
MLV_Animation_sequence* MLV_create_animation_sequence ( unsigned int  nb_frames,
unsigned int  nb_layers,
unsigned int  nb_channels 
)

Créé une séquence d'animation comportant un nombre d'image donné.

Une séquence d'animation est une succession d'image où à chaque image est associé un temps. Ce temps code le temps d'affichage de chaque image, lors du rendu de de l'animation. Pour des raisons de commodité, nos séquence d'animations sont composés de plusieurs couches. Elles sont donc des successions de couches contenant chacunes une image.

Une sequence d'animation (à ne pas confondre avec une animation) est une pure structure de donnée. Elle peut donc pas s'animer, ni s'afficher à l'ecran. Pour afficher une séquence d'animation, il faut utiliser une animation, qui s'aidera de la séquence d'animation pour s'afficher ou pour mettre en mouvement les images de la séquence d'animation.

Le temps d'une s'quence d'animation n'est pas codée en secondes. Il s'agit d'un entier. Lorsque vous utilisez une animation, l'animateur à un temps qui lui est propre et qui est codé à l'aide d'un entier qui croit. Les duree que vous ajouterez dans l'animation sont donc définit par rapport au temps de l'animation qui utilise la séquence d'animation.

Paramètres:
nb_frames Le nombre d'image que doit contenir l'animation
nb_layers Nombre de couches graphique de l'animation.
nb_channels Nombre de canaux sonore de l'animation.
Renvoie:
Un pointeur vers une animation.
Exemples:
advanced/9_animation.c.
void MLV_draw_animation ( MLV_Animation animation,
unsigned int  layer,
int  x,
int  y 
)

Dessine à une position donnée l'image actuellement lue par l'animateur. Cette image est situè à une couche donnée en paramètre.

Paramètres:
animation L'animateur contenant l'animation à aficher
layer Couche de l'image.
x Coordonnée en X de la position du sommet Nord-Ouest de l'image à afficher.
y Coordonnée en Y de la position du sommet Nord-Ouest de l'image à afficher.
Exemples:
advanced/11_animation_book.c, et advanced/9_animation.c.
void MLV_draw_animation_on_image ( MLV_Animation animation,
unsigned int  layer,
MLV_Image image,
int  x,
int  y 
)

Dessine sur une image donnée à une position donnée l'image actuellement lue par l'animateur et située à une couche donnée.

Paramètres:
animation L'animateur contenant l'animation à aficher
layer Couche de l'image.
image image sur laquel il faut dessiner l'animation
x Coordonnée en X de la position du sommet Nord-Ouest de l'image à afficher.
y Coordonnée en Y de la position du sommet Nord-Ouest de l'image à afficher.
void MLV_draw_partial_animation ( MLV_Animation animation,
unsigned int  layer,
int  source_x,
int  source_y,
int  source_width,
int  source_height,
MLV_Image image,
int  x,
int  y 
)

Dessine à l'écran à une position donnée, une portion de l'image actuellement lue par l'animateur et extraite de la couche spécifiée en paramètre.

Paramètres:
animation L'animateur contenant l'animation à aficher
layer Couche de l'image.
image image sur laquel il faut dessiner l'animation
source_x Coordonnée en X de la position de la portion à recopier
source_y Coordonnée en Y de la position de la portion à recopier
source_width Largeur de la portion à recopier
source_height Hauteur de la portion à recopier
x Coordonnée en X de la position du sommet Nord-Ouest de l'image à afficher.
y Coordonnée en Y de la position du sommet Nord-Ouest de l'image à afficher.
void MLV_draw_partial_animation_on_image ( MLV_Animation animation,
unsigned int  layer,
int  source_x,
int  source_y,
int  source_width,
int  source_height,
MLV_Image image,
int  x,
int  y 
)

Dessine sur une image donnée à une position donnée une portion de l'image actuellement lue par l'animateur et située à une couche donnée.

Paramètres:
animation L'animateur contenant l'animation à aficher
layer Couche de l'image.
image image sur laquel il faut dessiner l'animation
source_x Coordonnée en X de la position de la portion à recopier
source_y Coordonnée en Y de la position de la portion à recopier
source_width Largeur de la portion à recopier
source_height Hauteur de la portion à recopier
x Coordonnée en X de la position du sommet Nord-Ouest de l'image à afficher.
y Coordonnée en Y de la position du sommet Nord-Ouest de l'image à afficher.
void MLV_free_animation ( MLV_Animation animation  ) 

Libère l'espace mémoire alloué pour un animateur donné.

Paramètres:
animation L'animateur à suprimer
Exemples:
advanced/11_animation_book.c, et advanced/9_animation.c.
void MLV_free_animation_book ( MLV_Animation_book animation_book  ) 

Libère la memoire contenue par le livre d'animation.

Paramètres:
animation_book Le livre d'animation.
Exemples:
advanced/11_animation_book.c.
MLV_Animation_sequence* MLV_get_animation_from_id ( MLV_Animation_book animation_book,
int  id 
)

Renvoie une animation donnée contenue dans le livre d'animation.

Paramètres:
animation_book Le livre d'animation.
id L'identifiant
Renvoie:
La séquence d'animation.
MLV_Animation_sequence* MLV_get_animation_from_name ( MLV_Animation_book animation_book,
const char *  name 
)

Renvoie une animation donnée contenue dans le livre d'animation.

Paramètres:
animation_book Le livre d'animation.
name Le nom de l'animation
Renvoie:
La séquence d'animation.
Exemples:
advanced/11_animation_book.c.
int MLV_get_frame_delay_from_animation_sequence ( MLV_Animation_sequence animation,
unsigned int  position 
)

Renvoie le temps d'affichage de l'image présente à une position donnée d'une animation donnée.

Paramètres:
animation Animation à modifier
position position de l'image dans l'animation
Renvoie:
le temps d'affichage de l'image
void MLV_get_frame_from_animation_sequence ( MLV_Animation_sequence animation,
unsigned int  position,
unsigned int  layer,
MLV_Image **  image,
unsigned int *  delay 
)

Recupère l'image et le temps présents à une position et une couche donnée d'une animation.

Paramètres:
animation Animation à modifier
layer Couche de l'image.
position position de l'image dans l'animation
image image a ajouter dans l'animation
delay temps d'affichage de l'image
MLV_Image* MLV_get_frame_image_from_animation_sequence ( MLV_Animation_sequence animation,
unsigned int  position,
unsigned int  layer 
)

Renvoie l'image présente à une position et une couche donnée d'une animation donnée.

Paramètres:
animation Animation à modifier
position position de l'image dans l'animation
layer Couche de l'image.
Renvoie:
l'image extraite.
const char* MLV_get_name_from_id_animation ( MLV_Animation_book animation_book,
int  id_animation 
)

Renvoie le nom d'un animation à partir de son identifiant dans le livre d'animation.

Paramètres:
animation_book Le livre d'animation.
id_animation L'identifiant de l'animation dans le livre.
Renvoie:
Le nom de l'animation.
int MLV_get_number_of_animation_sequences ( MLV_Animation_book animation_book  ) 

Détermine le nombre d'animations contenus par le livre d'animation.

Paramètres:
animation_book Le livre d'animation.
Renvoie:
le nombre d'animations contenus par le livre d'animation.
MLV_Animation_book* MLV_load_animation_book ( const char *  xml_file,
const char *  image_directory,
const char *  sound_directory 
)

Charge en memoire un livre contenant une multitude d'animations.

Bogue:
Lorsque le fichier xml contient des données corrompus, la fonction ne le detecte pas, continu de travailler avec les données corrompu et finie par faire une erreur de segmentation.
Paramètres:
xml_file Fichiers xml.
image_directory Le dossier ou se trouve toutes les images du livre d'animation. Si NULL est passe en parametre, alors le programme cherche dans le repertoire du fichier de configuration du livre d'animation.
sound_directory Le dossier ou se trouve toutes les échantillons sonore du livre d'animation. Si NULL est passe en parametre, alors le programme cherche dans le repertoire du fichier de configuration du livre d'animation.
Renvoie:
L'adresse de la sructure de données contenant toutes les animations.
Exemples:
advanced/11_animation_book.c.
void MLV_next_frame ( MLV_Animation animation  ) 

Force l'animateur à passer à l'image suivante.

Paramètres:
animation L'animateur
void MLV_play_animation ( MLV_Animation animation  ) 

Demare la lecture de l'animation lu par l'animateur.

Paramètres:
animation L'animateur
Exemples:
advanced/11_animation_book.c, et advanced/9_animation.c.
void MLV_play_revert_animation ( MLV_Animation animation  ) 

Demande à un animateur donné de jouer l'animation à l'envers.

Paramètres:
animation L'animateur
Exemples:
advanced/9_animation.c.
void MLV_previous_frame ( MLV_Animation animation  ) 

Force l'animateur à revenir sur l'image précédente.

Paramètres:
animation L'animateur
void MLV_rewind_animation ( MLV_Animation animation  ) 

Demande à l'animateur de reprendre la lecture de l'animation depuis le début.

Paramètres:
animation L'animateur
void MLV_stop_animation ( MLV_Animation animation  ) 

Met en pause la lecture d'un animateur donné.

Paramètres:
animation L'animateur
void MLV_turn_off_sound_on_animation ( MLV_Animation animation,
unsigned int  channel 
)

Désactive le son du canal d'une animation donnée.

Paramètres:
animation L'animateur concerné.
channel Le canal concerné.
Exemples:
advanced/11_animation_book.c.
void MLV_turn_on_sound_on_animation ( MLV_Animation animation,
unsigned int  channel 
)

Active le son du canal d'une animation donnée.

Paramètres:
animation L'animateur concerné.
channel Le canal concerné.
Exemples:
advanced/11_animation_book.c, et advanced/9_animation.c.
void MLV_update_animation ( MLV_Animation animation  ) 

Met a jour l'animateur.

L'horloge interne de l'animateur vois son temps incrémenter de 1 unité exactement.

La position de lecture de l'animation est mis a jour en conséquence de la mis à jour de l'horloge interne.

Paramètres:
animation L'animateur à mettre à jour
Exemples:
advanced/11_animation_book.c, et advanced/9_animation.c.