Home

Awesome

<a href="https://repology.org/metapackage/libsdl2pp/versions"> <img src="https://repology.org/badge/vertical-allrepos/libsdl2pp.svg" alt="libsdl2pp packaging status" align="right"> </a>

CI Github commits (since latest release)

libSDL2pp

This library provides C++ bindings/wrapper for SDL2 and satellite libraries.

Synopsis

try {
  using namespace SDL2pp;

  // Init SDL; will be automatically deinitialized when the object is destroyed
  SDL sdl(SDL_INIT_VIDEO | SDL_INIT_AUDIO);

  // Likewise, init SDL_ttf library
  SDLTTF sdl_ttf;

  // Straightforward wrappers around corresponding SDL2 objects
  // These take full care of proper object destruction and error checking
  Window window("libSDL2pp demo",
                SDL_WINDOWPOS_UNDEFINED, SDL_WINDOWPOS_UNDEFINED,
                640, 480, SDL_WINDOW_RESIZABLE);
  Renderer renderer(window, -1, SDL_RENDERER_ACCELERATED);
  Texture sprite1(renderer, SDL_PIXELFORMAT_ARGB8888,
                            SDL_TEXTUREACCESS_STATIC, 16, 16);
  Texture sprite2(renderer, "sprite.png"); // SDL_image support

  Font font("Vera.ttf", 20); // SDL_ttf font

  // Initialize audio mixer
  Mixer mixer(MIX_DEFAULT_FREQUENCY, MIX_DEFAULT_FORMAT, MIX_DEFAULT_CHANNELS, 4096);

  Chunk sound("effect.ogg"); // OGG sound file

  // Create texture from surface containing text rendered by SDL_ttf
  Texture text(renderer, font.RenderText_Solid("Hello, world!",
               SDL_Color{255, 255, 255, 255}));

  unsigned char pixels[16 * 16 * 4];

  // Note proper constructor for Rect
  sprite1.Update(Rect(0, 0, 16, 16), pixels, 16 * 4);

  // Most setter methods are chainable
  renderer.SetLogicalSize(640, 480).SetDrawColor(0, 16, 32).Clear();

  // Also note a safe way to specify null rects and points
  renderer.Copy(sprite1, NullOpt, NullOpt);

  // There are multiple convenient ways to construct e.g. a Rect;
  // Objects provide extensive set of getters
  renderer.Copy(text, NullOpt, Rect(Point(0, 0), text.GetSize()));

  // Copy() is overloaded, providing access to both SDL_RenderCopy and SDL_RenderCopyEx
  renderer.Copy(sprite2, NullOpt, NullOpt, 45.0);

  renderer.Present();

  // Play our sound one time on a first available mixer channel
  mixer.PlayChannel(-1, sound);

  // You can still access wrapped C SDL types
  SDL_Renderer* sdl_renderer = renderer.Get();

  // Of course, C SDL2 API is still perfectly valid
  SDL_Delay(2000);

  // All SDL objects are released at this point or if an error occurs
} catch (SDL2pp::Exception& e) {
  // Exception stores SDL_GetError() result and name of function which failed
  std::cerr << "Error in: " << e.GetSDLFunction() << std::endl;
  std::cerr << "  Reason: " << e.GetSDLError() << std::endl;
} catch (std::exception& e) {
  // This also works (e.g. "SDL_Init failed: No available video device")
  std::cerr << e.what() << std::endl;
}

There's also more elaborate tutorial.

Features

Currently, the library provides wrapper classes for

each with a subset of methods corresponding to SDL functions working with specific types of objects and, in some cases, additional convenience methods. These classes support:

Set of functional extensions above SDL2 is also available:

Building

Dependencies:

To build standalone version:

cmake .
cmake --build .

Following variables may be supplied to CMake to affect build:

Installation

To install the library system-wide, run:

cmake .
cmake --build .
cmake --install .

You can change installation prefix with CMAKE_INSTALL_PREFIX cmake variable:

cmake -DCMAKE_INSTALL_PREFIX=/usr/local .
cmake --build .
cmake --install .

SDL2pp installs pkg-config file, so it can be used with any build system that interacts with pkg-config, including CMake, meson and GNU Autotools. It also installs CMake module file, which can be used from CMake directly:

find_package(SDL2pp REQUIRED)

target_link_libraries(mytarget SDL2pp::SDL2pp)

Bundling

The library is easy to integrate into other CMake projects (and as the library has no stable API yet, this way of using it is still recommended).

Just place the library into dedicated directory in your project (for example, extlib/libSDL2pp) and add

set(SDL2PP_WITH_IMAGE ON) # if you need SDL_image support
set(SDL2PP_WITH_MIXER ON) # if you need SDL_mixer support
set(SDL2PP_WITH_TTF ON) # if you need SDL_ttf support
add_subdirectory(extlib/libSDL2pp)

into your core CMakeLists.txt. This will act similar to how find_package usually does, and will provide SDL2pp::SDL2pp target for your project. You will then be able it as usual:

target_link_libraries(mytarget SDL2pp::SDL2pp)

If bundled, libSDL2pp does not build examples and becomes a static library. See hoverboard project as an example of using both bundled and systemwide SDL2pp.

Completeness

The library still doesn't cover all aspects of SDL2, and the development is generally guided by the author's needs and interest without a goal for covering all SDL2 functions as soon as possible. However, if you need specific bits which are not yet implemented in the library, feel free to drop an issue. Patches are of course more than welcome.

It should be noted, however, that I currently do not plan to implement any wrappers over non object-oriented SDL2 code, as these will not bring any benefits over using plain C API. E.g. I see no point in implementing SDL2pp::Delay() as it won't bring any convenience over SDL_Delay().

The same strongly applies to the SDL2 bits which duplicate C++17 standard library, e.g. threads and atomic ops.

Users

Projects using libSDL2pp:

WWW

Author

Contributors

License

libSDL2pp comes under zlib license, the same license as SDL2. See COPYING.txt.