Unigine::AsyncQueue Class

Header:

#include <UnigineAsyncQueue.h>

List of functions:

List of Variables:

CALLBACK_BEGIN
CALLBACK_END
CALLBACK_FILE_LOADED
CALLBACK_IMAGE_LOADED
CALLBACK_MESH_LOADED
CALLBACK_NODE_LOADED
NUM_CALLBACKS

Loading of files/meshes/images/nodes on demand is performed in a separate system thread, in addition to asynchronous content streaming. This class is used to control asynchronous data loading. It is possible to control loading queue by organizing files in groups and setting individual weights inside these groups.

To load files on demand, call the functions in the following order:

First loadFile() function is called to place the file in the queue for loading and obtain an ID, that will be used to identify a resource in subsequent operations.
After that, different operations can be performed:
- forceFile() to load the file immediately.
- removeFile() to remove the file from the queue in case there is no need to load it any more of to remove a file from the list of loaded files if it was loaded but no longer needed.
- checkFile() to check if the given file was requested to be loaded via loadFile() or if it has already been loaded.

The same algorithm is true for meshes, images and nodes.

To get a loaded resource (image, mesh, or node) the following 2 groups of methods can be used:

Get-methods - these methods return the loaded resource:
Take-methods - these methods return the loaded resource and remove it from the list of loaded ones:

For example:

Source code (C++)

// specify a relative path when loading to the queue
int id = AsyncQueue::get()->loadMesh("box.mesh");
// check if the mesh is loaded into the queue
MeshPtr box = AsyncQueue::get()->getMesh(id);
while(!box) {
    // waiting...
}

Adding Callbacks

You can add "resource loaded" callbacks for files, images, meshes or nodes and perform certain actions as a resource is loaded. The example below shows how to add a "loaded" callback for image resource, that reports the name and id of the loaded image.

Notice

Do not call take-methods inside a callback function unless you are absolutely sure, that the resource is yours, otherwise internal engine managers will be forced to load it again and again every time. In such cases it is recommended to use get-methods.

Source code (C++)

void image_loaded(const char *name, int id)
{
	Log::message("Image \"%s\" loaded, ID: %d\n", name, id);
    // ...
}
					
// somewhere in the code
auto async = AsyncQueue::get();
async->addCallback(AsyncQueue::CALLBACK_IMAGE_LOADED, MakeCallback(image_loaded));
async->loadImage("image.dds");

Notice

This class is a singleton.

AsyncQueue Class

Members

int addCallback(int callback, Unigine::CallbackBase * func)

Adds a callback of the specified type. Callback functions can be used to determine actions to be performed when certain resources are loaded.

Notice

Source code (C++)

void image_loaded(const char *name, int id)
{
	Log::message("Image \"%s\" loaded, ID: %d\n", name, id);

	// ...

}
					
// somewhere in the code
auto async = AsyncQueue::get();
async->addCallback(AsyncQueue::CALLBACK_IMAGE_LOADED, MakeCallback(image_loaded));
async->loadImage("image.dds");

Arguments

int callback - Callback type. One of the CALLBACK_* variables.
Unigine::CallbackBase * func - Callback pointer.

Return value

Number of the last added callback of the specified type, if the callback was added successsfully; otherwise, -1.

AsyncQueue * get()

Returns a pointer to the existing AsyncQueue instance.

Return value

Pointer to the AsyncQueue instance.

Ptr<Image> getImage(int id)

Returns the image loaded by the specified operation.

Notice

This method does not remove the image from the list of loaded ones. If you want the image to be removed from this list right after retrieving it, use the takeImage() method.

Arguments

int id - Loading operation identifier (see the loadImage() method).

Return value

Image smart pointer.

Ptr<Mesh> getMesh(int id)

Returns the mesh loaded by the specified operation.

Notice

This method does not remove the mesh from the list of loaded ones. If you want the mesh to be removed from this list right after retrieving it, use the takeMesh() method.

Arguments

int id - Loading operation identifier (see the loadMesh() method).

Return value

Mesh smart pointer.

Ptr<Node> getNode(int id)

Returns the node loaded by the specified operation. If the node loaded by the specified operation consists of multiple objects, a new dummy object to combine them is created and its smart pointer is returned.

Notice

This method does not remove the node from the list of loaded ones. If you want the node to be removed from this list right after retrieving it, use the takeNode() method.

Arguments

int id - Loading operation identifier (see the loadNode() method).

Return value

Node smart pointer.

int getNodes(int id, Vector< Ptr<Node> > & nodes)

