|
| 1 | +#  |
| 2 | + |
| 3 | +#### [Crystal][] bindings to [Simple and Fast Multimedia Library][sfml]. |
| 4 | + |
| 5 | +Documentation |
| 6 | +------------- |
| 7 | + |
| 8 | +#### [Introduction](#introduction) |
| 9 | +#### [Installation](#installation) |
| 10 | +#### [Tutorials][] |
| 11 | +#### [API Documentation][] |
| 12 | +#### [Examples](examples) / [Demos][] |
| 13 | + |
| 14 | + |
| 15 | +Introduction |
| 16 | +------------ |
| 17 | + |
| 18 | +**Note to existing users**: *CrSFML* has been recently rewritten from scratch. See the [release notes][releases] for information. |
| 19 | + |
| 20 | +*CrSFML* is a library that allows SFML to be used with the Crystal programming language. [SFML][] is a library written in C++, so *CrSFML* also needs to ship C bindings to SFML, called *VoidCSFML*. |
| 21 | + |
| 22 | +To quote the official site of SFML, |
| 23 | + |
| 24 | +> SFML provides a simple interface to the various components of your PC, to ease the development of games and multimedia applications. |
| 25 | +
|
| 26 | +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. |
| 27 | + |
| 28 | +*CrSFML* consists almost entirely of automatically generated code, based on SFML's header files. The *dev* git branch contains the [generator program](generate.cr) and the small manually written source files. The generated source code can be viewed at the [sources][] branch. |
| 29 | + |
| 30 | +### Differences between SFML and CrSFML |
| 31 | + |
| 32 | +The API of *CrSFML* (a library for Crystal) attempts to be similar to SFML (a C++ library), but some general changes are present: |
| 33 | + |
| 34 | +- Methods are renamed to `snake_case`. |
| 35 | +- Getter, setter methods are changed: |
| 36 | + - `x.getSomeProperty()` becomes `x.some_property`. |
| 37 | + - `x.isSomeProperty()`, `x.hasSomeProperty()` become `x.some_property?`. |
| 38 | + - `x.setSomeProperty(v)` becomes `x.some_property = v`. |
| 39 | +- Structs in Crystal are are always passed by copy, so modifying them can be problematic. For example, `my_struct.x = 7` is fine but `array_of_structs[2].x = 5` will 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). |
| 40 | +- Member functions, such as `loadFromFile`, that are used for initialization, each have a corresponding shorthand class method (`from_file`) that raises `SF::InitError` on failure. |
| 41 | +- SFML sometimes uses *enum* values as bitmasks. You can combine them using the `|` operator. |
| 42 | +- *enum* members are exposed at class level, so instead of `SF::Keyboard::Code::Slash` you can use `SF::Keyboard::Slash`. |
| 43 | +- 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. |
| 44 | +- The `Event` *union* and `EventType` *enum* are represented as a class hierarchy. Instead of `ev.type == SF::Event::Resized` use `ev.is_a?(SF::Event::Resized)`; instead of `ev.size.width` use `ev.width`. |
| 45 | +- Instead of subclassing `Drawable`, include the `Drawable` module with an abstract `draw` method. |
| 46 | +- Most of the [documentation](http://blaxpirit.github.io/crsfml/api/) is taken directly from SFML, so don't be surprised if it talks in C++ terms. |
| 47 | + |
| 48 | + |
| 49 | +Installation |
| 50 | +------------ |
| 51 | + |
| 52 | +This section defines two sets of step-by-step instructions to install *CrSFML* but these are not the only ways to do it; they can even be mixed (see [VoidCSFML installation instructions](voidcsfml/README.md#installation) for an alternative look) |
| 53 | + |
| 54 | +- [Approach 1](#approach-1): Generate latest *CrSFML* and *VoidCSFML* source code "from scratch"; build and use them from a local directory |
| 55 | + - Advantages: |
| 56 | + - The bindings can be fine-tuned to your system. |
| 57 | + - Should support any SFML 2.3.x, maybe even other versions. |
| 58 | + - This is the right setup if you wish to contribute to *CrSFML*. |
| 59 | + - Disadvantages: |
| 60 | + - Need to always provide full path to *VoidCSFML* libraries when running a program using *CrSFML*. |
| 61 | + - Can't install *CrSFML* directly though [shards][]. |
| 62 | +- [Approach 2](#approach-2): Use pre-compiled sources; build *VoidCSFML* and install it globally; install a release of *CrSFML* through [shards][] |
| 63 | + - Advantages: |
| 64 | + - Easier installation. |
| 65 | + - Disadvantages: |
| 66 | + - Tied to a particular version of SFML. |
| 67 | + - Although sizes of SFML objects seem to always be of equal or smaller sizes than on Linux 64-bit (where the sources are generated), this is not completely guaranteed. So, in case of a mismatch, data may be written outside of the memory region allocated for an object. |
| 68 | + |
| 69 | +### Install SFML |
| 70 | + |
| 71 | +The first step is to install the [SFML][] library itself. There are detailed [official instructions][sfml-install] on how to install it manually, however, on many systems there are easier ways. |
| 72 | + |
| 73 | +#### Linux |
| 74 | + |
| 75 | +Linux-based systems known to provide SFML 2.3.2 through their package manager: Ubuntu 16.04, Arch Linux, Fedora. Note that if you're installing an older version of SFML, it is not guaranteed to work (in fact, installation with [Approach 2](#approach-2) is almost guaranteed **not** to work). |
| 76 | + |
| 77 | +For information on building SFML from source, check out [this article][sfml-install-linux] (but no need to install CSFML). It is as simple as downloading the source code and running: |
| 78 | + |
| 79 | +```bash |
| 80 | +cmake . && make && sudo make install |
| 81 | +``` |
| 82 | + |
| 83 | +#### Mac |
| 84 | + |
| 85 | +The easiest way to install SFML on macOS is through the [Homebrew][] package manager: |
| 86 | + |
| 87 | +```bash |
| 88 | +brew update |
| 89 | +brew install sfml |
| 90 | +``` |
| 91 | + |
| 92 | +It can also be installed by copying binaries, as described in [official instructions][sfml-install], or by building from source in the same way as on [Linux](#linux). |
| 93 | + |
| 94 | + |
| 95 | +### Approach 1 |
| 96 | + |
| 97 | +Prerequisites: [Git][], [CMake][], [Crystal][], a C++ compiler |
| 98 | + |
| 99 | +#### [Install SFML](#install-sfml) |
| 100 | + |
| 101 | +#### Download latest generator source code |
| 102 | + |
| 103 | +```bash |
| 104 | +git clone -b dev https://github.com/blaxpirit/crsfml |
| 105 | +cd crsfml |
| 106 | +``` |
| 107 | + |
| 108 | +#### Build CrSFML |
| 109 | + |
| 110 | +```bash |
| 111 | +cmake . && make |
| 112 | +``` |
| 113 | + |
| 114 | +**Optional:** [out-of-source builds][] are also supported, but note that even the sources go to the build directory, so you need perform all the following steps inside the build directory and not the root *crsfml* directory. |
| 115 | + |
| 116 | +If ran successfully, this generates all the source files for *VoidCSFML* and *CrSFML*, and also compiles *VoidCSFML*. |
| 117 | + |
| 118 | +If SFML can't be found, make sure it is installed and consult the [CMake options](voidcsfml/README.md#cmake-options) section. |
| 119 | + |
| 120 | +#### Configure the path to VoidCSFML libraries |
| 121 | + |
| 122 | +The *voidcsfml/lib* folder contains the dynamic libraries that are needed to run any *CrSFML* program. So you need to configure the full path to them whenever you work with *CrSFML* so the linker can find them. To apply these for the current shell session, run: |
| 123 | + |
| 124 | +```bash |
| 125 | +export LIBRARY_PATH=/full/path/to/crsfml/voidcsfml/lib |
| 126 | +export LD_LIBRARY_PATH="$LIBRARY_PATH" |
| 127 | + |
| 128 | +# Try running an example: |
| 129 | +cd examples |
| 130 | +crystal snakes.cr |
| 131 | +``` |
| 132 | + |
| 133 | +#### Make CrSFML available to your project |
| 134 | + |
| 135 | +Create a symbolic link to *CrSFML* in your project's *libs* folder. |
| 136 | + |
| 137 | +```bash |
| 138 | +cd ~/my-project |
| 139 | +mkdir libs |
| 140 | +ln -s /full/path/to/crsfml/src libs/crsfml |
| 141 | + |
| 142 | +# Try importing it: |
| 143 | +echo 'require "crsfml"' >> my_project.cr |
| 144 | +crystal my_project.cr |
| 145 | +``` |
| 146 | + |
| 147 | +### Approach 2 |
| 148 | + |
| 149 | +Prerequisites: [CMake][], [Crystal][], a C++ compiler |
| 150 | + |
| 151 | +#### [Install SFML](#install-sfml) |
| 152 | + |
| 153 | +#### Download a release of CrSFML |
| 154 | + |
| 155 | +Find the release of *CrSFML* that corresponds to your installed version of *SFML* (latest is strongly recommended) at the [releases][] page. |
| 156 | + |
| 157 | +Download and extract it, and remember the version of the release (let's say v1.2.3) for later. |
| 158 | + |
| 159 | +#### Install VoidCSFML |
| 160 | + |
| 161 | +Go to the *voidcsfml* subfolder, build *VoidCSFML* and install it globally: |
| 162 | + |
| 163 | +```bash |
| 164 | +cd voidcsfml |
| 165 | +cmake . && make && sudo make install |
| 166 | +``` |
| 167 | + |
| 168 | +This should put the headers in */usr/local/include* and the libs in */usr/local/lib*. |
| 169 | + |
| 170 | +If SFML can't be found, make sure it is installed and consult the [CMake options](voidcsfml/README.md#cmake-options) section. |
| 171 | + |
| 172 | +#### Install a release of CrSFML |
| 173 | + |
| 174 | +Create a shard.yml file in your project's folder (or add to it) with the following contents: |
| 175 | + |
| 176 | +```yaml |
| 177 | +name: awesome-game |
| 178 | + |
| 179 | +dependencies: |
| 180 | + crsfml: |
| 181 | + github: BlaXpirit/crsfml |
| 182 | + version: 1.2.3 |
| 183 | +``` |
| 184 | +
|
| 185 | +(Replace *1.2.3* with the actual version of *CrSFML* that you downloaded earlier.) |
| 186 | +
|
| 187 | +Resolve dependencies with [shards][]: |
| 188 | +
|
| 189 | +```bash |
| 190 | +crystal deps |
| 191 | + |
| 192 | +# Try importing it: |
| 193 | +echo 'require "crsfml"' >> awesome_game.cr |
| 194 | +crystal awesome_game.cr |
| 195 | +``` |
| 196 | + |
| 197 | + |
| 198 | +Credits |
| 199 | +------- |
| 200 | + |
| 201 | +*CrSFML* was made by [Oleh Prypin][blaxpirit]. |
| 202 | + |
| 203 | +*CrSFML* is [licensed](LICENSE) under the terms and conditions of the *zlib/libpng* license. |
| 204 | + |
| 205 | +This library uses and is based on [SFML][sfml-authors]. |
| 206 | + |
| 207 | +Thanks to [Alan Willms][alanwillms] for translating [tutorials][] to Crystal. |
| 208 | + |
| 209 | + |
| 210 | +[tutorials]: http://blaxpirit.github.io/crsfml/tutorials/ |
| 211 | +[api documentation]: http://blaxpirit.github.io/crsfml/api/ |
| 212 | +[releases]: https://github.com/blaxpirit/crsfml/releases |
| 213 | +[demos]: https://github.com/blaxpirit/crsfml-examples |
| 214 | +[sources]: https://github.com/blaxpirit/crsfml/tree/sources |
| 215 | + |
| 216 | +[sfml]: http://www.sfml-dev.org/ "Simple and Fast Multimedia Library" |
| 217 | +[csfml]: http://www.sfml-dev.org/download/csfml/ |
| 218 | +[sfml-authors]: https://github.com/SFML/SFML#readme |
| 219 | +[sfml-install]: http://www.sfml-dev.org/tutorials/ |
| 220 | +[sfml-install-linux]: http://blaxpirit.com/blog/12/build-sfml-and-csfml-on-linux.html |
| 221 | + |
| 222 | +[cmake]: https://cmake.org/ |
| 223 | +[out-of-source builds]: https://cmake.org/Wiki/CMake_FAQ#Out-of-source_build_trees |
| 224 | +[homebrew]: http://brew.sh/ |
| 225 | +[git]: https://git-scm.com/ |
| 226 | + |
| 227 | +[crystal]: http://crystal-lang.org/ |
| 228 | +[shards]: https://github.com/crystal-lang/shards |
| 229 | + |
| 230 | +[blaxpirit]: https://github.com/BlaXpirit |
| 231 | +[alanwillms]: https://github.com/alanwillms |
0 commit comments