Jo Engine 2026.11.6
Jo Sega Saturn Engine
Loading...
Searching...
No Matches
fs.h File Reference

Jo Engine File System function prototypes. More...

Go to the source code of this file.

Macros

#define JO_ROOT_DIR
 Specify the root directory (on the CD) for jo_fs_read_file(), jo_map_load_from_file(), etc.
#define JO_CURRENT_DIR
 Specify the current directory (on the CD) for jo_fs_read_file(), jo_map_load_from_file(), etc.
#define JO_PARENT_DIR
 Specify the parent directory for jo_fs_read_file(), jo_map_load_from_file(), etc.
#define JO_CD_DRIVE_PAUSE
 Drive status: the drive is paused.
#define JO_CD_DRIVE_PLAY
 Drive status: the drive is playing (audio or data).

Typedefs

typedef void(*) jo_fs_async_read_callback(char *contents, int length, int optional_token)
 Function prototype for ().

Functions

bool jo_fs_cd (const char *const sub_dir)
 Change the current directory (equivalent of Unix cd command).
bool jo_fs_file_exists (const char *const filename)
 Check if a file is in the current directory of the CD (no error printed when it is not: an optional file).
char * jo_fs_read_file_in_dir (const char *const filename, const char *const sub_dir, int *len)
 Read a file on the CD.
char * jo_fs_read_file_ptr (const char *const filename, void *buf, int *len)
 Read a file on the CD and put the contents to "buf".
void jo_fs_get_read_stats (unsigned int *const vblanks, unsigned int *const bytes, unsigned int *const files, const bool reset)
 Statistics of the files read by jo_fs_read_file_ptr() (the time of a loading: the CD or the CPU).
static __jo_force_inline char * jo_fs_read_file (const char *const filename, int *len)
 Read a file on the CD.
bool jo_fs_read_file_async_ptr (const char *const filename, jo_fs_async_read_callback callback, int optional_token, void *buf)
 Read a file on the CD asynchronously and put the contents to "buf".
void jo_fs_wait_background_jobs (void)
 Wait for the end of the reads of jo_fs_read_file_async() (their callbacks called, the files they start too).
static __jo_force_inline bool jo_fs_read_file_async (const char *const filename, jo_fs_async_read_callback callback, int optional_token)
 Read a file on the CD asynchronously.
bool jo_fs_open (jo_file *const file, const char *const filename)
 Open a file.
void jo_fs_close (jo_file *const file)
 Close a file.
void jo_fs_set_read_sector_count (const int count)
 Set the size of the read buffer of the files opened by jo_fs_open().
int jo_fs_read_next_bytes (jo_file *const file, char *buffer, unsigned int nbytes)
 Read bytes from a file.
static __jo_force_inline bool jo_fs_read_exact (jo_file *const file, void *const buffer, const unsigned int nbytes)
 Read bytes from a file: all of them.
bool jo_fs_seek_forward (jo_file *const file, unsigned int nbytes)
 Seek forward from current position of a file.

Detailed Description

Jo Engine File System function prototypes.

Author
Johannes Fetz
Bug
No known bugs.

Macro Definition Documentation

◆ JO_CD_DRIVE_PAUSE

#define JO_CD_DRIVE_PAUSE

Drive status: the drive is paused.

◆ JO_CD_DRIVE_PLAY

#define JO_CD_DRIVE_PLAY

Drive status: the drive is playing (audio or data).

◆ JO_CURRENT_DIR

#define JO_CURRENT_DIR

Specify the current directory (on the CD) for jo_fs_read_file(), jo_map_load_from_file(), etc.

◆ JO_PARENT_DIR

#define JO_PARENT_DIR

Specify the parent directory for jo_fs_read_file(), jo_map_load_from_file(), etc.

◆ JO_ROOT_DIR

#define JO_ROOT_DIR

Specify the root directory (on the CD) for jo_fs_read_file(), jo_map_load_from_file(), etc.

Typedef Documentation

◆ jo_fs_async_read_callback

typedef void(*) jo_fs_async_read_callback(char *contents, int length, int optional_token)

Function prototype for ().

Function Documentation

◆ jo_fs_cd()

bool jo_fs_cd ( const char *const sub_dir)

Change the current directory (equivalent of Unix cd command).

Parameters
sub_dirSub directory name (use JO_PARENT_DIR for parent directory)
Returns
true if the directory is the current one, false if not found or not read (the current directory is kept)

◆ jo_fs_close()

void jo_fs_close ( jo_file *const file)

Close a file.

Parameters
filePointer to an allocated and valid jo_file struct

◆ jo_fs_file_exists()

bool jo_fs_file_exists ( const char *const filename)

Check if a file is in the current directory of the CD (no error printed when it is not: an optional file).

Parameters
filenameFile name (example: "LEVEL.BIN")
Returns
true if the file exists

◆ jo_fs_get_read_stats()

void jo_fs_get_read_stats ( unsigned int *const vblanks,
unsigned int *const bytes,
unsigned int *const files,
const bool reset )

Statistics of the files read by jo_fs_read_file_ptr() (the time of a loading: the CD or the CPU).

