# Documentation de la bibliothèque MLV-1.2.1

- Presentation
- Téléchargement
- Installation
- Compilation
- Exemples
- API
- Liste des fonctions
- bogues
- FAQ
- contacts

Définitions de type | Fonctions
Référence du fichier MLV_image.h

Ce fichier définit tous les prototypes concernant les fonctions permettant d'insérer des images. Plus de détails...

Aller au code source de ce fichier.

## Définitions de type
typedef struct _MLV_Image | MLV_Image
| Définit le type Image dans la bibliothèque MLV. Plus de détails...

## Fonctions
MLV_Image * | MLV_load_image (const char *file_image)
| Charge en mémoire une image contenue dans un fichier. Plus de détails...
int | MLV_save_image_as_bmp (const MLV_Image *image, const char *file_image)
| Sauvegarde une image dans une fichier BMP. Plus de détails...
MLV_Image * | MLV_create_image (int width, int height)
| Créer une image de composante alpha opaque. Plus de détails...
void | MLV_free_image (MLV_Image *image)
| Libère la mémoire utilisée par l'image. Plus de détails...
MLV_Image * | MLV_copy_image (const MLV_Image *image)
| Copie une image. Plus de détails...
MLV_Image * | MLV_copy_partial_image (const MLV_Image *image, int x, int y, int width, int height)
| Copie une partie de l'image. Plus de détails...
void | MLV_get_image_size (const MLV_Image *image, int *width, int *height)
| Retourne la taille d'une image donnée. Plus de détails...
int | MLV_get_image_width (const MLV_Image *image)
| Retourne la largeur d'une image donnée. Plus de détails...
int | MLV_get_image_height (const MLV_Image *image)
| Retourne la hauteur d'une image donnée. Plus de détails...
void | MLV_resize_image (MLV_Image *image, int width, int height)
| Redimensionne l'image en ne respectant pas les proportions de l'image originale. Plus de détails...
void | MLV_vertical_image_mirror (MLV_Image *image)
| Modifie l'image en réalisant une réflexion verticale. Plus de détails...
void | MLV_horizontal_image_mirror (MLV_Image *image)
| Modifie l'image en réalisant une réflexion horizontale. Plus de détails...
void | MLV_resize_image_with_proportions (MLV_Image *image, int width, int height)
| Cette fonction redimensionne l'image en repsectant les proportions de l'image originale. Plus de détails...
void | MLV_scale_image (MLV_Image *image, double scalar)
| Modifie l'image à l'aide d'une homotétie ( Étire l'image ) Plus de détails...
void | MLV_rotate_image (MLV_Image *image, double rotation)
| Éffectue une rotation sur une image donnée. Plus de détails...
void | MLV_rotate_and_scale_image (MLV_Image *image, double rotation, double scalar)
| Éffectue une rotation suivie d'une homotétie. Plus de détails...
void | MLV_scale_xy_image (MLV_Image *image, double scalar_x, double scalar_y)
| Étire l'image suivant l'axe X et l'axe Y avec des coefficients de proportionnalité différents pour les deux axes. Plus de détails...
void | MLV_rotate_and_scale_xy_image (MLV_Image *image, double rotation, double scalar_x, double scalar_y)
| Éffectue une rotation, puis étire l'image suivant l'axe X et l'axe Y avec des coefficients de proportionnalité différents pour les deux axes. Plus de détails...
void | MLV_draw_image (const MLV_Image *image, int x, int y)
| Dessine une image donnée à une position donnée de la fenêtre. Plus de détails...
void | MLV_draw_partial_image (const MLV_Image *image, int x_source, int y_source, int width_source, int height_source, int x, int y)
| Dessine une partie d'une image donnée à une position donnée sur la fenêtre. Plus de détails...
void | MLV_set_alpha_on_image (MLV_Alpha alpha, MLV_Image *image)
| La composante alpha de l'image est remplacée par une composante alpha homogène dont la valeur est donnée en paramètre. Plus de détails...
void | MLV_set_pixel_on_image (int x, int y, MLV_Color color, MLV_Image *image)
| Écrase les composantes rouge, bleue, vert et alpha d'un pixel par celles passées en paramètre de la fonction. Plus de détails...
void | MLV_get_pixel (int x, int y, int *red, int *green, int *blue, int *alpha)
| Renvoie la couleur du pixel de l'écran pour une position donnée. Plus de détails...
void | MLV_get_pixel_on_image (const MLV_Image *image, int x, int y, int *red, int *green, int *blue, int *alpha)
| Renvoie la couleur du pixel présent à une position donnée d'une image donnée. Plus de détails...
void | MLV_draw_partial_image_on_image (const MLV_Image *source_image, int source_x, int source_y, int width, int height, MLV_Image *destination_image, int destination_x, int destination_y)
| Dessine une image dans une image destination. Plus de détails...
void | MLV_draw_image_on_image (const MLV_Image *source_image, MLV_Image *destination_image, int destination_x, int destination_y)
| Dessine une image dans une image destination. Plus de détails...
SDL_Surface * | MLV_get_image_data (MLV_Image *image)
| Renvoie les données internes de l'image. Plus de détails...
void | MLV_save_screen ()
| Enregistre l'image de l'écran dans un presse papier interne à la bibliothèque MLV..
void | MLV_load_screen ()
| Charge l'image présent dans le presse papier interne de la bibliothèque MLV.

