serafimarts / ffi-sdl

SDL2 FFI bindings for the PHP language

FFI SDL Bindings

A SDL FFI bindings for the PHP language.

• System Requirements
• Installation
• Extensions
• Documentation
• Initialization
• Example

Requirements

• PHP ^8.1
• ext-ffi
• Windows, Linux, BSD or MacOS
  • Android, iOS or something else are not supported yet
• SDL >= 2.0

Installation

Library is available as composer repository and can be installed using the following command in a root of your project.

$ composer require serafim/ffi-sdl

Additional dependencies:

• Debian-based Linux: sudo apt install libsdl2-2.0-0 -y
• MacOS: brew install sdl2
• Window: Can be downloaded from here

Extensions

• SDL Image
• SDL TTF
• SDL Mixer

Documentation

The library API completely supports and repeats the analogue in the C language.

• SDL2 official documentation

• API not yet fully documented and may not work in places.

• Low level and inline functions (such as SDL_malloc or SDL_memcpy) have been removed.

Initialization

To specify a library pathname explicitly, you can add the library argument to the Serafim\SDL\SDL constructor.

By default, the library will try to resolve the binary's pathname automatically.

// Load library from pathname (it may be relative or part of system-dependent path)
$sdl = new Serafim\SDL\SDL(library: __DIR__ . '/path/to/library.so');

// Try to automatically resolve library's pathname
$sdl = new Serafim\SDL\SDL(library: null);

You can explicitly specify the platform (OS) that will be used as the basis for compiling headers.

By default, the library will try to resolve the platform automatically.

// Use Linux as compile-aware platform
$sdl = new Serafim\SDL\SDL(platform: Serafim\SDL\Platform::LINUX);

// Detect platform automatically
$sdl = new Serafim\SDL\SDL(platform: null);

You can also specify the library version explicitly. Depending on this version, the corresponding functions of the SDL will be available.

By default, the library will try to resolve SDL version automatically.

// Use v2.28.2 from string
$sdl = new Serafim\SDL\SDL(version: '2.28.2');

// Use v2.24.1 from predefined versions constant
$sdl = new Serafim\SDL\SDL(version: \Serafim\SDL\Version::V2_24_1);

// Use latest supported version
$sdl = new Serafim\SDL\SDL(version: \Serafim\SDL\Version::LATEST);

To speed up the header compiler, you can use any PSR-16 compatible cache driver.

$sdl = new Serafim\SDL\SDL(cache: new Psr16Cache(...));

In addition, you can control other preprocessor directives explicitly:

$pre = new \FFI\Preprocessor\Preprocessor();
$pre->setLogger(new ExampleLogger());
$pre->define('__ANDROID__', '1');

$sdl = new Serafim\SDL\SDL(pre: $pre);
$jni = $sdl->SDL_AndroidGetJNIEnv();

Example

use Serafim\SDL\SDL;
use Serafim\SDL\Event\Type;

$sdl = new SDL();

$sdl->SDL_Init(SDL::SDL_INIT_VIDEO);

$window = $sdl->SDL_CreateWindow(
    'An SDL2 window',
    SDL::SDL_WINDOWPOS_UNDEFINED,
    SDL::SDL_WINDOWPOS_UNDEFINED,
    640,
    480,
    SDL::SDL_WINDOW_OPENGL
);

if ($window === null) {
    throw new \Exception(sprintf('Could not create window: %s', $sdl->SDL_GetError()));
}

$event = $sdl->new('SDL_Event');
$running = true;

while ($running) {
    $sdl->SDL_PollEvent(FFI::addr($event));
    if ($event->type === Type::SDL_QUIT) {
        $running = false;
    }
}

$sdl->SDL_DestroyWindow($window);
$sdl->SDL_Quit();

ffi-sdl's Issues

Passing incompatible argument 2 of C function 'SDL_CreateTextureFromSurface', expecting 'struct SDL_Surface*', found 'struct SDL_Surface*'

• code

<?php

define('ROOT_DIR', __DIR__ . '/..');

require ROOT_DIR . '/vendor/autoload.php';

use Serafim\SDL\SDL;
use Serafim\SDL\TTF\TTF;
use Serafim\SDL\Event\Type;

$sdl = new SDL(library: ROOT_DIR . '/lib/SDL2.dll');
$ttf = new TTF(sdl: $sdl, library: ROOT_DIR . '/lib/SDL2_ttf.dll');

$sdl->SDL_Init(SDL::SDL_INIT_EVERYTHING);
$ttf->TTF_Init();

$window = $sdl->SDL_CreateWindow(
    'An SDL2 window',
    SDL::SDL_WINDOWPOS_UNDEFINED,
    SDL::SDL_WINDOWPOS_UNDEFINED,
    640,
    480,
    SDL::SDL_WINDOW_OPENGL
);

if ($window === null) {
    throw new \Exception(sprintf('Could not create window: %s', $sdl->SDL_GetError()));
}

$renderer = $sdl->SDL_CreateRenderer($window, -1, 0);
if (!$renderer) {
    throw new \Exception("Can't create renderer!");
}

$font = $ttf->TTF_OpenFont(ROOT_DIR . '/font/arial.ttf', 42);

