Intégrer Ogre à Qt

Interagir avec un jeu ou une scène 3D se fait couramment par le biais d'interfaces. L'utilisation majoritaire de ces interfaces est plutôt à chercher du côté de la conception d'interfaces in-game (tels les systèmes d'inventaires ou les menus que vous pouvez voir dans n'importe quel jeu). À ces interfaces, il faut ajouter ce que les concepteurs vont utiliser, c'est-à-dire des outils qui vont leur faciliter la création de scènes ou de niveaux, de matériaux, etc. Vous pouvez penser à l'éditeur Aurora de Neverwinter Nights, ou encore à l'Unreal Editor.
Ces deux besoins d'interfaces appellent deux réponses différentes. Pour le premier cas d'utilisation (interfaces in-game), on peut trouver des frameworks très performants, tel CEGUI, qui remplissent parfaitement leur rôle de framework d'interfaces dédiées aux menus de jeux. Cependant, pour des besoins plus lourds tels les éditeurs, les fonctionnalités fournies ne répondent plus vraiment aux besoins des concepteurs, et plus particulièrement des concepteurs d'outils. C'est pourquoi, afin de gagner en concision, en souplesse et afin de ne pas réinventer constamment la roue, il est indispensable d'intégrer le moteur graphique dans un framework de conception d'applications (tels Qt, WxWidgets, gtkmm, .Net etc.).
Ce tutoriel s'appliquera, vous l'aurez deviné, à l'intégration du moteur 3D Ogre dans Qt. Plus que l'intégration, nous verrons par la suite quelques cas standards (bien que basiques) d'utilisation.

• Une installation de Qt 4 fonctionnelle.
• une installation d'Ogre3D fonctionnelle (tuto réalisé avec la 1.4.5 et 1.4.8).
• En plus des bases en Qt (signaux/slots, création de widgets), il est utile de connaître un minimum Ogre.

Avant d'entrer plus loin dans ce sujet, voici les tutoriels qu'il est bon d'avoir suivis. Les mécanismes présentés ici s'appuient sur des concepts basiques, mais les mécanismes spécifiques à Qt et Ogre seront assez peu abordés :

• Tutoriels Ogre sur DVP ;
• Tutoriel avancé n° 2 et n° 3 sur le Wiki Ogre (utilisation de RaySceneQuery utilisé dans la partie IV de ce tuto).

Je vais détailler dans un premier temps la création du widget qui servira de réceptacle à l'affichage. Ce widget doit dériver de QWidgetQWidget (surpris ? :)), et réimplémenter quelques méthodes ; le minimum étant showEvent, paintEvent, moveEvent et resizeEvent (toutes quatre sont des méthodes virtuelles protégées).
Ce widget devra avoir la propriété permettant de ne pas laisser le système dessiner un fond automatiquement : Qt::WA_OpaquePaintEvent et de ne pas laisser Qt gérer un double buffer : Qt::WA_PaintOnScreen.

OgreWidget::OgreWidget(QWidget *parent)
:QWidget(parent),
ogreRoot(0), ogreSceneManager(0), ogreRenderWindow(0), ogreViewport(0),
ogreCamera(0)
{
    setAttribute(Qt::WA_OpaquePaintEvent);
    setAttribute(Qt::WA_PaintOnScreen);
    setMinimumSize(240,240);
}

Nous allons réimplémenter showEvent afin d'initialiser le système Ogre. En effet, son initialisation dépend du fait que nous ayons un handle système pour la fenêtre. Or cet handle n'est récupérable que lorsque la fenêtre est créée au niveau du système, et le moment le plus sûr est sa première apparition.

void OgreWidget::showEvent(QShowEvent *e)
{
    if(!ogreRoot)
    {
        initOgreSystem(); // l'initialisation d'Ogre est détaillée plus bas
    }
    
    QWidget::showEvent(e);
}

paintEvent sera réimplémenté afin de demander un rafraîchissement du viewport d'Ogre. En effet, si Ogre n'est pas maître de la boucle d'événement (ce qui va être le cas), il faut demander explicitement la mise à jour des viewports utilisés. De plus, on informe le reste du moteur qu'une nouvelle frame est dessinée.

