PhysicsFS/PhysFS++ Tutorial

This is a follow-up from a promise that I made in my tutorial video on designing an asset manager using SFML. That video can be found here.

This tutorial is centred around PhysFS++, a C++ wrapper for PhysicsFS. For the sake of the tutorial, it’s assumed that the reader is familiar with PhysicsFS and what it’s capable of. Described here is a workflow for simple use of the library. Anything more discrete is beyond the scope and will have to be ascertained by the reader on their own accord.

Lastly of note, PhysFS++ encapsulates PhysicsFS calls in a PhysFS namespace. The functions are global within this namespace and there are only a few classes that are provided. PhysFS++ further encapsulates key PhysicsFS constructs, notably those corresponding to archived files, into said classes that are derivatives of STL stream classes (a huge boon).

Like some other libraries, PhysicsFS requires explicit initialisation before it can be used. This is facilitated by a function named init. It takes one argument of type const char* and is semantically directed at a terminal invocation argument triaged through the much loved argv. However, this can be an empty string especially if you’re not expecting to handle terminal invocations. Thus, a very general call to init can be performed as such:

PhysFS::init (nullptr);

Right of the bat we have to mention a caveat here. From PhysFS++, there’s no way to assert the initialisation process of PhysicsFS. This is counter-intuitive to the upstream library which relies on the tried-and-true zero on failure, non-zero on success return values as sanity checks. Furthermore, while PhysFS++ implements C++ exceptions, the init function doesn’t throw any at all. Ostensibly, what one is left with is an unchecked call to init. Because one needs to compile PhysFS++ from the source, it is possible to modify the code, as I have done, to add a check to this call.

Once init has successfully completed, the next step is to mount an archive file into the virtual filesystem created by init. This is performed with the mount function. mount expects three arguments: the archive file on disk, a string specifying a mount point in the virtual filesystem, and a boolean which appends the mount point to the search path. One should place the archive file in the working directory for the binary file of their executable so PhysFS++ can see it. The second argument can be an empty string which would force root mounting, and the third can be true. Thus, for our example, if we assume we have an archive file named funphotos.zip on our disk in the binary’s working directory, we can issue a call to mount as such:

PhysFS::mount (“funphotos.zip”, “”, 1);

Unfortunately, as was the case with init, mount wraps an upstream function that adheres to the zero-or-nonzero return value paradigm that is outright dropped by PhysFS++ with no exception catering otherwise. Thus, if mount fails to mount the archive for whatever reason, it’ll be a little difficult to ascertain why; plan accordingly.

Assuming mount has returned properly, one can start to work with the files that are contained in the archive. At this point, you should begin working in the mentality of filesystem calls. It’s possible to have archive files with complex directory layouts which would require one to perform recursive searches. That being said, everything should be considered a file – even a directory. An analysis of the PhysicsFS and PhysFS++ APIs will provide for you the full breadth of your available capabilities so for the sake of brevity, only a select number of those will be touched here.

Enumeration of files in a directory can be performed with the enumerateFiles function. It takes as an argument a string which indicates the directory to use as a root for the enumeration. As a return it provides the caller with a vector of strings indicating the name of the file. For ease of use, a call to this to enumerate the files in root can be performed as such:

auto rootfiles = PhysFs::enumerateFiles (“/”);

To actually work with a file in the filesystem, one needs to use the PHYSFS_file ADT. This upstream ADT is encapsulated by one of three classes: PhysFS::ifstream, PhysFS::ostream, or PhysFS::fstream. Each of these is fantastic in that they encapsulate a PHYSFS_file ADT in a standard stream which means that one can now perform established stream operations on the file itself. Each class has its own use: fstream for reading files, ostream for writing to files, and ifstream for bidirectional file handling. In any case, any of these classes can be instantiated with a string argument that contains a fully qualified pathname to a file in the virtual filesystem that one wants to work with. For example, given that our virtual filesystem has a file named goofycats.png located at the path /textures/cats, we could instantiate a read file as such:

PhysFS::fstream gc (“/textures/cats/goofycats.png”);

Again, the underlying upstream call to open the file goes unchecked.

What you do from here is largely subjective relative to your program’s context. Say, for example (and this is actually pretty specific to my own use case), that you have a series of files of various formats in an archive that are being used in a video game program. The multimedia library you’re using should have ADTs that represent types of assets such as textures, fonts, etc. One could do some work to transpose the raw data of these streams into the aforementioned ADTs for use in the multimedia library. The following snippet of code, borrowed from one of my own projects, illustrates this. A PhysFS::fstream instance named f is created with a certain file. Following up is a char array named d is instantiated with the size of f. The read function of f is called to transpose the bytes from f into d. Then, d is used to instantiate an instance of sf::Music from SFML contained in a std::unordered_map:

code

This covers most the basic and general needs of users of PhysicsFS. Should you require anything else from it, you’d do well to read up on the Doxygen file of PhysicsFS or the source for PhysFS++. Lastly, when one is done with the library, you’ll need to call a deinitialization function called deinit:

PhysFS::deinit ();

Clicky Game – Development Journal 0001

Because I have no life, and because I really suck at having good ideas, the concept of Clicky Game was born.

Now ordinarily I wouldn’t bat two shits at this thing after having written something like that, but I wanted to use this as an opportunity to really dig deep back into C++ and use some of the features in C++11. I just want an excuse to use lambdas liberally. 🙂

I’m doing a few interesting things with this project. First of all, I’m writing it in Visual Studio. Yes, I know, blasphemy. The reason for this though is because my new job throws me into a DevOps-type position where I’m going to have to be writing code for integration into an ERP Package we use. Unfortunately they only provide an API in C# and since we’re a majority Microsoft Shop, I need a MSVS Primer. This would be it.

Sticking with the badassery that is MSVS, I’m trying out Team Foundation Server for VCS. This is drastically different from my traditional use of Git. So far, I hate it. It’s OVERKILL for a single dev such that it’s almost not quite suitable for a single dev. But we’re going to stick with it.

So far, I’ve had two solid days of coding (about 12 hours a day) and I’ve gotten into this interesting area where I’m very heavily extending the SFML Framework that I’m using for the major library. It’s actually a really good library. It’s just missing a lot of things that I need. For example, there is no native construct for handling 2D animation. I find this to be a little odd since it’s primarily a 2D library. But that’s sort of cool since it lets your roll your own implementation. It also doesn’t have any native constructs for UI. This leaves me in a bit of a predicament since there’s no real solid UI library that integrates with SFML (guichan is strictly for SDL/Allegro) so now my current task has been to create a bit of a library that does this.

Doing all of this seemingly extra work is actually pretty cool since I’m able to use modern coding features like named lambdas for event handling (by use of std::function wrapper for class member). As another challenge, all allocations are dynamic keeping as little overhead on the stack as possible. So far, this seems to have a tremendous performance benefit but, as you could imagine, it’s requiring A LOT of double checking for things like new/delete pairing, reference/dereference members for appropriate address/value access syntax, test assertions on members prior to use in expressions even in places where it may be safe to assume that the memory should be successfully allocated and the respective member instantiated, thread safety, cross-member asset access, etc… A lot of really interesting technical hurdles.

I think I’m going to do a little bit of a piece on this for the next installment of “Something with Greg” which is shaping up to be the programmer episode.

Projekt Vagabond Isn’t Dead. I Swear.

I’m starting to get back to a point where I can start working on this thing again and it’s like flipping through a kindergarten yearbook. Every now and then I’ll find something that makes me think I had a stroke of genius. Other times it’s like seeing a photo of that one kid you hated more than bees. Like you’d prefer taking nails hammered into your ears than listen to that twat for a single second more than you had to.

Tonight I had more of the latter instead of the former.

This thing has taken several forms starting out as a PoC Bash Script that was around sometime shortly before Ohio Linux Fest 2014 to a full-blown 15,000+ line C++ program which would have worked but I didn’t realize how insanely asinine packaging software has to be (I don’t have that kind of time, especially these days). But then I had the bright idea to simply make a Vagrant Box (I was already using Vagrant in the backend for handling a lot of things) and just distribute that instead of all this rigmarole. Funny thing here is that there are still quite a few snags.