echo 'Hinting: ' . $ttf->TTF_GetFontHinting($font) . "\n";
echo 'Kerning: ' . $ttf->TTF_GetFontKerning($font) . "\n";
echo 'Style:   ' . match($ttf->TTF_GetFontStyle($font)) {
    TTF::TTF_STYLE_NORMAL => 'normal',
    TTF::TTF_STYLE_BOLD => 'bold',
    TTF::TTF_STYLE_ITALIC => 'italic',
    TTF::TTF_STYLE_UNDERLINE => 'underline',
    TTF::TTF_STYLE_STRIKETHROUGH => 'strikethrough',
}   . "\n";


$color = $sdl->new('SDL_Color');
$color->r = 120;
$color->g = 100;
$color->b = 80;

$surface = $ttf->TTF_RenderText_Solid($font, 'Hello World!', FFI::addr($color));
$texture = $sdl->SDL_CreateTextureFromSurface($renderer, $surface);

$event = $sdl->new('SDL_Event');
$running = true;

while ($running) {
    $sdl->SDL_PollEvent(FFI::addr($event));
    if ($event->type === Type::SDL_QUIT) {
        $running = false;
    }
}

$sdl->SDL_FreeSurface($surface);
$sdl->SDL_DestroyTexture($texture);
$sdl->SDL_DestroyWindow($window);
$ttf->TTF_Quit();
$sdl->SDL_Quit();

• error

Hinting: 0
Kerning: 1
Style:   normal

Fatal error: Uncaught FFI\Exception: Passing incompatible argument 2 of C function 'SDL_CreateTextureFromSurface', expecting 'struct SDL_Surface*', found 'struct SDL_Surface*' in E:\Git\ffi-sdl-test\vendor\ffi\proxy\src\ProxyAwareTrait.php:21
Stack trace:
#0 E:\Git\ffi-sdl-test\vendor\ffi\proxy\src\ProxyAwareTrait.php(21): FFI->SDL_CreateTextureFromSurface(Object(FFI\CData:struct SDL_Renderer*), Object(FFI\CData:struct SDL_Surface*))
#1 E:\Git\ffi-sdl-test\src\ttf.php(54): FFI\Proxy\Proxy->__call('SDL_CreateTextu...', Array)
#2 {main}
  thrown in E:\Git\ffi-sdl-test\vendor\ffi\proxy\src\ProxyAwareTrait.php on line 21

Unable to run the example

I tried running the example provided within the "Usage" section and all I got are these errors:

PHP Fatal error:  Uncaught Error: Call to undefined method FFI::init() in C:\Users\alex\Desktop\test_sdl\vendor\serafim\ffi-sdl\src\Support\ProxyTrait.php:153
Stack trace:
#0 C:\Users\alex\Desktop\test_sdl\index.php(9): Serafim\SDL\SDL::__callStatic('init', Array)
#1 {main}
  thrown in C:\Users\alex\Desktop\test_sdl\vendor\serafim\ffi-sdl\src\Support\ProxyTrait.php on line 153

Fatal error: Uncaught Error: Call to undefined method FFI::init() in C:\Users\alex\Desktop\test_sdl\vendor\serafim\ffi-sdl\src\Support\ProxyTrait.php:153
Stack trace:
#0 C:\Users\alex\Desktop\test_sdl\index.php(9): Serafim\SDL\SDL::__callStatic('init', Array)
#1 {main}
  thrown in C:\Users\alex\Desktop\test_sdl\vendor\serafim\ffi-sdl\src\Support\ProxyTrait.php on line 153

I enabled the FFI extension in php.ini, then ran the "php -m" command to make sure the extension is available

I installed the composer package with this command: composer require serafim/ffi-sdl
And the composer.json file ended up like this:

{
    "require": {
        "serafim/ffi-sdl": "^1.0"
    }
}

Here is the php script I'm trying to run:
index.zip

I tried installing the "dev-master" version but all I got was this error about a composer package that doesn't appear to exist anywhere:
serafim/ffi-sdl dev-master requires serafim/flux ^1.0 -> could not be found in any version, there may be a typo in the package name.

Windows 10 Version 20H2 (19042.630)
PHP 7.4.8 (cli) (built: Jul 9 2020 11:30:33) ( NTS Visual C++ 2017 x64 ) downloaded from php.net
Composer 2.0.7

Core dump when cast Rect

Whenever when I create SDL_React and then I try to var_dump it or set variable for it I got
50030 segmentation fault (core dumped) php index.php

$rect = $sdl->new(SDL_Rect::class);
$rect->x = 1;
$rect->y = 1;
$rect->w = 10;
$rect->h = 10;
$sdlRect = $sdl->cast(\Serafim\SDL\RectPtr::class, $rect); // <<<<< HERE

var_dump($sdlRect);

or

$sdlRect->x = 32;

or

$sdl->SDL_QueryTexture($texture, null, null,  SDL::addr($sdlRect->w), SDL::addr($sdlRect->h) );

➜ php index.php
object(FFI\CData:struct SDL_Rect*)#21 (1) {
  [0]=>
  [1]    51564 segmentation fault (core dumped)  php index.php