Documentation
[SDK Documentation] [CGapiVFS]

 

GapiDraw Classes CGapiSurface CGapiRGBASurface CGapiDraw CGapiDisplay CGapiMaskSurface CGapiBitmapFont CGapiCursor CGapiApplication CGapiInput CGapiVFS CGapiTimer CGapiGradient

CGapiVFS

Overview

GapiVFS is a virtual file system to store images, sound files and other data files needed by the application. Files can be stored in folders and subfolders, and can be selectively compressed using zip-compression.

You create VFS archives using the included VFSEdit application which is shown in the picture below.

VFSEdit

This document has been updated for use with GapiDraw 4.0 or later.
Last updated on October 5, 2008.

 

CGapiVFS::CreateVFS

Creates a virtual file system from a file or resource.

HRESULT CreateVFS(const _TCHAR* filename);
Parameters
dwResourceID
The resource ID of the first VFS resource segment.
filename
The name of the file you want to use as a virtual file system.
Return values

If this method succeeds, the return value is GD_OK.

If the method fails, the return value may be one of the following return values:

GDERR_INVALIDPARAMS
GDERR_INVALIDVFSFILE
GDERR_OUTOFMEMORY
GDERR_UNEXPECTEDENDOFVFS
GDERR_VFSNOTFOUND
GDERR_WRONGVFSVERSION

Remarks

You create files containing a virtual file system with the tool VFSEdit, which is included with the GapiDraw distribution in the folder "misc\VFSEdit". Files stored in the virtual file system can be individually compressed with zip compression, and will be automatically decompressed when loaded.

If you use a relative file position as a filename, CreateVFS will try to open the file relative to the current folder, not the folder in which your executable file is located.

CGapiVFS::FreeVFS

Closes the virtual file system and frees all allocated memory.

HRESULT FreeVFS();
Parameters
None
Return values

If this method succeeds, the return value is GD_OK.

If the method fails, the return value may be one of the following return values:

GDERR_OPENVFSFILES

Remarks

CGapiVFS::FreeVFS is automatically called in the CGapiVFS destructor. If the file system had opened files, CGapiVFS::FreeVFS will still close the virtual file system but will return GDERR_OPENVFSFILES.

CGapiFileBuffer::Open

Opens a file from the virtual file system, decompresses it, and stores the expanded file in a new memory buffer.

virtual HRESULT Open(CGapiVFS* pVFS, const _TCHAR* pFilename);
Parameters
pVFS
A pointer to the CGapiVFS virtual file system instance.
pFilename
The name of the file to be opened from the virtual file system.
Return values

If this method succeeds, the return value is GD_OK.

If the method fails, the return value may be one of the following return values:

GDERR_CORRUPTFILE
GDERR_FILENOTFOUND
GDERR_INVALIDPARAMS
GDERR_OUTOFMEMORY
GDERR_VFSNOTOPEN

Remarks

The pFilename string must start with a slash, '/', otherwise CGapiFileBuffer::Open will return GDERR_FILENOTFOUND. Also, use '/' to specify folders, such as '/myrootfolder/mysubfolder/myfile.bmp'.

CGapiFileBuffer::Close

Closes the file buffer and frees all allocated memory.

virtual void Close();
Parameters
None
Return values

None

Remarks

CGapiFileBuffer::Close is automatically called in the CGapiFileBuffer destructor.

CGapiFileBuffer::GetFileInfo

Returns information on the CGapiFileBuffer.

virtual HRESULT GetFileInfo(VFILEINFO* pFileinfo);
Parameters
pFileinfo
A pointer to a VFILEINFO structure that will contain information on the file such as size and zip-compression.
 
Return values

If this method succeeds, the return value is GD_OK.

If the method fails, the return value may be one of the following return values:

GDERR_FILENOTOPEN
GDERR_INVALIDPARAMS

CGapiFileBuffer::GetBuffer

Used to retrieve a pointer to CGapiFileBuffer's internal memory buffer.

HRESULT GetBuffer(GAPIFILEBUFFER* pFileBuffer);
Parameters
pFileBuffer
A pointer to a GAPIFILEBUFFER structure that will contain information on the memory buffer.
Return values

