Ogre 3.0 roadmap

[darksylinc]

Rather than rendering features, Ogre 2.4 will be focusing on robusting its source code base. There is a lot of code debt which needs to be addressed

• Project name change Proposal: make the project side-by-side installable with Ogre (1.x) #232
• Remove D3D9
• Remove Terrain
• Remove RTShaderSystem
• Remove NaCL
• Remove dead SceneManagers
• Remove ( void ) from empty functions
• Remove StaticGeometry
• Remove files under Deprecated/ folders
• Move to C++11
  • Remove code under __cplusplus that uses < 201103L >= 201103L or numbers below 201103L
• Math::Log2 should use log2
• All virtuals must have overload keyword
• Apply this patch. We can't for 2.3 because it's not compatible with C++98/03
• Remove HardwareUniformBuffer, HardwareCounterBuffer
• Fix strict aliasing via bit_cast (write workaround for pre C++20, very easy since it just wraps memcpy)
• Fix many warnings. Try to compile using -Werror
• Clean up Media folder and remove unused stuff from Ogre samples.
• Add ASAN CMake option
• Use OGRE_DEPRECATED
• Add cmake option to embed debug level into OgreBuildSettings
  • Bakes OGRE_DEBUG_MODE into OgreBuildSettings.h; which is on by default on Ninja/GNU Make generators and disabled for the rest.
• Pass cookie to Ogre Root initialization to catch obvious ABI errors. Each library could call checkAbiCookie on initialization to avoid problems
  • For static libs we must check:
    • _OgreExport, _OgrePrivate is consistent
    • -fvisibility=hidden and -fvisibility-inlines-hidden are consistent
• Default to clang's ld linker on Linux, i.e. set( CMAKE_EXE_LINKER_FLAGS "-fuse-ld=lld" )
• Use -gsplit-dwarf on Linux
• Enable /debug:fastlink (Update: do not use fastlink), /PDBTMCACHE and /Zf on Visual Studio
• Revisit HlmsPso constructors (e.g. see 055ed8f). Possibly by hand-rolling equalExcludePassData & lessThanExcludePassData instead of relying on memcmp
• Add GCov and see https://github.com/codecov/example-cpp11 and https://github.com/codecov/example-cpp11-cmake
• Remove OgreShadowVolumeExtrudeProgram.cpp
• Fix deprecation warnings
• Remove Serializer::readString? According to PVS-Studio it's buggy and apparently not used.
• AnimationTrack::_buildKeyFrameIndexMap needs attention. According to PVS-Studio it's buggy. However I believe the proposed solution may change observable behavior. It appears the code is explicitly relying on the fact that the out of bounds access should not happen.
• Remove (deprecate?) SceneManager::setFog
• Deprecate OgreAny (NumericKeyFrame seems to depend on it. It may stay but only for that) and refactor UserObjectBindings. It's overly bloated.
• Remove getShadowCasterVertex

New features

• Add memoryless flag for textures. RenderWindow's Depth Buffer should use it by default (because we don't allow sampling from it)
• Metal should use RootLayout to assign binding slots
  • Hardcoded slots are useful, but advanced features like CIVCT is hitting those limits
• Minify all samplers used per pass in Hlms. D3D11 is hitting those limits w/ CIVCT
  • We can make a table of predefined samplers and bind the table AND the sampler by addressing it from the table for OpenGL
  • Use a custom CbTexture command that ignores the sampler except on OpenGL

Stretch goals

• Check if clang format can be run while preserving git authorship / git blame
• Remove memory allocator stuff (see Ogre 1.x)
• Remove nedmalloc
• Typedef SharedPtr to std::shared_ptr (see Ogre 1.x)
• Run with UB sanitizer and fix
• Use __nullable and __nonnull
• FreeImage seems to be getting compiled with wrong visibility settings (i.e. inconsistent with Ogre)

[oldmanauz]

From ticket #245
Components to remove:

• Paging
• RTShaderSystem
• Terrain
• Volume

Plugins to remove:

• BSP plugin
• Octree Scene Manager plugin
• Octree Zone plugin
• PCZ Scene Manager plugin

Rendersystems to remove:

