BuildNewOMKComponent

Un article de OpenMASKWiki.

Jump to: navigation, search


CETTE PAGE EST EN CONSTRUCTION

Les composants génériques d'OpenMASK sont des classes C++ respectant les conventions d'OpenMASK. Ils sont actuellement de plusieurs types : les objets de simulation de base (OSO, les objets de simulation extensibles (ESO), les extensions d'objets (EDO), les types de données OMK et les variables OMK.
OpenMASK propose également un ensemble de conseils, d'exemples et de tutoriaux, ainsi que des outils complémentaires pour aider à un développement cohérent et homogène des contributions.
Voici un premier tutoriel consacré à la programmation de nouveaux composants OpenMASK.
--

Sommaire

OpenMASK Simulated Object (OSO)

Une classe "support"

Dans la version 4, l'OSO n'est plus directement utilisé mais devient la classe support de toute nouvelle classe d'objet extensible.
Une classe OSO est une classe héritant de OMK::SimulatedObject. Elle est doit notamment redéfinir quatre méthodes suivantes :

void init ()
void compute ()
void finish ()
void processEvent (Event *)


Dans la version 4, il est déconseillé d'implémenter de nouvelles classes héritant de simulatedObject car les fonctionnalités de celles ci ne pourront pas, si besoin, être ultérieurement étendues par des extensions. Il est donc préférable de créer de nouvelles classes basée sur les objets extensibles utilisant les attributs.
Les explication de programmation d'une nouvelle classe d'objet sont donc fournies dans le chapitre suivant.

Communications entre objets

Les communications entre objets s'appuient sur des entrées et des sorties pour les communications synchrones, et sur des évènements pour les communications asynchrones.

OpenMASK Extensible Simulted Object (ESO)

Un Extensible Simulated Object est une classe héritant de OMK::ExtensibleSimulatedObject, qui elle même hérite de OMK::SimulatedObject.
Elle est doit notamment redéfinir les méthodes suivantes :

virtual void loadParameters ()
virtual void computeInputs ()
virtual void computeParameters ()
virtual void computeOutputs ()
virtual void finish ()
virtual bool processEvent (Event *)

Actuellement, la méthode ProcessEvent sera souvent délaissée au profit de un (ou plusieurs) EventListener qui réagit directement à un événement donné.

Factory des objets

La création des objets est réalisée par le controleur OpenMASK en s'appuyant sur une factory. Deux macros sont à la disposition du programmeur pour introduire sa classe ESO dans la factory :

DECLARE_OBJECT_FACTORY( MaClasse ) ;
  • Cette macro est ajoutée dans la déclaration de la classe à la place du constructeur et du destructeur. Le paramètre MaClasse est l'identifiant C++ de la classe.
REGISTER_OBJECT_FACTORY( MaClasse, "MaClasse" ) ;
  • Cette seconde macro est intégrée dans le fichier d'implémentation. Elle ajoute la classe à la factory en lui association le libellé fourni qui devient son identifiant. Ce dernier sera utilisé comme identifiant de la classe. Il doit donc être précisé dans la documentation de la classe.

Les identifiants de classe serviront dans le fichier de configuration pour déclarer la classe de chaque objet utilisé.
Le constructeur générique de la classe ESO va enregistrer toutes les extensions demandées dans le fichier de configuration.

Extension des objets

Un mécanisme d'extension

Un objet extensible offre la possibilité de faire modifier son comportement ou la valeur de ses attributs par d'autres objets de type Extension (voir EDO). Une classe de type Extension aura défini plusieurs méthodes convenues qui seront appelées par l'objet auquel elle est attachée.
Il ya deux façons d'attacher à l'exécution les objets d'extension voulus à un objet extensible :

  • soit par l'envoie d'événements adhoc
  • soit en les décrivant dans le fichier de configuration, dans le champ Extensions { } de l'objet concerné

Redéfinitions prédéfinies

Pour comprendre le fonctionnement d'un objet extensible, il faut simplement savoir que les méthodes init et compute ont été redéfinies de la façon suivante :

  • la méthode init de la classe de base héritée par
{
 loadParameters()
 Pour toutes extensions : loadExtensionParameters()
}
  • la méthode compute de la classe de base héritée par
{
  computeInputs();
  Pour toutes extensions :  preComputeExtension() ;
  computeParameters();
  Pour toutes extensions :  postComputeExtension() ;
  computeOutputs();
}

Les fonctionnalités introduites par les extensions travailleront donc après la lecture des entrées et avant l'écriture des sorties. Cela permet de "préparer" les données du compute avant son action ou de les "rectifier" après.

Extension d'objet (EDO)

Une Extension d'objet est une classe héritant de OMK::Extension
Elle est doit notamment redéfinir les méthodes suivantes :

void loadObjectParameters ()
void loadExtensionParameters ()
void preComputeParameters ()
void postComputeParameters ()

La procédure loadObjectParameters permet à l'extension d'acquérir les valeurs des paramètres de son objet pour sa propre initialisation.
La procédure loadExtensionParameters permet à l'extension d'acquérir les valeurs de ses propres paramètres.
Attention, si plusieurs extensions sont ajoutées à un même objet extensible, l'ordre d'application des extensions est indéterminé aussi bien pour les pré-compute que pour les post-compute.

Types de données OMK

Variables OMK

Entrées/sorties

Un flux de données peut être établi entre deux objets de simulation en branchant une entrée d'un objet de simulation à une sortie d'un autre objet. Sur ce flux, les données sont datées et un mécanisme d'interpolation est appliqué si la production et la consommation de la donnée ne sont pas faites à la même date.

Evénements

Des événements avec ou sans valeurs associées peuvent être transmis entre les objets de simulation.

signaux

Un signal peut être diffusé à l'ensemble des objets de simulation.

Attributs

Les attributs sont des composants de communication OMK, utilisables dans les objet de simulation extensibles, pour s'abstraire de la gestion des entrées/sorties et événements. Un même attribut peut être en lien avec des entrées/sorties ou des événements selon des choix fixés après la programmation dans le fichier de configuration.
Un attribut doit être déclaré en tant que donnée de la classe :

/// An attribute example
OMK::AttributeT< float > _weight ;

Un attribut doit être initialisé dans le constructeur et ajouté comme composant de la classe OMK l'hébergeant :

parametersTesterOSO::parametersTesterOSO( OMK::Controller& ctrl, const OMK::ObjectDescriptor& objectDescriptor )
        : OMK::ExtensibleSimulatedObject( ctrl, objectDescriptor ),
          _weight("Weight", 0.0)
{  addAttribute( _weight ) ; }

Un attribut doit etre détruit dans le destructeur de sa classe d'hébergement :

parametersTesterOSO::~parametersTesterOSO()
{ removeAttribute(_weight.getId()); }

paramètres de configuration

Les paramètres de configuration sont, en général, initialisés dans le fichier de configuration de l'application.
Tout attribut peut être initialisé par un paramètre du même non.

Frequency 40   // valeur numérique
EventName "OnOff-Spot1"  // valeur chaine de caractères
GeometryFile "../Data-osg/cycab/GreyCycab.obj" // valeur de chemin
Position [ [0 0 2.0] [0.0 1.57 0.0] [1 2 1] ]  // valeur de transform (position, orientation, scale)
ConnectTo ["mobile1" "Position"]  // liste de chaine de caractère
Values[ [ [0 0 -6] ] [ [5 0 0.5] ] [ [0 0 6] [0.0 1.57 0.0] ] [ [0 0 2] ] ]  // liste de transform
ButtonEvents [ [21 ["ButtonToKeyEvent" "VRPN-Y-mobile1"] ]  [22 ["ButtonToKeyEvent" "VRPN-U-spot1"] ]  ]  // liste mixte

Outils complémentaires

Normes de codages

Il est recommandé de suivre les normes de codages d'OpenMASK.

système de traces

Un service de traçage contrôlable à volonté depuis le fichier de configuration est fourni par le module Trace d'OpenMASK. C'est une implémentation personnalisée d'un service fourni par la bibliothèque OBT.
La documentation en ligne est à cet URL : http://www.openmask.org/documentation/openmask4/group__trace_grp.html.

Principe

Le principe est d'associer un identifiant à des messages de trace dans un module de code puis de déterminer l'affichage ou non de ces messages par la présence ou non de cet identifiant dans le fichier de configuration. Plusieurs parametres de contrôle sont disponibles :

 TraceAll false 
TraceFile "trace.txt" 
TraceIds ["Vis:OSG" "Vis:OSG:Stack" "Addon:Mouse2DTo3DMove" ]  
//TraceIds [ "Kernel:Event" "Kernel:Attribute" "Kernel:Object" ]
  • le nom du fichier où seront écrits les messages
  • tous les messages peuvent être systématiquement affichés par TraceAll à vrai
  • pour un affichage partiel il faut fournir les identifiants des modules concernés

Traces OpenMASK disponibles

Le principe consiste à associer un identifiant global à une partie de code OpenMASK, à utiliser cet identifiant dans les messages de trace de ce code puis à déclarer cet identifiant dans le fichier de configuration lorsque l'on souhaite voir les messages de trace.

Traces des plugin personnels

Dans le code :

///\brief id for traces of the OSO.
/// Can be used with \ref OMTRACEID, see \ref traceSubSec2.
/// \ingroup traceGrp
#define OMK_DEBUG_Mouse2DTo3DMove "Addon:Mouse2DTo3DMove"
OMTRACEID( OMK_DEBUG_Mouse2DTo3DMove, "Sending event " << _eventID << " to " << _eventReceiver << " with translation [" 
    << _currentTransform.getTranslate().X() << ", " 
    << _currentTransform.getTranslate().Y()  "]" );

Dans le fichier de configuration :

OBT

Open Bunraku Tools (OBT) est une bibliothèque regroupant différents outils utilisés par OpenMASK (voir la documentation).

Navigation