Puts the nodes loaded by the specified operation to the specified array. If the node loaded by the specified operation consists of multiple objects, they are put into the array.

Notice

This method does not remove the nodes from the list of loaded ones. If you want the nodes to be removed from this list right after retrieving them, use the takeNodes() method.

Arguments

int id - Loading operation identifier.
Vector< Ptr<Node> > & nodes - Array of loaded nodes' smart pointers.

Return value

1 if the operation is successful; otherwise, 0.

int getNumQueuedFiles()

Returns the total number of queued files waiting for the background loading. The return value also includes currently processed ones.

Return value

Total number of queued files including currently processed ones.

int getNumQueuedImages()

Returns the total number of queued images waiting for the background loading. The return value also includes currently processed ones.

Return value

Total number of queued images including currently processed ones.

int getNumQueuedMeshes()

Returns the total number of queued meshes waiting for the background loading. The return value also includes currently processed ones.

Return value

Total number of queued meshes including currently processed ones.

int getNumQueuedNodes()

Returns the total number of queued nodes waiting for the background loading. The return value also includes currently processed ones.

Return value

Total number of queued nodes including currently processed ones.

int getNumQueuedResources()

Returns the total number of queued resources waiting for background loading. The return value represents the sum of queued and currently processed data, files, images and meshes.

Return value

Total number of queued resources including currently processed ones.

float getTotalTime()

Returns the total time it took to process the loading queue.

Return value

Total processing time, in milliseconds.

int checkFile(int id)

Returns a value indicating if the file is in the loading queue or already loaded.

Arguments

int id - Loading operation identifier (see the loadFile() method).

Return value

1 if the file is in the loading queue or already loaded; otherwise, 0.

int checkImage(int id)

Returns a value indicating if the image is in the loading queue or already loaded.

Arguments

int id - Loading operation identifier (see the loadImage() method).

Return value

1 if the image is in the loading queue or already loaded; otherwise, 0.

int checkMesh(int id)

Returns a value indicating if the mesh is in the loading queue or already loaded.

Arguments

int id - Loading operation identifier (see the loadMesh() method).

Return value

1 if the mesh is in the loading queue or already loaded; otherwise, 0.

int checkNode(int id)

Returns a value indicating if the node is in the loading queue or already loaded.

Arguments

int id - Loading operation identifier (see the loadNode() method).

Return value

1 if the node is in the loading queue or already loaded; otherwise, 0.

void clearCallbacks(int callback)

Clears all added callbacks of the specified type. Callback functions can be used to determine actions to be performed when certain resources are loaded.

Arguments

int callback - Callback type. One of the CALLBACK_* variables.

int forceFile(int id)

Forces loading of the file. The specified file will be loaded right after the currently loading file (if any) is processed. All other file system operations are suspended until the forced file is loaded.

NoticeThe file won't be loaded immediately after calling the method as it can be large.

Arguments

int id - Loading operation identifier (see the loadFile() method).

Return value

1 if the file is loaded successfully; otherwise, 0.

int forceImage(int id)

Forces loading of the image. The specified image will be loaded right after the currently loading image (if any) is processed. All other file system operations are suspended until the forced image is loaded.

NoticeThe image won't be loaded immediately after calling the method as it can be large.

Arguments

int id - Loading operation identifier (see the loadImage() method).

Return value

1 if the image is loaded successfully; otherwise, 0.

int forceMesh(int id)

Forces loading of the mesh. The specified mesf will be loaded right after the currently loading mesh (if any) is processed. All other file system operations are suspended until the forced mesh is loaded.

NoticeThe mesh won't be loaded immediately after calling the method as it can be large.

Arguments

int id - Loading operation identifier (see the loadMesh() method).

Return value

1 if the mesh is loaded successfully; otherwise, 0.

int forceNode(int id)

Forces loading of the node. The specified node will be loaded right after the currently loading node (if any) is processed. All other file system operations are suspended until the forced node is loaded.

NoticeThe node won't be loaded immediately after calling the method as it can be large.

Arguments

int id - Loading operation identifier (see the loadNode() method).

Return value

1 if the node is loaded successfully; otherwise, 0.

int loadFile(const char * name, int group = 0, float weight = 0.0f)

Loads a given file with the specified group and priority to the thread.

Arguments

const char * name - Absolute or relative path to the file (including its name).
int group - Priority group. Greater priority means faster loading. The default value is 0.
float weight - Weight of the priority inside the group. Greater weight means faster loading inside the same priority group. The default value is 0.0f.

Return value

Loading operation identifier.

int loadImage(const char * name, int group = 0, float weight = 0.0f)

