C’est quoi les Dof Shapes ?

Les Dof shapes sont les images qui sont affichées sur une backboard en Led-strips addressables.

Elles permettent de simuler plusieurs effets de lumière existants par ailleurs (Flashers, Strobes, Beacon…)

Elles permettent aussi d’afficher des effets, des lettres, des symboles qui seront déclenchés par le Dof.

Comment ça marche ?

Création et Description des Shapes

Je me suis basé sur la documentation de référence des BitmapShapes de DirectOutput :

http://pinball.weilenmann.net/docu/DirectOutputWIP/namespace_direct_output_1_1_f_x_1_1_matrix_f_x_1_1_bitmap_shapes.html

Les deux fichiers principaux de description des DofShapes sont générés par le DofConfigTool quand vous faites votre configuration de Dof.

Ils s’apellent DirectOutputShapes.png et DirectOutputShapes.xml, vous les retrouverez avec les autres fichiers de config Dof dans le répertoire config de votre installation DirectOutput (souvent c:\DirectOutput).

Le premier fichier DirectOutputShapes.png contient tous les sprites de ces shapes.

Voilà à quoi il ressemble :

Vous avez une première grille où se trouve les grandes icônes, animées ou non, colorées ou non.

Les Shapes de cette grille sont de taille 16×16 pixels, la grille bleue est de 17×17 pixels (ça aura du sens plus tard pour les Shape animées, quand il faudra calculer l’offset d’une frame à une autre)

La seconde grille contient les lettres, chiffres et symboles qui vont permettre d’écrire des petits messages.

Il y a plusieurs tailles de caractères, seuls ceux de 7×7 pixels seront utilisés dans les fichier XML

Le second fichier DirectOutputShapes.xml va contenir des descripteurs qui vont expliquer ce qu’il faut afficher pour une Shape donnée.

C’est un fichier au format XML (comme son extension l’indique 😊), il se compose ainsi :

<ShapeDefinitions>	Début du fichier de description de shapes
<BitmapFilePattern>path</BitmapFilePattern>	Chemin d’accès vers l’image de référence, ici DirectOutputShapes.png, à ne pas changer
<Shapes>	Début de la liste des descripteurs de Shapes
<Shape></Shape>	Un descripteur de Shape statique
<ShapeAnimated></ShapeAnimated>	Un descripteur de shape animée
</Shapes>	Fin de la liste des Shapes
</ShapeDefinitions>	Fin du fichier de descriptions des shapes.

Détaillons maintenant le contenu d’un descripteur de Shape, on va prendre deux exemples :

• Descripteur de Shape statique, Circle3 :

<Shape>	Début du descripteur
<Name>Circle3</Name>	Nom de la Shape qui sera utilisé plus tard
<BitmapFrameNumber>0</BitmapFrameNumber>	Index de la bitmap à recupérer (utile pour les GIF), ici toujours à zero car le PNG n’a qu’une image
<BitmapTop>18</BitmapTop>	Coordonnée Y sur l’image du coin haut/gauche de la shape
<BitmapLeft>35</BitmapLeft>	Coordonnée X sur l’image du coin haut/gauche de la shape
<BitmapWidth>16</BitmapWidth>	Largeur de la shape en Pixels
<BitmapHeight>16</BitmapHeight>	Heuteur de la shape en pixels
<DataExtractMode>BlendPixels</DataExtractMode>	Mode de lecture des pixels, ici toujours BlendPixels
</Shape>	Fin du descripteur

• Descripteur de Shape animée, CirclePulse :

<ShapeAnimated>	Début du descripteur
<Name>CirclePulse</Name>	Nom de la shape
<BitmapFrameNumber>0</BitmapFrameNumber>	idem shape statique, pour la première image de l’animation
<BitmapTop>18</BitmapTop>	idem shape statique, pour la première image de l’animation
<BitmapLeft>1</BitmapLeft>	idem shape statique, pour la première image de l’animation
<BitmapWidth>16</BitmapWidth>	idem shape statique, pour toutes les images de l’animation
<BitmapHeight>16</BitmapHeight>	idem shape statique, pour toutes les images de l’animation
<DataExtractMode>BlendPixels</DataExtractMode>	idem shape statique, pour toutes les images de l’animation
<AnimationStepDirection>Right</AnimationStepDirection>	Sens de défilement de l’animation. valeurs possibles : Up, Down, Left, Right
<AnimationStepSize>17</AnimationStepSize>	décalage entre deux images de la shape animée en pixels, dans le sens indiqué (peut être négatif)
<AnimationFrameCount>12</AnimationFrameCount>	Nombre d’images de l’animation
<AnimationBehaviour>Continue</AnimationBehaviour>	Comportement de l’animation. Valeurs possibles : Once, Loop, Continue
<AnimationFrameDurationMs>40</AnimationFrameDurationMs>	Temps d’attente entre deux étapes de l’animation en millisecondes.
</ShapeAnimated>	Fin du descripteur

Petites Précisions à propos de certains champs de la Shape animée :

