GdipSaveAddImage()



Syntaxe
Resultat.i = GdipSaveAddImage(*image, *newImage, @encoderParams.EncoderParameters)

Paramètres

*image

[in] Pointeur sur un objet image qui défini l'image d'origine à laquelle on ajoutera une page (une image dans la séquence).

*newImage

[in] Pointeur sur un objet image qui sera ajoutée à la séquence d'images de l'image identifiée par le paramètre *image. 

encoderParams.EncoderParameters

[in] Structure EncoderParameters qui contient des paramètres à utiliser par l'encodeur.

Description

Cette fonction permet d'ajouter une image à un fichier image ou à un stream contenant une séquence d'images (multiple-frame, format TIFF).

Gdi+ 1.0 ne supporte pas les gif à séquence d'images (images multiples).

Avec le format de fichiers TIFF, vous pouvez sauvegarder une séquence d'images (multiple-frame) dans un fichier unique. Chaque image peut être appelée une page. Pour sauvegarder la première page dans un fichier, utilisez la fonction GdipSaveImageToFile() ou dans une stream utilisez la fonction GdipSaveImageToStream(), ces fonctions permettant aussi de définir le fichier ou le stream comme étant une séquence d'images.

Pour sauvegarder les pages suivantes, utilisez la fonction décrite ici : GdipSaveAddImage().
Le premier paramètre (*image) de la fonction est l'identifiant GDI+ de l'image ayant servi à créer le fichier (fonction GdipSaveImageToFile()) ou le stream (GdipSaveImageToStream())
Le second paramètre (*newImage) de la fonction est l'identifiant GDI+ de l'image à ajouter à la séquence d'images.
Le dernier paramètre (encoderParams.EncoderParameters) est une variable de type EncoderParameters (ce n'est pas un pointeur).

Ce dernier paramètre possède deux éléments :
Le paramètre Count.l indique le nombre d'éléments du tableau Parameter.EncoderParameter qui est le deuxième élément de la structure EncoderParameters.
Le paramètre Parameter.EncoderParameter[1] est un tableau d'éléments EncoderParameter. Comme le nombre d'éléments de ce tableau n'est pas connu à l'avance, il est déclaré dans la structure avec un seul élément EncoderParameter. Si le nombre d'éléments est supérieur à 1, on utilisera un code similaire à celui donné après la définition de la structure EncoderParameters.
Le paramètre Parameter.EncoderParameter[1] permet de définir les valeurs requises par l'encodeur d'image utilisées pour l'opération de sauvegarde de l'image ajoutée à la séquence. L'encodeur sera également utilisé pour sauvegarder la première page, pour chaque ajout d'une page et également pour la fermeture du fichier qui est réalisée avec la fonction GdipSaveAdd().
Voici les différentes étapes à respecter pour sauvegarder une séquence d'image au format TIFF :
1. Retrouver l'identifiant CLSID pour l'encodeur voulu.
    La procédure GetEncoderClsid(format.s, *Clsid.CLSID) de l'exemple permet de retrouver cet identifiant
2. Charger les différentes images.
3. Remplir le tableau d'encoder (variable de type EncoderParameters) qui pour le cas de la création d'une séquence d'image TIFF, n'a qu'un seul élément.
    Le premier élément de la structure EncoderParameters vaut 1 car il n'y a qu'un seul élément de type EncoderParameter.
    Le tableau EncoderParameter sera rempli comme ceci :
    L'élément Guid sera rempli avec la valeur de l'identifiant EncoderSaveFlag (la valeur est définie dans le fichier PB des GUID).
    Ce paramètre est rempli avec la commande PB CopyMemory().
    L'élément EncoderParameter\NumberOfValues est mis à 1 car il indique le nombre d'éléments pointé par le membre *value de la structure qui est ici de 1.
    L'élément EncoderParameter\Type vaut #EncoderparameterValueTypeLong car le type de l'élément pointé par le membre *value de la structure est un mot de 32 bits.
    L'élément EncoderParameter\Value (pointeur) est l'adresse d'une variable de type long dont la valeur changera en fonction de l'opération à effectuer.
4. Sauvegarde de la première page (image). La variable pointée par le paramètre EncoderParameter\Value sera mise à #EncoderValueMultiFrame définissant ainsi l'image comme une séquence d'image.
    La fonction GdipSaveImageToFile() sera utilisée pour créer le fichier avec la première image.
    Cette fonction utilise comme premier paramètre l'ID GDI+ de l'image
    Second paramètre le nom du fichier avec le chemin
    Troisième paramètre l'ID CLSID de l'encodeur voulu (retrouvé avec la procédure GetEncoderClsid(format.s, *Clsid.CLSID) qui est définie dans le fichier gdiplus.pbi).
    Dernier paramètre l'adresse de la variable EncoderParameters.
5. Autant d'appels successifs à la fonction GdipSaveAddImage() qu'il y a d'images à ajouter.
    Cette fonction a 3 paramètres :
    Premier paramètre : l'ID GDI+ de la première image (utilisée avec la fonction GdipSaveImageToFile().
    Second paramètre : l'ID GDI+ de l'image à ajouter.
    Dernier paramètre l'adresse de la variable EncoderParameters.
    Pour l'ajout d'image, la variable pointée par le paramètre EncoderParameter\Value sera mise à :
       #EncoderValueFrameDimensionPage pour une séquence d'image TIIF

6. Fermeture du fichier avec la fonction GdipSaveAdd().
    Cette fonction a 2 paramètres :
    Premier paramètre : l'ID GDI+ de la première image (utilisée avec la fonction GdipSaveImageToFile() ou GdipSaveImageToStream()).
    Second paramètre : l'adresse de la variable EncoderParameters. Pour fermer le fichier, la variable pointée par le paramètre EncoderParameter\Value sera mise à #EncoderValueFlush.

Remarques :

Le fichier sauvegardé ne dois pas être le même fichier que celui ayant servi à créer la première image utilisée par la fonction GdipSaveImageToFile().

L'exemple charge 4 images de format et taille différentes, les affiche en taille réduite et permet en appuyant sur le bouton de sauvegarder une image au format TIFF regroupant les 4 images.

Résultat de la fonction

Si la fonction réussit, elle retourne #Ok qui est une constante de l'énumération status.
Si la fonction échoue, elle retourne une des autres valeurs de l'énumération status.

PB - OS

PureBasic v4.30 bêta 4 (Windows - x86)
Testé avec Windows Vista édition familiale Premium