Understanding the Mogre build process

It seems to me that there are a lot of people around here trying to understand the Mogre build process, and with good reason too, because it's a gigantic beast of confusion. So, I've started this topic to try and answer some of the questions. I think with our combined efforts we can get to the bottom of this.

As far as I know, the best instructions we have at the moment are the build instructions on bitbucket.

Here are some questions to get started:

- Clone Mogre: "hg clone http://bitbucket.org/mogre/mogre -u Mogre17 Mogre".
- Clone Ogre 1.7: "hg clone http://bitbucket.org/sinbad/ogre -u 58266f25ccd2 Mogre\Main\OgreSrc\ogre".

What software can I use to do this?
http://tortoisehg.bitbucket.org/

What do the parameters mean and how do I change them to build the latest version of Mogre?
http://www.selenic.com/mercurial/hg.1.html#clone

- Apply "Mogre\Main\Ogre Patches\58266f25ccd2.patch" to "Mogre\Main\OgreSrc\ogre".

What does the patch do?
How is it created?

- Download "http://surfnet.dl.sourceforge.net/project/ogre/ogre-dependencies-vc%2B%2B/1.7/OgreDependencies_MSVC_20100501.zip";.
- Unpack "OgreDependencies_MSVC_20100501.zip" into "Mogre\Main\OgreSrc\ogre", it will create a folder "Dependencies".
- For VS2008, open the dependencies solution file "Mogre\Main\OgreSrc\ogre\Dependencies\src\OgreDependencies.VS2008.sln" in Visual Studio.
- For VS2010, open the dependencies solution file "Mogre\Main\OgreSrc\ogre\Dependencies\src\OgreDependencies.VS2010.sln" in Visual Studio.
- Use batch build to rebuild all 32bit projects in the solution. Do NOT compile the x64 configurations!

Will I need different dependencies if I want to build a different version of Mogre?
Why can't I build the x64 versions?
Can I do this on the command line instead of in Visual Studio?

- Start CMake to generate Ogre build files. Select either "Visual Studio 9 2008" or "Visual Studio 10" as cmake project type.
- Use "Mogre\Main\OgreSrc\ogre" as source directory.
- Target "Mogre\Main\OgreSrc\build" as output directory for cmake.
- Make sure you have OGRE_CONFIG_ENABLE_PVRTC switched ON and OGRE_CONFIG_CONTAINERS_USE_CUSTOM_ALLOCATOR switched OFF.
- Then press "configure" again in cmake and if no more errors occur, press "generate".

Where can I get CMake? http://www.cmake.org/
Why do I need to change the OGRE_CONFIG_ENABLE_PVRTC and OGRE_CONFIG_CONTAINERS_USE_CUSTOM_ALLOCATOR options?
Can I do this on the command line?

- Go to folder "Mogre\Codegen\cpp2java" and execute "build.bat" in this folder.

What does this do?


- For VS2008, open solution "Mogre\Codegen\AutoWrap\AutoWrap.sln" in Visual Studio and compile the Debug version.
- For VS2010, open solution "Mogre\Codegen\AutoWrap\AutoWrap_vs2010.sln" in Visual Studio and compile the Debug version.
- Execute "AutoWrap.exe" in folder "Mogre\Codegen\AutoWrap\bin\Debug" and press button "Produce".

What does the AutoWrap tool do?

- Go to folder "Mogre\Main\Ogre" and execute "copy_to_ogre.bat" in this folder.

What does this do?

- Copy "Mogre\Main\include\auto\CLRObjects.inc" to folder "Mogre\Main\OgreSrc\build\include".
- Open solution "Mogre\Main\OgreSrc\build\OGRE.sln" in Visual Studio.
- In the solution explorer window of Visual Studio, find project "OgreMain" and right click it.
- Select "Add->Existing Item..." and navigate to "Mogre\Main\OgreSrc\ogre\OgreMain\src", add "CLRHandle.cpp" and "CLRObject.cpp".
- In the solution explorer window of Visual Studio, find project "OgreMain" and right click it.
- Select "Add->Existing Item..." and navigate to "Mogre\Main\OgreSrc\ogre\OgreMain\include", add "CLRConfig.h", "CLRHandle.h" and "CLRObject.h".
- Open "CLRConfig.h" in Visual Studio and change "#define LINK_TO_MOGRE 1" to "#define LINK_TO_MOGRE 0".

Why do I need to do these steps?

- Open the batch build window in Visual Studio.
- Select "Debug|Win32" and "Release|Win32" for the following projects:
...
- Rebuild all selected projects.

Can this be done on the command line?

- If there are linker errors for "_ITERATOR_DEBUG_LEVEL" mismatch, check "http://www.ogre3d.org/forums/viewtopic.php?f=1&t=54533&start=100#p388654";,
I could fix the errors by compiling debug version of dependencies first, then compiling release versions of dependencies separately.

I read the forum topic and I still don't understand this error?


- For VS2008, open soultion "Mogre\Main\Mogre_vc9.sln" in Visual Studio.
- For VS2010, open soultion "Mogre\Main\Mogre_vs2010.sln" in Visual Studio.
- Use batch build to rebuild all projects.
- Open solution "Mogre\Main\OgreSrc\build\OGRE.sln" again.
- Open "CLRConfig.h" in Visual Studio and change "#define LINK_TO_MOGRE 0" back to "#define LINK_TO_MOGRE 1".

What does the LINK_TO_MOGRE define do?

- Open batch build and use a normal build instead of rebuild all this time, this will save a lot of time.
- Debug binaries are in "Mogre\Main\lib\Debug" and "Mogre\Main\OgreSrc\build\lib\Debug".
- Release binaries are in "Mogre\Main\lib\Release" and "Mogre\Main\OgreSrc\build\lib\Release".

Where do I report problems if it didn't work?
viewforum.php?f=8

Right now, I am writing a wiki page that describes the whole build process and gives some more information. But this page won't be complete since I can only write down the experiences I made. But since I have tried to build Mogre about one hundred times (and now finally once successfully!) it is a pretty good start

As far as I know, the best instructions we have at the moment are the build instructions on bitbucket.
There are also some really good instructions in the archive provided by user Cgon.


If there are linker errors for "_ITERATOR_DEBUG_LEVEL" mismatch, check "http://www.ogre3d.org/forums/viewtopic.php?f=1&t=54533&start=100#p388654";, I could fix the errors by compiling debug version of dependencies first, then compiling release versions of dependencies separately.
I read the forum topic and I still don't understand this error?
I finally found a way to get rid of this error by reading the mentioned forum thread many times! I will post the solution on the wiki page.

So here it is. Please read and say what is wrong (hopefully nothing ) and what is not described enough (hopefully not much ). I tried to write it as I would be happy to had it when I first tried to compile Mogre and I tried to answer all questions mentioned above. Please comment!

To-Do:
When and how to add user Cygon's patch:

This patch adds some #pragma managed(push, off) sections around unmanaged
headers, preventing the compiler from generating MSIL representations of
countless C++ standard library types that aren't used on the C# side anyway.

The results were:
Mogre.dll (x86) from 12.3 MiB to 8.1 MiB
Mogre.dll (x64) from 20.8 MiB to 9.0 MiB

If also moves the shutdown code from the finalizer of Mogre.Root into its
destructor (IDisposable.Dispose()). This is done because Ogre's OpenGL driver
couldn't cope with the shutdown happening from the GC thread. Maybe future
versions of Ogre won't need this change.