Loads a given image file with the specified group and priority to the thread.

Arguments

const char * name - Absolute or relative path to the image file (including its name).
int group - Priority group. Greater priority means faster loading. The default value is 0.
float weight - Weight of the priority inside the group. Greater weight means faster loading inside the same priority group. The default value is 0.0f.

Return value

Loading operation identifier.

int loadMesh(const char * name, int group = 0, float weight = 0.0f)

Arguments

const char * name - Absolute or relative path to the *.mesh file (including its name).
int group - Priority group. Greater priority means faster loading. The default value is 0.
float weight - Weight of the priority inside the group. Greater weight means faster loading inside the same priority group. The default value is 0.0f.

Return value

Loading operation identifier.

int loadNode(const char * name, int group = 0, float weight = 0.0f)

Arguments

const char * name - Absolute or relative path to the *.node file (including its name).
int group - Priority group. Greater priority means faster loading. The default value is 0.
float weight - Weight of the priority inside the group. Greater weight means faster loading inside the same priority group. The default value is 0.0f.

Return value

Loading operation identifier.

void removeCallback(int callback, int num)

Removes a callback with the given number from the list of callbacks of the specified type. Callback functions can be used to determine actions to be performed when certain resources are loaded.

Arguments

int callback - Callback type. One of the CALLBACK_* variables.
int num - Callback number.

int removeFile(int id)

Removes the given file from the loading queue or from the list of loaded files, if it was already loaded.

NoticeIf the specified file is currently loading, it will be removed after the loading opertion is completed.

Arguments

int id - Loading operation identifier (see the loadFile() method).

Return value

1 if the file is successfully removed; otherwise, 0.

int removeImage(int id)

Removes the given image from the loading queue or from the list of loaded images, if it was already loaded.

NoticeIf the specified image is currently loading, it will be removed after the loading opertion is completed.

Arguments

int id - Loading operation identifier (see the loadImage() method).

Return value

1 if the image is successfully removed; otherwise, 0.

int removeMesh(int id)

Removes the given mesh from the loading queue or from the list of loaded meshes, if it was already loaded.

NoticeIf the specified mesh is currently loading, it will be removed after the loading opertion is completed.

Arguments

int id - Loading operation identifier (see the loadMesh() method).

Return value

1 if the mesh is successfully removed; otherwise, 0.

int removeNode(int id)

Removes the given node from the loading queue or from the list of loaded nodes, if it was already loaded.

NoticeIf the specified node is currently loading, it will be removed after the loading opertion is completed. Nodes are removed with all their hierarchy.

Arguments

int id - Loading operation identifier (see the loadNode() method).

Return value

1 if the node is removed successfully; otherwise, 0.

Ptr<Image> takeImage(int id)

Returns the image loaded by the specified operation and removes it from the list of loaded images.

Arguments

int id - Loading operation identifier (see the loadImage() method).

Return value

Image smart pointer.

Ptr<Mesh> takeMesh(int id)

Returns the mesh loaded by the specified operation and removes it from the list of loaded meshes.

Arguments

int id - Loading operation identifier (see the loadMesh() method).

Return value

Mesh smart pointer.

Ptr<Node> takeNode(int id)

Returns the node loaded by the specified operation and removes it from the list of loaded nodes.

Notice

Nodes are removed with all their hierarchy.

Arguments

int id - Loading operation identifier (see the loadNode() method).

Return value

Node smart pointer.

int takeNodes(int id, Vector< Ptr<Node> > & nodes)

Puts the nodes loaded by the specified operation to the specified array and removes them from the list of loaded nodes. If the node loaded by the specified operation consists of multiple objects, they are put into the array.

Notice

Nodes are removed with all their hierarchy.

Arguments

int id - Loading operation identifier.
Vector< Ptr<Node> > & nodes - Array of loaded nodes' smart pointers.

Return value

1 if the operation is successful; otherwise, 0.

int CALLBACK_BEGIN

Description

Beginning of the callbacks range.

int CALLBACK_END

Description

End of the callbacks range.

int CALLBACK_FILE_LOADED

Description

File loaded callback.

int CALLBACK_IMAGE_LOADED

Description

Image loaded callback.

int CALLBACK_MESH_LOADED

Description

Mesh loaded callback.

int CALLBACK_NODE_LOADED

Description

Node loaded callback.

int NUM_CALLBACKS

Description

Callback counter.

Last update: 20.10.2017

Помогите сделать статью лучше

Была ли эта статья полезной?

Сообщить о проблеме в этой статье

(или выберите слово/фразу и нажмите Ctrl+Enter