Unigine::Filesystem Class

Header:

#include <UnigineFileSystem.h>

List of functions:

On the engine file system initialization, all files and packages stored in the data folder are added to the file system automatically. At that, content of the ZIP and UNG packages is loaded into RAM as is (so, you'd better not store heavy content (e.g. terrains) in the packages).

Files and packages stored outside the data directory should be added to the file system on the application start-up or by using the corresponding functions (addDirectory(), loadPackage()).

Files, meshes and images stored under and outside the data directory are loaded on demand only.

The functions given below:

Provide control over asynchronous loading of files/meshes/images on demand under the data directory, including files in ZIP and UNG packages. Such packages are automatically handled by the engine and all their files are automatically added to the file system.
Allow adding directories (even with ZIP and UNG packages) that are outside the data directory and provide control over loading such files.
Allow adding ZIP and UNG packages that are outside the data directory. After that, files in such packages are accessed in a usual way, by specifying a path to the file only inside the package.
Allow caching files in the memory and adding files to blobs if they are accessed or modified multiple times in run-time.

Loading Files on Demand

Loading of files/meshes/images on demand is performed in a separate system thread, in addition to asynchronous content streaming. 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.
After that, different operations can be performed:
Notice
If you specify an absolute path to a file in the loadFile() function, you should use this absolute path when performing operations on it. The same is true for relative paths.
- 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.
- validateFile() to check if the file is still pending in the queue or if it has already been loaded.
- checkFile() to check if the given file was requested to be loaded vialoadFile().

The same algorithm is true for meshes and images. For example:

When a mesh is stored in the data folder:

Source code (C++)

// specify a relative path when loading to the queue
FileSystem::loadMesh("box.mesh");
// check if the mesh is loaded into the queue
Mesh box = FileSystem::getMesh("box.mesh");
while(box == NULL) {
    // waiting...
}

When a mesh is stored outside the data folder:

Source code (C++)

// specify a relative path when loading to the queue
FileSystem::loadMesh("D:/meshes/box.mesh");
// check if the mesh is loaded into the queue
Mesh box = FileSystem::getMesh("D:/meshes/box.mesh");
while(box == NULL) {
    // waiting...
}

Notice
				To use this class, include the UnigineFileSystem.h file.
This class is in the Unigine namespace.
This class is a singleton.

			

FileSystem Class

Members

FileSystem * get()

int isBlobFile(const char * name)

Checks if the given file is loaded into a blob. A path to the file can be both absolute or relative to the data directory.

Arguments

const char * name - An absolute or relative path to the file (including its name).

Return value

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

int isCacheFile(const char * name)

Checks if the given file is loaded into a cache. A path to the file should be relative to the data folder.

Arguments

const char * name - A relative path to the file (including its name).

Return value

1 if the file is added into a cache; otherwise, 0.

int isFile(const char * name)

Arguments

const char * name

const char * getFileName(const char * name)

Returns the relative path to the file by the given partial one. The path will be relative to the binary executable.

Arguments

const char * name - File name or the partial path to it.

Return value

The path which is relative to the binary executable.

void getFileNames(Vector< String > & names)

Fills the given vector with the list of unarchived files cached by the file system.

Arguments

Vector< String > & names - A vector where file names will be saved.

Ptr<Image> getImage(const char * name)

Checks whether the image is placed to the loading queue and return it if it is.

Arguments

const char * name - An absolute or relative path to the mesh (including its name).

Return value

Loaded image smart pointer. If the image is not placed to the queue, NULL is retuned.

int isKnownFile(const char * name)

Checks if the given file is known to the file system. A path to the file can be both relative or absolute to the data directory.

Arguments

const char * name - An absolute or relative path to the file (including its name).

Return value

1 if the file is known to the file system; otherwise, 0.

Ptr<Mesh> getMesh(const char * name)

Checks whether the mesh is placed to the loaded queue.

Arguments

const char * name - An absolute or relative path to the mesh (including its name).

Return value

Loaded mesh smart pointer. If the mesh is not placed to the queue, NULL is retuned.

const char * getModifier(int num)

Returns the name of the given modifier.

Arguments

int num - ID number of the modifier.

Return value

Modifier name.

int setMTime(const char * name, long long time)

Sets the time of the file last modification.

Arguments

const char * name - File name.
long long time - Time stamp to set.

Return value

1 if the time stamp is set successfully; otherwise, 0.

long long getMTime(const char * name)

Returns the time of the file last modification.

Arguments

const char * name - File name.

Return value

Time of the last modification. If there is no file with such name, -1 will be returned.

int getNumFiles()

Returns the number of files cached by the file system.

Return value

Number of cached files.

int getNumModifiers()

Returns the total number of file modifiers registered in the file system.

Return value

Number of modifiers.

int getNumPackageFiles(int num)

Returns the number of files inside of a given ZIP or UNG package.

Arguments

int num - Number of the ZIP or UNG package.

Return value

Number of files inside a package.

int getNumPackages()

Returns the number of ZIP and UNG packages inside the data directory.

Return value

Number of packages.

int getNumQueuedData()

Returns the number of queued file system data waiting for background loading. The return value also includes the currently processed data.

Return value

Number of queued file system data including the currently processed data.

int getNumQueuedFiles()

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

Return value

Number of queued files including the currently processed file.

int getNumQueuedImages()

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

Return value

Number of queued images including the currently processed image.

int getNumQueuedMeshes()

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

Return value

Number of queued meshes including the currently processed mesh.

int getNumQueuedResources()

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

Return value

Number of queued file system resources including the currently processed resources.

int isPackageFile(int num, const char * name)

Checks if the given file exists in the package.

Arguments

int num - Number of the ZIP or UNG package.
const char * name - File name.

Return value

1 if the file exists; otherwise, 0.

const char * getPackageFileName(int num, const char * name)

Returns the path to the given file relative to the package root directory. The path includes the name of the given file.

Source code (UnigineScript)

Log::message("A path to the file inside the package: %s\n",FileSystem::getPackageFilesystem(0,"material_ball.mesh"));

Output

A path to the file inside the package: meshes/material_ball.mesh

Arguments

int num - Number of the ZIP or UNG package in the array of the loaded packages.
const char * name - File name.

Return value

A path to the file of the package.

void getPackageFileNames(int num, Vector< String > & names)

Fills the given vector with the list of files in the specified ZIP or UNG package.

Arguments

int num - Number of the ZIP or UNG package.
Vector< String > & names - A vector where file names will be saved.

const char * getPackageName(int num)

Returns an absolute path (including a name) to a given ZIP or UNG package.

Source code (C++)

Log::message("A path to a package: %s\n",FileSystem::getPackageName(0));

Output

A path to a package: D:/unigine_projects/unigine_project/data/core.ung

Arguments

int num - Number of the ZIP or UNG package in the array of the loaded packages.

Return value

An absolute path to the package (including its name).

float getTotalTime()

Returns the total time (in milliseconds) of loading a file system resource.

Return value

The total time value, milliseconds.

int addBlobFile(const char * name)

Adds a file into a blob. It can be used for files that are frequently modified in run-time (for example, images). After such file is loaded from a disk and written into a blob in the memory, its modifications can be saved fast into this blob. A path to the file can be both absolute or relative to the data directory.

Arguments

const char * name - An absolute or relative path to the file (including its name).

Return value

1 if the file is successfully added into a blob; otherwise, 0.

int addCacheFile(const char * name)

Caches a file in the memory. It can be used for files that are accessed multiple times in run-time (for example, textures are read two times in a row). Such files are loaded into the memory for faster reading. A path to the file should be relative to the data folder.

Arguments

const char * name - A relative path to the file (including its name) to add to a cache.

Return value

1 if the file is successfully added to a cache; otherwise, 0.

void addDirectory(const char * name)

Adds an external directory to the file system.

Arguments

const char * name - An absolute path to the directory (including its name).

int addKnownFile(const char * name)

Registers the regular file name as known and appends it into the map used for fast searching. A path to the file can be both relative or absolute to the data directory.

Arguments

const char * name - An absolute or relative path to the file to register its name as known.

Return value

1 if the file name is appended successfully; otherwise, 0.

void addModifier(const char * name)

Registers a new modifier in the file system.

Arguments

const char * name - Modifier name.

int checkFile(const char * name)

Returns a value indicating if:

The given file was loaded to the file system.
The given file is being loaded to the file system at the moment.
The given file is in the loading queue.

Arguments

const char * name - An absolute or relative path to the file (including its name).

Return value

1 if the file is in the loading queue, already loaded to the file system or is being loaded to file system at the moment; otherwise, 0.

int checkImage(const char * name)

Returns a value indicating if:

The given image was loaded to the file system.
The given image is being loaded to the file system at the moment.
The given image is in the loading queue.

Arguments

const char * name - An absolute or relative path to the image (including its name).

Return value

1 if the image is in the loading queue, already loaded to the file system or is being loaded to file system at the moment; otherwise, 0.

int checkMesh(const char * name)

Returns a value indicating if:

The given mesh was loaded to the file system.
The given mesh is being loaded to the file system at the moment.
The given mesh is in the loading queue.

Arguments

const char * name - An absolute or relative path to the mesh (including its name).

Return value

1 if the mesh is in the loading queue, already loaded to the file system or is being loaded to file system at the moment; otherwise, 0.

void clearModifiers()

Unregister all modifiers in the file system.

int findPackage(const char * name)

Checks if an UNG or ZIP package has been added into the file system.

Arguments

const char * name - An absolute path to the package (including its name).

Return value

Number of the ZIP or UNG package if it is found; otherwise, -1.

int forceFile(const char * name)

Starts loading of the given file from the loading queue. The 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. Note that the file won't be loaded immediately after calling the function as it can be large, for example.

Arguments

const char * name - An absolute or relative path to the file (including its name).

Return value

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

int forceImage(const char * name)

Starts loading of the given image from the loading queue. The 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. Note that the image won't be loaded immediately after calling the function as it can be large, for example.

Arguments

const char * name - An absolute or relative path to the image (including its name).

Return value

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

int forceMesh(const char * name)

Starts loading of the given mesh from the loading queue. The mesh 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. Note that the mesh won't be loaded immediately after calling the function as it can be large, for example.

Arguments

const char * name - An absolute or relative path to the mesh (including its name).

Return value

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

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

Loads a file on demand: adds a file to the background loading queue (i.e. threaded file loading). Files with identical priorities and weights are loaded in the alphabetical order.

Arguments

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

Return value

1 if the file is successfully appended to the queue; otherwise, 0.

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

Adds an image to the background loading queue (i.e. threaded image loading). Images with the identical groups and weights are loaded in the alphabetical order.

Arguments

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

Return value

1 if the image is successfully appended to the queue; otherwise, 0.

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

Loads a mesh on demand: adds a mesh to the background loading queue (i.e. threaded mesh loading). Meshes with the identical groups and weights are loaded in the alphabetical order.

Arguments

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

Return value

1 if the mesh is successfully appended to the queue; otherwise, 0.

int loadPackage(const char * name, const char * extension = 0)

Loads an UNG or ZIP package into the file system. An archive can be located outside data directory ( an absolute path should be specified in this case).

NoticeUNG packages without password protection can be loaded even if the engine has built-in password for the file system packages.
							For example, it is possible to load both the core.ung package without a password and the my_assets.ung package protected with a password.

Arguments

const char * name - Package name. It can be an absolute path or a path relative to data directory, if it is inside of it.
const char * extension - ung or zip package extension.

Return value

1 if the package is loaded; otherwise, 0.

int reloadPackage(const char * name)

Reloads package files.

Arguments

const char * name

Return value

Returns 1 if the package is reloaded successfully; otherwise, 0.

int removeBlobFile(const char * name)

Removes a blob with a file from the blob. Blobbing can be used for files that are frequently modified in run-time (for example, images). After such file is loaded from a disk and written into a blob in the memory, its modifications can be saved fast into this blob. A path to the file can be both absolute or relative to the data directory.

Arguments

const char * name - An absolute or relative path to the file (including its name).

Return value

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

int removeCacheFile(const char * name)

Removes a cached file from the memory. Caching can be used for files that are accessed multiple times in run-time (for example, textures are read two times in a row). Such files are loaded into the memory for faster reading. A path to the file should be relative to the data folder.

Arguments

const char * name - A relative path to the file (including its name) to be removed from a cache.

Return value

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

int removeFile(const char * name)

Removes a pending file from the loading queue.

Arguments

const char * name - An absolute or relative path to the file (including its name).

Return value

int removeImage(const char * name)

Removes a pending image from the loading queue.

Arguments

const char * name - An absolute or relative path to the image (including its name).

Return value

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

int removeMesh(const char * name)

Removes a pending mesh from the loading queue.

Arguments

const char * name - An absolute or relative path to the mesh (including its name).

Return value

1 if the mesh is removed successfully; otherwise 0.

void removeModifier(const char * name)

Unregisters a given modifier in the file system.

Arguments

const char * name - Modifier name.

int removePackage(const char * name)

Unloads an UNG or ZIP package from the file system.

Arguments

const char * name - An absolute path to the package (including its name).

Return value

1 if the package is removed; otherwise, 0.

int validateFile(const char * name)

Checks whether the pending file placed in the loading queue has been loaded.

Arguments

const char * name - An absolute or relative path to the file (including its name).

Return value

1 if the file is loaded; 0 if it is still pending in the queue.

Last update: 2017-07-03

Help improve this article

Was this article helpful?

Report a problem related to this article

(or select a word/phrase and press Ctrl+Enter)