Merge branch 'v3-0'

OGRECave · Aug 5, 2024 · c4a1a08 · c4a1a08
2 parents 2e88283 + fcf4e01
commit c4a1a08
Show file tree

Hide file tree

Showing 2 changed files with 24 additions and 6 deletions.
diff --git a/Docs/src/manual/Migrating/Ogre3.0.Changes.md b/Docs/src/manual/Migrating/Ogre3.0.Changes.md
@@ -54,6 +54,24 @@ The piece block `LoadNormalData` got split into `LoadGeomNormalData` & `LoadNorm
 
 If you were overriding `LoadNormalData` in a custom piece, make sure to account for the new `LoadGeomNormalData`.
 
+## AbiCookie
+
+Creating Root changed slightly. One must now provide the Ogre::AbiCookie:
+
+```cpp
+const Ogre::AbiCookie abiCookie = Ogre::generateAbiCookie();
+mRoot = OGRE_NEW Ogre::Root( &abiCookie, pluginsPath, cfgPath,
+                         mWriteAccessFolder + "Ogre.log", windowTitle );
+```
+
+The ABI cookie is a verification step to validate the version of OgreNext your project was compiled against is the same one as the library being loaded. This includes relevant CMake options that would cause the ABI to change and cause subtle runtime corruption (e.Debug vs Release, `OGRE_BUILD_COMPONENT_PLANAR_REFLECTIONS`, `OGRE_FLEXIBILITY_LEVEL`, `OGRE_CONFIG_THREAD_PROVIDER`, etc).
+
+See Ogre::testAbiCookie for information of what to look for if the ABI cookie fails.
+
+The AbiCookie may not catch all possible ABI mismatch issues, but it will catch the most common known ones.
+
+Note that Ogre::generateAbiCookie is `FORCEINLINE` because it must see your project's settings.
+
 ## Move to C++11 and general cleanup
 
 Lots of dead \& long-deprecated code was removed.

diff --git a/OgreMain/include/OgreAbiUtils.h b/OgreMain/include/OgreAbiUtils.h
@@ -107,12 +107,12 @@ namespace Ogre
 
         They must match. If they don't, then:
 
-            - The libraries are outdated or too new
-            - Wrong Ogre version (e.g. 2.3 vs 2.4)
-            - The app was compiled against the wrong headers
-            - The app was compiled against the wrong OgreBuildSettings.h
-            - Some stale compiler cache. Rebuild everything from scratch.
-            - Compiler settings mismatch
+         - The libraries are outdated or too new
+         - Wrong Ogre version (e.g. 2.3 vs 2.4)
+         - The app was compiled against the wrong headers
+         - The app was compiled against the wrong OgreBuildSettings.h
+         - Some stale compiler cache. Rebuild everything from scratch.
+         - Compiler settings mismatch
 
     @param appCookie
         Cookie generated by generateAbiCookie