• Le AnimationStepSize permet de pointer sur le coin haut/gauche de l’image suivante, dans notre exemple il est de 17 car il y a une grille bleue dans l’image d’un pixel d’épaisseur donc pour sauter d’une image à la suivante il faut 16 pixels + 1 de la grille. Certaines ShapeAnimated (comme ArrowRight par exemple) ont un step plus court qui va plutôt servir à faire des translations (à noter que dans le PNG la grille n’est plus affichée pour cette shape pour ne pas être vue lors de l’animation). Un AnimationStepSize négatif partira dans le sens inverse du AnimationStepDirection (ce qui à assez peu de sens puisque les 4 directions sont possibles).

• Le AnimationBehaviour peut prendre 3 valeurs :
  • Once : L’anim est relancée à chaque trigering et s’arrête à la dernière image
  • Loop : L’anim est relancée à chaque triggering et boucle jusqu’au prochain triggering.
  • Continue : L’anim continue si un autre triggering de la même ShapeAnimated arrive, puis boucle jusqu’à un triggering d’une autre ShapeAnimated.

• Pour info pour les AnimationFrameDurationMs : 16 -> ~60FPS, 33-> ~30FPS, 1000-> 1FPS

Utilisation des Shapes

Passons maintenant aux endroits ou les shapes sont utilisée, soit les fichiers directoutputconfig.ini.

Prenez plus spécialement celui de votre Wemos (vous en avez plusieurs un pour la KL un pour la Wemos si vous avez déclaré ces deux cartes dans DofConfigTool)

Dans ce fichier trouvez la section [Variables DOF]

Dans cette section vous allez trouver des déclarations de variables qui indiquent des utilisations de shape.

• strblft, strbrgt : Strobes Left & Right
• Tous les flshemu : emulation des flashers (lo: left out, li left in, c: center, ri: right in, ro: right out)
• Tous les flasherc : extinction des flashers (tous les laisser sans shapes sinon vous allez avoir des choses allumées en permanence)
• Tous les Letter : Les lettrages
• Vous avez après plein de variable qui redirige vers des Shape ou des ShapeAnimated, à moins de vouloir vous lancer dans une customisation massive, laissons-les comme ça.

Pour utiliser une Shape sur ces variables il suffit de déclarer SHPLeNomDeLaShapeDuXML comme nom de shape, c’est tout simple.

Pour les Strobes et les Flashers la variable indique aussi ou la Shape va s’afficher, à priori ne pas toucher :

• AH : pourcentage en hauteur pour la shape de la backboard (la largeur de la shape sera recalculée en fonction du ratio de la shape)
• AL : Décalage vers la droite en pourcentage depuis le côté gauche de la Backboard
• AT : Décalage vers le bas en pourcentage depuis le haut de la Backboard

Vous pouvez indifféremment utiliser des Shape statiques ou animées (attention quand même si vous utilisez une Shape en mode Loop ou Continue, s’il n’y a plus d’autre shape demandée vous aurez une anim qui tourne en permanence, mais bon rien que les Flashers arrêtent pas de trigger des Shapes)

Dans l’absolu si vous voulez juste customiser vos flashers et strobes sur la backboard vous allez juste changer le nom des shapes dans les lignes strb et flshemu uniquement.

Cohabitation avec DofConfigTool

Puisque ces fichiers sont tous générés par le DofConfigTool vous allez devoir faire gaffe si vous voulez garder vos modifications à chaque fois que vous récupérez une nouvelle DofConfig.