## Description détaillée

Ce fichier définit tous les prototypes concernant les fonctions permettant d'insérer des images.

Auteur
  Adrien Boussicault
  Marc Zipstein

## Documentation des définitions de type

typedef struct _MLV_Image MLV_Image

Définit le type Image dans la bibliothèque MLV.

Une image dans la bibliothèque MLV est un tableau à deux dimentions dont chaque entée contient une couleur (voir MLV_Color). Nous rapellons que dans MLV les couleurs sont définies à l'aide de 4 entiers compris entre 0 et 256 exclu, que l'on appelle composantes :

- la composante Rouge ( R );
- la composante Verte ( G );
- la composant Blue ( B );
- la composante Alpha, c'est la transparence ( A ).

## Documentation des fonctions

MLV_Image* MLV_copy_image | ( | const MLV_Image * | image) |  |

Copie une image.

Cette fonction créé une nouvelle image qui est la copie conforme de l'image passée en paramètre. La gestion de la mémoire de l'image créée est laissée à l'utilisateur.

Paramètres

  image | L'image à copier.

Renvoie
  La copie de l'image.

MLV_Image* MLV_copy_partial_image | ( | const MLV_Image * | image,
|  | int | x,
|  | int | y,
|  | int | width,
|  | int | height
| ) |  |

Copie une partie de l'image.

Cette fonction créé une nouvelle image qui est la copie conforme d'une partie de l'image passée en paramètre. La gestion de la mémoire de l'image créée est laissée à l'utilisateur.

Paramètres

  image | L'image à copier.
  x | Abscisse du sommet Nord-Ouest de la partie de l'image à copier
  y | Ordonnée du sommet Nord-Ouest de la partie de l'image à copier
  width | Largeur de la partie de l'image à copier
  height | Hauteur de la partie de l'image à copier

Renvoie
  La copie de l'image.

Exemples:
  advanced/09_animation.c.

MLV_Image* MLV_create_image | ( | int | width,
|  | int | height
| ) |  |

Créer une image de composante alpha opaque.

Paramètres

  width | Largeur de l'image
  height | Hauteur de l'image

Renvoie
  L'image créé.

Exemples:
  advanced/08_zone_click.c.

void MLV_draw_image | ( | const MLV_Image * | image,
|  | int | x,
|  | int | y
| ) |  |

Dessine une image donnée à une position donnée de la fenêtre.

Paramètres

  image | Image à dessiner.
  x | Coordonnée en X de la position dans la fenêtre de sommet Nord-Ouest de l'image.
  y | Coordonnée en Y de la position dans la fenêtre du sommet Nord-Ouest de l'image.

Exemples:
  advanced/06_image.c, advanced/07_transparency.c, et advanced/08_zone_click.c.

void MLV_draw_image_on_image | ( | const MLV_Image * | source_image,
|  | MLV_Image * | destination_image,
|  | int | destination_x,
|  | int | destination_y
| ) |  |

Dessine une image dans une image destination.

Paramètres

  source_image | Image source
  destination_image | Image destination
  destination_x | Abscisse de la position où devra être recopier l'image. Il s'agit de la futur position du sommet nord-Ouest de la portion d'image à recopier.
  destination_y | Ordonnée de la position où devra être recopier l'image. Il s'agit de la futur position du sommet nord-Ouest de la portion d'image à recopier.

void MLV_draw_partial_image | ( | const MLV_Image * | image,
|  | int | x_source,
|  | int | y_source,
|  | int | width_source,
|  | int | height_source,
|  | int | x,
|  | int | y
| ) |  |

Dessine une partie d'une image donnée à une position donnée sur la fenêtre.