void OgreWidget::paintEvent(QPaintEvent *e)
{
    ogreRoot->_fireFrameStarted();
        ogreRenderWindow->update();
    ogreRoot->_fireFrameEnded();
    
    e->accept();
}

Il est aussi nécessaire de réimplémenter resizeEvent et moveEvent afin de signifier à Ogre un changement au niveau de la résolution, et prendre en compte le nouvel aspect pour la caméra.

void OgreWidget::moveEvent(QMoveEvent *e)
{
    QWidget::moveEvent(e);
    
    if(e->isAccepted() && ogreRenderWindow)
    {
        ogreRenderWindow->windowMovedOrResized();
        update();
    }
}

void OgreWidget::resizeEvent(QResizeEvent *e)
{
    QWidget::resizeEvent(e);
    
    if(e->isAccepted())
    {
        const QSize &newSize = e->size();
        if(ogreRenderWindow)
        {
            ogreRenderWindow->resize(newSize.width(), newSize.height());
            ogreRenderWindow->windowMovedOrResized();
        }
        if(ogreCamera)
        {
            Ogre::Real aspectRatio = Ogre::Real(newSize.width()) / Ogre::Real(newSize.height());
            ogreCamera->setAspectRatio(aspectRatio);
        }
    }
}

Passons maintenant à l'initialisation d'Ogre. Si vous avez déjà programmé avec Ogre sans utiliser le framework d'exemple, vous vous y retrouverez très certainement. Dans le cas contraire, il y aura quelques différences avec un développement se basant sur ledit framework. Nous allons nous-mêmes créer un objet Ogre::Root, ainsi que le Ogre::RenderingSystem et le Ogre::SceneManager. L'ensemble du code concernant l'initialisation d'Ogre est celui de la fonction OgreWidget::initOgreSystem().
La création de Ogre::Root est simplissime. Nous utiliserons ici le constructeur par défaut. Il faudra donc que vous fournissiez les fichiers « ogre.cfg » (bien que le contenu de celui-ci ne soit pas utilisé et n'est donc pas indispensable physiquement) et « plugins.cfg » (celui-ci reste par contre indispensable).

void OgreWidget::initOgreSystem()
{
    ogreRoot = new Ogre::Root();

Le RenderSystem se crée en demandant à root une instance d'un rendering manager correspondant à un nom donné. Ici, j'utiliserai directement le nom du rendersystem opengl pour rester cross platform et que nous n'ayons pas à proposer une liste de rendering system. Lors de l'appel à Root::initialise, notez que nous spécifions que nous ne voulons pas qu'Ogre crée une fenêtre automatiquement.
Si vous voulez le faire dans votre propre outil, il vous faudra en récupérer la liste grâce à Ogre::Root::getAvailableRenderers.

    Ogre::RenderSystem *renderSystem = ogreRoot->getRenderSystemByName("OpenGL Rendering Subsystem");
    ogreRoot->setRenderSystem(renderSystem);
    ogreRoot->initialise(false);

Il n'y a pas de difficulté particulière au niveau de la création du scene manager. Ici encore, je code en dur le nom d'un SM standard afin de simplifier le code d'exemple. Pour proposer à l'utilisateur tous les SM disponibles, il vous faudra utiliser Ogre::SceneManagerEnumerator. Contrairement aux rendersystems, il vous faudra obtenir un itérateur sur les métadonnées des SceneManager, grâce à Ogre::SceneManagerEnumerator::getMetaDataIterator. Une fois déréférencé, cet itérateur vous permettra d'obtenir un Ogre::SceneManagerMetaData qui contiendra tout ce qui permet de décrire un SceneManager.

    ogreSceneManager = ogreRoot->createSceneManager(Ogre::ST_GENERIC);

Vient maintenant le moment d'embarquer une vue Ogre au sein d'une fenêtre Qt : la création d'une Ogre::RenderWindow. Comme pour tous les objets vus précédemment, c'est sur demande à l'objet Root qu'une renderwindow est instanciée. Je vous encourage à jeter un œil à la doc de cette méthodeOgre::Root::createRenderWindow. Nous allons donc devoir remplir une NameValuePairList dans laquelle nous spécifierons l'attribut externalWindowHandle, et bien sûr nous ne demanderons pas un affichage fullscreen.

    Ogre::NameValuePairList viewConfig;
    size_t widgetHandle;
#ifdef Q_WS_WIN
    widgetHandle = (size_t)((HWND)winId());
#else
    QWidget *q_parent = dynamic_cast <QWidget *> (parent());
    QX11Info xInfo = x11Info();

    widgetHandle = Ogre::StringConverter::toString ((unsigned long)xInfo.display()) +
        ":" + Ogre::StringConverter::toString ((unsigned int)xInfo.screen()) +
        ":" + Ogre::StringConverter::toString ((unsigned long)q_parent->winId());
#endif
    viewConfig["externalWindowHandle"] = Ogre::StringConverter::toString(widgetHandle);
    ogreRenderWindow = ogreRoot->createRenderWindow("Ogre rendering window",
        width(), height(), false, &viewConfig);

Il ne reste plus après qu'à créer une caméra (sur demande au SceneManager) et un viewport (sur demande auprès de l'objet RenderWindow nouvellement créé).

    ogreCamera = ogreSceneManager->createCamera("myCamera");
    
    ogreViewport = ogreRenderWindow->addViewport(ogreCamera);
    ogreViewport->setBackgroundColour(Ogre::ColourValue(0,0,0));
    ogreCamera->setAspectRatio(Ogre::Real(width()) / Ogre::Real(height()));
}

