Changeset 25416 in project

10/24/11 02:59:39 (9 years ago)

Anonymous wiki edit for IP []: More docs

1 edited


  • wiki/eggref/4/physicsfs

    r25396 r25416  
    9 == Documentation
     9== Disclaimer
    11110.1 Is an alpha, and as such not ready for widespread use. A new release is coming soon, with documentation and a test suite.
    1616The interface adheres closely to the stock PhysicsFS interface; with all but the callback requiring functions available.
     18Much thanks to Ryan C. Gordon for the original library.
     20== Overview
     22The latest version of PhysicsFS can be found at [[|]]
     25With PhysicsFS, you have a single writing directory and multiple directories (the "search path") for reading. You can think of this as a filesystem within a filesystem. If (on Windows) you were to set the writing directory to "C:\MyGame\MyWritingDirectory", then no PHYSFS calls could touch anything above this directory, including the "C:\MyGame" and "C:\" directories. This prevents an application's internal scripting language from piddling over c:\\config.sys, for example. If you'd rather give PHYSFS full access to the system's REAL file system, set the writing dir to "C:\", but that's generally A Bad Thing for several reasons.
     28Drive letters are hidden in PhysicsFS once you set up your initial paths. The search path creates a single, hierarchical directory structure. Not only does this lend itself well to general abstraction with archives, it also gives better support to operating systems like MacOS and Unix.
     31Generally speaking, you shouldn't ever hardcode a drive letter; not only does this hurt portability to non-Microsoft OSes, but it limits your win32 users to a single drive, too. Use the PhysicsFS abstraction functions and allow user-defined configuration options, too. When opening a file, you specify it like it was on a Unix filesystem: if you want to write to "C:\MyGame\MyConfigFiles\game.cfg", then you might set the write dir to "C:\MyGame" and then open "MyConfigFiles/game.cfg". This gives an abstraction across all platforms. Specifying a file in this way is termed "platform-independent notation" in this documentation. Specifying a filename in a form such as "C:\mydir\myfile" or "MacOS hard drive:My Directory:My File" is termed "platform-dependent notation". The only time you use platform-dependent notation is when setting up your write directory and search path; after that, all file access into those directories are done with platform-independent notation.
     34All files opened for writing are opened in relation to the write directory which is the root of the writable filesystem. When opening a file for reading, PhysicsFS goes through the search path. This is NOT the same thing as the PATH environment variable. An application using PhysicsFS specifies directories to be searched which may be actual directories, or archive files that contain files and subdirectories of their own. See the end of these docs for currently supported archive formats.
     37Once the search path is defined, you may open files for reading. If you've got the following search path defined (to use a win32 example again):
     39 *  C:\\mygame
     40 *  C:\\mygame\\myuserfiles
     41 *  D:\\mygamescdromdatafiles
     42 *  C:\\mygame\\
     45Then a call to physfs#openRead("textfiles/myfile.txt") (note the directory separator, lack of drive letter, and lack of dir separator at the start of the string; this is platform-independent notation) will check for
     48 *  C:\\mygame\\textfiles\\myfile.txt, then
     49 *  C:\\mygame\\myuserfiles\\textfiles\\myfile.txt, then
     50 *  D:\\mygamescdromdatafiles\\textfiles\\myfile.txt, then, finally, for
     51 *  textfiles\\myfile.txt inside of C:\\mygame\\
     54Remember that most archive types and platform filesystems store their filenames in a case-sensitive manner, so you should be careful to specify it correctly.
     57Files opened through PhysicsFS may NOT contain "." or ".." or ":" as dir elements. Not only are these meaningless on MacOS Classic and/or Unix, they are a security hole. Also, symbolic links (which can be found in some archive types and directly in the filesystem on Unix platforms) are NOT followed until you call physfs#permitSymbolicLinks. That's left to your own discretion, as following a symlink can allow for access outside the write dir and search paths. For portability, there is no mechanism for creating new symlinks in PhysicsFS.
     60The write dir is not included in the search path unless you specifically add it. While you CAN change the write dir as many times as you like, you should probably set it once and stick to it. Remember that your program will not have permission to write in every directory on Unix and NT systems.
     63All files are opened in binary mode; there is no endline conversion for textfiles. Other than that, PhysicsFS has some convenience functions for platform-independence. There is a function to tell you the current platform's dir separator ("\\" on windows, "/" on Unix, ":" on MacOS), which is needed only to set up your search/write paths. There is a function to tell you what CD-ROM drives contain accessible discs, and a function to recommend a good search path, etc.
     66A recommended order for the search path is the write dir, then the base dir, then the cdrom dir, then any archives discovered. Quake 3 does something like this, but moves the archives to the start of the search path. Build Engine games, like Duke Nukem 3D and Blood, place the archives last, and use the base dir for both searching and writing. There is a helper function physfs#setSaneConfig that puts together a basic configuration for you, based on a few parameters. Also see the comments on physfs#getBaseDir, and physfs#getUserDir for info on what those are and how they can help you determine an optimal search path.
     69PhysicsFS 2.0 adds the concept of "mounting" archives to arbitrary points in the search path. If a zipfile contains "maps/" and you mount that archive at "mods/mymod", then you would have to open "mods/mymod/maps/" to access the file, even though "mods/mymod" isn't actually specified in the .zip file. Unlike the Unix mentality of mounting a filesystem, "mods/mymod" doesn't actually have to exist when mounting the zipfile. It's a "virtual" directory. The mounting mechanism allows the developer to seperate archives in the tree and avoid trampling over files when added new archives, such as including mod support in a game...keeping external content on a tight leash in this manner can be of utmost importance to some applications.
     72PhysicsFS is mostly thread safe. The error messages returned by physfs#getLastError are unique by thread, and library-state-setting functions are mutex'd. For efficiency, individual file accesses are not locked, so you can not safely read/write/seek/close/etc the same  file from two threads at the same time. Other race conditions are bugs  that should be reported/patched.
     75While you CAN use stdio/syscall file access in a program that has physfs#* calls, doing so is not recommended, and you can not use system filehandles with PhysicsFS and vice versa.
     78Note that archives need not be named as such: if you have a ZIP file and rename it with a .PKG extension, the file will still be recognized as a ZIP archive by PhysicsFS; the file's contents are used to determine its type where possible.
     81Currently supported archive types:
     82 *    .ZIP (pkZip/WinZip/Info-ZIP compatible)
     83 *    .GRP (Build Engine groupfile archives)
     84 *    .PAK (Quake I/II archive format)
     85 *    .HOG (Descent I/II HOG file archives)
     86 *    .MVL (Descent II movielib archives)
     87 *    .WAD (DOOM engine archives)
     90String policy for PhysicsFS 2.0 and later:
     92PhysicsFS 1.0 could only deal with null-terminated ASCII strings. All high ASCII chars resulted in undefined behaviour, and there was no Unicode support at all. PhysicsFS 2.0 supports Unicode without breaking binary compatibility with the 1.0 API by using UTF-8 encoding of all strings passed in and out of the library.
     95All strings passed through PhysicsFS are in null-terminated UTF-8 format. This means that if all you care about is English (ASCII characters <= 127) then you just use regular C strings. If you care about Unicode (and you should!) then you need to figure out what your platform wants, needs, and offers. If you are on Windows and build with Unicode support, your TCHAR strings are two bytes per character (this is called "UCS-2 encoding"). You should convert them to UTF-8 before handing them to PhysicsFS with  physfs#utf8FromUcs2. If you're using Unix or Mac OS X, your wchar_t strings are four bytes per character ("UCS-4 encoding"). Use physfs#utf8FromUcs4. Mac OS X can give you UTF-8 directly from a CFString, and many Unixes generally give you C strings in UTF-8 format everywhere. If you have a single-byte high ASCII charset, like so-many European "codepages" you may be out of luck. We'll convert from "Latin1" to UTF-8 only, and never back to Latin1. If you're above ASCII 127, all bets are off: move to Unicode or use your platform's facilities. Passing a C string with high-ASCII data that isn't UTF-8 encoded will NOT do what you expect!
     98Naturally, there's also physfs#utf8ToUcs2 and physfs#utf8ToUcs4 to get data back into a format you like. Behind the scenes, PhysicsFS will use Unicode where possible: the UTF-8 strings on Windows will be converted and used with the multibyte Windows APIs, for example.
     100PhysicsFS offers basic encoding conversion support, but not a whole string library. Get your stuff into whatever format you can work with.
     103Some platforms and archivers don't offer full Unicode support behind the scenes. For example, OS/2 only offers "codepages" and the filesystem itself doesn't support multibyte encodings. We make an earnest effort to convert to/from the current locale here, but all bets are off if you want to hand an arbitrary Japanese character through to these systems. Modern OSes (Mac OS X, Linux, Windows, PocketPC, etc) should all be fine.
     106Many game-specific archivers are seriously unprepared for Unicode (the Descent HOG/MVL and Build Engine GRP archivers, for example, only offer a DOS 8.3 filename, for example). Nothing can be done for these, but they tend to be legacy formats for existing content that was all ASCII (and thus, valid UTF-8) anyhow. Other formats, like .ZIP, don't explicitly offer Unicode support, but unofficially expect filenames to be UTF-8 encoded, and thus Just Work. Most everything does the right thing without bothering you, but it's good to be aware of these nuances in case they don't.
     109== Definitions
     111; physfs#File : A PhysicsFS file handle.
     113You get a pointer to one of these when you open a file for reading, writing, or appending via PhysicsFS.
     115As you can see from the lack of meaningful fields, you should treat this as opaque data. Don't try to manipulate the file handle, just pass the  pointer you got, unmolested, to various PhysicsFS APIs.
     118; physfs#ArchiveInfo : Information on various PhysicsFS-supported archives.
     120This structure gives you details on what sort of archives are supported by this implementation of PhysicsFS. Archives tend to be things like ZIP files and such.
     123; PHYSFS_Version : Information the version of PhysicsFS in use.
     125Represents the library's version as three levels: major revision (increments with massive changes, additions, and enhancements), minor revision (increments with backwards-compatible changes to the major revision), and patchlevel (increments with fixes to the minor revision).
    18127== Author
Note: See TracChangeset for help on using the changeset viewer.