vfs.h File Reference

Contains the Virtual File System (VFS), which sits atop the packaging layer and OS file I/O layer. More...

#include "assets/kasset_types.h"
#include "defines.h"
#include "strings/kname.h"

Go to the source code of this file.

Data Structures
struct	vfs_config
struct	vfs_asset_data
	Represents data and properties from an asset loaded from the VFS. More...
struct	vfs_state
struct	vfs_request_info
	The request options for getting an asset from the VFS. More...

Typedefs
typedef struct vfs_config	vfs_config
typedef enum vfs_asset_flag_bits	vfs_asset_flag_bits
typedef u32	vfs_asset_flags
typedef enum vfs_request_result	vfs_request_result
typedef struct vfs_asset_data	vfs_asset_data
	Represents data and properties from an asset loaded from the VFS. More...
typedef void(*	PFN_on_asset_loaded_callback) (struct vfs_state *vfs, vfs_asset_data asset_data)
typedef struct vfs_state	vfs_state
typedef struct vfs_request_info	vfs_request_info
	The request options for getting an asset from the VFS. More...

Enumerations
enum	vfs_asset_flag_bits { VFS_ASSET_FLAG_NONE = 0 , VFS_ASSET_FLAG_BINARY_BIT = 0x01 }
enum	vfs_request_result {   VFS_REQUEST_RESULT_SUCCESS = 0 , VFS_REQUEST_RESULT_FILE_DOES_NOT_EXIST , VFS_REQUEST_RESULT_NOT_IN_PACKAGE , VFS_REQUEST_RESULT_PACKAGE_DOES_NOT_EXIST ,   VFS_REQUEST_RESULT_READ_ERROR , VFS_REQUEST_RESULT_WRITE_ERROR , VFS_REQUEST_RESULT_INTERNAL_FAILURE }

Functions
KAPI b8	vfs_initialize (u64 *memory_requirement, vfs_state *out_state, const vfs_config *config)
	Initializes the Virtual File System (VFS). Call twice; once to get memory requirement (passing out_state = 0) and a second time passing allocated block of memory to out_state. More...
KAPI void	vfs_shutdown (vfs_state *state)
	Shuts down the VFS. More...
KAPI void	vfs_request_asset (vfs_state *state, vfs_request_info info)
	Requests an asset from the VFS, issuing the callback when complete. This call is asynchronous. More...
KAPI vfs_asset_data	vfs_request_asset_sync (vfs_state *state, vfs_request_info info)
	Requests an asset from the VFS synchronously. NOTE: This should be used sparingly as it performs device I/O directly. NOTE: Caller should also check out_data context to see if it needs freeing, as this is not handled automatically as it is in the async version. More...
KAPI const char *	vfs_path_for_asset (vfs_state *state, kname package_name, kname asset_name)
	Attempts to retrieve the path for the given asset, if it exists. More...
KAPI const char *	vfs_source_path_for_asset (vfs_state *state, kname package_name, kname asset_name)
	Attempts to retrieve the source path for the given asset, if one exists. More...
KAPI void	vfs_request_direct_from_disk (vfs_state *state, const char *path, b8 is_binary, u32 context_size, const void *context, PFN_on_asset_loaded_callback callback)
	Requests an asset directly a disk path via the VFS, issuing the callback when complete. This call is asynchronous. More...
KAPI void	vfs_request_direct_from_disk_sync (vfs_state *state, const char *path, b8 is_binary, u32 context_size, const void *context, vfs_asset_data *out_data)
	Requests an asset directly a disk path via the VFS synchronously. NOTE: This should be used sparingly as it performs device I/O directly. NOTE: Caller should also check out_data context to see if it needs freeing, as this is not handled automatically as it is in the async version. More...
KAPI b8	vfs_asset_write_binary (vfs_state *state, kname asset_name, kname package_name, u64 size, const void *data)
	Attempts to write the provided binary data to the VFS (or package). More...
