Chose promise, chose due. Voici un petit tuto pour tous ceux qui souhaitent utiliser les fichiers au format X. Je les trouve très pratiques et je les utilise depuis pas mal de temps. Jusqu’à une période récente, j’utilisais la version dite "legacy", qui est dite "deprecated" par Microsoft. J’ai donc entrepris de mettre à niveau mes applis. Comme je suis passé entre temps du Pascal au C++, ça n’a pas été sans mal.
Je n’ai trouvé aucun tuto pour m’aider. Alors pourquoi ne pas en écrire un moi-même ?
Tout d’abord, qu’est-ce qu’un fichier au standard .X ?
Le standard X permet de stocker et d’accéder à des données organisées suivant une structure arborescente.
Préliminaire : les templates de données
Pour utiliser un fichier .X, on commence par définir des templates de données (à noter qu’il existe des templates "prêts-à-porter" correspondant aux principales structures utilisées par DirectX).
Exemple :
Dans l’exemple ci-dessus, le premier template (d_elem) correspond à une structure C++ basique :Code:
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
Le second correspond à une liste desdites structures.Code:
2
3
4
5
6
7
8
9
10
Le troisième est un format ouvert : il indique que l’on pourra ajouter à la donnée enregistrée une donnée "enfant". Cette donnée "enfant" pourra, à son tour, comporter une liste ou une autre donnée enfant…
L’entête « xof 0303txt 0032 » définit le format du fichier (il existe une version binaire et une version texte).
Les GUID identifiant les templates sont obtenus en utilisant l’utilitaire GuidGen de Visual Studio.
Il faut également créer des objets "GUID" qui permettront de manipuler ces templates plus facilement par la suite :
Enregistrement des donnéesCode:
2
3
4
5
6
7
Les étapes de l’enregistrement :
- On crée une interface ID3DXFile.
- On enregistre les templates dans l’objet correspondant à cet interface.
- On crée à partir de cet objet D3DXFile un objet D3DXFileSaveObject (interface ID3DXFileSaveObject).
Il est important de comprendre que c’est cet objet D3DXFileSaveObject qui va recueillir l’ensemble des données que l’on enregistrera ensuite dans un fichier sur le disque dur.
La signification de D3DXF_FILESAVE_TOFILE et D3DXF_FILEFORMAT_TEXT est donnée dans la documentation de DirectX.Code:
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
On dispose paintenant d’un objet qui va recevoir toutes les données à enregistrer. On le conserve tout le temps nécessaire pour lui transférer toutes ces données. Lorsqu’on aura fini, on procèdera au transfert sur le disque :
Les deux "Release()" sont indispensables pour libérer les objets COM auxquels on accède au travers des interfaces mentionnés plus haut. En particulier, si l’on ne relâche pas pSaveObject, le transfert sur le disque ne sera pas effectué malgré le Save() qui précède.Code:
2
3
4
Une fois le Save() réalisé, il n’est plus possible d’ajouter d’autres données au fichier à moins de recommencer un cycle complet.
Comment ajoute-t’on les données ?
On encapsule les données à enregistrer dans des objets D3DXFileSaveData. On peut créer de tels objets à partir de notre objet D3DXFileSaveObject "racine" mais on peut également créer un objet D3DXFileSaveData comme enfant d’un autre objet D3DXFileSaveData. Ceci permet de créer une arborescence.
Voici le mécanisme général : prenons l’exemple d’une liste de structures myelem (qu’on appelle listelem).
Récapitulons :Code:
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
- on crée un buffer de longueur suffisante pour accueillir toute la liste (y compris le nombre d’éléments),
- on y recopie bout à bout les structures qui constituent la liste,
- on crée un objet D3DXFileSaveData dérivant directement de pSaveObject en précisant le GUID associé à son template, la taille du buffer à transférer et l’adresse de ce buffer. La méthode AddDataObject renvoie un pointeur sur l’objet ainsi créé. Si cet objet n’a pas d’enfant, on ne fera rien de ce pointeur. Si celui-ci a un enfant, on l’utilisera pour dériver un autre objet D3DXFileSaveData.
Reprenons l’exemple du template d_conf (cf ci-dessus). La structure de ce template permet d’ajouter un objet "enfant". Pour ce faire, on procède de la manière suivante :
Dans l’exemple qui précède, on retrouve dans StoreChild_conf (méthode perso) la même mécanique de création et d’écriture dans un buffer mais, cette fois, le buffer est attribué à un objet D3DXFileSaveData obtenu à partir du pSaveData passé en argument.Code:
2
3
4
5
6
7
8
9
10
11
12
Récupération des donnéesCode:
2
3
4
5
6
7
8
9
10
Ce n’est pas sorcier : on détricote…
Comme pour la sauvegarde, on passe par une interface D3DXFile. Cette fois, on ne crée pas un objet D3DXFileSaveObject mais un objet D3DXFileEnumObject. On n’a pas non plus besoin d’enregistrer les templates : on peut les récupère à partir de cet objet D3DXFileEnumObject.
La suite se comprend facilement si on a pigé le mécanisme de sauvegarde. On commence par récupérer le nombre d’objets "de premier niveau" de l’arborescence.Code:
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
Ceci permet de rentrer dans une boucle de récupération de ces objets. On utilise pour cela des objets de type D3DXFileData (le pendant des D3DXFileSaveData).Code:
2
3
4
La fonction ParseListElem (méthode perso) permet d’accéder aux données encapsulées dans l’objet pDataObj. Pour récupérer et recopier ces données, il faut d’abord verrouiller cet objet en mémoire. On récupère alors un pointeur sur les données et la taille du bloc correspondant. On termine en déverrouillant l’objet.Code:
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
On le voit, tout cela n’est pas sorcier. Les anglo-saxons disent : this is not rocket science.Code:
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
Si l’objet de rang "1" a des "enfants", on l’analyse de la même façon qu’on l’a fait pour l’énumérateur. Simplement, cette fois on utilise les méthodes de ID3DXFileData et non plus celles de ID3DXFileEnumObject.
On aura compris que l’intérêt du GetType est de permettre de faire un switch pour choisir le "parser" adapté.Code:
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
Voili voilà. On pensera juste à faire un Release() sur les objets .COM que l’on a créés, on ne sait jamais…
Ce mini tuto est terminé, j’espère qu’il vous aidera. Je ne suis pas un expert du fichier X (au sens propre comme au figuré) mais comme j’ai un peu galéré à mettre au point mon programme, autant en faire profiter les autres !
