Carltonus/0ad
1
0
Fork 0
forked from 0ad/0ad
Code Pull Requests Activity

add cppdoc (and fix a warning in ogl_shader)

Browse Source 
This was SVN commit r6204.
This commit is contained in:
janwas 2008-07-05 18:46:12 +00:00
parent de60ef26bd
commit 1de82c5efe
5 changed files with 179 additions and 77 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

108
source/lib/file/vfs/vfs.h
View File

@ -16,23 +16,6 @@
#include "lib/file/path.h"
#include "lib/file/vfs/vfs_path.h"
// VFS paths are of the form: "(dir/)*file?"
// in English: '/' as path separator; trailing '/' required for dir names;
// no leading '/', since "" is the root dir.
// there is no restriction on path length; when dimensioning character
// arrays, prefer PATH_MAX.
// pathnames are case-insensitive.
// implementation:
// when mounting, we get the exact filenames as reported by the OS;
// we allow open requests with mixed case to match those,
// but still use the correct case when passing to other libraries
// (e.g. the actual open() syscall).
// rationale:
// necessary, because some exporters output .EXT uppercase extensions
// and it's unreasonable to expect that users will always get it right.
namespace ERR
{
const LibError VFS_DIR_NOT_FOUND = -110100;
@ -43,13 +26,16 @@ namespace ERR
// (recursive mounting and mounting archives are no longer optional since they don't hurt)
enum VfsMountFlags
{
// all real directories mounted during this operation will be watched
// for changes. this flag is provided to avoid watches in output-only
// directories, e.g. screenshots/ (only causes unnecessary overhead).
/**
* all real directories mounted during this operation will be watched
* for changes. this flag is provided to avoid watches in output-only
* directories, e.g. screenshots/ (only causes unnecessary overhead).
**/
VFS_MOUNT_WATCH = 1,
// anything mounted from here should be added to archive when
// building via vfs_optimizer.
/**
* anything mounted from here should be included when building archives.
**/
VFS_MOUNT_ARCHIVABLE = 2
};
@ -60,6 +46,7 @@ struct IVFS
*
* @param mountPoint (will be created if it does not already exist)
* @param path real directory path
* @return LibError.
*
* if files are encountered that already exist in the VFS (sub)directories,
* the most recent / highest priority/precedence version is preferred.
@ -69,37 +56,82 @@ struct IVFS
**/
virtual LibError Mount(const VfsPath& mountPoint, const Path& path, int flags = 0, size_t priority = 0) = 0;
/**
* retrieve information about a file (similar to POSIX stat)
*
* @return LibError.
**/
virtual LibError GetFileInfo(const VfsPath& pathname, FileInfo* pfileInfo) const = 0;
// note: this interface avoids having to lock a directory while an
// iterator is extant.
// (don't split this into 2 functions because POSIX can't implement
// that efficiently)
/**
* retrieve lists of all files and subdirectories in a directory.
*
* @return LibError.
*
* rationale:
* - this interface avoids having to lock the directory while an
* iterator is extant.
* - we cannot efficiently provide routines for returning files and
* subdirectories separately due to the underlying POSIX interface.
**/
virtual LibError GetDirectoryEntries(const VfsPath& path, FileInfos* files, DirectoryNames* subdirectoryNames) const = 0;
// note: only allowing either reads or writes simplifies file cache
// coherency (need only invalidate when closing a FILE_WRITE file).
/**
* create a file with the given contents.
*
* @param size [bytes] of the contents, will match that of the file.
* @return LibError.
*
* rationale: disallowing partial writes simplifies file cache coherency
* (need only be invalidated when closing a FILE_WRITE file).
**/
virtual LibError CreateFile(const VfsPath& pathname, shared_ptr<u8> fileContents, size_t size) = 0;
// read the entire file.
// return number of bytes transferred (see above), or a negative error code.
//
// if non-NULL, <cb> is called for each block transferred, passing <cbData>.
// it returns how much data was actually transferred, or a negative error
// code (in which case we abort the transfer and return that value).
// the callback mechanism is useful for user progress notification or
// processing data while waiting for the next I/O to complete
// (quasi-parallel, without the complexity of threads).
/**
* read an entire file into memory.
*
* @param fileContents receives a smart pointer to the contents.
* CAVEAT: this will be taken from the file cache if the VFS was
* created with cacheSize != 0 and size < cacheSize. there is no
* provision for Copy-on-Write, which means that such buffers
* must not be modified (this is enforced via mprotect).
* @param size receives the size [bytes] of the file contents.
* @return LibError.
**/
virtual LibError LoadFile(const VfsPath& pathname, shared_ptr<u8>& fileContents, size_t& size) = 0;
/**
* dump a text representation of the filesystem to debug output.
**/
virtual void Display() const = 0;
/**
* empty the contents of the filesystem.
*
* the effect is as if nothing had been mounted.
**/
virtual void Clear() = 0;
/**
* retrieve the real (POSIX) path underlying a VFS file.
*
* this is useful when passing paths to external libraries.
**/
virtual LibError GetRealPath(const VfsPath& pathname, Path& path) = 0;
};
typedef shared_ptr<IVFS> PIVFS;
/**
* create an instance of a Virtual File System.
*
* @param cacheSize size [bytes] of memory to reserve for a file cache,
* or zero to disable it. if small enough to fit, file contents are
* stored here until no references remain and they are evicted.
*
* note: there is no limitation to a single instance, it may make sense
* to create and destroy VFS instances during each unit test.
**/
LIB_API PIVFS CreateVfs(size_t cacheSize);
#endif // #ifndef INCLUDED_VFS

