Unigine::Filesystem Class

Header:

#include <UnigineFileSystem.h>

Sort by:

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, images, and nodes stored under and outside the data directory are loaded on demand only.

Filesystem functions:

Provide control over asynchronous loading of files/meshes/images/nodes 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.

Notice
					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 to a blob. A path to the file can be both absolute or relative to the data directory.

Arguments

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

Return value

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

int isBlobFile(const UGUID & guid)

Checks if a file with the given GUID is loaded to a blob.

Arguments

const UGUID & guid - File GUID.

Return value

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

int isCacheFile(const char * name)

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

Arguments

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

Return value

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

int isCacheFile(const UGUID & guid)

Checks if a file with the given GUID is loaded into cache.

Arguments

const UGUID & guid - File GUID.

Return value

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

int isFile(const char * name, int strict = 0)

Checks if a file with the given name exists in the file system.

Arguments

const char * name - Absolute or relative path to the file (including its name).
int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.

Return value

1 if the file exists; otherwise, 0.

int isFile(const UGUID & guid, int strict = 0)

Checks if a file with the given GUID exists in the file system.

Arguments

const UGUID & guid - File GUID.
int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.

Return value

1 if the file exists; otherwise, 0.

const char * getFileName(const char * name, int strict = 0)

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.
int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.

Return value

Path which is relative to the binary executable.

const char * getFileName(const UGUID & guid, int strict = 0)

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

Arguments

const UGUID & guid - File GUID.
int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.

Return value

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.

int isKnownFile(const char * name, int strict = 0)

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).
int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.

Return value

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

int isKnownFile(const UGUID & guid, int strict = 0)

Checks if a file with the given GUID is known to the file system.

Arguments

const UGUID & guid - File GUID.
int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.

Return value

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

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, int strict = 0)

Sets the time of the file last modification.

Arguments

const char * name - File name.
long long time - Time stamp to set.
int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.

Return value

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

long long getMTime(const char * name, int strict = 0)

Returns the time of the file last modification.

Arguments

const char * name - File name.
int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.

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 isPackageFile(const char * name, int strict = 0)

Checks if a file with a given name exists in one of the loaded packages.

Arguments

const char * name - File name.
int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.

Return value

1 if the file exists; otherwise, 0.

int isPackageFile(int num, const char * name, int strict = 0)

Checks if a file with a given name exists in the specified package.

Arguments

int num - Number of the ZIP or UNG package in the array of the loaded packages.
const char * name - File name.
int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.

Return value

1 if the file exists; otherwise, 0.

int isPackageFile(const UGUID & guid, int strict = 0)

Checks if a file with a given GUID exists in one of the loaded packages.

Arguments

const UGUID & guid - File GUID.
int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.

Return value

1 if the file exists; otherwise, 0.

int isPackageFile(int num, const UGUID & guid, int strict = 0)

Checks if a file with a given GUID exists in the specified package.

Arguments

int num - Number of the ZIP or UNG package in the array of the loaded packages.
const UGUID & guid - File GUID.
int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.

Return value

1 if the file exists; otherwise, 0.

const char * getPackageFileName(int num, const char * name, int strict = 0)

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.
int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.

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).

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 - 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 addBlobFile(const char * name, const UGUID & guid)

Adds a file with the given GUID 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 - Absolute or relative path to the file (including its name).
const UGUID & guid - File GUID.

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 - Relative path to the file (including its name) to add to cache.

Return value

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

int addCacheFile(const char * name, const UGUID & guid)

Caches a file in the memory with the given GUID. 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 - Relative path to the file (including its name) to add to cache.
const UGUID & guid - File GUID.

Return value

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

void addDirectory(const char * name)

Adds an external directory to the file system.

Arguments

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

UGUID addKnownFile(const char * name, int strict = 0, int exist = 0)

Registers the regular file name as known and appends it to 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 - Absolute or relative path to the file to register its name as known.
int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.
int exist

Return value

File GUID if it was registered successfully or an empty GUID, otherwise.

int addKnownFile(const char * name, const UGUID & guid, int strict = 0, int exist = 0)

