This page has been translated automatically.
视频教程
界面
要领
高级
实用建议
UnigineEditor
界面概述
资产工作流程
设置和首选项
项目开发
调整节点参数
Setting Up Materials
Setting Up Properties
照明
Landscape Tool
Sandworm
使用编辑器工具执行特定任务
Extending Editor Functionality
嵌入式节点类型
Nodes
Objects
Effects
Decals
光源
Geodetics
World Objects
Sound Objects
Pathfinding Objects
Players
编程
基本原理
搭建开发环境
Usage Examples
UnigineScript
C++
C#
UUSL (Unified UNIGINE Shader Language)
File Formats
Rebuilding the Engine Tools
GUI
双精度坐标
应用程序接口
Containers
Common Functionality
Controls-Related Classes
Engine-Related Classes
GUI-Related Classes
Math Functionality
Node-Related Classes
Objects-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
IG Plugin
CIGIConnector Plugin
Rendering-Related Classes
创建内容
Content Optimization
Materials
Art Samples
Tutorials
注意! 这个版本的文档是过时的,因为它描述了一个较老的SDK版本!请切换到最新SDK版本的文档。
注意! 这个版本的文档描述了一个不再受支持的旧SDK版本!请升级到最新的SDK版本。

Unigine::FileSystem Class

Header: #include <UnigineFileSystem.h>

On the Engine file system initialization, all files and packages stored in the data folder are added to the virtual 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 are also added to the virtual file system, if they are mounted (i.e. referenced by a mount point).

Notice
If you add new files at run time, the Engine won't know anything about such files. To add the files to the virtual file system, use addVirtualFile().

File System 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 at run time.

Also methods of the FileSystem class can be used when implementing your own importer from an external format to UNIGINE-native ones. For example, you can store only the original file on the disk, files in UNIGINE-native formats can be stored in the virtual file system only.

Notice
  • This class is in the Unigine namespace.
  • This class is a singleton.

See also#

  • AsyncQueue Class to manage loading resources (files, images, meshes, and nodes) on demand.

FileSystem Class

Enums

CALLBACK_INDEX#

NameDescription
CALLBACK_FILE_ADDED = 0Callback fired after the file is added using the FileSystem API.
CALLBACK_FILE_REMOVED = 1Callback fired after the file is removed using the FileSystem API.
CALLBACK_FILE_CHANGED = 2Callback fired after the file is changed using the FileSystem API.
CALLBACK_FILES_ADDED = 3Callback fired at the end of the Engine::update() containing the files have been added during the frame.
CALLBACK_FILES_REMOVED = 4Callback fired at the end of the Engine::update() containing the files have been removed during the frame.
CALLBACK_FILES_CHANGED = 5Callback fired at the end of the Engine::update() containing the files have been changed during the frame.
NUM_CALLBACKS = 6Callback counter.

Members


Ptr<FileSystemMount> getMount ( const char * path ) #

Returns a mount point for the specified path.
Notice
This method will return the root mount for all files located directly in the data folder or its subfolders.

