Rust 的 EGL 绑定

此crate提供对Khronos EGL 1.5 API的绑定。它最初是egl crate的分支，该crate已被弃用。

使用方法

您可以使用由静态链接到编译时libEGL.so.1或运行时动态加载EGL库定义的Instance对象来访问EGL API。

静态链接

您必须在Cargo.toml中启用static功能以启用静态链接。

khronos-egl = { version = ..., features = ["static"] }

这将添加对pkg-config crate的依赖项，这是在编译时查找EGL库所必需的。

如果您想禁用此crate中的EGL链接，并在您的crate中提供链接，请启用no-pkg-config功能。

khronos-egl = {version = ..., features = ["static", "no-pkg-config"]}

以下是一个示例，展示了如何在启用静态链接时使用此库创建EGL上下文。

extern crate khronos_egl as egl;

fn main() -> Result<(), egl::Error> {
	// Create an EGL API instance.
	// The `egl::Static` API implementation is only available when the `static` feature is enabled.
	let egl = egl::Instance::new(egl::Static);

	let wayland_display = wayland_client::Display::connect_to_env().expect("unable to connect to the wayland server");
	let display = egl.get_display(wayland_display.get_display_ptr() as *mut std::ffi::c_void).unwrap();
	egl.initialize(display)?;

	let attributes = [
		egl::RED_SIZE, 8,
		egl::GREEN_SIZE, 8,
		egl::BLUE_SIZE, 8,
		egl::NONE
	];

	let config = egl.choose_first_config(display, &attributes)?.expect("unable to find an appropriate ELG configuration");

	let context_attributes = [
		egl::CONTEXT_MAJOR_VERSION, 4,
		egl::CONTEXT_MINOR_VERSION, 0,
		egl::CONTEXT_OPENGL_PROFILE_MASK, egl::CONTEXT_OPENGL_CORE_PROFILE_BIT,
		egl::NONE
	];

	egl.create_context(display, config, None, &context_attributes);

	Ok(())
}

由于它依赖于您的显示服务器，因此这里未详细介绍Display实例的创建。它使用指向显示服务器连接句柄的指针通过get_display函数创建。例如，如果您使用wayland-client crate，您可以使用Display::get_display_ptr方法获取此指针。

静态API实例

在一些应用程序中，将 Instance 传递给需要调用 EGL API 的每个函数可能令人烦恼。一个解决方案是在编译时使用静态链接定义一个静态的 Instance，但这在稳定的 rustc 编译器中尚未支持。使用夜间编译器，您可以组合 nightly 和 static 功能，使这个crate可以提供一个静态的 Instance，称为 API，然后可以在任何地方访问它。

use egl::API as egl;

动态链接

动态链接允许您的应用程序接受多个版本的 EGL 并更加灵活。您必须通过在您的 Cargo.toml 中启用 dynamic 功能来启用动态链接。

khronos-egl = { version = ..., features = ["dynamic"] }

这将添加对 libloading crate 的依赖，这是在运行时查找 EGL 库所必需的。然后，您可以按如下方式将 EGL API 装载到 Instance<Dynamic<libloading::Library>>

let lib = libloading::Library::new("libEGL.so.1").expect("unable to find libEGL.so.1");
let egl = unsafe { egl::DynamicInstance::<egl::EGL1_4>::load_required_from(lib).expect("unable to load libEGL.so.1") };

在这里，使用 egl::EGL1_4 指定必须由 libEGL.so.1 提供的 EGL 的最低必需版本。这将返回一个 DynamicInstance<egl::EGL1_4>，但如果 libEGL.so.1 提供了一个更新的 EGL 版本，您仍然可以将实例向上转换为提供特定版本的功能

match egl.upcast::<egl::EGL1_5>() {
	Some(egl1_5) => {
		// do something with EGL 1.5
	}
	None => {
		// do something with EGL 1.4 instead.
	}
};

NixOS

存在一个 shell.nix 文件，以便 nix 用户可以轻松构建 crate。只需使用给定的配置文件进入一个新的 nix shell，然后 cargo build 应该可以工作。如果您想运行测试和示例，您将需要使用 shell-wayland.nix 替换，它也会加载 wayland，因为大多数示例都依赖于它。

测试

大多数测试和示例都需要使用 static 功能编译。

故障排除

与 OpenGL ES 静态链接

当使用具有 static 功能的 khronos-egl 与 OpenGL ES 时，在您的应用程序顶部放置一个空的 extern 是必要的，该 extern 首先链接 libEGL，然后是 GLESv1/2。这是因为 libEGL 提供了 GLESv1/2 所需的符号。以下是解决方案：

#[link(name = "EGL")]
#[link(name = "GLESv2")]
extern {}

许可证

在您选择的情况下，许可如下：

• Apache 许可证 2.0 (LICENSE-APACHE 或 http://www.apache.org/licenses/LICENSE-2.0)
• MIT 许可证 (LICENSE-MIT 或 http://opensource.org/licenses/MIT)

。

如果原始的 egl crate 仅在 Apache 2.0 许可证下进行许可，我相信我已经做出了足够大的破坏性更改，以至于原始代码中没有相关的代码，其余代码可以重新许可。

贡献

除非您明确声明，否则根据Apache-2.0许可证定义的，您有意提交以包含在作品中的任何贡献，将采用上述双重许可，不附加任何其他条款或条件。