Registers the regular file name as known with the given GUID and appends it to 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 - Absolute or relative path to the file to register its name as known.
const UGUID & guid - File GUID.
int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.
int exist

Return value

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

int removeKnownFile(const char * name, int strict = 0)

Removes the known file with the given name.

Arguments

const char * name - Absolute or relative path to the known file to remove.
int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.

Return value

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

int removeKnownFile(const UGUID & guid, int strict = 0)

Removes the known file with the given GUID.

Arguments

const UGUID & guid - GUID of the known file to remove.
int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.

Return value

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

int renameKnownFile(const char * name, const char * new_name, int strict = 0)

Renames the specified known file.

Arguments

const char * name - Absolute or relative path to the file.
const char * new_name - New path for the file.
int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.

Return value

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

int renameKnownFile(const char * name, const char * new_name, const UGUID & new_guid, int strict = 0)

Renames the specified known file and assigns it the specified new GUID.

Arguments

const char * name - Absolute or relative path to the file.
const char * new_name - New path for the file.
const UGUID & new_guid - New GUID for the file.
int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.

Return value

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

int renameKnownFile(const UGUID & guid, const char * new_name, int strict = 0)

Renames the known file with the given GUID.

Arguments

const UGUID & guid - File GUID.
const char * new_name - New path for the file.
int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.

Return value

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

int renameKnownFile(const UGUID & guid, const char * new_name, const UGUID & new_guid, int strict = 0)

Renames the known file with the given GUID and assigns it the specified new GUID.

Arguments

const UGUID & guid - File GUID.
const char * new_name - New path for the file.
const UGUID & new_guid - New GUID for the file.
int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.

Return value

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

void addModifier(const char * name)

Registers a new modifier in the file system.

Arguments

const char * name - Modifier name.

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 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 removeBlobFile(const UGUID & guid)

Removes a file with the given GUID 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.

Arguments

const UGUID & guid - File GUID.

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 cache; otherwise, 0.

int removeCacheFile(const UGUID & guid)

Removes a cached file with the given GUID 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.

Arguments

const UGUID & guid - File GUID.

Return value

1 if the file is successfully removed from cache; 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.

String getAbsoluteFileName(const char * name, int strict = 0)

Returns the absolute path to the file with the specified name.

Arguments

const char * name - File name.
int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.

Return value

Absolute path to the file.

String getAbsoluteFileName(const UGUID & guid, int strict = 0)

Returns the absolute path to the file with the specified GUID.

Arguments

const UGUID & guid - File GUID.
int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.

Return value

Absolute path to the file.

int isAssetPath(const char * name)