Paramètres

  image | L'image à afficher sur la fenêtre
  x_source | La coordonnée en X du sommet Nord-Ouest de la partie de l'image à afficher.
  y_source | La coordonnée en Y du sommet Nord-Ouest de la partie de l'image à afficher.
  width_source | La largeur de la partie de l'image à afficher.
  height_source | La hauteur de la partie de l'image à afficher.
  x | Coordonnée en X de la position dans la fenêtre du sommet Nord-Ouest de la partie de l'image à afficher.
  y | Coordonnée en Y de la position dans la fenêtre du sommet Nord-Ouest de la partie de l'image à afficher.

void MLV_draw_partial_image_on_image | ( | const MLV_Image * | source_image,
|  | int | source_x,
|  | int | source_y,
|  | int | width,
|  | int | height,
|  | MLV_Image * | destination_image,
|  | int | destination_x,
|  | int | destination_y
| ) |  |

Dessine une image dans une image destination.

Paramètres

  source_image | Image source
  source_x | Abscisse du sommet nord-Ouest de la position de la portion d'image à recopier
  source_y | Ordonné du sommet nord-Ouest de la position de la portion d'image à recopier
  width | Largeur de la position à recopier
  height | Hauteur de la position à recopier
  destination_image | Image destination
  destination_x | Abscisse de la position où devra être recopier l'image. Il s'agit de la futur position du sommet nord-Ouest de la portion d'image à recopier.
  destination_y | Ordonnée de la position où devra être recopier l'image. Il s'agit de la futur position du sommet nord-Ouest de la portion d'image à recopier.

void MLV_free_image | ( | MLV_Image * | image) |  |

Libère la mémoire utilisée par l'image.

Paramètres

  image | Image à supprimer de la mémoire

Exemples:
  advanced/06_image.c, advanced/07_transparency.c, advanced/08_zone_click.c, et advanced/09_animation.c.

SDL_Surface* MLV_get_image_data | ( | MLV_Image * | image) |  |

Renvoie les données internes de l'image.

Cette fonction renvoie un pointeur vers la structure de donnée de la libriaire SDL codant une image.

N'utilisez cette fonction que si vous souhaitez effectuer une opération sur une image qui n'existe pas dans la bibliothèque MLV. En effet, modifier les données internes d'une image de type MLV_Image peut corrompre le fonctionnement de la bibliothèque MLV.

Vous pouvez alors utiliser les routines de la lirairie SDL pour modifier l'image. (http://libsdl.org)

Voici un exemple de code montrant comment il est possible de récupérer les composantes rouge, vert, bleu et alpha du pixel (3,4) de l'image.

int x=3, y=4;
SDL_Surface* surface = MLV_get_image_data( image );
Uint32 red, blue, green, alpha;
// Extracting color components from a 32-bit color value
SDL_PixelFormat *fmt;
Uint32 pixel;
SDL_LockSurface(surface);
fmt = surface->format;
pixel = *(((Uint32*) surface->pixels)+ y*surface->pitch/4 + x );
// Get Red component
red = pixel & fmt->Rmask; // Isolate red component
red = red >> fmt->Rshift; // Shift it down to 8-bit
red = red << fmt->Rloss; // Expand to a full 8-bit number
// Get Green component
green = pixel & fmt->Gmask; // Isolate green component
green = green >> fmt->Gshift; // Shift it down to 8-bit
green = green << fmt->Gloss; // Expand to a full 8-bit number
// Get Blue component
blue = pixel & fmt->Bmask; // Isolate blue component
blue = blue >> fmt->Bshift; // Shift it down to 8-bit
blue = blue << fmt->Bloss; // Expand to a full 8-bit number
// Get Alpha component
alpha = pixel & fmt->Amask; // Isolate alpha component
alpha = alpha >> fmt->Ashift; // Shift it down to 8-bit
alpha = alpha << fmt->Aloss; // Expand to a full 8-bit number
MLV_unlock_image( image );

Paramètres

  image | L'image dont vous souhaitez récuperer les données internes.

Renvoie
  un pointeur vers une image de la bibliothèque SDL.

int MLV_get_image_height | ( | const MLV_Image * | image) |  |

Retourne la hauteur d'une image donnée.

Paramètres

  image | L'image à analyser.

Renvoie
  La hauteur de l'image

void MLV_get_image_size | ( | const MLV_Image * | image,
|  | int * | width,
|  | int * | height
| ) |  |

Retourne la taille d'une image donnée.

Paramètres

  image | L'image pour laquelle la fonction doit retourner sa taille.
  width | La largeur de l'image.
  height | La hauteur de l'image.