20
source/lib/file/vfs/vfs_path.h
View File

@ -2,6 +2,21 @@
#define INCLUDED_VFS_PATH
struct VfsPathTraits;
/**
* VFS path of the form "(dir/)*file?"
*
* in other words: the root directory is "" and paths are separated by '/'.
* a trailing slash is allowed for directory names.
* rationale: it is important to avoid a leading slash because that might be
* confused with an absolute POSIX path.
*
* there is no restriction on path length; when dimensioning character
* arrays, prefer PATH_MAX.
*
* rationale: a distinct specialization of basic_path prevents inadvertent
* assignment from other path types.
**/
typedef fs::basic_path<std::string, VfsPathTraits> VfsPath;
typedef std::vector<VfsPath> VfsPaths;
@ -33,6 +48,11 @@ namespace boost
}
}
/**
* Does a path appear to refer to a directory? (non-authoritative)
*
* note: only used as a safeguard.
**/
extern bool vfs_path_IsDirectory(const VfsPath& pathname);
#endif // #ifndef INCLUDED_VFS_PATH

2
source/lib/res/graphics/ogl_shader.cpp
View File

@ -115,7 +115,7 @@ static LibError Ogl_Shader_reload(Ogl_Shader* shdr, const VfsPath& pathname, Han
{
const GLchar* strings[] = { (const GLchar*)file.get() };
const GLint tmp = file_size;
const GLint tmp = (GLint)file_size;
pglShaderSourceARB(shdr->id, 1, strings, &tmp);
pglCompileShaderARB(shdr->id);
}

50
source/lib/res/graphics/ogl_shader.h
View File

@ -32,16 +32,23 @@ NOTE: Only use functions form this module after verifying that the required
extensions are available, or all bets are off.
*/
// Create, load and compile a shader object of the given type
// (e.g. GL_VERTEX_SHADER_ARB). The given file will be used as
// source code for the shader.
/**
* Create, load and compile a shader object.
*
* @param pathname location of the file containing the shader's source code.
* @param type e.g. GL_VERTEX_SHADER_ARB.
**/
Handle ogl_shader_load(const VfsPath& pathname, GLenum type);
// Free all resources associated with the given handle (subject
// to refcounting).
/**
* Free all resources associated with the given handle
* (subject to reference counting).
**/
void ogl_shader_free(Handle& h);
// Attach a shader to the given OpenGL program.
/**
* Attach a shader to the given OpenGL program.
**/
LibError ogl_shader_attach(GLhandleARB program, Handle& h);
@ -49,21 +56,36 @@ LibError ogl_shader_attach(GLhandleARB program, Handle& h);
Encapsulate program objects into handles.
*/
// Load a program object based on the given XML file description.
// Shader objects are loaded and attached automatically.
Handle ogl_program_load(const char* fn);
/**
* Load a program object.
*
* @param pathname XML file describing the program.
*
* note: Shader objects are loaded and attached automatically.
**/
Handle ogl_program_load(const char* pathname);
// Free all resources associated with the given program handle.
/**
* Free all resources associated with the given program handle.
* (subject to reference counting).
**/
void ogl_program_free(Handle& h);
// Activate the program (glUseProgramObjectARB).
// h may be 0, in which case program objects are disabled.
/**
* Activate the program (glUseProgramObjectARB).
*
* @param h may be 0, in which case program objects are disabled.
**/
LibError ogl_program_use(Handle h);
// Query uniform information
/**
* Query uniform information
**/
GLint ogl_program_get_uniform_location(Handle h, const char* name);
// Query vertex attribute information
/**
* Query vertex attribute information
**/
GLint ogl_program_get_attrib_location(Handle h, const char* name);
#endif // INCLUDED_OGL_SHADER

76
source/lib/res/graphics/unifont.h
View File

@ -13,45 +13,73 @@
#include "lib/res/handle.h"
// Load and return a handle to the font defined
// in fn+".fnt" with texture fn+".tga"
/**
* Load a font.
*
* @param pathname path and basename of the font definition file
* (.fnt) and its texture (.tga)
**/
extern Handle unifont_load(const VfsPath& pathname, int flags = 0);
// Release a handle to a previously loaded font
/**
* Release a handle to a previously loaded font
* (subject to reference counting).
**/
extern LibError unifont_unload(Handle& h);
// Use the font referenced by h for all subsequent glwprintf() calls.
// Must be called before any glwprintf().
/**
* Use a font for all subsequent glwprintf() calls.
*
* Must be called before any glwprintf().
**/
extern LibError unifont_bind(Handle h);
// Output text at current OpenGL modelview pos.
extern void glvwprintf(const wchar_t* fmt, va_list args);
/**
* Output text at current OpenGL modelview pos.
*
* @param fmt - see fprintf
*
* this assumes an environment roughly like:
* glEnable(GL_TEXTURE_2D);
* glDisable(GL_CULL_FACE);
* glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA);
* glEnable(GL_BLEND);
* glDisable(GL_ALPHA_TEST);
* glTexEnvi(GL_TEXTURE_ENV, GL_TEXTURE_ENV_MODE, GL_MODULATE);
**/
extern void glwprintf(const wchar_t* fmt, ...);
/*
glwprintf assumes an environment roughly like:
/**
* varargs version of glwprintf.
*
* @param fmt, args - see vfprintf
**/
extern void glvwprintf(const wchar_t* fmt, va_list args);
glEnable(GL_TEXTURE_2D);
glDisable(GL_CULL_FACE);
glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA);
glEnable(GL_BLEND);
glDisable(GL_ALPHA_TEST);
glTexEnvi(GL_TEXTURE_ENV, GL_TEXTURE_ENV_MODE, GL_MODULATE);
*/
// Intended for the GUI (hence Unicode). 'height' is roughly the height of
// a capital letter, for use when aligning text in an aesthetically pleasing way.
/**
* Determine pixel extents of a string.
*
* @param text string in question.
* @param height is roughly the pixel height of a capital letter, for use
* when aligning text in an aesthetically pleasing way.
*
* note: This is intended for the GUI (hence Unicode).
**/
LibError unifont_stringsize(const Handle h, const wchar_t* text, int& width, int& height);
// Get only the height
/**
* @return height [pixels] of the font.
**/
int unifont_height(const Handle h);
// Get only the width of one character
/**
* @return width [pixels] of a certain character.
**/
int unifont_character_width(const Handle h, wchar_t c);
// Return spacing in pixels from one line of text to the next
/**
* @return spacing in pixels from one line of text to the next.
**/
int unifont_linespacing(const Handle h);
#endif // INCLUDED_UNIFONT