SPACE BOX

         /\         +------------------------------------------------------------+ 
    ____/  \____   /| zlib/MIT/Unlicenced game framework licensed to freely use, |
    \          /  / | copy, modify and sell without restriction                  |
  +--\ ^__^   /--+  |                                                            |
  | ~/        \~ |  | Learn more about [SPACE BOX] at [shampoo.ooo]              |
  | ~~~~~~~~~~~~ |  +------------------------------------------------------------+
  | SPACE ~~~~~  | /
  |  ~~~~~~~ BOX |/
  +--------------+   

[SPACE BOX] is a C++ framework that makes creating cross-platform games and other interactive applications easier and faster by providing an added layer of abstraction between SDL + OpenGL and the project.

Users can start a project by extending only a single function, the Game class's update function. Using a standard Makefile that can be taken from the examples, the framework can export the same code to multiple platforms like PC, OS/X, Linux, Web GL, Raspberry Pi, and Android.

It is in an early, untested state. It comes with a few simple examples that demonstrate how to use it.

Requirements

The repository includes some external libraries in lib/ that the default Makefile included with the demo shows how to compile, but there are other requirements, including external libraries that must be linked to a project in order to compile it.

• libSDL2 (developed against v2.0.14)
• libSDL2-image
• libSDL2-ttf
• libSDL2-mixer
• OpenGL/GLES/GLES2
• compiler that supports C++17

Installing Requirements

libSDL2, libSDL2-image, libSDL2-ttf, and libSDL2-mixer must be available to link with your project, so you can try your package manager's libSDL2 dev packages or build from source. The included sdl2-config utility program can be used to generate flags for linking to SDL2 when it is installed outside of your platform's usual library location.

libSDL2

• Download from http://libsdl.org/download-2.0.php
• Run ./configure --prefix=[YOUR LIBRARIES PATH] (for example, $HOME/local/sdl)
• Run make && make install

libSDL2-image, libSDL2-ttf, libSDL2-mixer

• Download from:
  • https://github.com/libsdl-org/SDL_image
  • https://github.com/libsdl-org/SDL_ttf
  • https://github.com/libsdl-org/SDL_mixer
• Run ./configure --prefix=[YOUR LIB PATH] --with-sdl-prefix=[YOUR SDL PATH]
• For example, prefix and SDL prefix can be $HOME/local/sdl

OpenGL/GLES/GLES2

• Install GL/GLES according to your platform and link to it during compilation. GLEW is included in the lib/ folder of this framework and should find GL on your platform if it is installed.

Demos

The demo/ folder contains programs that demonstrate and test the capabilities of the framework. In order to compile each, you should edit the definitions in the Makefile.

cube

Switch between GL and SDL contexts by pressing spacebar. The GL context draws a textured, rotating cube, and the SDL context draws basic geometric shapes and a moving 2D sprite.

2d_collision

Test collision detection between a 2D sprite and other 2D sprites and boxes. Per-pixel collision can be tested.

squircle

Map an image from a rectangle to a circle or from a circle to a rectangle using a shader program. Based on the elliptical grid mapping equations at http://squircular.blogspot.com/2015/09/mapping-circle-to-square.html

browser webcam

An example for using a C++ program to display a webcam stream in the browser using Emscripten to translate the code from C++ to WebAssembly. Get the frame pixel data from a canvas element, read it into a SPACEBOX object, write the pixel data to an OpenGL texture, and use Emscripten to display the video.

Other libraries

These are other libraries that have been used in projects that use this framework but aren't required by the framework

opencv

Linux

Download from https://opencv.org/releases/ and create a build directory, then configure and make. This example uses a custom installation path:

$ mkdir build_linux/ && cd build_linux/
$ cmake -DCMAKE_INSTALL_PREFIX=$HOME/local/opencv ..
$ make && make install

The libraries can then be linked by adding the following to the linker flags:

-L$(HOME)/local/opencv/lib -Wl,-rpath,$(HOME)/local/opencv/lib -lopencv_videoio -lopencv_core -lopencv_highgui \ 
    -lopencv_imgproc

The specific modules needed at the end of that list may vary depending on the project. There are detailed instructions for building OpenCV on Linux available at https://docs.opencv.org/4.6.0/d7/d9f/tutorial_linux_install.html

Emscripten

To build the WASM libraries necessary to include OpenCV in an Emscripten build of a SPACEBOX project, set up the Emscripten environment and run OpenCV's build_js.py script with the WASM output option. Note that OpenCV's cv::VideoCapture object will not be available in the libraries built this way because OpenCV emulates that object in its JS implementation.

$ source [EMSDK_PATH]/emsdk_env.sh
$ python3 [OPENCV_PATH]/platforms/js/build_js.py --emscripten_dir [EMSCRIPTEN_PATH] build_wasm --build_wasm

There is a detailed explanation of this process at https://docs.opencv.org/4.6.0/d4/da1/tutorial_js_setup.html And useful information for getting around the absence of cv::VideoCapture at https://docs.opencv.org/4.6.0/dd/d00/tutorial_js_video_display.html Check out a minimal example of using OpenCV with C++ and Emscripten at https://github.com/mpizenberg/emscripten-opencv

zbar

Linux

Download from http://zbar.sourceforge.net/download.html and configure to only use image processing features (requires the imagemagickwand library, available from, for example apt get libmagickwand-dev) and choose your installation directory:

./configure --without-gtk --without-python --without-qt --without-xshm --without-xv --without-jpeg \
    --disable-video --prefix=$HOME/local/zbar

make

make && make install

Emscripten

To build a WASM library that can be used to build an Emscripten version of a SPACEBOX project, set up the Emscripten environment and configure using emconfigure with the same disable flags as above.

$ source emsdk_env.sh
$ emconfigure ./configure --without-gtk --without-python --without-qt --without-xshm --without-xv --without-jpeg \
    --disable-video
$ emmake make
$ find . -iname *.a
./zbar/.libs/libzbar.a

There is a detailed tutorial on using Zbar with WebAssembly at https://barkeywolf.consulting/posts/barcode-scanner-webassembly/

Font

When initializing a Game object, the framework will attempt to load the font file "BPmono.ttf" from the project root (where the compiled executable is located). If this file isn't found, the program can still run successfully, but the framerate indicator (mapped to CTRL+f by default) will be disabled. The repository contains "BPmono.ttf", so you can create a symlink to the file in the project root if you want to use the framerate indicator.

License

SPACEBOX is released under the zlib license. It is free to use, copy, modify and sell. See LICENSE.txt for details.

Included libraries are included under various permissive licenses compatible with the zlib license:

• BPmono.ttf is licensed under the Creative Commons Attribution - No Derivative Works 3.0 license. See [LICENSE_BPmono.txt][]
• gif-h is unlicensed, public domain code released under the The Unlicense. See [lib/gif-h/LICENSE][]
• GLEW is included under the license in [lib/glew/LICENSE.txt][]
• GLM is included under the MIT license in [lib/glm/LICENSE][]
• nlohmann's json library is included under the MIT license in [lib/json/LICENSE.MIT][]
• SDL2 GFX is included under the license in [lib/sdl2-gfx/LICENSE][]
• superxbr.cpp is included under the license at the top of [lib/superxbr.cpp][]

Contact

• email: frank at shampoo dot ooo
• twitter: https://twitter.com/diskmem