@Beauty: Feel free to edit the page when its layout is not so good (it's only my second wiki page).

Great job, McDonte !!

I don't care so much about the layout.
Most important is your documented knowledge!

Update:
Now I added a few links. From other wiki pages to your page. And on your page to external websites. Also I announced your comprehensive wiki page in the Mogre news box.

Thank you for the improvements and for putting it in the news box. I noticed you already put in on the side "Building Mogre from source".

I don't care so much about the layout.
I think layout is important because it makes reading more comfortableand so the infromation more accessible

Most important is your documented knowledge!
I will keep adding information when I get/read/collect them somewhere!

That's awsome McDonte. This kind of documentation is far more valuable than just doing it yourself and handing over the binaries. It's kind of like the old saying, give a man a fish and feed him for a day, teach a man to fish and feed him for a lifetime.

A lot of developers dislike writing documentation (myself included) but as I move through my career as a software developer I've learned the difference between good software and great software is not features, but how easy it is to use. You've just made Mogre a little more great

And Beauty, good job keeping people motivated to update the wiki. It's becoming a tremendous resource.

Thank you zarfius, I hope I answered all questions you wrote down in the first post. To complete this guide I created today a new wiki page that contains special information about building Mogre for x64 systems. I thought about it because you asked why mstoyke wrote in the build instructions
Do NOT compile the x64 configurations!
I noticed that there are actually no instructions for the x64 build but actually it is not so hard. Hopefully there are no errors, otherwise please correct them.

@Beauty: My pages are still located in the sandbox, can you move them to the main wiki (because I have no idea how to do)?

@Beauty: My pages are still located in the sandbox, can you move them to the main wiki (because I have no idea how to do)?
Good question. Some days ago I also wanted to move a page to an other position of the wiki structure, but I couldn't find out how.
Either it's documented in the wiki help or somewhere in the forum topic The new Ogre wiki. I was to lazy to search again.

Or we just clone it at the new location... does this work?

It would work, but a it's no fine way and the history is deleted.
Better is to search for the "correct" way.

Or we just clone it at the new location... does this work?
It would work, but a it's no fine way and the history is deleted.
Better is to search for the "correct" way.

This says to ask a WikiAdmin, although, I think it should be easier than that and the instructions should be on the sandbox page.
http://www.ogre3d.org/tikiwiki/Ogre+Wik ... ew#Sandbox

Ok, I searched for it and found the solution in the forum.
Now I added the description to the wiki. (here) It can only be done by a wiki admin (like me).
Today I'm very tired. Tomorrow I go on holiday. I will do it when I'm back (next month).

Update:
To finish this work (instead of suppressing or forgetting) I did it now. Structure editing is very complicated and time killing (even by the linked quick guide). After "warming up" I corrected some other structure places of Mogre pages.
40 minutes just for a few structure edits

Thanks again Beauty for your hard wiki work. Have a nice vacation!

Thanks again Beauty for your hard wiki work. Have a nice vacation!
I agree in both cases!
Thank you and take some time to relax!

Quotes of an older post from an other topic, which also belongs to here.

Your problem is solved, but I want to add something.

For some mathematical calculations the Mogre wrapper still uses System.Math instead of Ogre.Math.
I suppose this decision was done by the retired Mogre author Bekas for performance reasons.
Unfortunately in some cases this causes different behaviour than Ogre or even invalid values in special cases. (e.g. look to the Quaternion.Yaw problem)
The know funktions/properties I added to the Mogre bug tracker.

I thought about to fix that issues in the Mogre wrapper code.
Either by use of Ogre.Math instead of System.Math (slower, secure) or by porting the calculation code to C# (faster).
1)
Both should be easy, but I have only very less C++ knowledge. So I'm aware to write invalide code.
2)
I'm not shure how/where to apply the changes correctly. When I update the wrapper code directly, the Mogre autowrapper would overwrite my changes (when it's applied later in the future).
Most of the Ogre class members are wrapped automatically by the autowrapper. Some other members are not wrapped and use pure .NET code instead (e.g. class Vector3).
Does anybody know how/where to apply changes for class members which are not wrapped by the autowrapper?
3)
Somebody has to re-build Mogre to become the changes available for applications.

Well, has anybody an idea how we want to fix this kind of Mogre bugs?


I suppose this decision was done by the retired Mogre author Bekas for performance reasons.

I think this decision was probably the right one because the math classes are often used in a lot of performance critical code. However, it's also important that the math classes work correctly.

Either by use of Ogre.Math instead of System.Math (slower, secure) or by porting the calculation code to C# (faster).

Porting the code to C# is probably okay since this code is likely very stable and unlikely to change.

I'm not sure how/where to apply the changes correctly.

This is the real issue here. Mogre has always been pretty difficult to maintain and runs the very real risk of getting behind the latest version of Ogre (especially in terms of plugins like the Terrain manager).

The only thing I can think to do is to make a list of all the problems we are currently having maintaining Mogre in another forum post (or on the wiki) and take small steps to solve them. The problems seem too great for any one person to solve alone.

My most important point is this:

I'm not shure how/where to apply the changes correctly. When I update the wrapper code directly, the Mogre autowrapper would overwrite my changes (when it's applied later in the future).
Most of the Ogre class members are wrapped automatically by the autowrapper. Some other members are not wrapped and use pure .NET code instead (e.g. class Vector3).
Does anybody know how/where to apply changes for class members which are not wrapped by the autowrapper?

Does anybody know more about this?

Today I found again a post, which I wrote 10 months ago.
It should be interesting for understanding the Mogre build process.

The whole discussion is in this (old) forum topic:
idea: new C# wrapper which supports Linux, MacOS, etc.

===============================================================================

I'm currently refractoring and documenting the whole AutoWrap code (which is quite hard as there's virtually no documentation at all in the code nor elsewhere). Perhaps this then could be used as starting point for creating a PInvoke wrapper but there's still a long way to go. You can check on the progress here:

http://bitbucket.org/manski/mymogre/ (branch: autowrap-dev)
(Post from here)

The wrapper documentation is a little bit hidden. Here are the direct links:
http://bitbucket.org/manski/mymogre/src/tip/build.txt (main doku)
http://bitbucket.org/manski/mymogre/src/tip/Codegen/AutoWrap/readme.txt (main doku)
http://bitbucket.org/manski/mymogre/src/tip/Codegen/cpp2java/readme.txt (tiny notes)
http://bitbucket.org/manski/mymogre/src/tip/Codegen/mogre_xml/readme.txt (tiny notes)


I will soon take some time to review the code changes that manski made. Then I will merge them into the official repository and I think manski might very soon have write access to the repository

I'm not sure whether you really want to review all code changes (as there are many) As for the code changes: I'm trying to be very careful about all code changes. Therefore before I commit a change, I always regenerate the whole MOGRE source code and compare it with the previous version. This way I can ensure that I don't introduce bugs/code that changes the code generation in some unwanted way. (This make the code rewrite much easier btw as the MOGRE code is my test suite.) However, it's still possible that I introduce bugs (by mistake, of course) in methods that aren't currently used for MOGRE's code generation. In this case (as in all others) any feedback is appreciated.

Regarding merging the code into the official repository: There are some changes that you should be aware of:

1. I've slightly changed the UI so screenshots and tutorials need to be updated.[/*:m]
   