Parameters
vblanksTime spent reading (VBLANK count), JO_NULL: not wanted
bytesBytes read
filesFiles read
resetThe counts start again from 0

◆ jo_fs_open()

bool jo_fs_open ( jo_file *const file,
const char *const filename )

Open a file.

Parameters
filePointer to an allocated jo_file struct
filenameFilename (upper case and shorter as possible like "A.TXT")
Returns
true if succeed
Remarks
A compressed file ("JOLZ" first, see jo_fs_read_file_ptr()) is read decompressed by jo_fs_read_next_bytes() and jo_fs_seek_forward() (file->size: the size of its data; 4 KB more of memory while it is open)

◆ jo_fs_read_exact()

__jo_force_inline bool jo_fs_read_exact ( jo_file *const file,
void *const buffer,
const unsigned int nbytes )
static

Read bytes from a file: all of them.

Parameters
filePointer to an allocated and valid jo_file struct
bufferPointer to an allocated buffer (length >= nbytes)
nbytesNumber of bytes to read
Returns
false if the file ends before or if the read failed

◆ jo_fs_read_file()

__jo_force_inline char * jo_fs_read_file ( const char *const filename,
int * len )
static

Read a file on the CD.

Parameters
filenameFilename (upper case and shorter as possible like "A.TXT")
lenreturn the file length
Returns
The stream

◆ jo_fs_read_file_async()

__jo_force_inline bool jo_fs_read_file_async ( const char *const filename,
jo_fs_async_read_callback callback,
int optional_token )
static

Read a file on the CD asynchronously.

Parameters
filenameFilename (upper case and shorter as possible like "A.TXT")
callbackCallback called when the file is loaded
optional_tokenUser value to identify the file
Returns
true if succeed

◆ jo_fs_read_file_async_ptr()

bool jo_fs_read_file_async_ptr ( const char *const filename,
jo_fs_async_read_callback callback,
int optional_token,
void * buf )

Read a file on the CD asynchronously and put the contents to "buf".

Parameters
filenameFilename (upper case and shorter as possible like "A.TXT")
callbackCallback called when the file is loaded
optional_tokenUser value to identify the file
bufOutput buffer: the file length + 1 byte at least (a null character is written after the contents)
Returns
true if succeed
Remarks
A compressed file (see jo_fs_read_file_ptr()) is read as it is on the CD (not decompressed)
The frames do not wait for the drive: each one takes the sectors already read (8 at most). The music (jo_audio_play_music()) goes on: it has the drive first when its buffer needs it. The files are read one after the other

◆ jo_fs_read_file_in_dir()

char * jo_fs_read_file_in_dir ( const char *const filename,
const char *const sub_dir,
int * len )

Read a file on the CD.

Parameters
filenameFilename (upper case and shorter as possible like "A.TXT")
sub_dirSub directory name (use JO_ROOT_DIR if the file is on the root directory)
lenreturn the file length
Returns
The stream

◆ jo_fs_read_file_ptr()

char * jo_fs_read_file_ptr ( const char *const filename,
void * buf,
int * len )

Read a file on the CD and put the contents to "buf".

Parameters
filenameFilename (upper case and shorter as possible like "A.TXT")
bufOutput buffer: the file length + 1 byte at least (a null character is written after the contents)
lenreturn the file length
Returns
The stream
Remarks
A compressed file ("JOLZ" first: Compiler/COMMON/jo_lz.py -f) is read decompressed: len is the size of its data, buf must hold it (+ 1). Fewer sectors read: a file of 40 % of its size loads about 2.5 times faster (the CPU decompresses about 1 MB per second, while the drive reads the next sectors)

◆ jo_fs_read_next_bytes()

int jo_fs_read_next_bytes ( jo_file *const file,
char * buffer,
unsigned int nbytes )

Read bytes from a file.

Parameters
filePointer to an allocated and valid jo_file struct
bufferPointer to an allocated buffer (length >= nbytes)
nbytesnumber of bytes to read
Returns
Number of bytes read (<= 0 means EOF)
Remarks
The whole sectors of a big read go straight to the buffer (not through the read buffer of the file: no copy, and the DMA when the buffer is 4 bytes aligned)

◆ jo_fs_seek_forward()

bool jo_fs_seek_forward ( jo_file *const file,
unsigned int nbytes )

Seek forward from current position of a file.

Parameters
filePointer to an allocated and valid jo_file struct
nbytesnumber of bytes to skip
Returns
true if succeed

◆ jo_fs_set_read_sector_count()

void jo_fs_set_read_sector_count ( const int count)

Set the size of the read buffer of the files opened by jo_fs_open().

Parameters
countNumber of sectors (2048 bytes) read at once by jo_fs_read_next_bytes() (1 by default)
Remarks
Only the files opened after this call use the new size
A file read in many small pieces (the models of a level read one at a time): a bigger buffer calls the CD less often (16 sectors: each call of the CD reads 32 KB)

◆ jo_fs_wait_background_jobs()

void jo_fs_wait_background_jobs ( void )

Wait for the end of the reads of jo_fs_read_file_async() (their callbacks called, the files they start too).

Remarks
The music (jo_audio_play_music()) goes on meanwhile