As I’m typing this, the box is uploading to a cloud store that I’ll make available to the public tomorrow. I ran into some problems during this process.

  • I wanted to be a somewhat normal person and upload the Box to Atlas, HashiCorps repository of Base Boxes. I thought that would have been a great way to make this available to people. But nope! I don’t know if there’s a size restriction on the Box size or what but it just wouldn’t take it. FYI – the Box is about 780MB in size. The goal here is that someone would have simply been able to issue “vagrant up gregfmartin/vagabond” and get the VM. Man that would have been nice…
  • Google pisses me off to no end these days. Tonight was no exception. It still blows my mind that I can’t update or configure an Android SDK Installation from the terminal without either (A) getting bitched at for some ridiculous reason or (B) having to press ‘yes’ to accept fifty licenses for these libraries instead of just being able to use an option that will opt-in to any license requests that would come up. The former makes it literally impossible to automate an installation. Some people on GitHub have described a work around for this but it’s really hacky and I’m a little concerned about the platform portability of solutions like those so I’m avoiding them like the flu.
  • This all lead to my idea of just making the Box and distributing the Box that I’ve manually tweaked. This has issues in and of itself in that (A) the bundled software is static unless the user wants to manually update or (B) wait for me to to update and republish an updated Box (which I REALLY don’t want to do if I’m being honest). This leads into supplementary tutorial material that will be on the project’s website.

In case anyone is wondering, the reason why the Box is so huge is because it contains a fully updated Ubuntu 14.02 64-bit base image, required prerequisite software to use the Android SDK and associate tools/IDE, the Android SDK installation with all 5.0.1 components as well as all Support Libraries that are compatible with Linux (important to note), and the recent version of IntelliJ Community Edition. So yeah, it’s a little fat. That’s the size it would be on your disk anyway.

Tomorrow I’ll get all of the stuff up on the website like documentation and how to do things with it and what you can expect by using it as well.

Something tells me I’m going to have to make some changes to this before too long. 🙂

Starting the SFML Journey with Fedora

I am a Fedora Fanboy. I love the distro. I will always recommend it to everyone. Despite that love, it seems like we have to cater our minds to how Fedora wants to do things. And believe me, it does things very differently when compared against Debian or any of its common derivatives. One major point of contention early on was getting used to how differently Apache works on Fedora opposed to Ubuntu. I actually prefer using Apache deployed on Ubuntu than I do Fedora. I fucking hate administering Apache on Fedora systems.

That being said, I wanted to take a few moments to discuss my adventure with SFML (Simple and Fast Multimedia Library) on Fedora from getting it installed, setting it up and actually compiling a simple source file with it.

First of all, I’m diving into SFML because there’s a project that I’ve been piecing together for a while and I think SFML fits the bill nicely based solely on research and reading the API. It also allows me to take a break from Java development and step back into C++ which is my favourite language. I feel all warm and fuzzy writing in it. I’ve always had 100% success getting SFML setup and configured on Windows computers with Visual Studio 2012. The obvious problems there are (A) I have to use a Windows computer (it’s bad enough that I’m surrounded by them at work and my laptop has Windows 7) and (B) while Visual Studio may be really pretty, I’ve never jived with how you have to use the GUI to configure all of the esoteric settings for the compiler and linker; it just feels clunky. I’d much rather type it out on the terminal or use a makefile.

Furthermore, as a bit of a primer, SFML is a multipurpose library for creating programs that need audio, graphics, networking or GUI resources in a cross-platform way using C++. The obvious use is video games but it can be applied to other types of programs as well.

Installation

Typically, when installing software libraries on Linux, you just hope and pray (if that’s your thing) that somewhere in your repositories that a pre-configured package exists for them. We shudder at the alternative method which is manually compiling and installing. I do anyway. So I was overwhelmingly pleased to see that the default repositories on Fedora did in fact have packages for SFML (SFML and SFML-devel). Cool!

First Attempt

For shits and giggles, I copied the source code that’s given on the SFML tutorial site and attempted to compile it (not link). I get my first ding.

#include <SFML/Graphics.hpp> not found

Fuck. Right off the bat, g++ can’t find a critical header that’s needed for the source to compile. So I did some digging. Knowing that library headers are typically under /usr/include, that’s where I started at. What a surprise! The headers got installed in a directory tree that went like this:

/usr/include/SFML-2.0/SFML/<blah-blah-blah>

Well that’s not going to work at all. So I moved the SFML directory out to /usr/include and removed the SFML-2.0 directory. Compilation success!

What About Linking?

This is usually the step where things get hairy when they go wrong. After getting a successful compile with an object file, I tried to link based on the steps in the tutorial.

g++ <file>.o -o <file> -lsfml-system -lsfml-window -lsfml-graphics

Result? ld can’t find any of the sfml-* libraries! Fan-fucking-tastic!

So there were a few things going on here that could have been causing the particular problem. First of all, I’m using a 64-bit version of Fedora. All libraries that are automatically installed by Yum, unless specified otherwise, will install the 64-bit version of the library. These files go under /usr/lib64. Some people have said that they’ll find them under /usr/local/lib64 but on my Fedora system they were under the former. It’s best to find out before you go rooting around and changing shit.