Returns a value indicating if the given path has a valid asset path format (e.g. "asset://1.tga)".

Arguments

const char * name - Path to be checked.

Return value

1 if the given path has a valid asset path format; otherwise, 0.

String getExtension(const char * name, int strict = 0)

Returns the extension of the file registered with the given name.

Arguments

const char * name - File name.
int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.

Return value

Extension of the file registered with the given name if it exists, or an emty string.

String getExtension(const UGUID & guid, int strict = 0)

Returns the extension of the file registered with the given GUID.

Arguments

const UGUID & guid - File GUID.
int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.

Return value

Extension of the file registered with the given GUID if it exists, or an emty string.

UGUID generateGUID()

Generates a new GUID.

Return value

New filesystem GUID if is was generated successfully; otherwise, an empty GUID.

int setGUID(const char * name, const UGUID & guid, int strict = 0)

Sets the specified GUID for the given file.

Arguments

const char * name - File path.
const UGUID & guid - GUID to be set for the file.
int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.

Return value

1 if the GUID is set successfully; otherwise, 0.

UGUID getGUID(const char * name, int strict = 0)

Returns the GUID (if it exists) for the given file.

Arguments

const char * name - File path.
int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.

Return value

File GUID if it exists, or an empty GUID, otherwise.

int isGUIDPath(const char * name)

Returns a value indicating if the given path has a valid GUID path format (e.g. "guid://e231e15beff2309b8f87c30b2c105cc4d2399973)".

Arguments

const char * name - Path to be checked.

Return value

1 if the given path has a valid GUID path format; otherwise, 0.

int saveGUIDs(const char * name, int binary = 1)

Saves all file system GUIDs to the specified file in the specified format (json or binary).

Arguments

const char * name - Path to the file, where file system GUIDs are to be stored.
int binary - Binary file format flag. When the flag is set to 1, the filesystem will save GUIDs to a binary file; otherwise, to a JSON file.

Return value

1 if all file system GUIDs are saved successfully; otherwise, 0.

int loadGUIDs(const char * name, int strict = 0)

Loads file system GUIDs from the specified file.

Arguments

const char * name - Path to the file, where file system GUIDs are stored.
int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.

Return value

1 if file system GUIDs are loaded successfully; otherwise, 0.

void clearGUIDs()

Clears all file system GUIDs.

void clearNonexistentPaths()

Clears all file paths, that don't exist.

String getRelativeFileName(const char * name, int strict = 0)

Returns a path to the given file which is relative to the data folder.

Arguments

const char * name - File name or the partial path to it.
int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.

Return value

Path to the file relative to the data folder.

String getRelativeFileName(const UGUID & guid, int strict = 0)

Returns a path to the given file which is relative to the data folder.

Arguments

const UGUID & guid - File GUID.
int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.

Return value

Path to the file relative to the data folder.

String getKnownFileName(const char * name, int strict = 0)

Returns a path to a known file with a given name.

Arguments

const char * name - File name or the partial path to it.
int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.

Return value

Path to the specified known file.

String getKnownFileName(const UGUID & guid, int strict = 0)

Returns a path to a known file with a given GUID.

Arguments

const UGUID & guid - File GUID.
int strict - Strict flag. When the flag is set to 1, the filesystem will disable checks for any other relative paths, that could contain specified path, and perform exact search instead.

Return value

Path to the specified known file.

void getKnownAbsoluteFileNames(Vector< String > & names)

Saves the list of absolute names for all known files registered in the file system to the specified string buffer.

Arguments

Vector< String > & names - String buffer to store the list of absolute names for all known files.

void getKnownFileNames(Vector< String > & names)

Saves the list of names for all known files registered in the file system to the specified string buffer.

Arguments

Vector< String > & names - String buffer to store the list of names for all known files.

Last update: 2018-04-26

Help improve this article

Was this article helpful?

Report a problem related to this article

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

Unigine::Filesystem Class

List of functions:

See also

FileSystem Class

Members

FileSystem * get()

int isBlobFile(const char * name)

Arguments

Return value

int isBlobFile(const UGUID & guid)

Arguments

Return value

int isCacheFile(const char * name)

Arguments

Return value

int isCacheFile(const UGUID & guid)

Arguments

Return value

int isFile(const char * name, int strict = 0)

Arguments

Return value

int isFile(const UGUID & guid, int strict = 0)

Arguments

Return value

const char * getFileName(const char * name, int strict = 0)

Arguments

Return value

const char * getFileName(const UGUID & guid, int strict = 0)

Arguments

Return value

void getFileNames(Vector< String > & names)

Arguments

int isKnownFile(const char * name, int strict = 0)

Arguments

Return value

int isKnownFile(const UGUID & guid, int strict = 0)

Arguments

Return value

const char * getModifier(int num)

Arguments

Return value

int setMTime(const char * name, long long time, int strict = 0)

Arguments

Return value

long long getMTime(const char * name, int strict = 0)

Arguments

Return value

int getNumFiles()

Return value

int getNumModifiers()

Return value

int getNumPackageFiles(int num)

Arguments

Return value

int getNumPackages()

Return value

int isPackageFile(const char * name, int strict = 0)

Arguments

Return value

int isPackageFile(int num, const char * name, int strict = 0)

Arguments

Return value

int isPackageFile(const UGUID & guid, int strict = 0)

Arguments

Return value

int isPackageFile(int num, const UGUID & guid, int strict = 0)

Arguments

Return value

const char * getPackageFileName(int num, const char * name, int strict = 0)

Arguments

Return value

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

Arguments

const char * getPackageName(int num)

Arguments

Return value

int addBlobFile(const char * name)

Arguments

Return value

int addBlobFile(const char * name, const UGUID & guid)