Les lecteurs attentifs auront remarqué dans l'en-tête la présence d'un slot setBackgroundColour(QColor c). J'ai choisi QColor comme type afin de faciliter l'intégration avec le reste de Qt, et tout particulièrement QColorDialog. Le seul problème de cette boîte de dialogue est qu'elle ne nous permettra pas de mettre à jour la vue en temps réel (elle est exécutée de façon modale et n'émet pas de signal correspondant à un changement de couleur). Mais à titre d'exemple, cela suffira amplement. L'intérêt du slot est nul dans ce cas de figure, mais si vous faites votre propre boîte de dialogue non modale, simplement avoir un slot à connecter à un signal sera un plaisir !
Il y a une chose utile à connaître ici : QColor stocke et permet d'obtenir la couleur grâce à un seul appel sous le format AARRGGBB. Ogre nous permet de spécifier une couleur dans ce format, cela nous évite donc de récupérer et spécifier chaque canal.

void OgreWidget::setBackgroundColour(QColor c)
{
    if(ogreViewport)
    {
        Ogre::ColourValue ogreColour;
        ogreColour.setAsARGB(c.rgba());
        ogreViewport->setBackgroundColour(ogreColour);
    }
}

Pour profiter de tout ça, il ne vous reste plus qu'à construire une QMainWindow avec notre OgreWidget pour widget principal. Pour spécifier la couleur, vous pouvez créer une action dont l'activation affichera une QColorDialog, et vous permettra d'en récupérer la valeur pour la spécifier à l'instance de OgreWidget.
Une archive contenant tout le code nécessaire à cette partie est disponible (miroir http). Prenez simplement garde à configurer les fichiers qt_ogre.pro et plugins.cfg selon vos besoins, et n'oubliez pas de le mettre dans le répertoire d'exécution de votre application.

