This documents an old version of bs::framework. Click here to see the latest release.
Core thread asynchronous methods

This type of method doesn't execute immediately when called. Instead it is queued for execution and will be executed when the current frame ends. These methods generally need to perform some kind of communication between the main and core (rendering) threads, making direct calls impossible.

You can force the core thread to start executing queued methods before the end of the current frame, by calling CoreThread::submit(). This guarantees the commands will start executing, but doesn't guarantee they will finish, as it might take the core thread some time to process all queued commands.

If you wish to wait until your command finishes executing then set blockUntilComplete parameter of CoreThread::submit() to true.

An example that reads the texture data from the GPU:

SPtr<Texture> texture = ... some texture we created earlier ...;
SPtr<PixelData> output = ... buffer to receive the data ...;
texture->readData(output);
// Assuming we need the data right away, we submit the
// core thread queue and block until the command executes
// It's now safe to read the pixel data
Color color = output->getColorAt(0, 0);

Optionally, if the method returns an AsyncOp object, you can call AsyncOp::blockUntilComplete() for the same result. However you must ensure that you don't call it before CoreThread::submit() has been called, otherwise the calling thread might deadlock as it waits for the operations to finish, even though it was never started.

If the method provides a return value, you can use the provided AsyncOp object to retrieve it using AsyncOp::getReturnValue<T>(). Calling this is only valid if AsyncOp::hasCompleted() returns true. Return value is always available after you blocked using either of the ways mentioned above.

Note that blocking is a very expensive operation and should not be done in performance critical code. If you need to wait until an async method completes, it is preferable to keep querying AsyncOp::hasCompleted() and do something else until it returns true.

If you wish to learn more about how core thread works, visit the core thread manual.