Arguments

  • const char * path - File path, for which a mount point is to be found. It can be a relative, absolute, network, or virtual path.
    Notice
    If you want to specify a path to an asset, you should use the asset path format (asset://). Otherwise, if you specify the regular path to the asset, it will be treated as the path to its runtime file (if any) from the .runtimes folder.

Return value

FileSystemMount class smart pointer on success; otherwise, nullptr.

Ptr<FileSystemMount> getMount ( const UGUID & guid ) #

Returns a mount point for the specified GUID.
Notice
This method will return the root mount for all files located directly in the data folder or its subfolders.

Arguments

  • const UGUID & guid - File GUID for which a mount point is to be found.

Return value

FileSystemMount class smart pointer on success; otherwise, nullptr.

void getMounts ( Vector< Ptr<FileSystemMount> > & container ) #

Returns a list of all mount points currently used by the file system and puts the to the specified output buffer.
Notice
This list will not include the root mount.

Arguments

Ptr<FileSystemMount> getRootMount ( ) #

Returns the root mount of the file system. It mounts the data folder to the root of the virtual file system. The root mount cannot be unmounted.

Return value

FileSystemMount class smart pointer for the root mount of the virtual file system.

Ptr<FileSystemMount> createMount ( const char * absolute_path, const char * virtual_path, int access ) #

Adds a new mount point for the specified external folder/package, virtual path and access mode. All mounted files are automatically added as known to the virtual file system.

Arguments

  • const char * absolute_path - Absolute path to the mounted folder/package.
  • const char * virtual_path - Virtual path to the folder to which the contents of the external folder/package is to be mounted.
  • int access - Mount point access mode, one of the FileSystemMount::ACCESS_* values.

Return value

FileSystemMount class smart pointer, if it was created successfully; otherwise, nullptr.

Ptr<FileSystemMount> addMount ( const char * umount_path ) #

Adds a new mount point using the data from the specified *.umount file. All mounted files are automatically added as known to the virtual file system.

Arguments

  • const char * umount_path - Absolute path to a *.umount file.

Return value

FileSystemMount class smart pointer, if it was created successfully; otherwise, nullptr.

bool saveMountFile ( const char * umount_path ) #

Saves the specified *.umount file.

Arguments

Return value

true if the specified *.umount file is saved successfully; otherwise, false.

bool removeMount ( const char * path ) #

Unmounts a mount point with a given path.
Notice
The root mount cannot be removed.

Arguments

  • const char * path - Absolute path to the mounted folder/package.

Return value

true if the mount point with a given path is successfully unmounted; otherwise, false.

void clearMounts ( ) #

Unmounts all mount points.
Notice
This method does not remove the root mount.

bool loadPackage ( const char * path ) #

Loads an UNG or ZIP package into the file system. Note that the package should be mounted, otherwise it won't be loaded.
Notice
UNG 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 * path - Package path. It can be a relative, absolute, network, or virtual path.

Return value

true if the package is loaded; otherwise, false.

bool loadPackage ( const char * path, const char * extension ) #

Loads a package with the specified extension (ung, zip, or pak) into the file system. Note that the package should be mounted, otherwise it won't be loaded.
Notice
UNG 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 * path - Package path. It can be a relative, absolute, network, or virtual path.
  • const char * extension - Extension of a custom package, one of the following values:
    • ung
    • zip
    • pak

Return value

true if the package is loaded; otherwise, false.

bool removePackage ( const char * path ) #

Unloads an UNG or ZIP package from the file system.

Arguments

  • const char * path - Package path. It can be a relative, absolute, network, or virtual path.

Return value

true if the package is removed; otherwise, false.

void getSupportedPackagesExtensions ( Vector< String > & extensions ) const#

Returns a list of registered extensions that can be loaded as a package.

Arguments

  • Vector< String > & extensions - An array to store registered extensions.

void getPackageVirtualFiles ( const char * path, Vector< String > & files ) #

Saves the list of names for all virtual files stored in the specified package to the specified string buffer.

Arguments

  • const char * path - Path to a custom package. It can be a relative, absolute, network, or virtual path.
  • Vector< String > & files - String buffer to store the list of names for all virtual files stored in the specified package.

void getPackageVirtualFiles ( const char * path, const char * extension, Vector< String > & files ) #

Saves the list of names for all virtual files stored in a package with the specified name and extension to the specified string buffer.

Arguments

  • const char * path - Path to a custom package. It can be a relative, absolute, network, or virtual path.
  • const char * extension - Extension of a custom package, one of the following values:
    • ung
    • zip
    • pak
  • Vector< String > & files - String buffer to store the list of names for all virtual files stored in the specified package.

void preloadExternPackage ( Package * package ) #

Loads the custom package before the file system initialization. The method should be called before the Engine init.
Source code (C++)
// preload package
FileSystem::preloadExternPackage(new MyPackage());
// init engine
EnginePtr engine(UNIGINE_VERSION, argc, argv);

Arguments

  • Package * package - Custom package instance.

void preloadExternPackage ( const char * virtual_path, Package * package ) #

Loads the custom package before the file system initialization and sets a virtual path to it. The method should be called before the Engine init.

Arguments

  • const char * virtual_path - Virtual path to a custom package.
  • Package * package - Custom package instance.

void clearPreloadedExternPackages ( ) #

Clears all preloaded custom packages (packages loaded before the file system initialization).

bool addExternPackage ( Package * package ) #

Adds a custom package to the virtual file system.

Arguments

  • Package * package - Custom package instance.

Return value

true if the package is added successfully; otherwise, false.

bool addExternPackage ( const char * path, Package * package ) #

Adds a custom package to the virtual file system and assigns a virtual path to it. The virtual path is obtained by using the given path.

Arguments

  • const char * path - Path to a custom package. It can be a relative, absolute, network, or virtual path.
  • Package * package - Custom package instance.

Return value

true if the package is added successfully; otherwise, false.

void getVirtualFiles ( Vector< String > & files ) #

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

Arguments

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

bool isVirtualFile ( const char * path ) #

Checks if the given file is known to the virtual file system.

Arguments

  • const char * path - File path. It can be a relative, absolute, network, or virtual path.

Return value

true if the file is known to the virtual file system; otherwise, false.

bool isVirtualFile ( const UGUID & guid ) #

Checks if a file with the given GUID is known to the virtual file system and has a virtual path registered.

Arguments

Return value

true if the file is known to the virtual file system; otherwise, false.

bool addVirtualFile ( const char * path, const UGUID & guid, bool must_exist = false ) #

Registers the regular file name as known virtual file with the given GUID and appends it to the map used for fast searching. This method should be used when you need to add, for example, a new content to the project.

Arguments

  • const char * path - File path. It can be a relative, absolute, network, or virtual path.
    Notice
    If you want to specify a path to an asset, you should use the asset path format (asset://). Otherwise, if you specify the regular path to the asset, it will be treated as the path to its runtime file (if any) from the .runtimes folder.
  • const UGUID & guid - File GUID.
  • bool must_exist - A flag indicating whether the specified file must exist.

Return value

true if the file name is appended successfully; otherwise, false.

UGUID addVirtualFile ( const char * path, bool must_exist = false ) #

Registers the regular file name as known virtual file and appends it to the map used for fast searching. This method should be used when you need to add, for example, a new content to the project.

Arguments

  • const char * path - File path. It can be a relative, absolute, network, or virtual path.
    Notice
    If you want to specify a path to an asset, you should use the asset path format (asset://). Otherwise, if you specify the regular path to the asset, it will be treated as the path to its runtime file (if any) from the .runtimes folder.
  • bool must_exist - A flag indicating whether the specified file must exist.

Return value

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

bool renameVirtualFile ( const char * path, const char * new_path ) #

Renames the specified known virtual file.

Arguments

  • const char * path - File path. It can be a relative, absolute, network, or virtual path.
    Notice
    If you want to specify a path to an asset, you should use the asset path format (asset://). Otherwise, if you specify the regular path to the asset, it will be treated as the path to its runtime file (if any) from the .runtimes folder.
  • const char * new_path - New path for the file.

Return value

true if the file is renamed successfully; otherwise, false.

bool renameVirtualFile ( const char * path, const char * new_path, const UGUID & new_guid ) #

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

Arguments

  • const char * path - File path. It can be a relative, absolute, network, or virtual path.
    Notice
    If you want to specify a path to an asset, you should use the asset path format (asset://). Otherwise, if you specify the regular path to the asset, it will be treated as the path to its runtime file (if any) from the .runtimes folder.
  • const char * new_path - New path for the file.
  • const UGUID & new_guid - New GUID for the file.

Return value

true if the file is renamed successfully; otherwise, false.

bool renameVirtualFile ( const UGUID & guid, const char * new_path ) #

Renames the known virtual file with the given GUID.

Arguments

  • const UGUID & guid - File GUID.
  • const char * new_path - New path for the file.

Return value

true if the file is renamed successfully; otherwise, false.

bool renameVirtualFile ( const UGUID & guid, const char * new_path, const UGUID & new_guid ) #

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

Arguments

  • const UGUID & guid - File GUID.
  • const char * new_path - New path for the file.
  • const UGUID & new_guid - New GUID for the file.

Return value

true if the file is renamed successfully; otherwise, false.

bool removeVirtualFile ( const char * path ) #

Removes the virtual file with the given name.

Arguments

  • const char * path - File path. It can be a relative, absolute, network, or virtual path.
    Notice
    If you want to specify a path to an asset, you should use the asset path format (asset://). Otherwise, if you specify the regular path to the asset, it will be treated as the path to its runtime file (if any) from the .runtimes folder.

Return value

true if the file is removed successfully; otherwise, false.

bool removeVirtualFile ( const UGUID & guid ) #

Removes the virtual file with the given GUID.

Arguments

  • const UGUID & guid - GUID of the known virtual file to remove.

Return value

true if the file is removed successfully; otherwise, false.

bool changeVirtualFile ( const char * path ) #

Marks the virtual file with the given name as modified. The corresponding CALLBACK_FILE_CHANGED signal is emitted. This method is used to notify the Engine that a resource has been modified and needs to be updated.

Arguments

  • const char * path - File path. It can be a relative, absolute, network, or virtual path.
    Notice
    If you want to specify a path to an asset, you should use the asset path format (asset://). Otherwise, if you specify the regular path to the asset, it will be treated as the path to its runtime file (if any) from the .runtimes folder.

Return value

true if the file is successfully marked as modified; otherwise, false.

bool changeVirtualFile ( const UGUID & guid ) #

Marks the virtual file with the given GUID as modified. The corresponding CALLBACK_FILE_CHANGED signal is emitted. This method is used to notify the Engine that a resource has been modified and needs to be updated.

Arguments

  • const UGUID & guid - GUID of the known virtual file to remove.

Return value

true if the file is successfully marked as modified; otherwise, false.

void removeNonExistingVirtualFiles ( ) #

Removes all non-existing virtual files from the File System. These files aren't physically exist on the disk, however, they are added to the virtual file system. For example, it can be a blob or a cache file.

bool isBlobFile ( const char * path ) #

Checks if the given file is loaded to a blob.

Arguments

  • const char * path - File path. It can be a relative, absolute, network, or virtual path.
    Notice
    If you want to specify a path to an asset, you should use the asset path format (asset://). Otherwise, if you specify the regular path to the asset, it will be treated as the path to its runtime file (if any) from the .runtimes folder.

Return value

true if the file is loaded to a blob successfully; otherwise, false.

bool isBlobFile ( const UGUID & guid ) #

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

Arguments

Return value

true if the file is loaded to a blob successfully; otherwise, false.

bool addBlobFile ( const char * path ) #

Adds a file into a blob. It can be used for files that are frequently modified at 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 char * path - File path. It can be a relative, absolute, network, or virtual path.
    Notice
    If you want to specify a path to an asset, you should use the asset path format (asset://). Otherwise, if you specify the regular path to the asset, it will be treated as the path to its runtime file (if any) from the .runtimes folder.

Return value

true if the file is successfully added into a blob; otherwise, false.

bool addBlobFile ( const UGUID & guid ) #

Adds a file with the given GUID into a blob. It can be used for files that are frequently modified at 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

Return value

true if the file is successfully added into a blob; otherwise, false.

bool removeBlobFile ( const char * path ) #

Removes a file from the blob. Blobbing can be used for files that are frequently modified at 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 char * path - File path. It can be a relative, absolute, network, or virtual path.
    Notice
    If you want to specify a path to an asset, you should use the asset path format (asset://). Otherwise, if you specify the regular path to the asset, it will be treated as the path to its runtime file (if any) from the .runtimes folder.

Return value

true if the file is removed successfully; otherwise, false.

bool removeBlobFile ( const UGUID & guid ) #

Removes a file with the given GUID from the blob. Blobbing can be used for files that are frequently modified at 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

Return value

true if the file is removed successfully; otherwise, false.

bool isCacheFile ( const char * path ) #

Checks if the given file is loaded into cache.

Arguments

  • const char * path - File path. It can be a relative, absolute, network, or virtual path.
    Notice
    If you want to specify a path to an asset, you should use the asset path format (asset://). Otherwise, if you specify the regular path to the asset, it will be treated as the path to its runtime file (if any) from the .runtimes folder.

Return value

true if the file is added into cache; otherwise, false.

bool isCacheFile ( const UGUID & guid ) #

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

Arguments

Return value

true if the file is added into cache; otherwise, false.

bool addCacheFile ( const char * path ) #

Caches a file in the memory. It can be used for files that are accessed multiple times at run time (for example, textures are read two times in a row). Such files are loaded into the memory for faster reading.

Arguments

  • const char * path - File path. It can be a relative, absolute, network, or virtual path.
    Notice
    If you want to specify a path to an asset, you should use the asset path format (asset://). Otherwise, if you specify the regular path to the asset, it will be treated as the path to its runtime file (if any) from the .runtimes folder.

Return value

true if the file is successfully added to cache; otherwise, false.

bool addCacheFile ( const UGUID & guid ) #

Caches a file in the memory with the given GUID. It can be used for files that are accessed multiple times at run time (for example, textures are read two times in a row). Such files are loaded into the memory for faster reading.

Arguments

Return value

true if the file is successfully added to cache; otherwise, false.

bool removeCacheFile ( const char * path ) #

Removes a cached file from the memory. Caching can be used for files that are accessed multiple times at run time (for example, textures are read two times in a row). Such files are loaded into the memory for faster reading.

Arguments

  • const char * path - File path. It can be a relative, absolute, network, or virtual path.
    Notice
    If you want to specify a path to an asset, you should use the asset path format (asset://). Otherwise, if you specify the regular path to the asset, it will be treated as the path to its runtime file (if any) from the .runtimes folder.

Return value

true if the file is successfully removed from cache; otherwise, false.

bool 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 at run time (for example, textures are read two times in a row). Such files are loaded into the memory for faster reading.

Arguments

Return value

true if the file is successfully removed from cache; otherwise, false.

bool isDiskFile ( const char * path ) #

Returns a value indicating if the specified file path is a path to a file on disk (i.e. not a package, a blob, or a cache file).

Arguments

  • const char * path - File path. It can be a relative, absolute, network, or virtual path.
    Notice
    If you want to specify a path to an asset, you should use the asset path format (asset://). Otherwise, if you specify the regular path to the asset, it will be treated as the path to its runtime file (if any) from the .runtimes folder.

Return value

true if the specified file path is a path to a file on disk; otherwise, false.

bool isDiskFile ( const UGUID & guid ) #

Returns a value indicating if the file with the specified GUID is a file on disk.

Arguments

Return value

true if the file with the specified GUID is a file on disk; otherwise, false.

bool isPackageFile ( const char * path ) #

Returns a value indicating if the specified file path is a path to a file inside a ZIP or UNG package.

Arguments

  • const char * path - File path. It can be a relative, absolute, network, or virtual path.

Return value

true if the specified file path is a path to a file inside a ZIP or UNG package; otherwise, false.

bool isPackageFile ( const UGUID & guid ) #

Returns a value indicating if the file with the specified GUID is file inside a ZIP or UNG package.

Arguments

Return value

true if the file with the specified GUID is file inside a ZIP or UNG package; otherwise, false.

String resolvePartialVirtualPath ( const char * path ) #

Converts the given partial path to a full virtual one.
Notice
If the file isn't added to the virtual file system, the full virtual path won't be returned.
For example, if you have the data/project/image_1.tga and want to use the partial virtual path image_1.tga, you should get the full virtual path first:
Source code (C++)
// convert partial virtual to full virtual path
String full_virtual_path = FileSystem::resolvePartialVirtualPath("image_1.tga"); // project/image_1.tga is returned
// use the converted path
Image::create(full_virtual_path);

Arguments

  • const char * path - Partial path to be resolved.

Return value

Full virtual path.

String getVirtualPath ( const char * path ) #

Resolves a virtual path for the given file path. The following examples show particular cases of the method usage:
  • If the given path is known for the virtual file system, the following can be returned:
    Source code (C++)
    String s1, s2, s3, s4;
    // absolute path to the folder
    s1 = FileSystem::getVirtualPath("D:/Unigine/data");			// an empty string
    s2 = FileSystem::getVirtualPath("D:/Unigine/data/");		// an empty string
    // path to assets in the folder
    s3 = FileSystem::getVirtualPath("asset://D:/Unigine/data");	// an empty string
    s4 = FileSystem::getVirtualPath("asset://D:/Unigine/data/");// an empty string
    In all cases, an empty string is returned: a virtual path is always returned relative to the data directory, and in the example, the data directory itself is specified. If you specify a known file inside it, the corresponding virtual path will be returned:
    Source code (C++)
    String s = FileSystem::getVirtualPath("D:/Unigine/data/1.tga");		// "1.tga"
  • If the given path is unknown for the virtual file system, the following can be returned:
    Source code (C++)
    // absolute path to the folder
    s1 = FileSystem::getVirtualPath("C:/temp");			// "C:/temp"
    s2 = FileSystem::getVirtualPath("C:/temp/");		// "C:/temp"
    // path to assets in the folder
    s3 = FileSystem::getVirtualPath("asset://C:/temp");	// "C:/temp"
    s4 = FileSystem::getVirtualPath("asset://C:/temp/");// "C:/temp"
    In all cases, the normalized path to the folder is returned, as the specified folder is unknown for the virtual file system, and, therefore, no virtual path can be returned. The same is for files, for example:
    Source code (C++)
    s = FileSystem::getVirtualPath("C:/temp/1.tga");			// "C:/temp/1.tga"
  • If the given path is the path to a mounted file. Here mount_1 is the mount_1.umount mount point. Note that in the example below, the 1.tga asset has no runtime files. If an asset has a runtime file, the virtual path to this runtime file (stored in the .runtimes folder of the mount point) will be returned.
    Source code (C++)
    // virtual path to the file specified as an absolute one
    s1 = FileSystem::getVirtualPath("D:/Unigine/data/mounts/mount_1/1.tga");// "mounts/mount_1/1.tga"
    // absolute path to the file
    s2 = FileSystem::getVirtualPath("D:/extern_content/1.tga");				// "mounts/mount_1/1.tga"
    // full virtual path to the file
    s3 = FileSystem::getVirtualPath("mounts/mount_1/1.tga");				// "mounts/mount_1/1.tga"
  • If the given path is the path to a mounted file stored in the nested mount points. Here mount_1 and mount_2 are the mount_1.umount and mount_2.umount mount points correspondingly. Note that in the example below, the 1.tga asset has no runtime files. If an asset has a runtime file, the virtual path to this runtime file (stored in the .runtimes folder of the mount point) will be returned.
    Source code (C++)
    // virtual path to the file specified as an absolute one
    s1 = FileSystem::getVirtualPath("D:/Unigine/data/mounts/mount_1/mount_2/1.tga");	// "mounts/mount_1/mount_2/1.tga"
    // absolute path to the file
    s2 = FileSystem::getVirtualPath("D:/extern_content_2/1.tga");						// "mounts/mount_1/mount_2/1.tga"
    // full virtual path to the file
    s3 = FileSystem::getVirtualPath("mounts/mount_1/mount_2/1.tga");					// "mounts/mount_1/mount_2/1.tga"

Arguments

  • const char * path - File path. It can be a relative, absolute, network, or virtual path, including a path to a folder.
    Notice
    If you want to specify a path to an asset, you should use the asset path format (asset://). Otherwise, if you specify the regular path to the asset, it will be treated as the path to its runtime file (if any) from the .runtimes folder.

Return value

Virtual path to the file relative to the data folder.

String getVirtualPath ( const UGUID & guid ) #

Resolves a virtual path for the given GUID.

Arguments

Return value

Virtual path to the file relative to the data folder.

String getAbsolutePath ( const char * path ) #

Resolves an absolute path for the given file path. The following examples show particular cases of the method usage:
  • If the given path is known for the virtual file system, the following can be returned:
    Source code (C++)
    String s1, s2, s3, s4;
    // absolute path to the folder
    s1 = FileSystem::getAbsolutePath("D:/Unigine/data");			// "D:/Unigine/data"
    s2 = FileSystem::getAbsolutePath("D:/Unigine/data/");			// "D:/Unigine/data"
    // absolute path to assets in the folder
    s3 = FileSystem::getAbsolutePath("asset://D:/Unigine/data");	// "D:/Unigine/data"
    s4 = FileSystem::getAbsolutePath("asset://D:/Unigine/data/");	// "D:/Unigine/data"
  • If the given path is unknown for the virtual file system, the following can be returned:
    Source code (C++)
    // absolute path to the folder
    s1 = FileSystem::getAbsolutePath("C:/temp");				// "C:/temp"
    s2 = FileSystem::getAbsolutePath("C:/temp/");				// "C:/temp"
    // absolute path to assets in the folder
    s3 = FileSystem::getAbsolutePath("asset://C:/temp");		// "C:/temp"
    s4 = FileSystem::getAbsolutePath("asset://C:/temp/");		// "C:/temp"
  • If the given path is the path to a mounted file. Here mount_1 is the mount_1.umount mount point. Note that in the example below, the 1.tga asset has no runtime files. If an asset has a runtime file, the absolute path to this runtime file (stored in the .runtimes folder of the mount point) will be returned.
    Source code (C++)
    // virtual path specified as an absolute one
    s1 = FileSystem::getAbsolutePath("D:/Unigine/data/mounts/mount_1/1.tga");		// "D:/extern_content/1.tga"
    // absolute path
    s2 = FileSystem::getAbsolutePath("D:/extern_content/1.tga");					// "D:/extern_content/1.tga"
    // virtual path
    s3 = FileSystem::getAbsolutePath("mounts/mount_1/1.tga");						// "D:/extern_content/1.tga"
  • If the given path is the path to a mounted file stored in the nested mount points. Here mount_1 and mount_2 are the mount_1.umount and mount_2.umount mount points correspondingly. Note that in the example below, the 1.tga asset has no runtime files. If an asset has a runtime file, the absolute path to this runtime file (stored in the .runtimes folder of the mount point) will be returned.
    Source code (C++)
    // virtual path specified as an absolute one
    s1 = FileSystem::getAbsolutePath("D:/UnigineGIT/data/mounts/mount_1/mount_2/1.tga");// "D:/extern_content_2/1.tga"
    // absolute path
    s2 = FileSystem::getAbsolutePath("D:/extern_content_2/1.tga");						// "D:/extern_content_2/1.tga"
    // virtual path
    s3 = FileSystem::getAbsolutePath("mounts/mount_1/mount_2/1.tga");					// "D:/extern_content_2/1.tga"
  • If the given path is a network path:
    Source code (C++)
    s1 = FileSystem::getAbsolutePath("//studio/work/shared_content/images.zip");			// "//studio/work/shared_content/images.zip"
    s2 = FileSystem::getAbsolutePath("\\\\studio\\work\\shared_content\\images.zip");		// "//studio/work/shared_content/images.zip"

Arguments

  • const char * path - File path. It can be a relative, absolute, network, or virtual path, including a path to a folder.
    Notice
    If you want to specify a path to an asset, you should use the asset path format (asset://). Otherwise, if you specify the regular path to the asset, it will be treated as the path to its runtime file (if any) from the .runtimes folder.

Return value

Absolute path to the file.

String getAbsolutePath ( const UGUID & guid ) #

Resolves an absolute path for the given file GUID.

Arguments

Return value

Absolute path to the file.

String getPackageVirtualPath ( const char * path ) const#

Resolves a virtual path for the given path to the package.

Arguments

  • const char * path - Path to a package. It can be a relative, absolute, network, or virtual path.

Return value

Virtual path to the package.

String getPackageVirtualPath ( const UGUID & guid ) const#

Resolves a virtual path for the given GUID.

Arguments

Return value

Virtual path to the package.

String getPackageAbsolutePath ( const char * path ) const#

Resolves an absolute path for the given path to the package.

Arguments

  • const char * path - Path to a package. It can be a relative, absolute, network, or virtual path.

Return value

Absolute path to the package.

String getPackageAbsolutePath ( const UGUID & guid ) const#

Resolves an absolute path for the given package GUID.

Arguments

Return value

Absolute path to the package.

String getExtension ( const char * path ) #

Returns the extension for the given file.

Arguments

  • const char * path - File path. It can be a relative, absolute, network, or virtual path.
    Notice
    If you want to specify a path to an asset, you should use the asset path format (asset://). Otherwise, if you specify the regular path to the asset, it will be treated as the path to its runtime file (if any) from the .runtimes folder.

Return value

File extension in lower case, if any; otherwise, an empty string.

String getExtension ( const UGUID & guid ) #

Returns the extension for a file with the specified GUID.

Arguments

  • const UGUID & guid - GUID of the file for which extension is to be returned.

Return value

File extension in lower case if any; otherwise, an empty string.

bool isFileExist ( const char * path ) #

Checks if the given file actually exists on the disk.
Notice
Calling this method every frame in the main thread, especially for multiple files, may cause a performance hit. It is better to optimize such checks and move them to a separate thread.

Arguments

  • const char * path - File path. It can be a relative, absolute, network, or virtual path.
    Notice
    If you want to specify a path to an asset, you should use the asset path format (asset://). Otherwise, if you specify the regular path to the asset, it will be treated as the path to its runtime file (if any) from the .runtimes folder.

Return value

true if the file exists; otherwise, false.

bool isFileExist ( const UGUID & guid ) #

Checks if a file with the given GUID actually exists.
Notice
Calling this method every frame in the main thread, especially for multiple files, may cause a performance hit. It is better to optimize such checks and move them to a separate thread.

Arguments

Return value

true if the file exists; otherwise, false.

bool isGUIDPath ( const char * path ) #

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

Arguments

  • const char * path - Path to be checked.

Return value

true if the given path has a valid GUID path format; otherwise, false.

bool isAssetPath ( const char * path ) #

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

Arguments

  • const char * path - Path to be checked.

Return value

true if the given path has a valid asset path format; otherwise, false.

long long getMTime ( const char * path ) #

Returns the time of the last modification of the given file.
Notice
Calling this method every frame in the main thread, especially for multiple files, may cause a performance hit. It is better to optimize such checks and move them to a separate thread.

Arguments

  • const char * path - File path. It can be a relative, absolute, network, or virtual path.
    Notice
    If you want to specify a path to an asset, you should use the asset path format (asset://). Otherwise, if you specify the regular path to the asset, it will be treated as the path to its runtime file (if any) from the .runtimes folder.

Return value

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

long long getMTime ( const UGUID & guid ) #

Returns the time of the last modification of the file with the specified GUID.
Notice
Calling this method every frame in the main thread, especially for multiple files, may cause a performance hit. It is better to optimize such checks and move them to a separate thread.

Arguments

Return value

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

bool loadGUIDs ( const char * path ) #

Loads file system GUIDs from the specified file.

Arguments

  • const char * path - Path to the file, where file system GUIDs are stored.

Return value

true if file system GUIDs are loaded successfully; otherwise, false.

bool saveGUIDs ( const char * path, bool binary = false ) #

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

Arguments

  • const char * path - Path to the file, where file system GUIDs are to be stored.
  • bool binary - Binary file format flag. When the flag is set to true, the file system will save GUIDs to a binary file; otherwise, to a JSON file.

Return value

true if all file system GUIDs are saved successfully; otherwise, false.

UGUID generateGUID ( ) #

Generates a new GUID.

Return value

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

bool setGUID ( const char * path, const UGUID & guid ) #

Sets the specified GUID for the given file.

Arguments

  • const char * path - File path. It can be a relative, absolute, network, or virtual path.
    Notice
    If you want to specify a path to an asset, you should use the asset path format (asset://). Otherwise, if you specify the regular path to the asset, it will be treated as the path to its runtime file (if any) from the .runtimes folder.
  • const UGUID & guid - GUID to be set for the file.

Return value

true if the GUID is set successfully; otherwise, false.

UGUID getGUID ( const char * path ) #

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

Arguments

  • const char * path - File path. It can be a relative, absolute, network, or virtual path.
    Notice
    If you want to specify a path to an asset, you should use the asset path format (asset://). Otherwise, if you specify the regular path to the asset, it will be treated as the path to its runtime file (if any) from the .runtimes folder.

Return value

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

int getNumModifiers ( ) #

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

Return value

Number of modifiers.

String getModifier ( int num ) const#

Returns the name of the given modifier.

Arguments

  • int num - ID number of the modifier.

Return value

Modifier name.

void addModifier ( const char * name ) #

Registers a new modifier in the file system.

Arguments

  • const char * name - Modifier name.

void removeModifier ( const char * name ) #

Unregisters a given modifier in the file system.

Arguments

  • const char * name - Modifier name.

void clearModifiers ( ) #

Unregister all modifiers in the file system.

void * addCallback ( int callback, Unigine::CallbackBase1< const Vector < FilePath > & > * func ) #

Adds a callback of the specified type. Callback functions can be used to determine actions to be performed when files are added, changed, or removed. The signature of the callback function must be as follows:
Source code (C++)
void callback_function_name(const Vector < FilePath > &paths);

Arguments

Return value

ID of the last added callback of the specified type, if the callback was added successfully; otherwise, nullptr. This ID can be used to remove this callback when necessary.

void * addCallback ( int callback, Unigine::CallbackBase2< const char *, UGUID > * func ) #

Adds a callback of the specified type. Callback functions can be used to determine actions to be performed when files are added, changed, or removed. The signature of the callback function must be as follows:
Source code (C++)
void callback_function_name(const char *arg1, UGUID uguid);

Arguments

Return value

ID of the last added callback of the specified type, if the callback was added successfully; otherwise, nullptr. This ID can be used to remove this callback when necessary.

bool removeCallback ( int callback, void * id ) #

Removes the specified callback from the list of callbacks of the specified type. Callback functions can be used to determine actions to be performed when files are added, changed, or removed.

Arguments

  • int callback - Callback type. One of the CALLBACK_* variables.
  • void * id - Callback ID obtained when adding it.

Return value

True if the callback with the given ID was removed successfully; otherwise false.

void clearCallbacks ( int callback ) #

Clears all added callbacks of the specified type. Callback functions can be used to determine actions to be performed when files are added, changed, or removed.

Arguments

  • int callback - Callback type. One of the CALLBACK_* variables.
Last update: 2021-04-29
Build: ()