J’ai regardé vite fait DofConfigToolClient (https://github.com/mkalkbrenner/dof_configtool_client) mais il ne semble pas pouvoir faire de patch sur les Shapes.

Il va donc falloir faire des backups de vos fichiers patchés pour remettre vos modifs dans les fichiers générés par DofConfigTool.

Les Shapes ne changent vraiment pas souvent, un rapide coup d’œil sur l’image PNG vous dira s’il y a eu du changement.

La plupart du temps quand vous upgradez vos DofConfig depuis le site, vous pouvez garder le PNG que vous avez modifié.

Pour ce qui est du XML et des .ini il faudra refaire vos modifs, soit à la pogne soit en utilisant des outils de merge texte comme WinMerge (https://winmerge.org/).

Cas pratique : Arnoz’ Teub Flashers

Comme tout bon système de customisation livré aux utilisateurs, on va commencer par dessiner des bites.

On va donc remplacer Les Shapes de nos flashers par l’emblème de notre Arnoz (inter)national.

Alors avant toute chose, backupez vos fichiers DirectOutputShapes.png, DirectOutputshapes.xml et tous vos directoutputconfig.ini. Ce n’est pas un drame si vous ne l’avez pas fait ils seront écrasés à la prochaine récupération depuis DofConfigTool le cas échéant, c’est plus votre travail de customisation que vous devriez backuper 😉.

Tout d’abord, un peu de dessin…vous prenez votre soft de dessin préféré (Adobe Photoshop 2023 version Pro Ultimate avec le pack de FX Spielberg/Lucas/MichaelBay installé devrait faire l’affaire).

Trouvez vous une place qui semble libre et laissez libre court à votre fibre artistique (15 ans chez Pixar et voilà le résultat !!) :

Moi je me suis mis là mais bon, à part vérifier dans le XML que la case est libre y’a pas trop de risque, j’ai juste pris une sûreté en laissant une case vide. L’animation va boucler donc pas besoin de refaire une grande teub à la fin.

Sauvez le PNG.

On va maintenant passer au XML.

Ouvrez DirectOutputShapes.xml, on va créer deux descripteurs de Shapes.

Prenez n’importe quel descripteur de Shape simple (prenez tout entre un tag <Shape> et </Shape>, tags compris)

Recopiez-le où bon vous semble, par exemple à la fin juste avant le tag </Shapes> qui indique la fin de la liste des Shapes.

Changez le nom dans les tags <Name></Name> en mettant Arnoz.

Vous allez juste avoir a mettre BitmapTop et BitmapLeft à jour pour pointer au bon endroit sur le PNG.

Aidez vous de votre outil de dessin pour connaitre les coordonnées du point en haut a gauche de votre shape (pas la grille bleue mais l’intérieur) et reportez ces valeurs.

Si vous avez dessiné dans la même case que moi vous devez avoir ça :

Passons maintenant à la Shape animée, recopiez cette fois ci un descripteur avec les tags <ShapeAnimated></ShapeAnimated>

On va partir sur la même image de départ, donc même coordonées, juste on va mettre un nouveau nom donc on finit par avoir ça :

• AnimationStepDirection = Right, on va scroller vers la droite
• AnimationStepSize = 17, largeur d’une shape +1 pour la grille bleue
• AnimationFrameCount = 6, on va jouer 6 frames
• AnimationBehaviour = Continue, si on triggers plusieurs fois d’affilée l’animation ne recommence pas du début.
• AnimationFrameDurationMs = 100, on va jouer l’anim a 10FPS (donc 0.6s par boucle)

Voilà vous pouvez sauver le XML.

Dernière étape on va aller dans le fichier ini de la Wemos. Pour l’instant j’ai toujours fait la modif aussi dans l’autre fichier ini (celui de la KL) car je ne sais pas trop laquelle est utilisée pour définir les shapes. Logiquement ça devrait être dans celui de la Wemos mais on les trouve dans les autres aussi…et je n’ai pas fait le test 😎 .

Là il ne vous reste plus qu’à trouver les ligne qui commencent par flshemu et de remplacer le nom de la Shape courant (surement SHPCircle3 sauf si vous avez changé dans DofConfigTool), par soit SHPArnoz pour la version statique, soit SHPArnozPulse pour la version animée, soit un peu des deux pour varier les plaisirs.

Et voilà si tout va bien quand vous retournerez jouer à vos tables préférées, vous aurez vous aussi l’immense joie de voir des teubs clignoter partout sur votre backboard.

A vous maintenant de vous faire des Shapes au thème de votre pincab par exemple, enjoy !!

Petites idées en vrac

J’ai testé quelques trucs qui rendent bien déjà avec les shapes existantes :

Ronds de tailles différentes, assez ondulé :

flshemulo = AH100 AL0 AT0 AW19 SHPRound4

flshemuli = AH100 AL20 AT0 AW19 SHPRound5

flshemuc = AH100 AL40 AT0 AW19 SHPRound6

flshemuri = AH100 AL60 AT0 AW19 SHPRound5

flshemuro = AH100 AL80 AT0 AW19 SHPRound4

Pasque y’a pas que les teubs dans la vie (un peu d’égocentrisme que diable) :

flshemulo = AH100 AL0 AT0 AW19 SHPLetterB

flshemuli = AH100 AL20 AT0 AW19 SHPLetterO

flshemuc = AH100 AL40 AT0 AW19 SHPLetterR

flshemuri = AH100 AL60 AT0 AW19 SHPLetterI

flshemuro = AH100 AL80 AT0 AW19 SHPLetterS

Pasque speciale dédicace 😊 :

flshemulo = AH100 AL0 AT0 AW19 SHPSmiley                    (SHPArnozPulse pour une double spéciale dédicace)

flshemuli = AH100 AL20 AT0 AW19 SHPLetterM

flshemuc = AH100 AL40 AT0 AW19 SHPLetterT

flshemuri = AH100 AL60 AT0 AW19 SHPLetterC

flshemuro = AH100 AL80 AT0 AW19 SHPSmiley

Sources :

• Monte ton Cab
• DirectOutput GitHub
• Google images
• L’atelier d’Arnoz (pour le design)
• Pixar..non j’déconne

Rédacteur : Boris « VrôÔnsh  Rajdam Ladiv»

Afin de poursuivre l’agrément de ce document nous comptons sur vos retours, vos expériences propres, vos idées et informations sur le groupe facebook « Monte ton Cab » ! Nous pourrons alors l’améliorer et mieux le documenter.

N’hésitez pas à nous signaler toutes erreurs que l’on aurait pu glisser dans le document ou retour de liens qui ne fonctionneraient plus !

En espérant que ce document vous soit utile, vous en souhaitant bonne lecture….