To quote the official site of SFML,
SFML provides a simple interface to the various components of your PC, to ease the development of games and multimedia applications.
Indeed, SFML is most often used to make video games. It provides features such as hardware-accelerated 2D graphics, handling keyboard, mouse and gamepad input, vector and matrix manipulation, managing windows (can also be used as a base for OpenGL drawing), working with multiple image formats, audio playback and recording, basic networking... Check out some demos of CrSFML to see what it can do.
First, install SFML.
Then create a shard.yml file in your project's folder (or add to it) with the following contents:
name: awesome-game version: 0.1.0 dependencies: crsfml: github: oprypin/crsfml version: ~> 2.5.2
Resolve dependencies with Shards:
During installation this will invoke
make to build the C++ wrappers as object files. If that fails, see Custom SFML location.
Try running an example:
cp lib/crsfml/examples/snakes.cr . crystal snakes.cr
Now you're ready for the tutorials!
Crystal does not officially support Windows, but CrSFML supports it and is perfectly usable already. See a video detailing the full setup.
The C++ wrappers require a C++ compiler (C++03 will do).
SFML must be installed, with the version that matches
SFML_VERSION in src/version.cr (usually latest). If it doesn't, no need to look for an older release of CrSFML, just re-generate the sources for your version. SFML versions 2.3.x through 2.5.x are supported by CrSFML.
There are detailed official instructions on how to install SFML manually, but on many systems there are easier ways.
If SFML is not installed in a global/default location, see Custom SFML location.
Many Linux-based systems provide SFML through their package manager. Make sure to install the -dev packages if there is such a separation in your Linux distribution of choice.
Note that most often the packages provided by Linux distributions are outdated. If you're installing an older version of SFML (not recommended), make sure that it's still supported by CrSFML. You will need to re-generate the sources.
The easiest way to install SFML on macOS is through the Homebrew package manager:
brew update brew install sfml
It can also be installed by copying binaries, as described in official instructions.
Building SFML from source is as simple as downloading the source code and running:
cmake . cmake --build . sudo make install # optional!
In some cases the dependencies are bundled with SFML, otherwise see the official build instructions.
Custom SFML location
If SFML's headers and libraries are not in a path where the compiler would look by default (and the defaults usually work only on Linux), additional steps are needed.
First, before building the extensions (
make) or generating sources, you need to configure the include path:
Setting these variables beforehand can also fix
Then, whenever using CrSFML, you need to configure the path to SFML libraries so the linker can find them. To apply these for the current shell session, run:
export LIBRARY_PATH=/full/path/to/sfml/lib # Used during linking export LD_LIBRARY_PATH=/full/path/to/sfml/lib # Used when running an executable
set LIB=c:\path\to\sfml\lib;%LIB% set PATH=c:\path\to\sfml\bin;%PATH%
CrSFML's top-level scripts also need the include path to work. E.g.
crystal generate.cr -- /full/path/to/sfml/include.
CrSFML's sources come almost entirely from a generator program. They are based on a particular version of SFML. But as sources for the latest version are already bundled, usually you don't need to do this. More details.
git clone https://github.com/oprypin/crsfml cd crsfml
Then we can generate the sources, either directly with
crystal generate.cr or as part of the build process:
touch generate.cr make
If run successfully, this generates all the source files and also compiles the C++ wrapper.
CrSFML without Shards
It's also possible to use CrSFML outside of Shards, as with any library. One option is to directly create a symbolic link to CrSFML in your project's lib folder.
mkdir lib ln -s /full/path/to/crsfml lib/crsfml
Another option is to
export CRYSTAL_PATH=/full/path/to a directory that contains the crsfml directory.
CrSFML as bindings to SFML
API differences between SFML and CrSFML
The API of CrSFML (a library for Crystal) attempts to be similar to SFML (a C++ library), but some general changes are present:
- Methods are renamed to
- Getter, setter methods are changed:
x.some_property = v.
- Structs in Crystal are always passed by copy, so modifying them can be problematic. For example,
my_struct.x = 7is fine but
array_of_structs.x = 5will not work. To work around this, copy the whole struct, modify it, then write it back. Better yet, avoid the need to modify structs (work with them like with immutable objects).
- Member functions, such as
loadFromFile, that are used for initialization, each have a corresponding shorthand class method (
from_file) that raises
- SFML sometimes uses enum values as bitmasks. You can combine them using the
- enum members are exposed at class level, so instead of
SF::Keyboard::Code::Slashyou can use
- SFML sometimes requires that an instance must remain alive as long as it is attached to the object. For example, a textured shape will cause errors if the texture object is destroyed. CrSFML prevents this problem by keeping a reference to the object.
EventTypeenum are represented as a class hierarchy. Instead of
ev.type == SF::Event::Resizeduse
ev.is_a?(SF::Event::Resized); instead of
- Instead of subclassing
Drawable, include the
Drawablemodule with an abstract
- Most of the API documentation is taken directly from SFML, so don't be surprised if it talks in C++ terms.
The C++ wrapper
The interface of the C++ → C wrapper (which Crystal ultimately binds to) consists entirely of simple functions that accept only native types (such as
char*) and untyped pointers (
void*). The untyped pointers are never exposed to the user, only to other auto-generated parts of the code. The function names consist of the original SFML class name, the function name itself, and a base62 hash of the parameter types. Return types are never used; instead, the output is done into a pointer (which is usually the last argument of the function), but, as usual, the memory allocation is the caller's job. The first argument of each function is a pointer to the receiver object (if applicable).
Abstract classes are implemented by exposing a collection of global callback variables, which must be set by the user if they want to use the corresponding class. The callback's first argument is the object, and some arguments are pointers that need to be assigned to inside the callback implementation (because return values are not used).
Compilation of the C++ extensions is based only on SFML's header files, these are made into object files, and all the linking is deferred to the final linker invocation done by Crystal.
Why not CSFML?
CSFML is a great library that allows SFML to be used with C. It goes to great lengths to be human-friendly and does a good job of converting C++ idioms to C idioms. In the past CrSFML used to be based on it, but after a while it became apparent that the advantages of CSFML's nice interface are also disadvantages when constructing (especially auto-generated) bindings that attempt to look as close to the real SFML as possible.
Many details about functions' signatures are lost, as well as function overloads. Names of data types had to be simplified (not namespaced). And many other such small things that bring the frustration of having to reconstruct the details of the original SFML interface based on the simplified CSFML interface.
There are many aspects that prevent an efficient implementation from the standpoint of bindings, most importantly, CSFML takes memory allocation into its own hands, so any object creation in CrSFML involved allocation of two objects on the heap by two different libraries, and every interaction with it had to go through at least two pointers. Structs in CSFML are actually completely separate data types and they have to be constantly be converted between a "SFML-struct" and a "CSFML-struct".
Instead of that, the C++ → C wrapper passes the bare SFML data types directly through untyped pointers, and relies on the higher-level binding to deal safely with them. In case of structs the data layout is mirrored, in case of classes the pointers remain completely opaque.
Not to forget that the wrapper is made automatically, so it can be quickly updated to any SFML release and prevents human error that could happen when implementing CSFML.
CrSFML was made by Oleh Prypin.
CrSFML is licensed under the terms and conditions of the zlib/libpng license.
This library uses and is based on SFML.