OGRE 1.12.10
Object-Oriented Graphics Rendering Engine
Loading...
Searching...
No Matches
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:

Ogre::TexturePtr tex = ...;
Ogre::WorkQueue::RequestID ticket = rbq.prepare(tex->getCreator()->getType(), tex->getName(), tex->getGroup());
This class is used to perform Resource operations in a background thread.
Definition OgreResourceBackgroundQueue.h:83
static ResourceBackgroundQueue & getSingleton(void)
Get the singleton instance.
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.
const String & getGroup(void) const
Gets the group which this resource is a member of.
Definition OgreResource.h:389
ResourceManager * getCreator(void)
Gets the manager which created this resource.
Definition OgreResource.h:401
const String & getName(void) const
Gets resource name.
Definition OgreResource.h:308
Definition OgrePrerequisites.h:343

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();
}
}
This abstract listener interface lets you get notifications of completed background processes instead...
Definition OgreResourceBackgroundQueue.h:94
virtual void operationCompleted(BackgroundProcessTicket ticket, const BackgroundProcessResult &result)=0
Called when a requested operation completes, queued into main thread.
Encapsulates the result of a background queue request.
Definition OgreResourceBackgroundQueue.h:52
bool error
Whether an error occurred.
Definition OgreResourceBackgroundQueue.h:54

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.

Note
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 -