2. I've reformatted some files of AutoWrap's code with my own styleguide. So some files are still in Bekas' style and some in mine. Sorry about that but Visual Studio is simply a horrible IDE (in some places) and doesn't allow me to specify a code style on a per-project- or per-solution-basis.[/*:m]
   
3. Currently the generated code will use two spaces instead of one tab for indention (I'm not a big fan of tabs as everyone has different tab widths) and use Windows line endings (instead of Linux line endings), though this is configurable.[/*:m]
   
4. The biggest changes (so far) is that my AutoWrap implementation creates set accessors for boolean property (where the old implementation create set methods). You can find the change to the code in changeset f24fcc3ed3fc. This is change is important as it breaks backward compatibility. I did this code change, as IMHO the code now does the correct thing.[/*:m][/list:u]
   
   I just need to make sure first that his changes will not break the code changes that were necessary for the new components.
   

===============================================================================

Unfortunatelly I think, manskis improvements were not included to the main repository.
We should look to his code changes and perhaps add grabb them.

It took me a long while until I found some time to read your post above and check the links you posted.
The whole discussion is in this (old) forum topic:
idea: new C# wrapper which supports Linux, MacOS, etc.
Really interesting to read, unfortunetaly it just breaks up and we do not know what happened to the project. My conclusion is:

1. We should stick with the way Mogre is wrapped at the moment.[/*:m]
   
2. Extending the wrapper to work also an other platforms sounds neat but I honestly do not understand what mstoyke's aim was and since he is not here anymore hew cannot explain.[/*:m]
   
3. Bekas' attempt to combine Ogre and Mogre into one binary should be followed. I think this is really only an issue about setting VS preferences the right way.[/*:m][/list:u]
   
   http://bitbucket.org/manski/mymogre/src/tip/build.txt (main doku)
   http://bitbucket.org/manski/mymogre/src ... readme.txt (main doku)
   http://bitbucket.org/manski/mymogre/src ... readme.txt (tiny notes)
   http://bitbucket.org/manski/mymogre/src ... readme.txt (tiny notes)
   This is probably the most useful Mogre ressource I have ever read. Thanks a lot, Beauty, everybody interested in Mogre development should take a serious look at it! Also you should look at this link: https://bitbucket.org/manski/mymogre/sr ... ibutes.txt
   It describes the usage of the AutoWrap tool.
   
   Unfortunatelly I think, manskis improvements were not included to the main repository.
   We should look to his code changes and perhaps add grabb them.
   This could be useful but as mstoyke already said, they might interfer with the changes he made for the new components. When we have figured out which changes from who affect what we can add them. Now I will go and take a look at the AutoWrap tool... all this information I read gave me some new motivation to understand this tool

By a search for an other topic I found possibly useful information about the wrapping process:


what's a native director??
If I remember correctly, this is for creating managed classes that can "override" the methods of a native class (if you override a virtual method from the managed class it gets called by the native object).


2-step linking process (build OgreMain with LINK_TO_MOGRE 0, then Mogre, then OgreMain again)



Hey guys,

I'm glad you like the changes I made to the AutoWrap code (and I'm even more glad that the original author likes them, too).

[...]

Regarding merging the code into the official repository: There are some changes that you should be aware of:

1. I've slightly changed the UI so screenshots and tutorials need to be updated.[/*:m]
   
2. I've reformatted some files of AutoWrap's code with my own styleguide. So some files are still in Bekas' style and some in mine. Sorry about that but Visual Studio is simply a horrible IDE (in some places) and doesn't allow me to specify a code style on a per-project- or per-solution-basis.[/*:m]
   
3. Currently the generated code will use two spaces instead of one tab for indention (I'm not a big fan of tabs as everyone has different tab widths) and use Windows line endings (instead of Linux line endings), though this is configurable.[/*:m]
   
4. The biggest changes (so far) is that my AutoWrap implementation creates set accessors for boolean property (where the old implementation create set methods). You can find the change to the code in changeset f24fcc3ed3fc. This is change is important as it breaks backward compatibility. I did this code change, as IMHO the code now does the correct thing.[/*:m][/list:u]
   [...]
   

Note for the last quote:
This is about the improvements of Manski. Currently they are not in the official repository.
I hope the improvements will be merged in the future. For this I created the forum topic Task: Add Mogre core improvements of Manski to repository

I've recently built Mogre using the original automated MogreBuilder. It wasn't particularly easy, but it did help to understand the build process better. For more details see this thread.

First of all:
Please don't forget to add the improvements of manski (e.g. documentation) to our official repository.

Second:
The last two days I talked with mstoyke (retired Mogre maintainer) in the mogre chat.
I asked him for details about the Terrain wrapper which he created. Here they are:

The Mogre autowrapper was modified to wrap the Terrain and Paging component automatically. (All public API members.)
In other words: The wrapper for the Terrain/Paging component is no hand written wrapper.
The advantage of the current solution is, that it wraps changes and new API features automatically.

Note: Some API functions of the components are disabled / not wrapped, because they caused problems.
The list of all disabled API functions are defined in file Codegen\AutoWrap\Attributes.xml.

So, I hope this is useful for people, who want be play with the components or modify the wrapper.

If found a post, written 3 months ago in the feature request topic:
That about "Ability to override Ogre classes" (from old Mogre roadmap)?
Classes like SimpleRenderable are very important if you want to convert c++ ogre code to mogre (for example the deferred shading example code from > 1.7 or gorilla) without messing around with movableobject.

How it's possible to enable "override" for a class?

1) Modify the wrapper tool?
2) Modify the Ogre source code before wrapping?

For the second case it would be easy to add a task to the MogreBuilder, which applies the modification.

Tubulii, can you give us some more details, please?
The best would be:
* Tell us the related file name(s)
* Quote the line of code current code (method definition)
* Tell us how it has to be modified to become overridable. (Perhaps it's just adding/removing/replacing one "command".)

If I figured out correct, the autowrapper "wrapping tasks" are configured in the file
Codegen\AutoWrap\Attributes.xml

It also contains disable flags for some methods of the terrain and paging components (which caused wrapping problems when mstoyke added support for the components).

Unfortunately I don't know details about how to make additions to the Mogre autowrapper.

Maybe this information is still useful for somebody.

There are also some really good instructions in the archive provided by user Cgon.
McDonte, can you please tell us more details?
In best case tell us the file names including path.

Or did you (Zarifus) already found/add them to the official Mogre sources?

I just want to remind this point, because it would be sad if this useful information get lost.
(Means: Nearly nobody remember that/where it exists. Especial this can happen for new people.)

Ok, this evening I put my effort to find and "import" the documentations of other users, which published them outside of our official Mogre repository. They describe details about the building and wrapping process.

Thanks to following users:

1. Manski[/*:m]
   
2. GantZ[/*:m]
   
3. mstoyke[/*:m]
   
4. Cygon[/*:m][/list:u]
   
   They all helped to share their knowledge.
   
   The build instruction files I added to the root directory of the Mogre repository.
   Maybe it's a little bit confusing to have 3 instruction files, but they all contain useful information.
   Also I added "forewords" to give the reader a better "orientation".
   
   To have everything inside of this topic, I just quote the content of the 3 files.
   
   If you want to make corrections or additions, just do it.
   Either check it in yourself or post the modified text paragraphs here.
   
   
   Build instructions by Manski.txt
   

--- Foreword ---

This instruction file was created by user Manski in August(?) 2010
related to Mogre 1.7.

It was the first comprehensive documentation, which was written at all.
This was hard reverse-engineering work, because there was not much
information before and the very few "wrapping specialists" became inactive.

Note:
Have a look to the MogreBuilder.
By this tool you can do the building/wrapping process very easy.
http://www.ogre3d.org/tikiwiki/MogreBuilder

So, this was my "foreword". (Written by Beauty in April 2012.)






Step by step instructions to build Mogre/Ogre with Visual Studio
================================================================

Repository information
----------------------
The repositories for MOGRE and OGRE are based on the official repositories.
They've slightly modified to fix certain bugs not (yet) fixed in the official
sources. They also aim to the goal to provide an easier way of build MOGRE.

By cloning the MOGRE repository, the other two repositories are cloned as well
automatically (as sub repositories). The can be found here:

/ - MOGRE repository: http://bitbucket.org/manski/mymogre/
/Main/OgreSrc/ogre - OGRE repository: http://bitbucket.org/manski/myogre
/Main/OgreSrc/ogre/Dependencies - OGRE dependencies repository: http://bitbucket.org/manski/myogredependencies/

Custom changes the MOGRE and the OGRE repository are placed in their own named
branch. The branches of the original repository remain unchanged to allow easier
pulling of changes in the original repositories. The named branches are:

MOGRE: mymogre
OGRE: mogre-patched
Dependencies: default (since there is no official repository for them)

To clone the MOGRE repository, use:

$ hg clone -u mymogre http://bitbucket.org/manski/mymogre


Necessary Software
------------------
You need to have the following pieces of software installed on your computer
to build MOGRE:

* Microsoft Visual Studio 2008 or 2010 (Express Edition should do; you need Visual C++)
http://www.microsoft.com/express/Windows/

* .NET framework 2.0 or higher (should usually be installed together with
Visual Studio)

* CMake for generating the project files for OGRE (tested with CMake 2.8.2)
http://www.cmake.org/

* A mercurial client for cloning the repository (TortoiseHg will work nicely)
http://mercurial.selenic.com/
http://tortoisehg.bitbucket.org/

* The DirectX SDK (tested with DirectX SDK June 2010)
http://msdn.microsoft.com/en-us/directx/


Building MOGRE
--------------
The following instructions can be used to build this MOGRE repository. Note that
most auto-generated code is already included in the repository. For more
information about the auto-generaed code and its regeneration, see below.

This instructions assume that you've already cloned the MOGRE repository. If
not, run the command from the previous section to do so. The directory in which
you've clone the repository will be represented by "$REPOS" in the instructions.

* Building the dependencies:
* Open the solution file apropriate for your Visual Studio version (e.g.
"OgreDependencies.VS2010.sln" for Visual Studio 2010) from:
$REPOS\Main\OgreSrc\ogre\Dependencies\src\

* Build both the DEBUG and the RELEASE versions! (Both version are needed for
CMake.)

* Create OGRE's project files:
* Open the cmake-gui (a link should have been created in your start menu when
you installed CMake)

* Under "Where is the source code" select this folder:
$REPOS\Main\OgreSrc\ogre

* Under "Where to build the binaries" select this folder (may not yet exist)
$REPOS\Main\OgreSrc\build

* Click "Configure". If you run configure for the first time, you need to
select your IDE (e.g. Visual Studio 2010). Leave all options (except for
the IDE selection) like they are, unless you know what you're doing.

* Change the following build properties (you need to switch to "Advanced" mode):
* OGRE_CONFIG_ENABLE_PVRTC = on
* OGRE_CONFIG_CONTAINERS_USE_CUSTOM_ALLOCATOR = off
* OGRE_BUILD_SAMPLES = off (optional; speeds up the build process by excluding example projects)

* Click "Configure" again

* Click "Generate" to generate the project files; they will be placed in the
"binaries" directory specified above.

* Build OGRE:
* Open the solution file for OGRE:
$REPOS\Main\OgreSrc\build\Ogre.sln

* Add the following files to the project "OgreMain". (You can do this by
expanding the project "OgreMain", right clicking on "Source Files"/
"Header Files" and choosing "Add" -> "Existing item...")
* Source Files:
$REPOS\Main\Ogre\CLRHandle.cpp
$REPOS\Main\Ogre\CLRObject.cpp
* Header Files (optional; just for easier editing):
$REPOS\Main\Ogre\CLRConfig.h
$REPOS\Main\Ogre\CLRHandle.h
$REPOS\Main\Ogre\CLRObject.h
$REPOS\Main\include\auto\CLRObjects.inc

* Unfortunately MOGRE and OGRE depend on each other (dependency cycle). So,
if this is the first time you build MOGRE (i.e. if the file
$REPOS\Main\lib\Debug,Release\mogre.lib doesn't exist), you need to break
this cycle once.
* To do so open the file "CLRConfig.h" in the "OgreMain" project and change
"LINK_TO_MOGRE" to "0":

#define LINK_TO_MOGRE 0

This avoids a linker error. We will revert this change in a later step.
If you already have a "mogre.lib" file, you should skip this step.

* Build the whole solution. You can build both DEBUG and RELEASE
version or just the one you want to use together with MOGRE (e.g. OGRE
Debug with MOGRE Debug).

* Build MOGRE:
* Open the solution file for MOGRE (according to your Visual Studio version)
located in this folder:
$REPOS\Main (e.g. Mogre_vx2010.sln)

* Build MOGRE.

* If you've set "LINK_TO_MOGRE" to "0" in the steps above, change it again to
"1" and then build the OGRE solution again (just a regular build, no rebuild
necessary).


The build results can be found here:
* For Debug: "$REPOS\Main\lib\Debug" and "$REPOS\Main\OgreSrc\build\lib\Debug"
* For Release: "$REPOS\Main\lib\Release" and "$REPOS\Main\OgreSrc\build\lib\Release".


Manually generate sources
-------------------------
Most of MOGRE's source code is auto-generated. This repository already contains
all auto-generated sources. However, if you need to re-auto-generate the sources
for some reason (for example when a new version of OGRE is released; see next
section), here is how this works.

IMPORTANT: Make sure that fixes that were applied to the sources are applied
again (or at least not overwritten). Check the changelog of the repository
for applied patches.

Prerequisite: You need to compile the "AutoWrap" project found here:
"$REPOS\Codegen\AutoWrap". Also you need to have a Java runtime (JRE)
installed on your system to be able to run "cpp2java".

Execute the following steps to generate MOGRE's sources from OGRE's sources:

* First the OGRE sources may need to be patched (depending on the grade of
change) to prepare them for use together with the .NET runtime (CLR). The
patch to do this can be found here:
$REPOS\Main\Ogre Patches

The "easiest" way to patch the sources is to install "patch" via Cygwin
(found under "Utils/Patch" in the installer). Then execute in a command
prompt:
$ cd $REPOS\Main\OgreSrc\ogre
$ c:\cygwin\bin\patch.exe --no-backup-if-mismatch -p0 <"..\..\..\Ogre Patches\mogre.patch"

* Execute "build.bat" (preferably in a command prompt) inside the folder:
$REPOS\Codegen\cpp2java

* Run "AutoWrap" from $REPOS\Codegen\AutoWrap and click on "Produce".

The auto-generated files are placed here:

* Headers: $REPOS\Main\include\auto
* Sources: $REPOS\Main\src\auto


Updating
--------
This section is for maintenance only and describes how to update the OGRE and
the MOGRE sources. For ease-of-use reasons the steps will use TortoiseHg (but
should be easily adaptable to any other Mercurial client).

Updating MOGRE and OGRE requires the same steps but on different repositories
and branches. (The paths of the custom repositories "myOgre" and "myMogre" are
described at the top of this file.)

1. Pull newest changes from the original repository into custom repository.
For this use the "Synchronize" dialog. Make sure you've added to original
repository to the repository settings (as non-default).

Original Repositories:
* OGRE: http://bitbucket.org/sinbad/ogre
* MOGRE: http://bitbucket.org/mogre/mogre

2. Merge changes into custom branch. Use the "Repository Explorer" for this.

"original branch"/"custom branch":
* OGRE: "v1-7"/"mogre-patched"
* MOGRE: "Mogre17"/"mymogre"

a. Make sure to have checked out the revision you want to merge with
(usually the tip of the "custom branch")
b. Select the "original branch" (like "v1-7" for OGRE) from the
"Branches..." dropdown field.
c. Check which changes can be safely merged into the working copy.
d. Right-click the latest, safe revision and choose "Merge with...". Then
click "Merge". This will merge the changes into the working copy.
e. Resolve any conflicts and commit the changes to the "custom branch".
IMPORTANT: Make sure you commit to the right branch (selectable in the
"Commit" window).

3. Changes to the source may make it necessary to regenerate the MOGRE's
sources. See above how to do this.
IMPORTANT: Regenerating may overwrite certain code changes in the
auto-generated source. Make sure to add these changes again after
re-generating the sources.

4. Push the changes back to bitbucket (using the "Synchronization" dialog).


For "myOgreDependencies" see "[Repos]/Main/OgreSrc/ogre/Dependencies/build.txt"


This is what cmake printed out for me as project configuration summary
======================================================================

----------------------------------------------------------------------------
FEATURE SUMMARY
----------------------------------------------------------------------------

Building components:
+ Paging
+ Terrain
+ RTShader System
+ RTShader System Core Shaders
+ RTShader System Extensions Shaders
Building plugins:
+ BSP scene manager
+ Cg program manager
+ Octree scene manager
+ Portal connected zone scene manager
+ Particle FX
Building rendersystems:
+ Direct3D 9
+ OpenGL
Building executables:
+ Samples
+ Tools
Building core features:
+ DDS image codec
+ PVRTC image codec
+ FreeImage codec
+ ZIP archives

Build type: dynamic
Threading support: none
Use double precision: disabled
Allocator type: nedmalloc (pooling)
STL containers use allocator: disabled
Strings use allocator: disabled
Memory tracker (debug): disabled
Memory tracker (release): disabled
Use new script compilers: enabled
Use Boost: disabled

   
   
   
   
   Build instructions by mstoyke.txt
   

--- Foreword ---

This instruction file was originally written by user GantZ
in year 2010. Later it was improved by user mstoyke (also in 2010).
It's related to Mogre 1.7.


Note:
Have a look to the MogreBuilder.
By this tool you can do the building/wrapping process very easy.
http://www.ogre3d.org/tikiwiki/MogreBuilder

So, this was my "foreword". (Written by Beauty in April 2012.)







Step by step instructions to build Mogre/Ogre 1.7.1 with Visual Studio:
=======================================================================

- Clone Mogre: "hg clone http://bitbucket.org/mogre/mogre -u Mogre17 Mogre".
- Clone Ogre 1.7: "hg clone http://bitbucket.org/sinbad/ogre -u 58266f25ccd2 Mogre\Main\OgreSrc\ogre".
- Apply "Mogre\Main\Ogre Patches\58266f25ccd2.patch" to "Mogre\Main\OgreSrc\ogre".
- Download "http://surfnet.dl.sourceforge.net/project/ogre/ogre-dependencies-vc%2B%2B/1.7/OgreDependencies_MSVC_20100501.zip";.
- Unpack "OgreDependencies_MSVC_20100501.zip" into "Mogre\Main\OgreSrc\ogre", it will create a folder "Dependencies".
- For VS2008, open the dependencies solution file "Mogre\Main\OgreSrc\ogre\Dependencies\src\OgreDependencies.VS2008.sln" in Visual Studio.
- For VS2010, open the dependencies solution file "Mogre\Main\OgreSrc\ogre\Dependencies\src\OgreDependencies.VS2010.sln" in Visual Studio.
- Use batch build to rebuild all 32bit projects in the solution. Do NOT compile the x64 configurations!
- Start CMake to generate Ogre build files. Select either "Visual Studio 9 2008" or "Visual Studio 10" as cmake project type.
- Use "Mogre\Main\OgreSrc\ogre" as source directory.
- Target "Mogre\Main\OgreSrc\build" as output directory for cmake.
- Make sure you have OGRE_CONFIG_ENABLE_PVRTC switched ON and OGRE_CONFIG_CONTAINERS_USE_CUSTOM_ALLOCATOR switched OFF.
- Then press "configure" again in cmake and if no more errors occur, press "generate".
- Go to folder "Mogre\Codegen\cpp2java" and execute "build.bat" in this folder.
- For VS2008, open solution "Mogre\Codegen\AutoWrap\AutoWrap.sln" in Visual Studio and compile the Debug version.
- For VS2010, open solution "Mogre\Codegen\AutoWrap\AutoWrap_vs2010.sln" in Visual Studio and compile the Debug version.
- Execute "AutoWrap.exe" in folder "Mogre\Codegen\AutoWrap\bin\Debug" and press button "Produce".
- Go to folder "Mogre\Main\Ogre" and execute "copy_to_ogre.bat" in this folder.
- Copy "Mogre\Main\include\auto\CLRObjects.inc" to folder "Mogre\Main\OgreSrc\build\include".
- Open solution "Mogre\Main\OgreSrc\build\OGRE.sln" in Visual Studio.
- In the solution explorer window of Visual Studio, find project "OgreMain" and right click it.
- Select "Add->Existing Item..." and navigate to "Mogre\Main\OgreSrc\ogre\OgreMain\src", add "CLRHandle.cpp" and "CLRObject.cpp".
- In the solution explorer window of Visual Studio, find project "OgreMain" and right click it.
- Select "Add->Existing Item..." and navigate to "Mogre\Main\OgreSrc\ogre\OgreMain\include", add "CLRConfig.h", "CLRHandle.h" and "CLRObject.h".
- Open "CLRConfig.h" in Visual Studio and change "#define LINK_TO_MOGRE 1" to "#define LINK_TO_MOGRE 0".
- Open the batch build window in Visual Studio.
- Select "Debug|Win32" and "Release|Win32" for the following projects:
+ OgreMain
+ OgrePaging
+ OgreRTShaderSystem
+ OgreTerrain
+ Plugin_BSPSceneManager
+ Plugin_CgProgramManager
+ Plugin_OctreeSceneManager
+ Plugin_OctreeZone
+ Plugin_ParticleFX
+ Plugin_PCZSceneManager
+ RenderSystem_Direct3D9
+ RenderSystem_GL
- Rebuild all selected projects.
- If there are linker errors for "_ITERATOR_DEBUG_LEVEL" mismatch, check "http://www.ogre3d.org/forums/viewtopic.php?f=1&t=54533&start=100#p388654";,
I could fix the errors by compiling debug version of dependencies first, then compiling release versions of dependencies separately.
- For VS2008, open soultion "Mogre\Main\Mogre_vc9.sln" in Visual Studio.
- For VS2010, open soultion "Mogre\Main\Mogre_vs2010.sln" in Visual Studio.
- Use batch build to rebuild all projects.
- Open solution "Mogre\Main\OgreSrc\build\OGRE.sln" again.
- Open "CLRConfig.h" in Visual Studio and change "#define LINK_TO_MOGRE 0" back to "#define LINK_TO_MOGRE 1".
- Open batch build and use a normal build instead of rebuild all this time, this will save a lot of time.
- Debug binaries are in "Mogre\Main\lib\Debug" and "Mogre\Main\OgreSrc\build\lib\Debug".
- Release binaries are in "Mogre\Main\lib\Release" and "Mogre\Main\OgreSrc\build\lib\Release".


This is what cmake printed out for me as project configuration summary:
=======================================================================

----------------------------------------------------------------------------
FEATURE SUMMARY
----------------------------------------------------------------------------

Building components:
+ Paging
+ Terrain
+ RTShader System
+ RTShader System Core Shaders
+ RTShader System Extensions Shaders
Building plugins:
+ BSP scene manager
+ Cg program manager
+ Octree scene manager
+ Portal connected zone scene manager
+ Particle FX
Building rendersystems:
+ Direct3D 9
+ OpenGL
Building executables:
+ Samples
+ Tools
Building core features:
+ DDS image codec
+ PVRTC image codec
+ FreeImage codec
+ ZIP archives

Build type: dynamic
Threading support: none
Use double precision: disabled
Allocator type: nedmalloc (pooling)
STL containers use allocator: disabled
Strings use allocator: disabled
Memory tracker (debug): disabled
Memory tracker (release): disabled
Use new script compilers: enabled
Use Boost: disabled

----------------------------------------------------------------------------


OLD INSTRUCTIONS, KEPT HERE FOR REFERENCE, WILL BE REMOVED LATER:
=================================================================

Please verify this!

- Download boost (http://www.boost.org). Compile and install it.
- Set the environment variables BOOST_INCLUDE_DIRECTORY
(e.g. C:\boost\include\boost-1_42) and BOOST_LIBRARY_DIRECTORY
(e.g. C:\boost\lib).
- Download Ogre Dependencies and extract them, e.g.
http://sf.net/projects/ogre/files/ogre- ... %2B%2B/1.7
into Main/OgreSrc/Dependencies. Compile the Dependencies.
- Clone ogre sources, branch 1.7 into Main/OgreSrc.
See Main/OgreSrc/readme.txt for more.
- Patch Ogre files by applying "Main/Ogre Patches/Mogre.patch"
- Start CMake to generate Ogre build files. Make sure you have
OGRE_CONFIG_ENABLE_PVRTC switched ON and
OGRE_CONFIG_CONTAINERS_USE_CUSTOM_ALLOCATOR switched OFF. Target
Main/OgreSrc/build as output directory.
- execute Codegen/cpp2java/build.bat (from within Codegen/cpp2java)
- Compile AutoWrap (Codegen/AutoWrap/AutoWrap.sln or ...AutoWrap_vs2010.sln)
- Run AutoWrap and click "Generate".
- Compile Ogre. If you get the error "missing mogre.lib",
make sure that in CLRConfig.h it is "#define LINK_TO_MOGRE 0"
- Compile Mogre (either Main/Mogre_vc9.sln or Main/Mogre_vs2010.sln)
- Change in Main/OgreSrc/ogre/OgreMain/include/CLRConfig.h the define
to "#define LINK_TO_MOGRE 1"
- Compile Ogre again (no need for a full rebuild)

   
   
   
   
   Build instructions of the Cygon Builds.txt
   

======== Foreword ========

This file contains alternative build instructions.
They were created by user Cygon, who created his own custom
Visual Studio files and figured out his own way how to
compile Ogre, its depencies and Mogre (including wrapping).

User Cygon created his builds from the scratch in August 2011
with the target to build Mogre 1.7 for .NET 4.0.
Some of his improvements we still included to the official Mogre
repository. Others we currently didn't add yet. It's difficult,
because the official Ogre setup (by CMake) autogenerates
Visual Studio files, including settings.
The VS files of Cygon are made by hand. Currently it seems not
to be possible to merge the costom settings to the autogenerated
ones.




So you have to decide:


1)
Do it the "official way" (using Ogres CMake setup).
This can be done very easy by help of the tool MogreBuilder:
http://www.ogre3d.org/tikiwiki/MogreBuilder


2)
Do it the Cygon way:
Follow the build instructions below.
Additional look into these files:
http://www.nuclex.org/MogreTutorial-1.7 ... x86-x64.7z
http://www.nuclex.org/MogrePatchesAndSolutions-1.7.3.7z
Further details are in the forum topic:
viewtopic.php?p=81869#p81869
Perhaps it's very easy to update and compile it with the custom
VS files of Cygon. (There are 32 and 64 bit configurations.)




So, this was my "foreword". (Written by Beauty in April 2012.)




======== Instructions for the "Cygon Builds" ========


0. Start out with the Mogre 1.7.1 source tree and place it into a
directory called Mogre-1.7.3 (we'll update it to that version in a minute)

1. Download the Ogre 1.7.3 source distribution and extract it into

...\Mogre-1.7.3\MAIN\OgreSrc\ogre

Parity check: Your OgreException file should have ended up in this path:

...\Mogre-1.7.3\MAIN\OgreSrc\ogre\OgreMain\src\OgreException.cpp

2. Apply the CLRObject patch. This adds some fields into public Ogre classes
that will be used by Mogre to look up the managed wrappers (so when the Ogre
API returns some object, like a texture, for which a managed wrapper already
exists, Mogre can just look it up and return the existing wrapper).

In ...\ (one level above the Mogre-1.7.3 directory) run
patch -p0 < mogre-1.7.3-clrobject.patch

3. Run cpp2java (just double-click Codegen\cpp2java\build.bat)
It's a script that runs DoxyGen, configured to output the structure of
the Ogre classes and structs in an XML format. The XML is then massaged
into a format understood by AutoWrap.

4. Run AutoWrap (open Codegen\AutoWrap\AutoWrap_vs2010.sln)
It's a C# application, just open the solution and run it. It should start
up without any errors and complete successfully when you click on
the "produce" button.

AutoWrap will generate C++/CLI wrappers for all of the classes in the public
Ogre headers. This will end up in Main\include\auto and Main\src\auto.

5. Copy Main\Ogre\*.h to Main\OgreSrc\ogre\OgreMain\include\
Copy Main\Ogre\*.cpp to Main\OgreSrc\ogre\OgreMain\src\
Copy Main\include\auto\CLRObjects.inc to Main\OgreSrc\ogre\OgreMain\include\

6. (Optional) Apply the cygon patch.

This patch adds some #pragma managed(push, off) sections around unmanaged
headers, preventing the compiler from generating MSIL representations of
countless C++ standard library types that aren't used on the C# side anyway.

The results were:
Mogre.dll (x86) from 12.3 MiB to 8.1 MiB
Mogre.dll (x64) from 20.8 MiB to 9.0 MiB

If also moves the shutdown code from the finalizer of Mogre.Root into its
destructor (IDisposable.Dispose()). This is done because Ogre's OpenGL driver
couldn't cope with the shutdown happening from the GC thread. Maybe future
versions of Ogre won't need this change.

7. Edit Main\OgreSrc\ogre\OgreMain\include\CLRConfig.h
Set LINK_TO_MOGRE to 0

8. Compile Ogre. You can use CMake and the standard Mogre solution, but for my
builds, I used my own solutions. You can get them by extracting
mogre-1.7.3-solutions.7z one level above your Mogre-1.7.3 directory

Main\OgreSrc\ogre\Build\msvc-2010\OgreMain (x86).sln
Main\OgreSrc\ogre\Build\msvc-2010\OgreMain (x64).sln

You can compile both simultaneously, they won't collide. The only projects
that have to be compiled at this stage are OgreMain, OgrePaging and OgreTerrain.

The way these projects are configured, they expect some dependencies to sit
parallel to the Mogre-1.7.3 directory, eg.

Devel\
Mogre-1.7.3\
FreeImage-3.15.1\
Boost-1.47.0\
ZLib-1.2.5\
ZZipLib-0.13.60\

If that's not your directory layout, either prepare a directory with this layout or
update the paths in the project files ;)

9. Compile Mogre via one of the provided solutions (that is, if you extracted
the .7z archive above. Otherwise, use the official Mogre solution).

Main\Mogre (x86).sln
Main\Mogre (x64).sln

As before, you can compile both simultaneously without running into trouble.

Notice that you need to change the 'Key File' property under
Project Settings -> Linker -> Advanced. Either remove it (to generate
an assembly without a strong name) or point it to your own strong name
(generated via sn -k keyfile.snk).

Another notice for users of Visual Studio 2010 SP1 (affects Express and Full):
SP1 has broken assembly signing for C++/CLI projects in the x86 architecture.
http://blogs.msdn.com/b/vcblog/archive/ ... 40139.aspx
http://msdn.microsoft.com/en-us/visualc/gg701941

10. Edit Main\OgreSrc\ogre\OgreMain\include\CLRConfig.h
Set LINK_TO_MOGRE to 1

11. Compile Ogre via one of the provided solutions:

Main\OgreSrc\ogre\Build\msvc-2010\OgreMain (x86).sln
Main\OgreSrc\ogre\Build\msvc-2010\OgreMain (x64).sln

This time, compile everything.

12. You can now pick up your binaries from (again assuming you used the custom
solutions from the .7z archive)

Main\OgreSrc\ogre\Build\msvc-2010\bin\{x86|x64}\<project>\Release
Main\bin\{x86|x64}\<project>\Release


I also want to say thanks to

1. McDonte - for his documentation on the wiki page Building Mogre 1.7 Step By Step[/*:m]
   
2. Zarifus - for creating this topic and applying the knowledge to the MogreBuilder[/*:m][/list:u]
   
   I will add URL files to the repository, too.
   So I further developers should find the useful information quickly.

Also you should look at this link: https://bitbucket.org/manski/mymogre/sr ... ibutes.txt
It describes the usage of the AutoWrap tool.


I read this whole topic. Good that I did so.
Thanks for pointing to this great documentation. I added this file, too.

It's a shame that it wasn't added for 1.5 years.
It was nearly forgotten. Without your hint maybe it would be lost forever.

This evening I wanted to concentrate to update the Ogre depencies.
But now I think it was much more better that I picked up the scattered Mogre documentation instead.

How to modify the AutoWrapper.txt


Attributes.xml
==============
The file "Attributes.xml" specifies information about how to convert the native
OGRE sources to the CLR MOGRE sources. It is used by the "AutoWrap" application
to tweak the file "meta.xml" (generated by "cpp2java").

This file will provide some documentation for the "Attributes.xml" file.

As for the terminology: We need to differentiate between "native" (C/C++, source
source code) source code and CLR (C++/CLI + .NET, destination source code)
source code. Therefore the former will be called "native" and the latter "CLR".


Attributes.xml in general: Adding attributes
--------------------------------------------
As said above this file is used to tweak the generation of the source files.
This section will provide some examples on how to read/write this file.

The basic idea behind this file is to add XML attributes to elements of the
"meta.xml" file. Each element is identified by

* its position in the XML tree, i.e. in which <namespace> the element is
contained in
* the element type (e.g. "<class>", "<typedef>", "<variable>", ...)
* the element's name (i.e. the name attribute)

Therefore a class in the "Ogre" namespace (note that its the native namespace,
not the CLR namespace - if they have different names) named "ScriptToken" would
be identified by this XML code:

<meta>
<namespace name="Ogre">
<class name="ScriptToken"/>
</namespace>
</meta>

To add attributes to this element, simply add them to the XML element. For
example, to ignore the previously mentioned class, use this XML code:

<meta>
<namespace name="Ogre">
<class name="ScriptToken" Ignore=""/>
</namespace>
</meta>

If the attribute requires a lot of information (such as a custom implementation),
it can alternatively be implemented as a so called "Attached Attribute". An
attached attribute is an XML element with the attribute name as tag name but
prefixed with an underscore (see example below). The attribute is "attached" to
the surrounding XML element (hence the name). For example, the following code
does the same as the previous code: ignoring the class "ScriptToken":

<meta>
<namespace name="Ogre">
<class name="ScriptToken">
<_Ignore/>
</class>
</namespace>
</meta>

The text within the attached attribute (none was provided in the previous
example) will be used as attribute value while the tag name (without the
underscore) will obviously be used as attribute name.

Another example: To rename a member variable (e.g. "error") of a class (e.g.
"BackgroundProcessResult"), use this XML code:

<meta>
<namespace name="Ogre">
<class name="BackgroundProcessResult">
<variable name="error" Rename="Error" />
</class>
</namespace>
</meta>

Note also that you may specify an element multiple times. The changes to the
class/element will be merged:

<meta>
<namespace name="Ogre">
<class name="MovableObject">
<function name="isVisible" Method=""/>
</class>
...
<class name="MovableObject">
<function name="setUserAny" Ignore="" />
<function name="getUserAny" Ignore="" />
</class>
</namespace>
</meta>


Adding custom code
------------------
Another major point is the ability to add custom code to the generated files.
There are the following XML elements available for this:

* <_CustomIncDeclaration> : Places the code in the .h file.
* <_CustomCppDeclaration> : Places the code in the .cpp file.
* <_CustomDisposing> : Adds code to the dispose method ("!ClassName()").

You can add this element either to <class>es/<struct>s or to <function>s. The
following XML code adds some C++/CLI code at the top of Texture's class
definition (in the .h file):

<meta>
<namespace name="Ogre">
<class name="Texture">
<_CustomIncDeclaration>
#ifdef LoadImage
#undef LoadImage
#endif
</_CustomIncDeclaration>
</class>
</namespace>
</meta>

NOTE: Be careful when adding code that contains templates/generics. The brackets
will be interpreted by the XML parser if they aren't escaped (with &lt;/&gt;
or the code with <![CDATA[ ... ]]>).

Note that the indention of the code snippet is copy directly to the source file;
this means that the indention in the Attributes.xml file might not match the
indention of the XML tags (as in the example above).

Besides simply adding code, the most important use of this feature is to replace
the code of some functions. There are basically two ways of doing this tough
these ways have a subtle difference.

Option 1: replace the function's body (note that the name of the function has
been changed in the C++/CLI code).

<class name="Mesh">
<function name="softwareVertexPoseBlend">
<_CustomCppDeclaration>
void Mesh::SoftwareVertexPoseBlend( Mogre::Real weight, Collections::Generic::SortedList&lt;size_t, Mogre::Vector3>^ vertexOffsetMap, Mogre::VertexData^ targetVertexData )
{
Ogre::map&lt;size_t,Ogre::Vector3>::type o_vertexOffsetMap;
FillMapFromSortedList&lt;Ogre::map&lt;size_t,Ogre::Vector3>::type, size_t, Mogre::Vector3>(o_vertexOffsetMap, vertexOffsetMap);

Ogre::Mesh::softwareVertexPoseBlend( weight, o_vertexOffsetMap, targetVertexData );
}
</_CustomCppDeclaration>
</function>
</class>

Option 2: Ignore the function and provide custom code for the surrounding class.

<class name="DriverVersion" WrapType="ValueType" SequentialLayout="">
<function name="toString" Ignore="" />
<_CustomIncDeclaration>
public:
virtual System::String^ ToString() override {
return System::String::Format("{0}.{1}.{2}.{3}", major, minor, release, build);
}
</_CustomIncDeclaration>
</class>

As mentioned before there is a subtle difference between these two options. If
you ignore a function (like "toString" in the example before), its definition
will be removed from the .cpp and the .h file. Therefore when ignoring a
function and creating custom declaration results in:

* with <_CustomIncDeclaration>: Function is moved to the header file (but
remains visible
* with <_CustomCppDeclaration>: Not possible (at least not together with a
simple "Ignore") since you can't define a class function in a .cpp file when
the function hasn't been declared in the .h file (usually).


Reference
---------
The following XML elements are available (under <namespace>):

* <class> : denotes a "class"
* <struct> : denotes a "struct"
* <typedef> : ???
* <variable> : denotes a classes'/struct's member variable
* <function> : denotes a classes' method

TODO: See XML class documentation under "Meta\Attributes".

The following XML attributes can be added to the above mentioned XML elements:

* "Ignore" - valid values: value ignored - valid elements: all
If this attribute is found, the element (class, typedef, variable, ...)
will be ignore, meaning that no code will be generated for it. (The value
of the attribute is ignored as well. Even setting it to "false" still
results in the element to be ignored.)

* "Rename" - valid values: identifier name - valid elements: all
Renames the element, i.e. it'll have a different name in the generated
sources than it had in the original sources.

* "PureManagedClass" - valid values: member variable name or empty - valid elements: "class"
Indicates that the class is completely replaced by a custom
implementation with the same name. If a value is provided for this
attribute, it denotes the name of the classes' member variable whose
pointer represent the classes' data (i.e. this is usually the first member
variable, like "m00" for a matrix).
TODO: What happens when there is no name? What's the exact difference?

* "WrapType" - valid values: see below - valid elements: "class", "struct"
Sets how the class or the struct are to be wrapped. The following values
are available (but only one can be used at a time):
TODO: What happens without this attribute?
* CLRHandle - valid for: "class"
creates a wrapper for this class
TODO: What's exactly the difference when not using "WrapType"?
* Interface - valid for: "class"
converts an abstract C++ class into a CLR interface. The class must
not contain any implemented methods (except an empty destructor). The
name is prefixed with an "I" (like "IMeshSerializerListener" for
"MeshSerializerListener").
* ValueType - valid for: "class", "struct"
converts this class/struct to a "value class" (a C# struct).
* NativePtrValueType - valid for: "class", "struct"
creates a "pure" wrapper for this class or struct. "Pure" means that
all calls to the generated class will be redirected to the underlying
native type. Note that the generated class will be a "value class".
* PlainWrapper - valid for: "class", "struct"
the same as "NativePtrValueType" except that a "ref class" will be
generated (instead of a "value class").
* NativeDirector
???
* ReadOnlyStruct - valid for: "class", "struct"
generates a "ref class" which all member variables converted to
readonly CLR properties
* NonOverridable
??? (used for enums)

* ReadOnly - valid values: value ignored - valid elements: "class", "struct", "typedef"
??? (if not specified, allows creation of new elements)

* SequentialLayout - valid values: value ignored - valid elements: "class", "struct"
Adds the CLR attribute "[StructLayout(LayoutKind::Sequential)]" to the
class. Note that the wrap type must be a "value class".


Tubulii, can you give us some more details, please?
The best would be:
* Tell us the related file name(s)
* Quote the line of code current code (method definition)
* Tell us how it has to be modified to become overridable. (Perhaps it's just adding/removing/replacing one "command".)
My knowledge of C++/CLI is nearly zero (I am a big fan of c++ converters ).
Overriding of methods is not an easy to implement feature, if I am right, the biggest problem is that you can not create new unmanaged classes with managed code (the wrapper/ogre is already compiled) and unmanaged code needs to call managed code. Solution (again, maybe I am wrong): First: Create a speacial unmanaged classes, e.g. RenderableExCpp. Inherit from Renderable and override ALL methods (in c++). All unmanaged calls need to detoured to our managed code: Create a managed class RenderableEx (in C++/CLI) which has an unmanaged pointer to RenderableExCpp. The RenderableEx "hooks" into all overriden methods (maybe some kind of event system?) and calls the managed code instead (= the overridable methods). Any return values need to passed through to the unmanaged world (e.g. functions). Conclusion: Complex topic, allways the same and therefore very time-consuming but it should be easy to implement if you are a true C++/CLI programmer. And the most important class is Renderable (in my opinion). If someone implemented this class, it should be easy to clone it and do the rest (even for me )

Thanks for your answer.
An interesting idea.
I added the feature request, including the link of your suggestion to the Mogre bugtracker:
https://bitbucket.org/mogre/mogre/issue/15/

I worked a bit on the override-problem:
I managed to wrap a native class with virtual methods in cli/c++:

It is more or less the same than I have written before (I was right ), but I will try to explain my steps with one example (not related to ogre, just a try-and-error-project):

1. Native world meets managed world
I created a new native class called "person" with three methods: getName, getFamilyName and getFullName.
Both getName and getFamilyName are virtual. getFullName returns getName + " " + getFamilyName, default return value is "Hans Meier" (getName->Hans, getFamilyName->Meier).
The first goal is to print these three strings in the console.

I created a new managed class called "ManagedPerson", included a pointer to the native class, ... . I made GetName and GetFamilyName virtual and redirected the native strings.

The first output was:
Hans
Meier
Hans Meier

I was happy and subclassed ManagedPerson and overriden the two methods:
The second output was:
Thorben
Brown
Hans Meier

Conclusion: I succesfully overriden the methods but only "in the managed world". In reality the native class still returns the old values.

2. Managed world meets native world
I need to redirect the managed values to the native world (because I want to override GetName and GetFamilyName).
This is done by a new (native) class called "PersonImp".
It inherits Person and holds a pointer to our wrapper class (ManagedPerson) which itself holds a pointer to PersonImp. Terrible but neccessary.
PersonImp overrides ALL methods of Person and returns the values of ManagedPerson instead. But now ManagedPerson redirect all values from PersonImp and PersonImp all values from ManagedPerson (deadlock).
Solution: ManagedPerson is totally abstract or returns default values and not redirects native values.

The final output was:
Thorben
Brown
Thorben Brown

Final Conclusion: C++ is terrible and C is a nightmare. It took me hours to get this working and it's full of memory leaks but it's working.
I will post the project if someone wants it.

Does somebody know how to integrate custom classes into Autowrapper without editing the ogre sources?
I will try to extend mogre to have (at first) one overrideable class (maybe SimpleRenderable or Plugin) but I thing I have to separate it from the original classes because it may interfer with the Autowrapper's wrap steps.

I was doing some poking around on the override topic as well. I came across this in the Mogre FAQ
http://www.ogre3d.org/tikiwiki/Mogre+FAQ#I_see_a_Renderable_class_and_a_IRenderable_interface_isn_t_only_one_of_them_enough_
But if you want to create a custom class that implements the interface, you can't just add it to the class definition; you will implement it on the .NET side but it won't be usable by Ogre. For these cases there is a class that you should derive from if you want to implement the interface. For example, in order to implement IRenderable, you should subclass the Renderable class.
So, I created a class deriving from Renderable and added it to the RenderQueue and, sure enough,the breakpoint I had on the GetMaterial method was hit. Looking at the call stack there was a class called Renderable_Proxy making the call to my class, so that might be a place to start looking. All that said, I have no idea if the material I was returning ever made it back to the native code.

At some point, I'd be interested to see what you've got, but right now I'm fairly certain it would still be gibberish to me since I have zero understanding of the C++/CLI stuff. Right now I'm trying to see if I can add the missing classes from the Compositor framework to the wrapping process. Maybe after that I'll have a little better idea of how all this fits together.

missing classes from the Compositor framework to the wrapping process.
Add the missing classes to the bug tracker.

And goog luck. Send me a PM if you want to source code of my test project.

Add the missing classes to the bug tracker.
The bug tracker you find here:
https://bitbucket.org/mogre/mogre/issues

BrainScan, if you don't want to register, you can create entries anonymously.


Does somebody know how to integrate custom classes into Autowrapper without editing the ogre sources?
One important configuration file for wrapping is Codegen\Autowrap\Attributes.xml.
3 weeks ago I added documentation files to the Mogre repository. There is also information about adding custom sources.

Look to file Documentation\How to modify the AutoWrapper.txt at section "Adding custom code".
Link: here

There are also whole custom classes (e.g. Vector3 and Math). Unfortunately I don't know how these classes are embedded by the autowrapper.
In this way (I suppose) it could be easy to add custom managed classes.

Bug report

Maybe there is a bug in the cpp2java configuration.

File: Codegen \ cpp2java \ xslt \ config.xml
Contains:

<!-- path to file with typedefs that won't be generated -->
<ignore>ignore.xml</ignore>


Problem:
There is no file with the name ignore.xml.
But there is a file with the name ignorelist.xml.

I'm not shure if I should edit the file name in config.xml.
If this is a bug, I wonder why we get no trouble for wrapping.
On the other hand - maybe it causes only trouble with Ogre 1.8 ??

I have not much knowledge about the wrapping details.
What do you think?

Our new forum member Lexer wrote:
-------------------------
Hi Beauty,

I'd like to spend some time to update Mogre to 1.9 soon,
should I look at MogreBuilder, or directly at the Mogre source?

I haven't looked at the source yet, I have a few questions:

* how is Mogre parsing Ogre header files to extract class metadata? (using Doxygen?)
* what is not automated?


any thing to know before I look at it would be helpful.

ps: I have the required C++, C++/CLI and .NET skills.
-------------------------

This message is interesting not only for me - so I publish it here.


I'd like to spend some time to update Mogre to 1.9 soon
We are happy about everybody, who likes to use Mogre and publish improvements.

should I look at MogreBuilder, or directly at the Mogre source?
Our tool MogreBuilder is great to process the whole wrapping and compiling process.
Internally it uses tasks for each step. I suggest to look into it's code to understand how the pipeline works in general.
To look into the Mogre code as first step could be overkill.
I suggest to read all post of this topic and related links.

* how is Mogre parsing Ogre header files to extract class metadata? (using Doxygen?)
Yes, Doxygen is involved. Unfortunately I don't remeber all details.
I think it was like this:
* Modification of the Ogre sources to add information, which is needed for wrapping. (Done by Oxygen?)
* Build modified Ogre without link to Mogre classes (or similar)
* Build Mogre
* Build modified Ogre including linking of Mogre classes

A few classes aren't wrappped (e. g. Mogre.Math). Instead ported classes are used. You find them in directory MogreSrc \ Main \ include \ Custom of the Mogre repository.

* what is not automated?
In general Mogre can be wrapped/build fully automatically by MogreBuilder.
But this way you can't apply different options (e. g. enable/disable Boost).
Additionally the wrapping and/or building of add-ons is only implemented partially.
More modifications are needed to apply the wrapping / build of a newer Ogre version.

What you can try:
User BrainScan updated the Mogre wrapper and could build Mogre against Ogre 1.8.1.
For this have a look to the topic Updating Mogre! [Mogre 1.8.1 was build successfully]. Start reading at this post.
Then you can try to use MogreBuilder to build his modified code.
If there are problems, you can search for the reason and hopefully find a solution.
Just an idea how you could move on.

After this you could try to move on to Ogre 1.9.
The changelog from Ogre 1.8 to 1.9 you find here: http://www.ogre3d.org/tikiwiki/GhadamonNotes

any thing to know before I look at it would be helpful.
I hope I could help a little bit.

ps: I have the required C++, C++/CLI and .NET skills.
This should be very useful.

Hi beauty,
thanks for your answer, so far I don't know how much time and energy I'm going to spend on this. I can't tell if I'm going to make it, especially since I saw the code


Yes, Doxygen is involved. Unfortunately I don't remeber all details.

I think it was like this:
* Modification of the Ogre sources to add information, which is needed for wrapping. (Done by Oxygen?)
* Build modified Ogre without link to Mogre classes (or similar)
* Build Mogre
* Build modified Ogre including linking of Mogre classes


My understanding so far :
* a patch is applyed to Ogre sources to allow some natives class to track CLR instances. (not very convinient when an update is needed)
* doxygen parse Ogre headers to extract metadata into an xml.
* cpp2java transforms the xml using xslt to a more convinient format
* project Autowrap will generate c++/CLI wraping code from the meta.xml (from cpp2java) and attributes.xml (hand written xml to customize wrapping)
* Ogre is built
* Mogre generated sources are built, linking to Ogre
* Ogre is built again, linking to Mogre

now I'm realizing it's such a mess



What you can try:
User BrainScan updated the Mogre wrapper and could build Mogre against Ogre 1.8.1.
For this have a look to the topic Updating Mogre! [Mogre 1.8.1 was build successfully]. Start reading at this post.
Then you can try to use MogreBuilder to build his modified code.


I've checked out Mogre from bitbucket yesterday, are his changes already there?

After this you could try to move on to Ogre 1.9.
The changelog from Ogre 1.8 to 1.9 you find here: http://www.ogre3d.org/tikiwiki/GhadamonNotes


I don't know yet if I can make it, nor if I'll have enough time to do so.
But if I do, I may rewrite a big part of it, especially the code generation part which is awful. I may use T4 templates for that. And why not starting straight away with Ogre 2.0?
Also I need to understand precisely in which cases Ogre needs to reference managed instances (probably for Listeners, Observers, callbacks) but I need to figure out if there is another alternative than making Ogre referencing Mogre.

it's such a complex task. I may or may not do it. At least I'll try.

My understanding so far :
* a patch is applyed to Ogre sources to allow some natives class to track CLR instances. (not very convinient when an update is needed)
* doxygen parse Ogre headers to extract metadata into an xml.
* cpp2java transforms the xml using xslt to a more convinient format
* project Autowrap will generate c++/CLI wraping code from the meta.xml (from cpp2java) and attributes.xml (hand written xml to customize wrapping)
* Ogre is built
* Mogre generated sources are built, linking to Ogre
* Ogre is built again, linking to Mogre
This is correct for the basic high level view of the steps involved. I know its a lot of steps and there are ways to reduce them, but that would require some large rewrites. I've simply accepted the process for now since it's not too bad to make changes once you understand the steps. At some point I'd love to tackle some rewrites but for my recent purposes, learning the ins and outs of mogre was less time consuming than starting from scratch.

I've checked out Mogre from bitbucket yesterday, are his changes already there?
There doesn't seem to be an active maintainer of the official repository. So, all my work is in my fork on bitbucket.
https://bitbucket.org/BrainScan/mogre
Also I am keeping the first post in this thread up to date with all my notes and todo list on my work with 1.8. I've made numerous improvements to parts of the code generation as well.
viewtopic.php?f=8&t=30176

I don't know yet if I can make it, nor if I'll have enough time to do so.
But if I do, I may rewrite a big part of it, especially the code generation part which is awful. I may use T4 templates for that. And why not starting straight away with Ogre 2.0?
Also I need to understand precisely in which cases Ogre needs to reference managed instances (probably for Listeners, Observers, callbacks) but I need to figure out if there is another alternative than making Ogre referencing Mogre.
There's significant enough changes with Ogre 2.0 that it may be the best time to start from scratch. However, 2.0 is not even released yet and even when the community preview is officially released there will be many missing features. I'm waiting it out right now because I don't specifically need anything in 1.9 yet and 2.0 isn't ready for use. That could change as my project progresses. I am certainly interested in further discussion on the topic.

There doesn't seem to be an active maintainer of the official repository. So, all my work is in my fork on bitbucket.
https://bitbucket.org/BrainScan/mogre
Thanks for all your work.
Unfortunately I have very less free time. So I can't follow all Mogre activity, nor helping frequently.
I merged your pull request to the Mogre main repository (improvements to Mogre 1.7).
Additionally I gave you write access to the repositories Mogre, MogreAddons and MogreBuilder.

You wrote in the forum that you have good experience in source management systems. Additionally I have the feeling that you know what you do.
So I'm glad to give you write access to the official repository and I'm happy that you continued the development of Mogre.


Next steps, which I suggest for the community:
1.)
Check if the MogreBuilder can handle the updated Mogre sources successfully. If not, MogreBuilder should be updated.

2a.)
Think about how to handle the different improvements of the repository branches "default" and "TerrainAndPaging".
It would be useful to apply several commits to the the other branch, too.

2b.)
Think about how to handle the improvements for Mogre 1.8.
Maybe create a new branch of the current "default". One for Mogre 1.7 and one for Mogre 1.8.

If I find more time, I want to help, too.


Thanks to Lexer for document of the steps of the Mogre build pipeline.

There's significant enough changes with Ogre 2.0 that it may be the best time to start from scratch. However, 2.0 is not even released yet and even when the community preview is officially released there will be many missing features. I'm waiting it out right now because I don't specifically need anything in 1.9 yet and 2.0 isn't ready for use. That could change as my project progresses. I am certainly interested in further discussion on the topic.


I've been working those last three days on something that looks like a complete rewrite.
It will take some time, since I work on it few hours a day in train between work and home, but I already have a clear architecture in mind. It will be a very -light- tool.
the only thing I plan to reuse from mogre are the custom implementation.
so far I'm collecting Ogre api metadata in a sql database, it is important to make the api queryable.

I'll give a deeper explanation when it will start looking serious.

Thanks for all your work.
Unfortunately I have very less free time. So I can't follow all Mogre activity, nor helping frequently.
I merged your pull request to the Mogre main repository (improvements to Mogre 1.7).
Additionally I gave you write access to the repositories Mogre, MogreAddons and MogreBuilder.
Thanks Beauty. I'll have a look at moving all the 1.8 code over to the official repository this weekend. I'll do the branches in a way similar to the way ogre does it. One branch for each major version (1.7, 1.8, etc) and the latest "bleeding edge" development in the default branch. People have already been able to build 1.8 with MogreBuilder by just changing the config to point to my repository, so no changes will be needed there. At some point I guess the default config should be updated to build 1.8 though.