README

A PHP extension that brings GPU rendering, audio, video recording, streaming, and input handling to PHP. Foundation layer for the PHPolygon game engine.

Features

• Multi-Backend GPU Rendering — Direct3D 12, Direct3D 11, Metal, Vulkan (MoltenVK), OpenGL 4.1
• 2D Batch Renderer — Rects, circles, lines, sprites, text (z-sorted, up to 4096 items)
• 3D Pipeline — Meshes, shaders, pipelines, textures, uniform/storage buffers
• Shader Toolchain — GLSL to SPIR-V compilation, reflection, cross-compilation
• Audio — Playback via miniaudio (MP3, WAV, FLAC)
• Video Recording — H.264 encoding via FFmpeg (with VideoToolbox HW acceleration)
• Network Streaming — RTMP and SRT via FFmpeg
• Input — Keyboard, mouse, and gamepad support via GLFW
• Headless Mode — Offscreen rendering for tests and visual regression testing
• Plugin System — Extensible output/input/filter plugins
• Cross-Platform — macOS, Linux, Windows

Requirements

• PHP >= 8.5

All native libraries are optional — the extension compiles and runs without them, features are simply unavailable at runtime:

Installation

Via PIE (PHP Installer for Extensions)

pie install phpolygon/php-vio

Pre-built Binaries

Download platform-specific binaries from the Releases page. Available for:

• Linux x86_64 / ARM64
• macOS x86_64 (Intel) / ARM64 (Apple Silicon)
• Windows x64

From Source (macOS)

brew install glfw glslang spirv-cross ffmpeg

phpize
./configure --enable-vio --with-glfw --with-glslang --with-spirv-cross \
  --with-vulkan --with-ffmpeg --with-metal
make -j$(sysctl -n hw.ncpu)
sudo make install

From Source (Linux)

# Ubuntu/Debian
sudo apt install php-dev libglfw3-dev glslang-dev libvulkan-dev \
  libavcodec-dev libavformat-dev libavutil-dev libswscale-dev \
  spirv-cross libspirv-cross-c-shared-dev

phpize
./configure --enable-vio --with-glfw --with-glslang --with-spirv-cross \
  --with-vulkan --with-ffmpeg
make -j$(nproc)
sudo make install

Windows

On Windows, no build toolchain is needed — PHP extensions are distributed as pre-compiled DLLs. Download the matching DLL from the Releases page (match your PHP version and thread-safety mode), then:

1. Copy php_vio.dll into your PHP ext\ directory
2. Add extension=vio to your php.ini
3. Restart PHP / your web server

All backends use conditional compilation (#ifdef HAVE_*), so builds without certain dependencies compile fine — those features are simply unavailable at runtime.

Quick Start

<?php

// Create a window with OpenGL backend
$ctx = vio_create("opengl", [
    "width"  => 800,
    "height" => 600,
    "title"  => "Hello VIO",
]);

while (!vio_should_close($ctx)) {
    vio_begin($ctx);
    vio_clear($ctx, 0.1, 0.1, 0.1);

    // 2D drawing
    vio_rect($ctx, 50, 50, 200, 100, ["color" => 0xFF0000FF]);
    vio_circle($ctx, 400, 300, 60, ["color" => 0x00FF00FF]);
    vio_draw_2d($ctx);

    vio_end($ctx);
    vio_poll_events($ctx);
}

vio_close($ctx);
vio_destroy($ctx);

API Overview

71 functions across these categories:

Full API documentation: see vio.stub.php

Backends

Backend auto-selection is platform-specific:

• Windows: Direct3D 12 → Direct3D 11 → Vulkan → OpenGL
• macOS: Metal → OpenGL (Vulkan via MoltenVK is opt-in, not auto)
• Linux: Vulkan → OpenGL

Null is never auto-selected; request it explicitly with vio_create("null") for headless tests. Override auto-selection per call (vio_create("d3d11")) or globally via the vio.default_backend INI setting.

Performance: Metal vs OpenGL

Benchmarked on Apple M2 Pro (macOS 26.4, 1280x720, VSync off). Measures draw + flush time only (excludes present/VSync wait).

Tail latency (frame time consistency):

Metal is slightly slower on simple scenes due to command encoding overhead, but 20% faster on heavy scenes (1000+ draw calls with text). More importantly, Metal delivers 30-40% better tail latency — fewer frame time spikes and more consistent rendering.

Testing

NO_INTERACTION=1 TEST_PHP_EXECUTABLE=$(which php) \
  php run-tests.php -d extension=$PWD/modules/vio.so tests/

38 tests included, covering headless rendering, 2D/3D pipelines, shaders, audio, input, and visual regression testing.

License

MIT