Provided by: libmlv3-dev_3.1.0-3_amd64 bug

NAME

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

SYNOPSIS

   Définitions de type
       typedef struct _MLV_Image MLV_Image
           Définit le type Image dans la bibliothèque MLV.

   Fonctions
       MLV_Image * MLV_load_image (const char *file_image)
           Charge en mémoire une image contenue dans un fichier.
       int MLV_save_image_as_bmp (const MLV_Image *image, const char *file_image)
           Sauvegarde une image dans une fichier BMP.
       MLV_Image * MLV_create_image (int width, int height)
           Créer une image de composante alpha opaque.
       void MLV_free_image (MLV_Image *image)
           Libère la mémoire utilisée par l'image.
       MLV_Image * MLV_copy_image (const MLV_Image *image)
           Copie une 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.
       void MLV_get_image_size (const MLV_Image *image, int *width, int *height)
           Retourne la taille d'une image donnée.
       int MLV_get_image_width (const MLV_Image *image)
           Retourne la largeur d'une image donnée.
       int MLV_get_image_height (const MLV_Image *image)
           Retourne la hauteur d'une image donnée.
       void MLV_resize_image (MLV_Image *image, int width, int height)
           Redimensionne l'image en ne respectant pas les proportions de l'image originale.
       void MLV_vertical_image_mirror (MLV_Image *image)
           Modifie l'image en réalisant une réflexion verticale.
       void MLV_horizontal_image_mirror (MLV_Image *image)
           Modifie l'image en réalisant une réflexion horizontale.
       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.
       void MLV_scale_image (MLV_Image *image, double scalar)
           Modifie l'image à l'aide d'une homotétie ( Étire l'image )
       void MLV_rotate_image (MLV_Image *image, double rotation)
           Éffectue une rotation sur une image donnée.
       void MLV_rotate_and_scale_image (MLV_Image *image, double rotation, double scalar)
           Éffectue une rotation suivie d'une homotétie.
       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.
       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.
       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.
       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.
       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.
       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.
       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.
       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.
       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.
       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.
       SDL_Surface * MLV_get_image_data (MLV_Image *image)
           Renvoie les données internes de l'image.
       void MLV_save_screen ()
           Enregistre l'image de l'écran dans un presse papier interne à la bibliothèque MLV..
       MLV_Image * MLV_get_screen ()
           Renvoie l'image qui se trouve à l'écran.
       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.

   MLV_Image* MLV_get_screen ()
       Renvoie l'image qui se trouve à l'écran.

       Renvoie:
           L'image qui est affiché à l'écran.

   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.

Auteur

       Généré automatiquement par Doxygen pour MLV-3.1.0 à partir du code source.