KAPI b8	vfs_asset_write_text (vfs_state *state, kname asset_name, kname package_name, const char *text)
	Attempts to write the provided text data to the VFS (or package). More...
KAPI void	vfs_asset_data_cleanup (vfs_asset_data *data)
	Releases resources held by data. NOTE: This does NOT account for any dynamic allocations made within said context! More...

Detailed Description

Contains the Virtual File System (VFS), which sits atop the packaging layer and OS file I/O layer.

Author

Travis Vroman (travi.nosp@m.s@ko.nosp@m.hieng.nosp@m.ine..nosp@m.com)

Version

1.0

Date

2024-07-31

Copyright

Kohi Game Engine is Copyright (c) Travis Vroman 2021-2024

Typedef Documentation

PFN_on_asset_loaded_callback

typedef void(* PFN_on_asset_loaded_callback) (struct vfs_state *vfs, vfs_asset_data asset_data)

vfs_asset_data

typedef struct vfs_asset_data vfs_asset_data

Represents data and properties from an asset loaded from the VFS.

vfs_asset_flag_bits

typedef enum vfs_asset_flag_bits vfs_asset_flag_bits

vfs_asset_flags

typedef u32 vfs_asset_flags

vfs_config

typedef struct vfs_config vfs_config

vfs_request_info

typedef struct vfs_request_info vfs_request_info

The request options for getting an asset from the VFS.

vfs_request_result

typedef enum vfs_request_result vfs_request_result

vfs_state

typedef struct vfs_state vfs_state

Enumeration Type Documentation

vfs_asset_flag_bits

enum vfs_asset_flag_bits

Enumerator
VFS_ASSET_FLAG_NONE
VFS_ASSET_FLAG_BINARY_BIT

vfs_request_result

enum vfs_request_result

Enumerator
VFS_REQUEST_RESULT_SUCCESS	The request was fulfilled successfully.
VFS_REQUEST_RESULT_FILE_DOES_NOT_EXIST	The asset exists on the manifest, but the primary file could not be found on disk.
VFS_REQUEST_RESULT_NOT_IN_PACKAGE	The package does not contain the asset
VFS_REQUEST_RESULT_PACKAGE_DOES_NOT_EXIST	Package does not exist.
VFS_REQUEST_RESULT_READ_ERROR	There was an error reading from the file.
VFS_REQUEST_RESULT_WRITE_ERROR	There was an error writing to the file.
VFS_REQUEST_RESULT_INTERNAL_FAILURE	An internal failure has occurred in the VFS itself.

Function Documentation

vfs_asset_data_cleanup()

KAPI void vfs_asset_data_cleanup

(

vfs_asset_data *

data

)

Releases resources held by data. NOTE: This does NOT account for any dynamic allocations made within said context!

Parameters

data	A pointer to the VFS data to be released.

vfs_asset_write_binary()

KAPI b8 vfs_asset_write_binary	(	vfs_state *	state,
		kname	asset_name,
		kname	package_name,
		u64	size,
		const void *	data
	)

Attempts to write the provided binary data to the VFS (or package).

Parameters

state	A pointer to the system state. Required.
asset_name	The name of the asset to be written within the given package.
package_name	The name of the package to write the data into.
size	The size of the data to be written.
data	A constant pointer to the block of data to be written.

Returns

True on success; otherwise false.

vfs_asset_write_text()

KAPI b8 vfs_asset_write_text	(	vfs_state *	state,
		kname	asset_name,
		kname	package_name,
		const char *	text
	)

Attempts to write the provided text data to the VFS (or package).

Parameters

state	A pointer to the system state. Required.
asset_name	The name of the asset to be written within the given package.
package_name	The name of the package to write the data into.
size	The size of the data to be written.
data	A constant pointer to the block of data to be written.

Returns

True on success; otherwise false.

vfs_initialize()

KAPI b8 vfs_initialize	(	u64 *	memory_requirement,
		vfs_state *	out_state,
		const vfs_config *	config
	)

