Migrate ogre1 backend from OGRE 1.9.0 to OGRE 1.12.10

[j-rivero]

The ogre (OGRE-1) backend currently pins to OGRE 1.9.0. It is an EOL version that ships freeimage which bring many security problems. ogre-1.9 has been removed from Debian and the next Ubuntu. Ubuntu Noble (the gz-rendering target distro) ships libogre-1.12-dev . This issue tracks the migration of the ogre backend to OGRE 1.12.10. The ogre2 (OGRE-Next 2.x) backend is out of scope and unchanged.

Asking Claude to put the analyze the whole list of change between 1.9 to 1.12 and refers on what gz-rendering is using, there is a non trivial list of many items to cover https://gist.github.com/j-rivero/25ac7dc5c555c1a4d7b707a350705acd.

[j-rivero]

I made an experimental migration with the heavy support of AI agents (Sonnet 4.6, GPT-5.4 and Opus 4.7). It was a mix of technical knowledge of the topic and gazebo internals, manual reviews of a good bunch of the changes and a bit of vide-coding blindly accepting some changes in rendering areas where I have no experience. Here is a brief summary. Take it with a grain of salt, part is AI generated, most of it (if not all) reviewed by myself that I'm not a rendering expert:

Approach

Work was done in a single branch first, providing the IA agent with the curated changelog report in this issue description, a copy of ogre-1.12.10 and a colcon workspace with gz-rendering + gui + sensors + sim. First try to compile, second go over the testing suite and third end-to-end testing on difficult worlds:

Problematic aspects found

• Replace deprecated 1.9 APIs with their 1.12 successors (with version guards where needed to keep the intermediate state building on both).
• Update the shipped GLSL / RTSS shader library to OGRE 1.12 syntax.
• Fix rendering-correctness regressions surfaced under 1.12 (PSSM shadow depth, depth/lidar matrix push, projector decal pass, terrain material generator).
• Make texture upload paths robust to libogre-1.12-dev's missing PNG/JPG codecs and to 16-bit-per-channel sources (heap-overflow fix on Fuel models).
• Discover OGRE Media via OGRE_MEDIA_DIR from upstream OGREConfig.cmake so the build resolves shader and terrain media on Linux distros, Homebrew, vcpkg, Conda, and NixOS — not only on FHS layouts.

Initial output

• Branch main...jrivero/ogre112
• Largee change in the code base: 33 commits, 40 files changes, 2k lines added / 600 lines removed (this include particular shader files we embedded into gz-rendering).

Clean up the work for review

The amount of changes is not suitable for a single PR so I've tried to categorize all the commits and create PRs that can be merged separately. Only one part of the work can be merged atomically without changing the base dependency to 1.12 the rest needs to be done in a larger PR. For this large one I've categorized the commits into trivial (migration direct instructions and other technical issues I can review) and behaviour changes or changes requiring expertise to be analyzed:

PR1 "OGRE-1: replace deprecated 1.9 APIs (forward-compatible cleanup)"

Branch: jrivero/ogre112-pr1-deprecated-apis-guarded (10 commits)

Forward-compatible API renames, wrapped in version guards so the tree still builds on OGRE 1.9 and 1.12. No packages.apt change. New OGRE_VERSION_LT_1_10_0 / _LT_1_11_0 / _LT_1_12_0 / _LT_1_12_9 macros are added in ogre/src/CMakeLists.txt; an internal OgreCompat.hh shim provides Ogre::HBU_GPU_ONLY / HBU_CPU_TO_GPU aliases when building against pre-1.12.9 OGRE.

Renames covered: <OgreVector3.h> → <OgreVector.h>, ST_GENERIC → "DefaultSceneManager", HBU_*_WRITE_ONLY → Ogre::HBU_GPU_ONLY / HBU_CPU_TO_GPU, getBoneIterator() → range-for over getBones(),
RGN_DEFAULT group on MaterialManager::getByName, internal OgreGLFBORenderTexture.h removed; defensive dynamic_cast + null-guard in OgreHeightmap::SetupShadows; SetNormalMap extracted into a shared CreateOgreTextureFromImage helper.

