gazebosim / gazebosim/gz-rendering

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

Open
#1,118 6 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
C++
Stars
81
Forks
90
Avg merge
1d 13h
Merged PRs (30d)
10

Description

## 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 https://github.com/gazebosim/gz-rendering/issues/1010 and https://github.com/gazebosim/gz-cmake/pull/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:
```c++
#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 https://github.com/gazebosim/gz-cmake/pull/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.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.