Strategy to expand Ogre-Next support to Ogre-Next>=3.0.0 (Eris)

[sumir0]

Desired behavior

Ogre-Next>=3.0.0 (can be) or (is) used to provide a rendering plugin.

Currently, gz-rendering provides several rendering plugins:

• gz-rendering-optix (probably, outdated at the moment, see OptiX 8.0.0 is ALREADY out... #1010 and Tentative fix for FindOptiX.cmake gz-cmake#472);
• gz-rendering-ogre;
• gz-rendering-ogre2.

None of them are meant to provide Ogre-Next>=3.0.0 functionality/compatibility (as far as I know).

Alternatives considered

Alternative B

Adding gz-rendering-ogre3 plugin alongside gz-rendering-ogre2 plugin.

Pros:

• no need to recompile the code if user wants to use two different versions of Ogre-Next (highly unlikely scenario).

Cons:

• Ogre-Next>=4.0.0 will require another additional plugins alongside (gz-rendering-ogre(x)) for each major version.

Alternative C

Replacing gz-rendering-ogre2 plugin with gz-rendering-ogre3 plugin.

Pros:

• Ogre-Next>=3.0.0 is used.

Cons:

• no ability to use Ogre-Next<3.0.0 out of the box (though, custom plugins are supported);
• Ogre-Next>=4.0.0 will require another plugin replacement (or addition).

Alternative D

Adding gz-rendering-ogre-next plugin alongside gz-rendering-ogre2 plugin.

Pros:

• no need to recompile the code if user wants to use two different versions of Ogre-Next (highly unlikely scenario);
• different Ogre-Next versions can be used;
• can be extended to support Ogre-Next>=4.0.0 after its release.

Cons:

• implementation is not trivial (see the implementation details paragraph below);
• redundant in case if user has Ogre-Next<3.0.0 (depending on the implementation, gz-rendering-ogre-next may be equivalent to gz-rendering-ogre2 or may be not provided in that case at all).

Implementation details

As Ogre-Next<3.0.0 and Ogre-Next>=3.0.0 have similar APIs, gz-rendering-ogre-next plugin and gz-rendering-ogre2 plugin will have common source code. As you don't want to copy ogre2 directory into something like ogre-next directory (because there would be two versions of the same code which need to be supported individually, i.e. changes in one version, probably, will need to be in another version and vice versa), gz-rendering-ogre-next plugin needs to be configured to use ogre2 directory (or some other common directory). That will, possibly, require changes in gz-cmake.

Implementation suggestion

Alternative A

Changing gz-rendering-ogre2 plugin into gz-rendering-ogre-next plugin.

Pros:

• implementation seems to be trivial (see the implementation details paragraph below);
• different Ogre-Next versions can be used;
• can be extended to support Ogre-Next>=4.0.0 after its release.

Cons:

• requires existing users to migrate from gz-rendering-ogre2 to gz-rendering-ogre-next (more on a user-friendly migration plan in the corresponding paragraph below).

Implementation details

gz-rendering-ogre-next plugins for different versions of Ogre-Next will have common source code. Different APIs of different versions can be supported via #if. For example:

#if OGRE_NEXT_VERSION_MAJOR >= 4
  // use Ogre-Next>=4 API
#elif OGRE_NEXT_VERSION_MAJOR >= 3
  // use Ogre-Next==3 API
#else
  // use Ogre-Next==2 API
#endif

There are few cases (as far as I investigated) when such a code structure is needed to be used, i.e. Ogre-Next==3 and Ogre-Next==2 in most cases will have the same API.

A user-friendly migration plan

As our existing users rely on the gz-rendering-ogre2 plugin, we can not simply change this plugin into gz-rendering-ogre-next plugin. I propose a 3-stage plan to give users time to migrate. I think one stage per one major version is long enough (2-3 years, as far as I know, new major version is released each year).

1st stage

• Add deprecation warnings, provide users and contributors with the information about the deprecation plan, update documentation, tutorials to replace the old plugin with the new plugin.
• Make gz-rendering-ogre-next plugin available as a copy of gz-rendering-ogre2 plugin.
• Add support for gz-rendering-ogre-next plugin (modify src/RenderEngineManager.cc, etc.).
• Accept changes related to Ogre-Next>=3.0.0 (via #if structures) into ogre2 directory.

2nd stage

• Update deprecation warnings, if necessary provide users and contributors with the information about the deprecation plan.
• Add ogre-next directory based on ogre2 directory (rename classes, variables, etc.).
• Change gz-rendering-ogre-next plugin to be built using ogre-next directory.
• Stop supporting ogre2 directory, i.e. don't make changes related to Ogre-Next<3.0.0 in ogre2 directory, but make them instead in ogre-next directory (to avoid double work; there may be some cases when changes are necessary, in which cases ogre2 directory may be modified, but, generally, work related to Ogre-Next should be concentrated in ogre-next directory).
• Port changes made in the period between the addition of ogre-next directory and the termination of support of ogre2 directory to ogre-next directory (if any).

3rd stage

• Remove ogre2 directory.
• Remove support for gz-rendering-ogre2 plugin (modify src/RenderEngineManager.cc, etc.).

Additional notes

CMake support for Ogre-Next>=3.0.0 built from source was added in gazebosim/gz-cmake#468. In my distribution Ogre-Next 3.0.0 is already available and works with the PR. Don't know about other distributions yet.

Author's note

I think I can help with the implementation of the strategy if needed. I hope this feature request helps. As always, I am open to any feedback|comments|conversation|etc.

[iche033]

Thanks for putting together a detailed plan! I also think that the proposed Alternative A option is the way going forward.

As for the migration plan, I am thinking of ways to avoid keeping a complete copy of ogre2 folder. One option would be:

• Rename ogre2 directory to ogre-next
  • Rename the classes to be OgreNextXXX (from Ogre2XXX)
  • Add typedefs for all classes for backward compatibility e.g. typedef OgreNextCamera Ogre2Camera
    • so that it does not break user code, e.g. classes deriving from Ogre2XXX, or code calling Ogre2XXX static functions.
• Still keep an ogre2 directory but:
  • make ogre2/include/gz/rendeirng/ogre2 a symbolic link to ogre-next/include/gz/rendering/ogre-next
    • so that #include <gz/rendering/ogre2/Ogre2xxx.hh> still works
  • update ogre2/src/CMakeLists.txt to create a ogre2 component from srcs in ogre-next/src
    • so that any logic to find ogre2 cmake target or libgz-rendering-ogre2.so still works

I maybe missing other things.

If we follow the usual gz deprecation cycle, the changes and deprecation warnings can be added in gz-rendering10 (current main branch), and then safely remove the deprecations in gz-rendering11

[sumir0]

Thanks for the response!

I also think it would be preferable to avoid keeping a complete copy of ogre2 folder. I believe you named pretty much of what needs to be done! But of course, time will tell.

I would like to add that there is ogre2/src/media/ folder in which Ogre-Next v2 resources are located. These resources were updated in Ogre-Next v3. Probably, we will want to update them too. But I didn't fully check if v3 resources break functionality of gz-rendering-ogre2 plugin. We can, possibly, use some resources (which are not modified for use with gz-rendering somehow, if there are any) directly from the upstream (and not provide them via ogre2/src/media/ folder). And if we need to provide any version-specific resources we can add, for example, ogre-next/src/media/v2/, ogre-next/src/media/v3, and ogre-next/src/media/vX folders to store them in and choose the needed folder:

• during CMake configuration or
• in resource locations management in ogre-next/src/OgreNextRenderEngine.cc (currently ogre2/src/Ogre2RenderEngine.cc) via #ifs.

Again many thanks for the response! My understanding of what is going on now more clear than ever. For the time being I will look into other things, but feel free to let me know if you need any help! I am closing this issue because the strategy seems to be determined, but don't hesitate to reopen or to comment.