Initializes the Virtual File System (VFS). Call twice; once to get memory requirement (passing out_state = 0) and a second time passing allocated block of memory to out_state.

Parameters

memory_requirement	A pointer to hold the memory requirement. Required.
out_state	If gathering the memory requirement, pass 0. Otherwise pass the allocated block of memory to use as the system state.
config	A pointer to the config. Required unless only getting memory requirement.

Returns

True on success; otherwise false.

vfs_path_for_asset()

KAPI const char* vfs_path_for_asset	(	vfs_state *	state,
		kname	package_name,
		kname	asset_name
	)

Attempts to retrieve the path for the given asset, if it exists.

Parameters

state	A pointer to the system state. Required.
package_name	The package name to request from.
asset_name	The name of the asset to request.

Returns

The path for the asset, if it exists. Otherwise 0/null.

vfs_request_asset()

KAPI void vfs_request_asset	(	vfs_state *	state,
		vfs_request_info	info
	)

Requests an asset from the VFS, issuing the callback when complete. This call is asynchronous.

Parameters

state	A pointer to the system state. Required.
info	The information detailing specifics about the VFS asset request.
callback	The callback to be made once the asset load is complete. Required.

vfs_request_asset_sync()

KAPI vfs_asset_data vfs_request_asset_sync	(	vfs_state *	state,
		vfs_request_info	info
	)

Requests an asset from the VFS synchronously. NOTE: This should be used sparingly as it performs device I/O directly. NOTE: Caller should also check out_data context to see if it needs freeing, as this is not handled automatically as it is in the async version.

Parameters

state	A pointer to the system state. Required.
info	The information detailing specifics about the VFS asset request.
out_data	A pointer to hold the loaded asset data. Required.

vfs_request_direct_from_disk()

KAPI void vfs_request_direct_from_disk	(	vfs_state *	state,
		const char *	path,
		b8	is_binary,
		u32	context_size,
		const void *	context,
		PFN_on_asset_loaded_callback	callback
	)

Requests an asset directly a disk path via the VFS, issuing the callback when complete. This call is asynchronous.

Parameters

state	A pointer to the system state. Required.
path	The path to the file to load (can be relative or absolute). Required.
is_binary	Indicates if the asset is binary. Otherwise is loaded as text.
context_size	The size of the context in bytes.
context	A pointer to the context to be used for this call. This is passed through to the result callback. NOTE: A copy of this is taken immediately, so lifetime of this isn't important.
callback	The callback to be made once the asset load is complete. Required.

vfs_request_direct_from_disk_sync()

KAPI void vfs_request_direct_from_disk_sync	(	vfs_state *	state,
		const char *	path,
		b8	is_binary,
		u32	context_size,
		const void *	context,
		vfs_asset_data *	out_data
	)

Requests an asset directly a disk path via the VFS synchronously. NOTE: This should be used sparingly as it performs device I/O directly. NOTE: Caller should also check out_data context to see if it needs freeing, as this is not handled automatically as it is in the async version.

Parameters

state	A pointer to the system state. Required.
path	The path to the file to load (can be relative or absolute). Required.
is_binary	Indicates if the asset is binary. Otherwise is loaded as text.
context_size	The size of the context in bytes.
context	A pointer to the context to be used for this call. This is passed through to the result callback. NOTE: A copy of this is taken immediately, so lifetime of this isn't important.
out_data	A pointer to hold the loaded asset data. Required.

vfs_shutdown()

KAPI void vfs_shutdown

(

vfs_state *

state

)

Shuts down the VFS.

Parameters

state

A pointer to the system state.

vfs_source_path_for_asset()

KAPI const char* vfs_source_path_for_asset	(	vfs_state *	state,
		kname	package_name,
		kname	asset_name
	)

Attempts to retrieve the source path for the given asset, if one exists.

Parameters

state	A pointer to the system state. Required.
package_name	The package name to request from.
asset_name	The name of the asset to request.

Returns

The source path for the asset, if it exists. Otherwise 0/null.