• DirectX9 Render System
• GLES2 Render System

CMAKE config cleanup:

• Remove legecy componetns, plugins and rendersystems from the configuration
• Remove the threading config options: OGRE_CONFIG_THREADS & OGRE_CONFIG_THREADS_PROVIDER
• Remove boost stuff from CMAKE

Documentation changes:

• Make the Ogre version number a variable that gets built by CMAKE (assuming this is dooable) and that way when a new version is release, we don't need to track the version throughout the manual
• Merge some documentation pages from Ogre which are still relevant to Ogre Next: Resource system, mesh tools
• Some samples have incorrect or are missing F1 help text.
• Promote some samples from api usage to showcase? Possibilities: IES ligts, Instant radiosity, Local reflections, Planar reflections.
• Modles section in manual needs to be cleaned up or removed
• Interest in a documentation refresh? Doxygen looks dated. Possible options:
  • New docs systems. This is potentially a lot of mucking around so not sure it is a great idea.
    • Docsforge flecs example is nicer to search
    • Sphinx bgfx example is visually appealing, the layout of the API reference is potentially harder to read than doxygen. Extra steps and dependencies to build the docs.
  • New theme for doxygen like doxygen awesome (Night mode - wow!)
  • New style as per Update CSS the style in API Reference page #84

[oldmanauz]

Sorry if this is thread polution, I'll move to sepeate issue if required:

• Can we also get clarifiaction on the exact name for ogre-next? So I can get some standardisation in the documentation. Currently it is called: Ogre V2, ogre-next, OgreNext, Ogre Next, Ogre-Next... etc
• Can we get the documents website setup so we can point to https://ogrecave.github.io/ogre-next/api/latest/manual.html. Currently we are doing: https://ogrecave.github.io/ogre-next/api/2.3/manual.html and having to update links for each new version.

[darksylinc]

Make the Ogre version number a variable that gets built by CMAKE (assuming this is dooable) and that way when a new version is release, we don't need to track the version throughout the manual

What does that mean? Examples? I have no idea what you're talking about 😕

Interest in a documentation refresh? Doxygen looks dated. Possible options:

YESS! Doxygen looks really ugly and not the best way to navigate!

So far what I like the best is just plain old Markdown from Github. Even our own doxygen sources in Github look better than their Doxygen counterparts but unfortunately there is no navigation and Doxygen's flavour of MD does not always work on Github.

Also unfortunately, it has no way to parse our source code either. Speaking of which; Doxygen should be able to generate pictures of relationships between component/classes but I can't find them and we're should be using them. Something is broken there.

Docsforge flecs example is nicer to search

Mmm looks good

Sphinx bgfx example is visually appealing, the layout of the API reference is potentially harder to read than doxygen. Extra steps and dependencies to build the docs.

Sphinx looks BEAUTIFUL and has multiple outputs which I like (HTML, PDF) but unfortunately:

• It doesn't parse source code
• Like you said steps for processing are... complex
• Nonetheless its benefits may be worth it
• I wouldn't rule out doxygen for parsing code with graphs, and SPHINX for regular documentation

• theme for doxygen like doxygen awesome (Night mode - wow!)

OK that looks nice!

New style as per #84

OK I just merged it.

Can we also get clarifiaction on the exact name for ogre-next? So I can get some standardisation in the documentation. Currently it is called: Ogre V2, ogre-next, OgreNext, Ogre Next, Ogre-Next... etc

I wish we had.

Ogre V2 was the name for a long time until Pavel wanted to make a bigger distinct since the branches diverged too much while V1 became active. We still use it when it need to differentiate between the two, but is getting abandoned.

The suffix Next was needed to separate the projects. We couldn't put a lot of thought into it.

The repo is ogre-next, but that is hard for me to type but so is Ogre-Next and Ogre Next, but I prefer the latter over the former. Probably OgreNext is easier for me to type but looks awkward.

