Introduzione a PyOgre
Traduzione non ufficiale (e da revisionare) di http://www.ogre3d.org/wiki/index.php/Introduction_to_PyOgre
Introduzione a PyOgre
Versione originale da Clay Culver Aggiornata da Andy come parte del progetto di Python-Ogre
Introduzione
Grazie per aver provato Python-Ogre. Abbiamo lavorato sodo cercando di portare Python-Ogre a una situazione stabile e usabile, e l'abbiamo fatto per piattaforme Windows e Linux - con OSx in arrivo. Ci sono alcune cose che bisogna sapere prima di iniziare con il resto del tutorial, però, e questa pagina dovrebbe fornirvi un crash course e tutto ciò che dovete sapere prima di iniziare a lavorare con Python-Ogre.
Python-Ogre ora il supporto di Active Python Ogre
Python-Ogre è la continuazione del progetto originale PyOgre come è documentato qui. Si prega di visitare il sito principale.
Breve Storia e Perché SWIG <Outdated>
Ogre è un motore di rendering 3D scritto interamente in C++. Supporta una impressionante serie di funzionalità, ed è stato utilizzato con grande successo per creare giochi ancora più impressionanti. Ogre ha avuto i binding Python per molto tempo utilizzando Boost.Python. Questi binding hanno cambiato proprietario nel corso del tempo, a seconda della perdita o guadagno di interesse da parte delle persone che li mantenevano.
Nei primi mesi del 2005, fui avvicinato da Federico Di Gregorio (fog), che voleva ottenere la versione Boost.Python di PyOgre funzionante sotto Linux. Questo può sembrare un compito semplice, dal momento che entrambi Ogre e Boost.Python sono librerie multipiattaforma, ma si è rivelato essere un compito estremamente arduo a causa della complessità di Ogre. I wrapper di interfaccia generati necessitavano di grandi quantità di modifica manuale per la compilazione anche sotto le più recenti versioni di GCC. Letteralmente dopo un mese di duro lavoro da parte di me e fog (per la maggior parte fog), arrivammo alla fine dell'impresa. Boost.Python fa alcune cose molto belle, ma il suo modello magico non poteva capire alcuni dei costrutti che Ogre utilizzava. Fog allora mi avvicinò con l'idea di fare una completa riscrittura utilizzando SWIG invece di utilizzare Boost.Python. Egli finalmente mi convinse, e abbiamo iniziato a lavorare ai primi di aprile 2005, per riscrivere la libreria. Sono molto felice dei risultati.
PyOgre è legato al C++
La cosa più importante da ricordare di PyOgre è che si tratta di un binding di una libreria C++. Ogre è straordinariamente veloce e flessibile, e PyOgre eredita sia la velocità sia la flessibilità dal suo progetto genitore. Dal momento che Ogre è multipiattaforma, ciò dà l'immediato vantaggio che anche PyOgre è multipiattaforma. Essa attualmente gira sotto Windows e Linux, e abbiamo dei riscontri che sia possibile compilarlo ed eseguirlo sotto Mac OS X. Tuttavia dal momento che né il sottoscritto né fog utilizzariamo un Mac (e nessuno si è spinto fino al punto di offrire aiuto in tale piattaforma), non vi è alcun sostegno diretto (o pacchetti) per essa.
Tuttavia questa velocità e flessibilità hanno un prezzo da pagare. Ogre è certamente una libreria C++, e anche se abbiamo fatto quanto in nostro potere per renderla più Pythonica (come ad esempio la modifica di metodi get/set in proprietà Python, fare il wrapping degli iteratori, ecc), ci saranno sempre parti della libreria dove poteva sembrare molto meglio se fosse stato fatto in puro Python. Se trovate una parte della libreria in cui pensate che si potrebbe dare una ripulita, fatecelo sapere. Il secondo problema con il binding di una libreria C++ è che vi è la possibilità di gravi crash (segfaults sotto Linux, violazioni di accesso alla memoria in Windows). Questi dovrebbero auspicabilmente essere pochi e rari, e noi dovremmo risolverli ogni volta che ne troviamo uno. Vorrei solo che tu fossi consapevole del fatto che questo può accadere, e che noi risolveremo il problema nel più breve tempo possibile se aprirai un bug o un post nel forum descrivendo il problema.
Le stranezze di SWIG
Abbiamo costruito questa libreria utilizzando SWIG, e SWIG talvolta fa alcune cose strane. Esse in realtà non pregiudicano il normale uso della libreria (e si possono ignorare in tutta sicurezza)[,and you should never actually run into them, but I wanted to mention what they were in case you run across them and ask "what the heck is this for?"].
Swig non genera un coerente modulo Python/C che viene importato. Invece esso genera un modulo Python/C modulo, che richiede una grande quantità di codice Python per guidarlo. Questo è quello che si vedrebbe se effettivamente si aprisse e ispezionasse il modulo ogre.py che viene importato. Un paio di cose da notare:
SWIG aggiunge pochi membri supplementari per ogni classe. La variabile "thisown" vale True o False a seconda se Python o C++ possiede la particolare variabile. Questo è utilizzato per liberare la memoria assegnata. Alcune classi hanno anche metodi __disown__. Questo significa qualcosa di simile alla variabile "thisown", ma chiamarla ha conseguenze quando si ha a che fare con le callbacks di C++. In generale, non si dovrebbe mai modificare "thisown" o chiamare __disown__, e dimenticarsi che esistono è probabilmente la cosa più sicura da fare.
SWIG crea anche una classe Ptr per ogni classe C++. Quindi, la classe Entity avrà un corrispondente EntityPtr, la classe Node ha una classe NodePtr. Queste servono per la meccanica interna di SWIG, e si dovrebbero ignorare. Esse non dovrebbero mai essere effettivamente restituite da una funzione o servire come parametro di alcuna funzione.
Documentazione
Sia Ogre sia CEGUI sono enormi librerie con estesa documentazione. Mantenere la libreria aggiornata con le docstrings esattamente corrette sarebbe pressoché impossibile. Invece ci basiamo sulla guida di riferimento delle API C++ di Ogre per la nostra documentazione API. Detto questo, la libreria ha docstrings che sono molto utili.
Per le funzioni, fornisce i parametri e valori di ritorno. Ciò consente di avere una prima idea di come utilizzare una funzione. Se avete bisogno di sapere che cosa la funzione effettivamente fa, si dovrebbe consultare la guida di riferimento delle API di Ogre. Ad esempio, supponiamo che tu abbia bisogno di avere informazioni su SceneNode.rotate. Puoi consultare l'help incorporato per vedere con quali parametri devi chiamarlo:
>>> help(ogre.SceneNode.rotate)
Help on method rotate in module pyogre.ogre:
rotate(*args) unbound pyogre.ogre.SceneNode method
rotate(self, Vector3 axis, Radian angle, TransformSpace relativeTo=TS_LOCAL)
rotate(self, Vector3 axis, Radian angle)
rotate(self, Quaternion q, TransformSpace relativeTo=TS_LOCAL)
rotate(self, Quaternion q)
Se hai una domanda su come usarlo, allora si può consultare la API reference per SceneNode, che contiene una descrizione di ciò che in realtà è la funzione:
virtual void rotate (const Vector3 &axis, const Radian &angle, TransformSpace relativeTo=TS_LOCAL)
Rotate the node around an arbitrary axis.
virtual void rotate (const Quaternion &q, TransformSpace relativeTo=TS_LOCAL)
Rotate the node around an aritrary axis using a Quarternion.
Come ho già accennato, tutti i metodi get/set in Ogre sono stati "wrappati" in attributi. Quindi, se si sta tentando di utilizzare un metodo get/set che vedete nella C++ API Reference, basta assegnarlo direttamente invece di cercare di chiamare i metodi:
1 # Si potrebbe fare in questo modo:
2 sceneNode.position = ogre.Vector3(100, 200, -150)
3 # Ma così è più carino:
4 sceneNode.position = (100, 200, -150) # le tuple possono essere usate al posto dei Vectors
Se non siete sicuri di un attributo, utilizzare l'aiuto incorporato su di esso:
Help on property:
Node.position -> Ogre::Vector3
This is equivalent to calling the C++ Ogre methods:
get: Ogre::Vector3 Node::getPosition()
set: void Node::setPosition(Ogre::Vector3)
Abbiamo discusso l'effettiva incorporazione delle API C++ di riferimento in PyOgre stesso, ma ciò avrebbe richiesto un grande supplemento di spazio/memoria alla libreria, e avremmo dovuto passare attraverso un sacco di arzigogoli per far sì che SWIG generasse le corrette docstrings. Abbiamo ancora in programma di tornare su questo in futuro per cercare di rendere le docstrings più utili, ma ora ci stiamo concentrando su altri problemi con PyOgre.
Versioni e stabilità dell'API
PyOgre in realtà si compone di due librerie. La prima è Ogre (che è un motore di rendering 3D), la è CEGUI (che è un sistema GUI embedded). Questi due progetti sono indipendenti l'uno dall'altro, e hanno diversi livelli di stabilità.
Ogre è stato definito come stabile dalla release 1.0.0. Il core-API non cambia in una patch di revisione (nel senso che non cambiano da 1.0.0 a 1.0.1, ma cambia da 1.0.0 a 1.1.0). Questo significa che PyOgre non dovrebbe cambiare durante le revisioni patch, ma noi siamo in balia di chi mantiene Ogre per questo.
CEGUI non è così vecchia, e non è stata definita stabile. Esse possono, e spesso lo fanno, bloccare le interfacce della libreria. Bisogna essere consapevoli di questo, se si decide di utilizzare CEGUI.
Si noti inoltre che Ogre e CEGUI sono completamente indipendenti l'uno dall'altro. È possibile utilizzare Ogre con un diverso set di widget (o si può scrivere il proprio). Si può anche utilizzare CEGUI con !PyOpenGL invece di Ogre.
GUI e altre librerie
Una nota veloce sulle GUI. Ogre si può occupare della creazione di una finestra per voi su qualsiasi piattaforma che si sta utilizzando. Se non si desidera utilizzare questa funzione, è possibile creare la propria finestra e incorporare PyOgre all'interno di essa. Ci sono delle demo nella directory demos/ che vi mostrano come incorporare PyOgre in una finestra wxPython. Credo che fog abbia avuto buon successo anche utilizzando pyGTK come un sistema GUI per PyOgre.
Se siete alla ricerca di un "embedded GUI" (qualcosa che viene eseguito all'interno dell'ambiente di rendering), si dovreste utilizzare CEGUI. Non so di altre GUI incorporate che funzionano con Ogre.
Velocizzare PyOgre
Alcune persone provano continuamente ad ottimizzare e velocizzare le loro applicazioni PyOgre. Credo che pyogre sia già più veloce nel rendering 3D rispetto ad altri motori 3D per Python. Tuttavia, se siete ancora interessati ci sono davvero solo due cose che dovete sapere. Prima di tutto pysco (un Python JITer) lavora alla grande con PyOgre. Può accelerare l'esecuzione di codice python di una sorprendente quantità. La seconda cosa che dovete sapere è che il sovraccarico di chiamate per qualsiasi funzione di Ogre è significativo. Per questo si dovrebbe probabilmente mantenere la maggior parte delle vostre operazioni matematiche in codice psyco ottimizzato. Oppure, se siete veramente interessati al riguardo, scrivere le vostre pesanti operazioni matematiche in codice C/C++.
Ottenere aiuto
Il modo migliore per ottenere aiuto è quello di chiedere nei forum di PyOgre. Non posso promettere che fog e io sappiamo tutto su Ogre, ma facciamo il nostro meglio per capire il problema e come provi rimedio. Inoltre, poiché il codice C++ di Ogre può essere molto facilmente convertito in codice Python, se noi non fossimo in grado di risolvere il problema, la cosa più semplice da fare è chiedere al forum di Ogre in C++ e la risposta ottenuta là potrà essere facilmente tradotta in equivalenti costrutti Python.
Grazie, e godetevi PyOgre.
PyOgreTutorial/Principianti1 - PyOgreTutorial/Principianti2 - PyOgreTutorial/Principianti3 -PyOgreTutorial/Principianti4 - PyOgreTutorial/Principianti5