Threaded Hlms

We introduced threaded Hlms shader generation, shader compilation, and PSO compilation.

This is used by the new warm_up compositor pass (see Ogre::CompositorPassWarmUp and Ogre::CompositorPassWarmUpDef), the Hlms Disk Cache, and during regular rendering.

This means that most Hlms operations gained a tid parameter, which contains the thread index in range [0; num_threads).

Operations done in Ogre::Hlms::preparePassHash and Ogre::Hlms::calculateHashFor are single threaded and thus should use Ogre::Hlms::kNoTid.

Hlms implementations and listeners

Custom Hlms implementations and listeners must update their virtual overload functions to accommodate the tid parameter.

This is explained in detail the new Multithreaded Shader Compilation section.

Porting tips (from <= 3.0)

Watch out for calls to mSetProperties.clear(); which now must be changed to either mSetProperties[kNoTid].clear(); or mSetProperties[tid].clear();.

The same happens with mSetProperties.empty();.

We strongly recommend you use override C++ keyword to locate the API signatures that have changed (which now require you to add the tid argument).

Once that's done, most Hlms-related compiler errors (if setting `OGRE_SHADER_COMPILATION_THREADING_MODE = 2`) can be fixed by doing a Find & Replace:

Find:	Replace with:
`setProperty(`	`setProperty( tid,`
`getProperty(`	`getProperty( tid,`
`setProperty(`	`setProperty( kNoTid,`
`getProperty(`	`getProperty( kNoTid,`

You should Find & Replace in that order. If you first find all setProperty( and replace them with setProperty( kNoTid,; you will end up with code that compiles but introduces race conditions and no way to identify them.

However if you first find all setProperty( and replace them with setProperty( tid,, you will end up with code that does not compile wherever kNoTid should be used (still exercise care when replacing tid with kNoTid, make sure to be conscious of it. See The tid (Thread ID) argument for details).

Compositor Script changes

Added the not_texture keyword. This can improve performance in scenarios where you don't intend to sample from this texture i.e. usually in conjuntion with either the uav or explicit_resolve keywords:

compositor_node RenderingNodeMsaa
{
    in 0 rt_renderwindow
 
    texture msaaSurface target_width target_height target_format target_orientation_mode msaa 4 not_texture explicit_resolve
 
    rtv mainRtv
    {
        colour 0 msaaSurface resolve rt_renderwindow
    }
 
    target mainRtv
    {
        pass render_scene
        {
        }
    }
 
    out 0 rt_renderwindow
}

New initialization step

If you plan on using Alpha Hashing, we provide both blue and white noise.

But blue noise requires you to call mRoot->getHlmsManager()->loadBlueNoise() during start up. See its new section in the manual for more information.

HlmsUnlit changes

HlmsUnlit now behaves like HlmsPbs when it comes to the use of mReservedTexBufferSlots & mReservedTexSlots.

The variable HlmsUnlit::mSamplerUnitSlotStart was removed and HlmsUnlit::mTexUnitSlotStart is now autocalculated every pass, which means users must not rely on overriding this value.

Users deriving from HlmsUnlit must set mReservedTexBufferSlots & mReservedTexSlots instead, like it is done for HlmsPbs.

See Colibri project's commit for an example of how the change was ported.

Header renames

Due to issues with different IDEs and build systems, renamed several headers so that all header files have a unique name, even if they live in a different folder.

For example Animation/OgreTagPoint.h is now Animation/OgreTagPoint2.h because OgreTagPoint.h already existed. This can cause build errors when upgrading to 4.0 that are easily fix by switching to their new names.

See commits 75801f33df72844384549b11de96b10421584bce and 67f9fddd4292877dbedb2507fba7719c42aad97c for affected files. The message of the commit was:

Avoid identically named source files - some build systems have problems with it, even if CMake have none (headermaps in XCode, shared intermediate folder in Visual Studio)

Table of Contents