Second of all, ld wasn’t looking in /usr/lib64 for libraries. You can find out where ld is looking for libraries by looking at the /etc/ld.so.conf file. Although not entirely proper, I simply tacked the path to the end of the file and wrote it out. Once you do that, you need to run ldconfig (as root) to enforce the changes. If this step weren’t done, you’d have to keep linking with -L<path-to-library>/lib every time.

Lastly, even after all of that, my linking attempts were still failing. The reason this time? Name mismatches! That’s right the damn names of the libraries were wrong. The tutorial tells you to link to -lsfml-window. By default, I should have linked to -lsfml-window-2.0. Fucking bullshit. That went for any of the SFML shared object files. So I renamed those symlinks and took out the “-2.0” at the end so that -lsfml-window would work.

The End

After all that, I finally got a successful build of a demo SFML program and got the green circle in a 200×200 window. Why I had to go through all that trouble to get the trivial tutorial program to compile is beyond me but now that it’s working, I can move forward with my deeply laid plans to make shit happen.

Developer’s Notes 0001 – Revisiting Box2D (Start)

This is an excerpt taken from my OneNote page regarding Box2D. If anything, it shows that I took a lengthy hiatus from this library and I wanted to get back into using it. However I hit the same wall I hit before which was determining a sane pixel-to-meter scalar which is required for a proper implementation. Also, it clearly outlines that I’m not a physicist in any way and that I write in a very wordy manner.

 

Something that I’ve always had trouble with regarding the usage of this library is the scalar for pixels-to-meters. The official notes from the library developer state that it’s really dependent upon the game as to what value this scalar should be. However that response always struck me as odd; why should this value be so volatile as to not have some standard that works for a majority of cases so that you can at least get started using it? I always thought there would have to be some common expression of this scalar that could be applied to any rigid body in a simulation unit. As it turns out, there may be one although I’ve only been able to catch glimpses of it here and there on the internet.

One site in particular, run by an Italian ActionScript developer, makes a claim of an “unwritten rule” that 1m is equivalent to roughly 30px. (http://www.emanueleferonato.com/2008/11/17/understanding-pixels-and-meters-with-box2d-and-how-to-select-an-object-with-mouse-part-2/) I have seen this claim on a few other fringe sites that have appeared in the recesses of Google searches however there has been nothing that has substantiated this claim by any leading developers or physicists who use this library for simulation purposes.

The core of the issue stems from the units that Box2D uses to express rigid bodies. Relying on the MKS (meter-kilometer-second) system, a 1/1 ratio between meter and pixel doesn’t exist. Knowing that the conversion factor of a meter to a foot is 1/3.28, if a 1/1 ratio between pixels and meters existed, a 320px X 64px image would be 320m X 64m (1049.6ft X 209.92ft) which would most likely not translate to a real-world object that we would want to exist in the simulation.  Furthermore, the force that would need to be applied to that body to get it to move, assuming it were a non-static body, would be immense.

There is a small paragraph on the official wiki for Box2D which is effectively a FAQ. One of the questions is as follows:

Image

There are a few things to take into consideration while reading this example:

  • The scalar chosen in the example (0.01) appears to be entirely arbitrary. There is no real rhyme or reason as to why it was used instead of another arbitrary scalar like 0.25.
  • The scalar is applied not only to the dimensions of the sprite (measured 100px X 100px thus making its rigid body representation 1m X 1m (100 * 0.01)), but also to the coordinate system as well in order to accurately reflect the body’s relative location. In the example, the sprite starts at Pixel Coordinates (345, 679). To Box2D, and based on the chosen scalar, it would actually be located at (3.45, 6.79) as a result of ((345 * 0.01), (679 * 0.01)). Upon moving, the sprite is then located at (2.31, 4.98) in Box2D Coordinates. The translation to Pixel Coordinates requires the inverse operation of the scalar applied ((2.31 / 0.01), (4.98 / 0.01)) which would place the sprite at (231, 498) in Pixel Coordinates.
  • The example clearly does not state or even remotely lean to an “unwritten rule” that would be indicative of the 1m/30px ratio. Instead it leaves it up to the reader’s interpretation as to what the scalar should be.

Clearly there will have to be some investigation as to what would work well. The information that I’ve been able to find here should be sufficient enough to get started with a simulation to play with.