:(

Suggestions welcomed.

Can we get the documents website setup so we can point to https://ogrecave.github.io/ogre-next/api/latest/manual.html. Currently we are doing: https://ogrecave.github.io/ogre-next/api/2.3/manual.html and having to update links for each new version.

I agree. The documentation is generated via github pages which uploads whatever is in the gh-pages branch. When we push, Github Actions runs this worklow which runs CMake, then the doxygen, and finally runs doxygen_remove_files.py to cleanup. IMHO likely the easiest solution is for doxygen_remove_files.py to copy/move the folder from 2.3 to latest

[oldmanauz]

What does that mean? Examples? I have no idea what you're talking about 😕

Haha. So currently in the manual we refer to an ogre verision very frequently (Ogre 2.3). This introduces pain becuase with each new release these version numbers get left in the documentation so there is lots of references to old version numbers (like Ogre 2.0) when they should read the latest version. Possible solutions:

• Once a standard way of refering to OgreNext(?) is decided, most of the references could be changed from a version number to OgreNext. Hopefully this will fix the issue.
• If there are remaining places where a version number is needed and it needs to be the current version, I was thinking we should genereate a version variable in a file with CMake that is equal to the current version, then use that variable in the manual so we don't need to chase old version numbers and update them to more current ones with each new release.

2. I agree that github markdown is very clean and simple. Also easy to create.

3. Does github.io give you flexability to create a structure of pages with markdown, then use the doxygen purely for the API reference? I have done almost zero research on this, but maybe github.io pages with markdown and use hyde and Jekyll to build c++ API?

4. I believe there is a plugin for Sphinx: Breathe, that parses doxygen xml output. To me it sounds like you end up with a complicated build process though but if it really gets you excited I could look at it. Reference implementation

5. As for the name. I would favour something with no spaces in the name, so: OgreNext or Ogre-Next. The latter is more annoying to type. Does this affect your renaming project? Or are you thinking of moving from the Next name completely?

I agree. The documentation is generated via github pages which uploads whatever is in the gh-pages branch. When we push, Github Actions runs this worklow which runs CMake, then the doxygen, and finally runs doxygen_remove_files.py to cleanup. IMHO likely the easiest solution is for doxygen_remove_files.py to copy/move the folder from 2.3 to latest

Can you grab any scripts from Ogre? Their site has this functionalitiy.

[oldmanauz]

Another TODO item:

• Particle system sample
• Unless I missed something, the OgreNext particleFX plugin is still legacy Ogre code? Should the ParticleFX plugin be updated? I saw someone had an attempt here Particle FX (PFX) a while back. Is there some code to look at for this somewhere? I didn't see any in the thread.

Also, I hope I don't sound like I'm dumping heaps of stuff on you to do. I want to help out where I can.

[cryham]

Hmm is this list up to date? Or should there be a 4.0 somewhere? Is it possible / how can we see which things are coming to Ogre-Next or are being worked on? There is also this trello board, not sure if it's less up to date or still used? Title has 2.1 so no idea now. There also wasn't any news post since a long while.

[darksylinc]

Hi!

I'm thinking of wrapping things up for OgreNext 3.0 and release. Whatever is left in this roadmap can be either be moved to 4.0 or abandoned. "The big tasks" have been taken care of now.

There is no 4.0 roadmap yet, it is living in the warm-up branch. The main focus will be multithreaded shader compilation.

[cryham]

* [ ]  Can we also get clarifiaction on the exact name for ogre-next? So I can get some standardisation in the documentation. Currently it is called: Ogre V2, ogre-next, OgreNext, Ogre Next, Ogre-Next... etc

I second this. Also an official logo for Ogre-Next? Or will it be just the same as old Ogre logo?

[darksylinc]

* [ ]  Can we also get clarifiaction on the exact name for ogre-next? So I can get some standardisation in the documentation. Currently it is called: Ogre V2, ogre-next, OgreNext, Ogre Next, Ogre-Next... etc

I second this.

I already replied to that.

Also an official logo for Ogre-Next? Or will it be just the same as old Ogre logo?

Our logo should be the new logo that Ogre1 is using. But I just noticed it's not there!? I swear I uploaded it.
Maybe it's because the Linux version does have the new logo?

I should check the Windows version has it as well (I think the logo on macOS is broken), as well as the documentation.

[darksylinc]

I just updated the Windows version: