在 PHP 中的 OpenGL：通过 FFI 设置图形上下文

PHP集成OpenGL：通过FFI和GLFW设置图形上下文

前一篇文章介绍了如何在PHP中使用GLFW库创建窗口。既然渲染的基本画布已准备就绪，下一步关键任务就是集成OpenGL库以执行图形操作。本文将详细概述如何通过PHP FFI连接OpenGL、配置图形上下文，以及建立GLFW窗口与OpenGL之间的关联。

项目架构与FFI跨平台兼容性

为了确保模块化和跨平台兼容性，GLFW库已被移至一个独立文件src/glfw3.php中。这种方法允许使用PHP FFI（外部函数接口）集中管理原生库连接。

glfw3.php的实现示例：

<?php

return FFI::cdef(
    code: (string) file_get_contents(__FILE__, offset: __COMPILER_HALT_OFFSET__),
    lib: $_SERVER['GLFW3_LIB'] ?? match (PHP_OS_FAMILY) {
        'Windows' => 'glfw3.dll',
        'Linux' => 'libglfw.so.3',
        'Darwin' => 'glfw3.dylib',
    },
);

__halt_compiler();

// ...GLFW function headers...

FFI中当前的lib选择实现依赖于PHP_OS_FAMILY，并且可能受到当前工作目录（CWD）或环境变量（PATH, LD_LIBRARY_PATH）等因素的影响。为了实现更稳健的连接，建议使用库的明确路径：

return FFI::cdef(..., lib: __DIR__ . '/path/to/lib.<dll/so/dylib/etc>');

然而，为了提高灵活性，可以通过GLFW3_LIB环境变量或在加载FFI对象之前直接在PHP代码中覆盖该路径：

通过命令行：$ GLFW3_LIB=/path/to/lib.so php ./app.php
在PHP代码中：$_SERVER['GLFW3_LIB'] = '/path/to/your/glfw3.dll';

这种方法允许适应各种部署环境，同时对原生库的加载保持高度控制。

OpenGL集成与初始配置

下一步是为OpenGL库建立类似的连接。在Windows平台上，这个过程最为直接：系统会使用opengl32.dll，它提供了一套基本的OpenGL函数（版本1.0-1.1），并由显卡驱动动态扩展到现代版本（最高4.6）。对于其他操作系统（Linux、macOS），直接连接opengl32.dll是行不通的，但这一点将在后续文章中通过GLFW来解决。

目前，针对Windows的最小化src/opengl.php如下所示：

<?php

return FFI::cdef(
    code: (string) file_get_contents(__FILE__, offset: __COMPILER_HALT_OFFSET__),
    lib: $_SERVER['OPENGL_LIB'] ?? match (PHP_OS_FAMILY) {
        'Windows' => 'opengl32.dll',
        // TODO: Add support for other OS
    },
);

__halt_compiler();

// ...OpenGL function headers...

创建src/opengl.php后，需要将其与GLFW一起包含在主应用程序文件app.php中：

<?php
// app.php

$glfw = require __DIR__ . '/src/glfw3.php';
$opengl = require __DIR__ . '/src/opengl.php';

// ...further window initialization and launch...

通过GLFW窗口提示配置OpenGL

为了让OpenGL与创建的窗口正确协作，必须设置图形上下文参数。GLFW提供了glfwWindowHint()机制，允许您在创建OpenGL上下文之前指定其所需的特性。这确保了兼容性和最佳性能。

需要设置的关键参数包括：

GLFW_SAMPLES：启用多重采样（MSAA），用于边缘抗锯齿。值为4表示4倍抗锯齿。
GLFW_CONTEXT_VERSION_MAJOR 和 GLFW_CONTEXT_VERSION_MINOR：定义所需的OpenGL版本。推荐使用3.3版本，因为它足够现代且得到广泛支持。尝试创建不支持版本的上下文将导致错误。
GLFW_OPENGL_FORWARD_COMPAT：启用前向兼容模式。对于OpenGL 3+，这意味着弃用旧的API函数。
GLFW_OPENGL_PROFILE：选择OpenGL配置文件。GLFW_OPENGL_CORE_PROFILE表示独占使用现代OpenGL特性，不兼容旧API。