Validated green on Jenkins for Linux Noble (1.9), macOS Homebrew, and Windows cnlwin (conda 1.10+).

PR2 "OGRE-1: cut over to OGRE 1.12.10 + robustness fixes"

Branch: jrivero/ogre112-pr2-combined (21 commits, stacked on PR 1)

The version flip + correctness/robustness fixes that 1.12 requires. After
this PR, the tree is on 1.12 only.

Highlights:

• Build / CI: bump gz_find_package(GzOGRE) to 1.12.10; switch packages.apt to libogre-1.12-dev; discover OGRE Media via OGRE_MEDIA_DIR.
• Resource discovery: register parent dir (not file path) for shaders, recursive addResourceLocation for fonts, register ShadowVolume/, Terrain/, RTSS shader libraries from the OGRE Media tree.
• Materials / textures: route SetTextureImpl and SetNormalMap through gz-common pre-decode (workaround for missing PNG/JPG codecs in libogre-1.12-dev); fix RGBA byte order in CreateOgreTextureFromImage; clamp manual upload to PF_BYTE_RGBA buffer size with a 16-bit MSB-extraction fallback (heap-overflow fix on Fuel models); handle
  ResourceManager::create now throwing on duplicates via createOrRetrieve + ownership flag.
• Rendering correctness: PSSM shadow caster outputs window-space depth (matches RTSS IntegratedPSSM receiver under 1.12 — wrong value silently zeroes directional-light diffuse); OgreDepthCamera / OgreGpuRays push per-object world matrix via a RenderObjectListener so legacy gl_ModelViewMatrix shaders see the right matrix (silent depth/lidar
  regression without it); projector decals use a hand-written GLSL pass (RTSS FFP path is gone in 1.12 GL3+); heightmap uses stock TerrainMaterialGeneratorA for OGRE ≥ 1.11.
• Shaders: GLSL files updated to OGRE 1.12 syntax (drops FFP_Assign / FFP_Construct helpers); new RTSS library files (SGXLib_DualQuaternion, SGXLib_LayeredBlending, SGXLib_NormalMap, SGXLib_TextureAtlas,
  SGXLib_TriplanarTexturing, FFPLib_AlphaTest, …); test Waves shader uses GLSL 1.50 texture() instead of textureCube().

Reviewer guide

The 33 squashed commits split roughly half-and-half between mechanical (T) and behavior-impacting (B). An expert rendering reviewer can fast-path the T set and concentrate on the B set. Top 5 commits to focus on, in priority order:

1. 5001f91 — PSSM shadow caster window-space depth (correctness of all shadowed scenes).
2. 7926e08 — depth/GPU-lidar per-object matrix push (correctness of all depth sensors).
3. 1206549 — projector decal rewrite (all decal/projector scenes).
4. c835356 — heightmap stock TerrainMaterialGeneratorA swap (all terrain scenes).
5. 8b23d54 + a48b445 — texture upload byte order + 16-bit clamp (all textured visuals; coupled).

Test coverage

• 134 unit + integration tests pass on Ubuntu Noble against libogre-1.12-dev.
• Real-world validation: 5 SDF scenes render correctly — jetty_demo, heightmap bowl, DEM, GPU-lidar, projector demo.

Known follow-up (not blocking)

Heightmap selection — Scene::VisualAt(...) over a terrain returns nullptr because terrain renderables are not SubEntity and OgreMaterialSwitcher lacks a per-renderable selection scheme for them. Cosmetic, will be tracked in a follow-up issue.

[j-rivero]

I put the IA agents to work on benchmarking the ogre-1.9 vs ogre-1.12 and generate some numbers, the whole code suite and results are in https://github.com/j-rivero/ogre-1.12-migration