MozReview-Commit-ID: L77ffKqR5QU
5.1 KiB
gl_generator
Code generators for creating bindings to the Khronos OpenGL APIs.
Usage
If you need a specific version of OpenGL, or you need a different API
(OpenGL ES, EGL, WGL, GLX), or if you need certain extensions, you should use
the gl_generator
plugin instead.
See gfx_gl for an example of using a custom gfx-rs loader for a project.
Add this to your Cargo.toml
:
[build-dependencies]
gl_generator = "0.5.0"
Under the [package]
section, add:
build = "build.rs"
Create a build.rs
to pull your specific version/API:
extern crate gl_generator;
use gl_generator::{Registry, Api, Profile, Fallbacks, GlobalGenerator};
use std::env;
use std::fs::File;
use std::path::Path;
fn main() {
let dest = env::var("OUT_DIR").unwrap();
let mut file = File::create(&Path::new(&dest).join("bindings.rs")).unwrap();
Registry::new(Api::Gl, (4, 5), Profile::Core, Fallbacks::All, [])
.write_bindings(GlobalGenerator, &mut file)
.unwrap();
}
Then use it like this:
mod gl {
include!(concat!(env!("OUT_DIR"), "/bindings.rs"));
}
/// Simple loading example
fn main() {
let window = ...;
// Assuming `window` is GLFW: initialize, and made current
gl::load_with(|s| window.get_proc_address(s));
}
The build.rs
file will generate all the OpenGL functions in a file named,
bindings.rs
plus all enumerations, and all types in the types
submodule.
Generator types
Global generator
The global generator is the one used by default by the gl
crate. See above
for more details.
Struct generator
The struct generator is a cleaner alternative to the global generator.
The main difference is that you must call gl::Gl::load_with
instead of
gl::load_with
, and this functions returns a struct of type Gl
. The OpenGL
functions are not static functions but member functions in this Gl
struct.
This is important when the GL functions are associated with the current
context, as is true on Windows.
The enumerations and types are still static and available in a similar way as in the global generator.
Static generator
The static generator generates plain old bindings. You don't need to load the functions.
This generator should only be used only if the platform you are compiling for is guaranteed to support the requested API. Otherwise you will get a compilation error. For example, you can use it for WGL and OpenGL 1.1 on Windows or GLX and OpenGL 1.3 on Linux, because Windows and Linux are guaranteed to provide implementations for these APIs.
You will need to manually provide the linkage. For example to use WGL or
OpenGL 1.1 on Windows, you will need to add
#[link="OpenGL32.lib"] extern {}
somewhere in your code.
Custom Generators
The gl_generator
can be extended with custom generators. This is a niche
feature useful only in very rare cases. To create a custom generator, implement
the gl_generator::Generator
trait. See the source of the
gl_generator::generators
module for examples.
Various utility functions are provided in the generators
module, but the api
is unstable, so it has been placed behind a feature flag. In access these
functions, you will need to add the "unstable_generator_utils"
feature to
your Cargo.toml
:
[build-dependencies.gl_generator]
version = "0.4.2"
features = ["unstable_generator_utils"]
Extra features
The global and struct generators will attempt to use fallbacks functions when
they are available. For example, if glGenFramebuffers
cannot be loaded it will
also attempt to load glGenFramebuffersEXT
as a fallback.
Changelog
v0.5.0
- Rename
Ns
toAPI
, and expose at the top level - Remove the need for clients to depend on the
khronos_api
crate by determining the XML source based on the requestedAPI
- Use a
(u8, u8)
instead of a string for the target version number - Use a
Profile
enum instead of a string for the profile - Remove unused fields from
Registry
- Accept types satisfying
AsRef<[&str]>
for extension lists - Separate parsing and generation stages in API
- Hide
registry::{Feature, Filter, Require, Remove, Extension}
types from the public API - Move
registry::{Fallbacks, Api, Profile}
types to top level module - Remove
GlxOpcode::type
field - Make
ty
fields onEnum
andBinding
takeCow<'static, str>
s to reduce allocations
v0.4.2
- Update crate metadata
v0.4.1
- Upgrade
khronos_api
to v1.0.0
v0.4.0
- Upgrade
xml-rs
to v0.2.2 - Use
raw::c_void
forGLvoid
- Remove
registry::{Group, EnumNs, CmdNs}
- Remove
groups
field fromregistry::Registry
- Remove
is_safe
field fromregistry::Cmd
- Remove
comment
field fromregistry::{Require, Remove, GlxOpcode}
- Downgrade
khronos_api
to be a dev-dependency