Introduction to PyOgre


Original version by Clay Culver
Updated by Andy as part of the Python-Ogre project

Introduction


Thank you for trying Python-Ogre We have been working hard trying to bring Python-Ogre to a stable and usable state, and have made this happen for the Windows and Linux ports — with OSx comming soon. There are a few things you should know before getting started with the rest of the tutorials though, and this page should give you a crash course in everything you need to know before starting to work with Python-Ogre.

Brief History and Why SWIG <Outdated>


Ogre is a 3D rendering engine written entirely in C++. It supports an impressive feature set, and has been used with great success to create even more impressive games. Ogre has had Python bindings for a very long time using Boost.Python. These bindings changed ownership over time as people gained and lost interest in maintaining them.

In early 2005, I was approached by Federico Di Gregorio (fog), who wanted to get the Boost.Python version of PyOgre working under Linux. This may sound like a simple task, since both Ogre and Boost.Python are cross platform libraries, but it turned out to be an extraordinarily daunting task due to the complexity of Ogre. The generated interface wrappers needed large amounts of manual editing to compile under even the most recent versions of GCC. After literally a month of hard from myself and fog (mostly fog), we were at the end of the rope. Boost.Python does some very nice things, but its template magic just could not understand some of the constructs that Ogre used. Fog then approached me with the idea of doing a complete rewrite using SWIG instead of using Boost.Python. He finally convinced me, and we began work in early April 2005 to rewrite the library. I'm very happy with the results.

PyOgre Binds C++


The most important thing to remember about PyOgre is that it is a binding of a C++ library. Ogre is extraordinarily fast and flexible, and PyOgre inherits that speed and flexibility from its parent project. Since Ogre is cross platform, this gives the immediate advantage that PyOgre is also cross platform. It will currently run under Windows and Linux, and we have heard reports that it is possible to compile and run it under Mac OS X. However since neither myself or fog use a Mac (and no one has stepped up to offer help in that area), there is no direct support (or packages) for it.

This speed and flexibility comes at a price though. Ogre is certainly a C++ library, and even though we have done what we can to make it more Pythonic (such as changing get/set methods into Python properties, wrapping iterators, etc), there will always be parts of the library where it could look a lot better had it been implemented in pure Python. If you find a part of the library that you think could use polishing, let us know. The second problem with binding a C++ library is that there is the possibility of hard crashes (segfaults under Linux, memory access violations under Windows). These should hopefully be few and far between, and we fix these every time we find one. I just wanted you to be aware that this can happen, and that we'll fix it as soon as possible if you https://developer.berlios.de/bugs/?group_id=3464 open a bug or post in the forum describing the problem.

SWIG Strangeness


We have built this library using SWIG, and SWIG sometimes does some strange things. They do not really affect the normal use of the library (and you can safely ignore all of them), 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 does not generate a coherent Python/C module that is imported. Instead it generates a Python/C module that requires a large amount of Python code to drive it. This is what you will see if you actually open up and inspect the ogre.py that is imported. A few things to note:

SWIG adds a few additional members to each class. The "thisown" variable is either true or false depending on if Python or C++ owns the particular variable. This is used for freeing allocated memory. Some classes also have disown methods as well. This does something similar to the "thisown" variable, but calling it has consequences when you are dealing with C++ callbacks. In general, you should never modify "thisown" or call disown, and forgetting they ever exist is probably the safest thing to do.

SWIG also creates a Ptr class for each C++ class. So the class Entity will have a corresponding EntityPtr, the Node class has a NodePtr class. These are for internal SWIG mechanics, and you should just ignore them. They should never actually be returned from any function or needed as a parameter for any function.

Documentation


Both Ogre and CEGUI are huge libraries with expansive documentation. Keeping the library up to date with exactly correct docstrings would be near impossible. Instead we rely on the C++ Ogre API reference for our API documentation. With this said, the library does have docstrings which are very helpful.

For functions, it gives the parameters and return values. This gives you a quick idea of how to use a function. If you need to know what the function actually does, you should consult the Ogre API reference. For example, lets say you needed to know information about SceneNode.rotate. You can consult the builtin help to see what parameters you need to call it with:

>>> 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)


If you have a question about how to use it, then you can consult the API reference for SceneNode, which contains a description of what the function actually does:

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.


As I mentioned before, all of the get/set methods in Ogre have been wrapped into attributes. So if you are trying to use a get/set method you see in the C++ API Reference, just assign it directly instead of trying to call the methods:

# You could do it this way:

sceneNode.position = ogre.Vector3(100, 200, -150)
 
 # But this is nicer:
 sceneNode.position = (100, 200, -150)  # python tuples can be used instead of Vectors


If you are unsure of an attribute, use the builtin help on it:

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)


We have debated putting the actual C++ API reference into PyOgre itself, but this would require a very large overhead in space/memory that the library would take up, and we would have to jump through a lot of hoops to make SWIG generate the proper docstrings. We still plan to come back to this at a future date to try to make the docstrings more useful, but right now we are focusing on other issues with PyOgre.

Versions and API Stability


PyOgre actually consists of two libraries. The first being http://www.ogre3d.org Ogre (which is a 3D rendering engine), the second is http://www.cegui.org.uk CEGUI (which is an embedded GUI system). These two projects are independent of each other, and they are at differing levels of stability.

Ogre has been marked stable as of release 1.0.0. The core API will not change on a patch revision (meaning it won't change from 1.0.0 to 1.0.1, but it does change from 1.0.0 to 1.1.0). This means that PyOgre should not change on patch revisions either, but we are at the mercy of Ogre maintainers for that.

CEGUI is not as old, and has not been marked stable. They can, and frequently do, break interfaces of the library. Be aware of this if you decide to use CEGUI.

Also note that Ogre and CEGUI are completely independent of each other. You can use Ogre with a different widget set (or write your own). You can also use CEGUI with PyOpenGL instead of Ogre.

GUIs and Other Libraries


A quick note about GUIs. Ogre can take care of creating a window for you on whatever platform you are using. If you do not wish to use that feature, you may create your own window and embed PyOgre within it. There are demos in the demos/ directory which show you how to embed PyOgre in a wxPython window. I believe fog has also had good success using pyGTK as a GUI system for PyOgre as well.

If you are looking for an embedded GUI (something that runs from within the rendering environment), you should use CEGUI. I do not know of any other embedded GUI that works with Ogre.

Speeding up PyOgre


Some people go on and on about trying to optimize and speed up their PyOgre applications. I believe pyogre is already faster at 3D rendering than other Python 3D engines. However, if you are still concerned there are really only two things you need to know. First of all pysco (a Python JITer) works great with PyOgre. It can speed up the execution of python code by an astonishing amount. The second thing you need to know is that the overhead in calling any ogre function is significant. So you should probably keep most of your math operations in psyco optimized code. Or, if you are really concerned about it, push your heavy math operations in C/C++ code.

Getting Help


The best way to get help is to ask in the PyOgre forums. I can't promise that fog and I know everything about Ogre, but we try our best at figuring out what the problem is and how to fix it. Also, since C++ Ogre code can be converted very easily into python code, if we can't solve the problem the easiest thing to do is to ask in the C++ Ogre forums and the response you get there can easily be translated into their equivalent Python constructs.

Thanks, and enjoy PyOgre.


Alias: Introduction to PyOgre

<HR>
Creative Commons Copyright -- Some rights reserved.


THE WORK (AS DEFINED BELOW) IS PROVIDED UNDER THE TERMS OF THIS CREATIVE COMMONS PUBLIC LICENSE ("CCPL" OR "LICENSE"). THE WORK IS PROTECTED BY COPYRIGHT AND/OR OTHER APPLICABLE LAW. ANY USE OF THE WORK OTHER THAN AS AUTHORIZED UNDER THIS LICENSE OR COPYRIGHT LAW IS PROHIBITED.

BY EXERCISING ANY RIGHTS TO THE WORK PROVIDED HERE, YOU ACCEPT AND AGREE TO BE BOUND BY THE TERMS OF THIS LICENSE. THE LICENSOR GRANTS YOU THE RIGHTS CONTAINED HERE IN CONSIDERATION OF YOUR ACCEPTANCE OF SUCH TERMS AND CONDITIONS.

1. Definitions

  • "Collective Work" means a work, such as a periodical issue, anthology or encyclopedia, in which the Work in its entirety in unmodified form, along with a number of other contributions, constituting separate and independent works in themselves, are assembled into a collective whole. A work that constitutes a Collective Work will not be considered a Derivative Work (as defined below) for the purposes of this License.
  • "Derivative Work" means a work based upon the Work or upon the Work and other pre-existing works, such as a translation, musical arrangement, dramatization, fictionalization, motion picture version, sound recording, art reproduction, abridgment, condensation, or any other form in which the Work may be recast, transformed, or adapted, except that a work that constitutes a Collective Work will not be considered a Derivative Work for the purpose of this License. For the avoidance of doubt, where the Work is a musical composition or sound recording, the synchronization of the Work in timed-relation with a moving image ("synching") will be considered a Derivative Work for the purpose of this License.
  • "Licensor" means the individual or entity that offers the Work under the terms of this License.
  • "Original Author" means the individual or entity who created the Work.
  • "Work" means the copyrightable work of authorship offered under the terms of this License.
  • "You" means an individual or entity exercising rights under this License who has not previously violated the terms of this License with respect to the Work, or who has received express permission from the Licensor to exercise rights under this License despite a previous violation.
  • "License Elements" means the following high-level license attributes as selected by Licensor and indicated in the title of this License: Attribution, ShareAlike.

2. Fair Use Rights

Nothing in this license is intended to reduce, limit, or restrict any rights arising from fair use, first sale or other limitations on the exclusive rights of the copyright owner under copyright law or other applicable laws.

3. License Grant

Subject to the terms and conditions of this License, Licensor hereby grants You a worldwide, royalty-free, non-exclusive, perpetual (for the duration of the applicable copyright) license to exercise the rights in the Work as stated below:

  • to reproduce the Work, to incorporate the Work into one or more Collective Works, and to reproduce the Work as incorporated in the Collective Works;
  • to create and reproduce Derivative Works;
  • to distribute copies or phonorecords of, display publicly, perform publicly, and perform publicly by means of a digital audio transmission the Work including as incorporated in Collective Works;
  • to distribute copies or phonorecords of, display publicly, perform publicly, and perform publicly by means of a digital audio transmission Derivative Works.
  • For the avoidance of doubt, where the work is a musical composition:
    • Performance Royalties Under Blanket Licenses. Licensor waives the exclusive right to collect, whether individually or via a performance rights society (e.g. ASCAP, BMI, SESAC), royalties for the public performance or public digital performance (e.g. webcast) of the Work.
    • Mechanical Rights and Statutory Royalties. Licensor waives the exclusive right to collect, whether individually or via a music rights society or designated agent (e.g. Harry Fox Agency), royalties for any phonorecord You create from the Work ("cover version") and distribute, subject to the compulsory license created by 17 USC Section 115 of the US Copyright Act (or the equivalent in other jurisdictions).
    • Webcasting Rights and Statutory Royalties. For the avoidance of doubt, where the Work is a sound recording, Licensor waives the exclusive right to collect, whether individually or via a performance-rights society (e.g. SoundExchange), royalties for the public digital performance (e.g. webcast) of the Work, subject to the compulsory license created by 17 USC Section 114 of the US Copyright Act (or the equivalent in other jurisdictions).


The above rights may be exercised in all media and formats whether now known or hereafter devised. The above rights include the right to make such modifications as are technically necessary to exercise the rights in other media and formats. All rights not expressly granted by Licensor are hereby reserved.

4. Restrictions

The license granted in Section 3 above is expressly made subject to and limited by the following restrictions:

  • You may distribute, publicly display, publicly perform, or publicly digitally perform the Work only under the terms of this License, and You must include a copy of, or the Uniform Resource Identifier for, this License with every copy or phonorecord of the Work You distribute, publicly display, publicly perform, or publicly digitally perform. You may not offer or impose any terms on the Work that alter or restrict the terms of this License or the recipients' exercise of the rights granted hereunder. You may not sublicense the Work. You must keep intact all notices that refer to this License and to the disclaimer of warranties. You may not distribute, publicly display, publicly perform, or publicly digitally perform the Work with any technological measures that control access or use of the Work in a manner inconsistent with the terms of this License Agreement. The above applies to the Work as incorporated in a Collective Work, but this does not require the Collective Work apart from the Work itself to be made subject to the terms of this License. If You create a Collective Work, upon notice from any Licensor You must, to the extent practicable, remove from the Collective Work any credit as required by clause 4(c), as requested. If You create a Derivative Work, upon notice from any Licensor You must, to the extent practicable, remove from the Derivative Work any credit as required by clause 4(c), as requested.
  • You may distribute, publicly display, publicly perform, or publicly digitally perform a Derivative Work only under the terms of this License, a later version of this License with the same License Elements as this License, or a Creative Commons iCommons license that contains the same License Elements as this License (e.g. Attribution-ShareAlike 2.5 Japan). You must include a copy of, or the Uniform Resource Identifier for, this License or other license specified in the previous sentence with every copy or phonorecord of each Derivative Work You distribute, publicly display, publicly perform, or publicly digitally perform. You may not offer or impose any terms on the Derivative Works that alter or restrict the terms of this License or the recipients' exercise of the rights granted hereunder, and You must keep intact all notices that refer to this License and to the disclaimer of warranties. You may not distribute, publicly display, publicly perform, or publicly digitally perform the Derivative Work with any technological measures that control access or use of the Work in a manner inconsistent with the terms of this License Agreement. The above applies to the Derivative Work as incorporated in a Collective Work, but this does not require the Collective Work apart from the Derivative Work itself to be made subject to the terms of this License.
  • If you distribute, publicly display, publicly perform, or publicly digitally perform the Work or any Derivative Works or Collective Works, You must keep intact all copyright notices for the Work and provide, reasonable to the medium or means You are utilizing: (i) the name of the Original Author (or pseudonym, if applicable) if supplied, and/or (ii) if the Original Author and/or Licensor designate another party or parties (e.g. a sponsor institute, publishing entity, journal) for attribution in Licensor's copyright notice, terms of service or by other reasonable means, the name of such party or parties; the title of the Work if supplied; to the extent reasonably practicable, the Uniform Resource Identifier, if any, that Licensor specifies to be associated with the Work, unless such URI does not refer to the copyright notice or licensing information for the Work; and in the case of a Derivative Work, a credit identifying the use of the Work in the Derivative Work (e.g., "French translation of the Work by Original Author," or "Screenplay based on original Work by Original Author"). Such credit may be implemented in any reasonable manner; provided, however, that in the case of a Derivative Work or Collective Work, at a minimum such credit will appear where any other comparable authorship credit appears and in a manner at least as prominent as such other comparable authorship credit.

5. Representations, Warranties and Disclaimer

UNLESS OTHERWISE AGREED TO BY THE PARTIES IN WRITING, LICENSOR OFFERS THE WORK AS-IS AND MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND CONCERNING THE MATERIALS, EXPRESS, IMPLIED, STATUTORY OR OTHERWISE, INCLUDING, WITHOUT LIMITATION, WARRANTIES OF TITLE, MERCHANTIBILITY, FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, OR THE ABSENCE OF LATENT OR OTHER DEFECTS, ACCURACY, OR THE PRESENCE OF ABSENCE OF ERRORS, WHETHER OR NOT DISCOVERABLE. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO SUCH EXCLUSION MAY NOT APPLY TO YOU.

6. Limitation on Liability.

EXCEPT TO THE EXTENT REQUIRED BY APPLICABLE LAW, IN NO EVENT WILL LICENSOR BE LIABLE TO YOU ON ANY LEGAL THEORY FOR ANY SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR EXEMPLARY DAMAGES ARISING OUT OF THIS LICENSE OR THE USE OF THE WORK, EVEN IF LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

7. Termination

  • This License and the rights granted hereunder will terminate automatically upon any breach by You of the terms of this License. Individuals or entities who have received Derivative Works or Collective Works from You under this License, however, will not have their licenses terminated provided such individuals or entities remain in full compliance with those licenses. Sections 1, 2, 5, 6, 7, and 8 will survive any termination of this License.
  • Subject to the above terms and conditions, the license granted here is perpetual (for the duration of the applicable copyright in the Work). Notwithstanding the above, Licensor reserves the right to release the Work under different license terms or to stop distributing the Work at any time; provided, however that any such election will not serve to withdraw this License (or any other license that has been, or is required to be, granted under the terms of this License), and this License will continue in full force and effect unless terminated as stated above.

8. Miscellaneous

  • Each time You distribute or publicly digitally perform the Work or a Collective Work, the Licensor offers to the recipient a license to the Work on the same terms and conditions as the license granted to You under this License.
  • Each time You distribute or publicly digitally perform a Derivative Work, Licensor offers to the recipient a license to the original Work on the same terms and conditions as the license granted to You under this License.
  • If any provision of this License is invalid or unenforceable under applicable law, it shall not affect the validity or enforceability of the remainder of the terms of this License, and without further action by the parties to this agreement, such provision shall be reformed to the minimum extent necessary to make such provision valid and enforceable.
  • No term or provision of this License shall be deemed waived and no breach consented to unless such waiver or consent shall be in writing and signed by the party to be charged with such waiver or consent.
  • This License constitutes the entire agreement between the parties with respect to the Work licensed here. There are no understandings, agreements or representations with respect to the Work not specified here. Licensor shall not be bound by any additional provisions that may appear in any communication from You. This License may not be modified without the mutual written agreement of the Licensor and You.