If this method succeeds, the return value is GD_OK.

If the method fails, the return value may be one of the following return values:

GDERR_FILENOTOPEN
GDERR_INVALIDPARAMS

Remarks

Do not attempt to manually free the memory buffer allocated by CGapiFileBuffer, instead call CGapiFileBuffer::Close to free the memory.

CGapiFileStream::Open

Opens a file from the virtual file system and prepares it for streaming.

virtual HRESULT Open(CGapiVFS* pVFS, const _TCHAR* pFilename);
Parameters
pVFS
A pointer to the CGapiVFS virtual file system instance.
pFilename
The name of the file to be opened from the virtual file system.
Return values

If this method succeeds, the return value is GD_OK.

If the method fails, the return value may be one of the following return values:

GDERR_CORRUPTFILE
GDERR_FILENOTFOUND
GDERR_INVALIDPARAMS
GDERR_OUTOFMEMORY
GDERR_VFSNOTOPEN

Remarks

The file path must start with a slash, '/', otherwise CGapiFileBuffer::Open will return GDERR_FILENOTFOUND. Relative search paths within the virtual file system is not allowed. Also, use '/' to specify folders, such as '/myrootfolder/mysubfolder/myfile.bmp'.

If the file is compressed it will be decompressed in real time when CGapiFileStream::Read is called.

CGapiFileStream::Close

Closes the file stream and frees the memory allocated for real-time decompression.

virtual void Close();
Parameters
None
Return values

None

Remarks

CGapiFileStream::Close is automatically called in the CGapiFileStream destructor.

CGapiFileStream::GetFileInfo

Returns information on the CGapiFileStream.

virtual HRESULT GetFileInfo(VFILEINFO* pFileinfo);
Parameters
pFileinfo
A pointer to a VFILEINFO structure that will contain information on the file such as size and zip-compression.
 
Return values

If this method succeeds, the return value is GD_OK.

If the method fails, the return value may be one of the following return values:

GDERR_FILENOTOPEN
GDERR_INVALIDPARAMS

CGapiFileStream::IsEOF

Checks to see if the file stream has reached the end of file.

BOOL IsEOF();
Parameters
None
Return values

Returns TRUE if the internal file offset equals the size of the file.

CGapiFileStream::Read

Reads a number of bytes from the file, automatically decompressing the data if necessary.

HRESULT Read(void* pBuffer, DWORD* pdwCount);
Parameters
pBuffer
A pointer to a memory buffer which will contain the data. The size of pBuffer must be large enough to store pdwCount bytes.
pdwCount
A pointer to a DWORD containing the number of bytes to be read. After CGapiFileStream::Read returns, pdwCount will contain the number of bytes that was actually read from the file.
Return values

If this method succeeds, the return value is GD_OK.

If the method fails, the return value may be one of the following return values:

GDERR_CORRUPTFILE
GDERR_FILENOTOPEN
GDERR_INVALIDPARAMS
GDERR_INVALIDZLIBVERSION
GDERR_OUTOFMEMORY

CGapiFileStream::Reset

Resets the position of the file to the start position.

HRESULT Reset();
Parameters
None
Return values

If this method succeeds, the return value is GD_OK.

If the method fails, the return value may be one of the following return values:

GDERR_CORRUPTFILE
GDERR_FILENOTOPEN
GDERR_INVALIDPARAMS
GDERR_INVALIDZLIBVERSION
GDERR_OUTOFMEMORY

CGapiFileStream::Seek

Changes the current position in the file.

HRESULT Seek(DWORD dwOffset);
Parameters
dwOffset
The file offset in bytes where to change the current location.
Return values

If this method succeeds, the return value is GD_OK.

If the method fails, the return value may be one of the following return values:

GDERR_CORRUPTFILE
GDERR_FILENOTOPEN
GDERR_INVALIDZLIBVERSION
GDERR_OUTOFMEMORY

CGapiFileStream::Tell

Returns the current offset in the file.

DWORD Tell();
Parameters
None
Return values

Returns the current file offset.