app.php中的配置示例：

// app.php
// ...after glfwInit()...

$glfw->glfwWindowHint(GLFW_SAMPLES, 4);
$glfw->glfwWindowHint(GLFW_CONTEXT_VERSION_MAJOR, 3);
$glfw->glfwWindowHint(GLFW_CONTEXT_VERSION_MINOR, 3);
$glfw->glfwWindowHint(GLFW_OPENGL_FORWARD_COMPAT, 1);
$glfw->glfwWindowHint(GLFW_OPENGL_PROFILE, GLFW_OPENGL_CORE_PROFILE);

// ...further window creation...

这些常量和glfwWindowHint()函数必须通过从GLFW头文件（例如glfw3.h）中复制其定义，在src/glfw3.php中进行声明：

// src/glfw3.php

// Constants
const GLFW_SAMPLES = 0x0002100D;
const GLFW_CONTEXT_VERSION_MAJOR = 0x00022002;
const GLFW_CONTEXT_VERSION_MINOR = 0x00022003;
const GLFW_OPENGL_FORWARD_COMPAT = 0x00022006;
const GLFW_OPENGL_PROFILE = 0x00022008;
const GLFW_OPENGL_CORE_PROFILE = 0x00032001;

// ... return FFI::cdef(...);

__halt_compiler();

// Function declaration
void glfwWindowHint(int hint, int value);
// ...other GLFW functions...

绑定OpenGL到窗口并验证

创建窗口并配置上下文后，您必须明确告诉OpenGL它应该绑定到哪个窗口进行渲染。这通过使用glfwMakeContextCurrent()函数来完成：

// app.php
// ...immediately after window creation...

$glfw->glfwMakeContextCurrent($window);

// ...then the main event loop...

glfwMakeContextCurrent()函数也需要在src/glfw3.php中声明：

// src/glfw3.php

// ... __halt_compiler();

void glfwMakeContextCurrent(GLFWwindow* window);
// ...other GLFW functions...

为了验证集成是否成功，可以使用一个简单的OpenGL缓冲区清除函数。在应用程序的主循环中，在渲染每一帧之前，调用glClear()：

// app.php
while (!$glfw->glfwWindowShouldClose($window)) {
    // Clears the color buffer with the current clear color (default black)
    $opengl->glClear(GL_COLOR_BUFFER_BIT);

    // $glfw->glfwSwapBuffers($window);
    // etc...
}

为此，必须在src/opengl.php中定义GL_COLOR_BUFFER_BIT常量并声明glClear()函数：

<?php
// src/opengl.php

// Constant
const GL_COLOR_BUFFER_BIT = 0x00004000;

// ... return FFI::cdef(...);

__halt_compiler();

// Function declaration and typedef
typedef unsigned int GLbitfield;
void glClear(GLbitfield mask);

完成这些步骤后，应用程序的成功无错误启动，确认了OpenGL上下文已正确初始化并绑定到GLFW窗口。尽管视觉结果可能保持不变（一个黑窗口），但这表明系统已准备好执行实际的图形命令。

关键要点

模块化FFI连接：为FFI对象使用独立文件（glfw3.php、opengl.php）可确保代码整洁并简化原生库管理。
FFI跨平台兼容性：正确配置库路径（lib）以及使用环境变量以实现跨不同操作系统的灵活连接至关重要。
上下文配置：在创建窗口之前通过glfwWindowHint()设置OpenGL参数对于选择OpenGL版本、配置文件（核心配置文件）以及启用MSAA等功能至关重要。
窗口绑定：glfwMakeContextCurrent()函数设置活动的OpenGL上下文，指定哪个窗口将执行图形操作。
验证：简单的OpenGL调用，例如glClear()，用于确认成功集成以及系统已准备好进行渲染。