Au code présenté ci-dessus, il va nous falloir ajouter une fonction qui va initialiser les ressources (pour l'objet et son matériau) ainsi qu'une fonction qui va créer la scène. La fonction initialisant les ressources n'est pas très intéressante en elle-même, il vous suffit de reprendre le code du framework d'exemple (ExempleApplication::setupResources dans le fichier ExampleApplication.h). Nous pourrions utiliser QSettings pour lire le fichier, mais il n'y a pas grand-chose à y gagner ici. La scène créée sera très simple : il s'agit juste d'une lumière ambiante et d'un objet non animé.
Le chargement des ressources et la création de la scène se font à la fin de notre fonction d'initialisation. Ce sont des manipulations purement liées à Ogre et l'intégration dans un toolkit graphique n'a pas la moindre importance. Vous devriez obtenir l'image suivante en compilant et en exécutant l'archive fournie ici (miroir http). Dans cette dernière, j'ai ajouté le besoin du plugin Cg ainsi que les matériaux et objets nécessaires.

Cette partie va vous permettre de voir plusieurs façons de manipuler un objet. Ici, nous allons voir comment déplacer la caméra de trois façons différentes :

• utilisation de spinbox ;
• utilisation du clavier ;
• utilisation de la souris.

Une fois que nous aurons vu le positionnement, vous ne devriez pas avoir de problème pour implémenter l'orientation. La première modification à apporter concerne la classe OgreWidget. En effet, quelle que soit la méthode, nous allons devoir communiquer par le biais d'un signal la nouvelle position de la caméra. Le but ici est de conserver les spinbox synchronisées avec la position de la caméra, quelle que soit la méthode qui sert au déplacement. Voici la signature dudit signal :

signals:
    void cameraPositionChanged(const Ogre::Vector3 &pos);

III-B-1. Contrôle du positionnement de la caméra par des spinbox▲

Le but ici est d'avoir trois QDoubleSpinBox qui nous permettront de spécifier la position sur chacun des trois axes de la caméra.
Afin de simplifier ce contrôle, mais aussi dans le but de pouvoir le réutiliser pour autre chose que la caméra, vous pouvez créer un widget qui regroupera trois de ces spinbox (la classe Coordinate3DModifier dans l'exemple). Ce widget s'est vu doté d'un signal coordinateChanged(const Ogre::Vector3&) qui est émis à chaque modification de la valeur de l'une des spinbox. La fonction suivante est donc ce slot appelé à chaque modification de la valeur de l'une des spinbox :

 

Sélectionnez

void Coordinate3DModifier::onCoordinateChanged()
{
    Ogre::Vector3 newCoord(sbx->value(),
                           sby->value(),
                           sbz->value());
    emit coordinateChanged(newCoord);
}

Ce signal est connecté à un slot qui a été créé dans notre OgreWidget dont voici le code :

 

Sélectionnez

void OgreWidget::setCameraPosition(const Ogre::Vector3 &pos)
{
    ogreCamera->setPosition(pos);
    ogreCamera->lookAt(0,50,0);
    update();
    emit cameraPositionChanged(pos);
}

Dans ce slot, nous repositionnons la caméra à l'endroit désiré, tout en lockant l'orientation vers le centre (approximativement) du robot (le modèle utilisé dans les exemples fournis). Nous demandons ensuite à mettre à jour l'affichage de notre widget, ce qui entraîne le rendu d'une frame par Ogre. Nous finissons par émettre la nouvelle position de la caméra à qui sera intéressé.

J'ai précisé plus haut que, quelle que soit la méthode de déplacement, il faut que les spinbox indiquant les coordonnées de la caméra restent synchrones avec sa position réelle. Nous allons donc connecter le signal OgreWidget::cameraPositionChanged à un slot qui s'occupera de mettre à jour lesdites spinbox. Exemple tiré du code fourni plus bas :

 

Sélectionnez

void Coordinate3DModifier::setNewCoordinate(const Ogre::Vector3 &coordinate)
{
    blockSignals(true);
    sbx->setValue(coordinate.x);
    sby->setValue(coordinate.y);
    sbz->setValue(coordinate.z);
    blockSignals(false);
}

Je tiens à souligner l'utilisation des méthodes QObject::blockSignals. En effet, un appel à QDoubleSpinBox::setValue entraîne l'émission d'un signal QDoubleSpinBox::valueChanged. Ce signal entraîne l'exécution de notre slot Coordinate3DModifier::onCoordinateChanged. Ce dernier entraîne l'émission du signal Coordinate3DModifier::coordinateChanged et donc l'exécution du slot OgreWidget::setCameraPosition. Ce dernier va émettre le signal OgreWidget::cameraPositionChanged, lequel entraîne l'exécution du slot Coordinate3DModifier::setNewCoordinate. Si nous ne bloquons pas immédiatement tout déclenchement de signal, je vous laisse le soin d'imaginer la tête qu'aura la pile d'appels (enfin, le peu de temps qu'elle et le programme vont exister).
Il est donc assez important de documenter le fait que la modification des coordonnées par le slot Coordinate3DModifier::setNewCoordinate n'entraîne pas l'émission du signal Coordinate3DModifier::coordinateChanged. Mais que pour rester à l'écoute de la position de la caméra, il vaut mieux se connecter directement au signal fourni par OgreWidget.

Voici le résultat obtenu à la fin de cette partie :

Une archive contenant tout le code nécessaire à cette partie est disponible (miroir http).

III-B-2. Contrôle du positionnement de la caméra par le clavier▲

OgreWidget::OgreWidget(QWidget *parent)
:QWidget(parent),
ogreRoot(0), ogreSceneManager(0), ogreRenderWindow(0), ogreViewport(0),
ogreCamera(0)
{
    setAttribute(Qt::WA_OpaquePaintEvent);
    setAttribute(Qt::WA_PaintOnScreen);
    setMinimumSize(240,240);
    
    setFocusPolicy(Qt::ClickFocus);
}

void OgreWidget::keyPressEvent(QKeyEvent *e)
{
    static QMap<int, Ogre::Vector3> keyCoordModificationMapping;
    static bool mappingInitialised = false;
    
    if(!mappingInitialised)
    {
        keyCoordModificationMapping[Qt::Key_Z]           = Ogre::Vector3( 0, 0,-5);
        keyCoordModificationMapping[Qt::Key_S]           = Ogre::Vector3( 0, 0, 5);
        keyCoordModificationMapping[Qt::Key_Q]           = Ogre::Vector3(-5, 0, 0);
        keyCoordModificationMapping[Qt::Key_D]        = Ogre::Vector3( 5, 0, 0);
        keyCoordModificationMapping[Qt::Key_PageUp]   = Ogre::Vector3( 0, 5, 0);
        keyCoordModificationMapping[Qt::Key_PageDown] = Ogre::Vector3( 0,-5, 0);
        
        mappingInitialised = true;
    }
    
    QMap<int, Ogre::Vector3>::iterator keyPressed =
        keyCoordModificationMapping.find(e->key());
    if(keyPressed != keyCoordModificationMapping.end() && ogreCamera)
    {
        const Ogre::Vector3 &actualCamPos = ogreCamera->getPosition();
        setCameraPosition(actualCamPos + keyPressed.value());
        
        e->accept();
    }
    else
    {
        e->ignore();
    }
}

III-B-3. Contrôle du positionnement de la caméra par la souris▲

void OgreWidget::wheelEvent(QWheelEvent *e)
{
    Ogre::Vector3 zTranslation(0,0, -e->delta() / 60);
    
    if(e->modifiers().testFlag(Qt::ControlModifier))
    {
        zTranslation.z *= turboModifier;
    }

    const Ogre::Vector3 &actualCamPos = ogreCamera->getPosition();
    setCameraPosition(actualCamPos + zTranslation);
    
    e->accept();
}

void OgreWidget::mouseMoveEvent(QMouseEvent *e)
{
    if(e->buttons().testFlag(Qt::LeftButton) && oldPos != invalidMousePoint)
    {
        const QPoint &pos = e->pos();
        Ogre::Real deltaX = pos.x() - oldPos.x();
        Ogre::Real deltaY = pos.y() - oldPos.y();
        
        if(e->modifiers().testFlag(Qt::ControlModifier))
        {
            deltaX *= turboModifier;
            deltaY *= turboModifier;
        }
        
        Ogre::Vector3 camTranslation(deltaX, deltaY, 0);
        const Ogre::Vector3 &actualCamPos = ogreCamera->getPosition();
        setCameraPosition(actualCamPos + camTranslation);
        
        oldPos = pos;
        e->accept();
    }
    else
    {
        e->ignore();
    }
}

void OgreWidget::mousePressEvent(QMouseEvent *e)
{
    if(e->buttons().testFlag(Qt::LeftButton))
    {
        oldPos = e->pos();
        e->accept();
    }
    else
    {
        e->ignore();
    }
}

void OgreWidget::mouseReleaseEvent(QMouseEvent *e)
{
    if(!e->buttons().testFlag(Qt::LeftButton))
    {
        oldPos = QPoint(invalidMousePoint);
        e->accept();
    }
    else
    {
        e->ignore();
    }
}