OGRE  13.1
Object-Oriented Graphics Rendering Engine
Background Resource Loading

Ogre uses thread pool based concurrency, where a fixed number of persistent worker threads are used to process incoming jobs. The worker threads are organized in WorkQueues, which allows implementing load-balancing.

By default Ogre creates one Ogre::WorkQueue, implementing Ogre::DefaultWorkQueueBase with 1-2 workers attached. The workers are started after the first Ogre::RenderWindow is created. You can customize the default work queue by calling Ogre::DefaultWorkQueueBase::setWorkerThreadCount and Ogre::DefaultWorkQueueBase::setWorkersCanAccessRenderSystem before the WorkQueue is started or later by manually restarting the WorkQueue.

For resource loading, there is additionally the high-level Ogre::ResourceBackgroundQueue interface, that dispatches work to the default WorkQueue, but hides the internal Ogre::WorkQueue::Request/ Ogre::WorkQueue::Response handling.

To prepare a Texture in the background you can do:

the returned ticket can be used to identify the request via Ogre::WorkQueue::abortRequest, or to poll whether it is finished via Ogre::ResourceBackgroundQueue::isProcessComplete. However, the preferred way to get notified about the operation being completed is to pass a Ogre::ResourceBackgroundQueue::Listener as the final argument.

The following code shows an sample implementation that loads a previously prepared resource on the main thread.

class LoadWhenPreparedListener : public Ogre::ResourceBackgroundQueue::Listener
std::map<Ogre::WorkQueue::RequestID, Ogre::ResourcePtr> mResources;
if (!result.error) mResources[id]->load();

In the default build config, background workers cannot access the Ogre::RenderSystem to avoid the overhead incurred by the underlying APIs. Therefore, only Ogre::Resource::prepare can be called by a worker, while Ogre::Resource::load must be done on the main thread.

This makes calls to Ogre::Resource::setBackgroundLoaded obsolete as they cause Resources to ignore load() calls from the main thread, enforcing that they are loaded from a Worker thread.

The table below shows an overview what the prepared and loaded states mean for different resource types.

Type Prepared Loaded
Mesh read file to memory parsed and uploaded to GPU
Material prepared and compiled supported techniques supported techniques loaded
Texture read and decoded images uploaded to GPU
GpuProgram (HLSL) read source and compiled microcode uploaded to GPU and created buffers
GpuProgram (GLSL) read and preprocessed source compiled and uploaded to GPU
Compositor - compiled supported techniques and created textures
Skeleton read and parsed animation -
const String & getName(void) const
Gets resource name.
Definition: OgreResource.h:310
static ResourceBackgroundQueue & getSingleton(void)
Get the singleton instance.
Encapsulates the result of a background queue request.
Definition: OgreResourceBackgroundQueue.h:51
virtual BackgroundProcessTicket prepare(const String &resType, const String &name, const String &group, bool isManual=false, ManualResourceLoader *loader=0, const NameValuePairList *loadParams=0, Listener *listener=0)
Prepare a single resource in the background.
bool error
Whether an error occurred.
Definition: OgreResourceBackgroundQueue.h:54
virtual void operationCompleted(BackgroundProcessTicket ticket, const BackgroundProcessResult &result)=0
Called when a requested operation completes, queued into main thread.
const String & getGroup(void) const
Gets the group which this resource is a member of.
Definition: OgreResource.h:391
This abstract listener interface lets you get notifications of completed background processes instead...
Definition: OgreResourceBackgroundQueue.h:95
ResourceManager * getCreator(void)
Gets the manager which created this resource.
Definition: OgreResource.h:403
Ogre::SharedPtr< Texture >
unsigned long long int RequestID
Numeric identifier for a request.
Definition: OgreWorkQueue.h:82
This class is used to perform Resource operations in a background thread.
Definition: OgreResourceBackgroundQueue.h:83