Exemples:
  advanced/06_image.c, et advanced/08_zone_click.c.

int MLV_get_image_width | ( | const MLV_Image * | image) |  |

Retourne la largeur d'une image donnée.

Paramètres

  image | L'image à analyser.

Renvoie
  La largeur de l'image.

void MLV_get_pixel | ( | int | x,
|  | int | y,
|  | int * | red,
|  | int * | green,
|  | int * | blue,
|  | int * | alpha
| ) |  |

Renvoie la couleur du pixel de l'écran pour une position donnée.

Les paramètres red, blue, green et alpha peuvent être égaux à 0. Dans ce cas, ils sont ignorés.

Paramètres

  x | Coordonnée en X de la position du pixel.
  y | Coordonnée en Y de la position du pixel.
  red | Composante rouge du pixel.
  green | Composante verte du pixel.
  blue | Composante bleue du pixel.
  alpha | Composante alpha (transparence) du pixel.

void MLV_get_pixel_on_image | ( | const MLV_Image * | image,
|  | int | x,
|  | int | y,
|  | int * | red,
|  | int * | green,
|  | int * | blue,
|  | int * | alpha
| ) |  |

Renvoie la couleur du pixel présent à une position donnée d'une image donnée.

Les paramètres red, blue, green et alpha peuvent être égaux à NULL. Dans ce cas, ils sont ignorés.

Paramètres

  image | Image à inspecter.
  x | Coordonnée en X de la position du pixel à inspecter.
  y | Coordonnée en Y de la position du pixel à inspecter.
  red | Composante rouge du pixel.
  green | Composante verte du pixel.
  blue | Composante bleue du pixel.
  alpha | Composante alpha (transparence) du pixel.

Exemples:
  advanced/08_zone_click.c.

void MLV_horizontal_image_mirror | ( | MLV_Image * | image) |  |

Modifie l'image en réalisant une réflexion horizontale.

Paramètres

  image | L'image à modifier.

MLV_Image* MLV_load_image | ( | const char * | file_image) |  |

Charge en mémoire une image contenue dans un fichier.

Cette fonction permet de charger les images des formats suivants: ICO(Icon)/CUR(Cursor)/BMP, PNM (PPM/PGM/PBM), XPM, LBM(IFF ILBM), PCX, GIF, JPEG, PNG, TGA, TIFF, and XV.

Bogue:
  Cette fonction provoque une erreur de segmentation si elle est utilisée avant MLV_create_window(). Pour l'instant, nous vous conseillons d'utiliser cette fonction apres MLV_create_window().

Bogue:
  Il est possible que cette fonction n'arrive pas à charger correctement les images qui ne sont pas en 32 bits (RGBA) - bug à tester.

Bogue:
  BUG PRESENT SOUS WINDOWS ET MACOS X : Lorsque la composante alpha d'un pixel est à 0, MLV_load_image met à 0 les composantes Rouge, Verte et bleue du pixel associé. Ce bug provient de la bibliothèque SDL_image.

Paramètres

  file_image | Chemin d'accès du fichier contenant l'image.

Renvoie
  L'image chargée.

Exemples:
  advanced/06_image.c, advanced/07_transparency.c, advanced/08_zone_click.c, et advanced/09_animation.c.

void MLV_resize_image | ( | MLV_Image * | image,
|  | int | width,
|  | int | height
| ) |  |

Redimensionne l'image en ne respectant pas les proportions de l'image originale.

La hauteur et la largeur de la nouvelle image deviennent respectivement la hauteur et la largeur passées en paramètres.

Paramètres

  image | L'image à redimentionner.
  width | La largeur de l'image.
  height | La hauteur de l'image.

void MLV_resize_image_with_proportions | ( | MLV_Image * | image,
|  | int | width,
|  | int | height
| ) |  |

Cette fonction redimensionne l'image en repsectant les proportions de l'image originale.

L'image résultat est la plus grande image possible incluse dans le rectangle de largeur width et de hauteur height.

L'utilisateur peut entrer un entier négatif pour les champs width et height. Ces champs ne sont alors pas pris en compte dans le redimensionnement de l'image. Dans ce cas, si le paramètre width (resp. height) est négatif, alors l'image finale aura pour largeur (resp. hauteur) la taille spécifiée dans le paramètre width (resp. height).

Paramètres

  image | L'image à redimentionner.
  width | La nouvelle largeur de l'image.
  height | La nouvlle hauteur de l'image.

Exemples:
  advanced/06_image.c.

void MLV_rotate_and_scale_image | ( | MLV_Image * | image,
|  | double | rotation,
|  | double | scalar
| ) |  |

Éffectue une rotation suivie d'une homotétie.

Paramètres

  image | L'image à modifier.
  rotation | L'angle de la rotation.
  scalar | Le coéfficient de proportionnalité de l'homotétie.

void MLV_rotate_and_scale_xy_image | ( | MLV_Image * | image,
|  | double | rotation,
|  | double | scalar_x,
|  | double | scalar_y
| ) |  |

Éffectue une rotation, puis étire l'image suivant l'axe X et l'axe Y avec des coefficients de proportionnalité différents pour les deux axes.

Paramètres

  image | L'image à modifier.
  rotation | L'angle de la rotaiton.
  scalar_x | Le coéfficient de proportionnalité de l'axe X.
  scalar_y | Le coéfficient de proportionnalité de l'axe Y.

void MLV_rotate_image | ( | MLV_Image * | image,
|  | double | rotation
| ) |  |

Éffectue une rotation sur une image donnée.

Paramètres

  image | L'image à modifier.
  rotation | L'angle de la rotation.

int MLV_save_image_as_bmp | ( | const MLV_Image * | image,
|  | const char * | file_image
| ) |  |

Sauvegarde une image dans une fichier BMP.

Bogue:
  Cette fonction ne sauvegarde pas la composante alpha.

Paramètres

  image | Image à sauvegarder
  file_image | Chemin d'accès du fichier contenant l'image.

Renvoie
  0 si c'est un succés, -1 s'il y a eut une erreur.

void MLV_scale_image | ( | MLV_Image * | image,
|  | double | scalar
| ) |  |

Modifie l'image à l'aide d'une homotétie ( Étire l'image )

Paramètres

  image | L'image à modifier.
  scalar | Coefficient de proportionalité de l'homotétie ( >1 l'image est agrandie, <1 l'image est rétrécie ).

void MLV_scale_xy_image | ( | MLV_Image * | image,
|  | double | scalar_x,
|  | double | scalar_y
| ) |  |

Étire l'image suivant l'axe X et l'axe Y avec des coefficients de proportionnalité différents pour les deux axes.

Paramètres

  image | L'image à modifier.
  scalar_x | Le coéfficient de proportionnalité de l'axe X.
  scalar_y | Le coéfficient de proportionnalité de l'axe Y.

void MLV_set_alpha_on_image | ( | MLV_Alpha | alpha,
|  | MLV_Image * | image
| ) |  |

La composante alpha de l'image est remplacée par une composante alpha homogène dont la valeur est donnée en paramètre.

La transparence joue un role lorsqu'une image est dessinée à l'écran, ou lorsqu'une image est recopiée à l'intérieure d'une autre image. Lorsque l'on recopie une image, les pixels du résultat final sont obtenus en faisant un barycentre entre le pixel de l'image source avec celui de l'image destination. Les poids des barycentres sont définis par la composante transparente ( composante alpha ) de l'image source. La transparence de l'image destination reste inchangée.

Par exemple,

    couleur pixel source : RGBA( 60,80,100,128 )
    couleur destination : RGBA( 0,20,40,30 )
    couleur final après recopie :
      RGBA(
        barycentre( 60,  128,  0,   256-128 ),
        barycentre( 80,  128,  20,  256-128 ),
        barycentre( 100, 128,  40,  256-128 ),
        30
     ) =
     RGBA(
         ( 60  * 128  +  0  * (256-128) ) / 256,
         ( 80  * 128  +  20 * (256-128) ) / 256,
         ( 100 * 128  +  40 * (256-128) ) / 256,
         30
     ) =
     RGBA( 30, 50, 70, 30 )

Paramètres

  image | L'image à modifier.
  alpha | La nouvelle composante alpha de l'image.

Exemples:
  advanced/07_transparency.c.

void MLV_set_pixel_on_image | ( | int | x,
|  | int | y,
|  | MLV_Color | color,
|  | MLV_Image * | image
| ) |  |

Écrase les composantes rouge, bleue, vert et alpha d'un pixel par celles passées en paramètre de la fonction.

Paramètres

  x | La coordonnée en x du pixel à modifier.
  y | La coordonnée en y du pixel à modifier.
  color | La nouvelle couleur du pixel.
  image | L'image à modifier.

Exemples:
  advanced/08_zone_click.c.

void MLV_vertical_image_mirror | ( | MLV_Image * | image) |  |

Modifie l'image en réalisant une réflexion verticale.

Paramètres

  image | L'image à modifier.