API improvements

- Use (u8, u8) for version number
- Allow extension lists to be any types that implement AsRef<[&str]>
- Separate parsing and generation stages in API

Author: brendanzab

gl/build.rs

@@ -14,7 +14,7 @@
 
 extern crate gl_generator;
 
-use gl_generator::{Fallbacks, GlobalGenerator, Api, Profile};
+use gl_generator::{Registry, Fallbacks, GlobalGenerator, Api, Profile};
 use std::env;
 use std::fs::File;
 use std::path::Path;
@@ -23,6 +23,7 @@ fn main() {
     let out_dir = env::var("OUT_DIR").unwrap();
     let mut file = File::create(&Path::new(&out_dir).join("bindings.rs")).unwrap();
 
-    gl_generator::generate_bindings(GlobalGenerator, Api::Gl, Fallbacks::All,
-                                    vec![], "4.5", Profile::Core, &mut file).unwrap();
+    Registry::new(Api::Gl, (4, 5), Profile::Core, Fallbacks::All, [])
+        .write_bindings(GlobalGenerator, &mut file)
+        .unwrap();
 }

gl_generator/README.md

@@ -33,33 +33,34 @@ Create a `build.rs` to pull your specific version/API:
 ```rust
 extern crate gl_generator;
 
-use gl_generator::{Fallbacks, GlobalGenerator, Api, Profile};
+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();
+    let mut file = File::create(&Path::new(&dest).join("gl_bindings.rs")).unwrap();
 
-    gl_generator::generate_bindings(GlobalGenerator, Api::Gl, Fallbacks::All,
-                                    vec![], "4.5", Profile::Core, &mut file).unwrap();
+    Registry::new(Api::Gl, (4, 5), Profile::Core, Fallbacks::All, [])
+        .write_bindings(GlobalGenerator, &mut file)
+        .unwrap();
 }
 ```
 
 Then use it like this:
 
 ```rust
-mod gles {
+mod gl {
     include!(concat!(env!("OUT_DIR"), "/bindings.rs"));
 }
 
-/*
- * Simple loading example
- */
+/// Simple loading example
 fn main() {
-    // Assuming window is GLFW, initialized, and made current
-    gles::load_with(|s| window.get_proc_address(s));
+    let window = ...;
+
+    // Assuming `window` is GLFW: initialize, and made current
+    gl::load_with(|s| window.get_proc_address(s));
 }
 ```
 
@@ -105,11 +106,8 @@ OpenGL 1.1 on Windows, you will need to add
 ### Custom Generators
 
 The `gl_generator` crate is extensible. This is a niche feature useful only in
-very rare cases. To create a custom generator, [create a new plugin
-crate](http://doc.rust-lang.org/guide-plugin.html#syntax-extensions) which
-depends on `gl_generator`. Then, implement the `gl_generator::Generator` trait
-and in your plugin registrar, register a function which calls
-`gl_generator::generate_bindings` with your custom generator and its name.
+very rare cases. To create a custom generator, implement the
+`gl_generator::generators::Generator` trait.
 
 ## Extra features
 
@@ -122,14 +120,16 @@ also attempt to load `glGenFramebuffersEXT` as a fallback.
 ### vX.X.X
 
 - Rename `Ns` to `API`, and expose at the top level
-- Use `Api` for `Extension::supported` and `Filter::api` fields
-- Remove `source` argument from `generate_bindings`, removing the need for
-  clients to depend on the `khronos_api` crate
-- Add `Profile` enum for specifying the API profile, and change the `source`
-  argument to use it instead of a string
-- Remove `features` and `extensions` fields from `Registry`
-- Hide `registry::{Feature, Filter, Require, Remove, Extension}` from the public API
-- Move `registry::{Fallbacks, Api, Profile}` to top level module
+- Remove the need for clients to depend on the `khronos_api` crate by
+  determining the XML source based on the requested `API`
+- 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
 
 ### v0.4.2
 

gl_generator/lib.rs

@@ -23,7 +23,7 @@
 //! ```no_run
 //! extern crate gl_generator;
 //!
-//! use gl_generator::{Fallbacks, GlobalGenerator, Api, Profile};
+//! use gl_generator::{Registry, Api, Profile, Fallbacks, GlobalGenerator};
 //! use std::env;
 //! use std::fs::File;
 //! use std::path::Path;
@@ -32,8 +32,9 @@
 //!     let dest = env::var("OUT_DIR").unwrap();
 //!     let mut file = File::create(&Path::new(&dest).join("gl_bindings.rs")).unwrap();
 //!
-//!     gl_generator::generate_bindings(GlobalGenerator, Api::Gl, Fallbacks::All,
-//!                                     vec![], "4.5", Profile::Core, &mut file).unwrap();
+//!     Registry::new(Api::Gl, (4, 5), Profile::Core, Fallbacks::All, [])
+//!         .write_bindings(GlobalGenerator, &mut file)
+//!         .unwrap();
 //! }
 //! ```
 //!
@@ -64,11 +65,11 @@
 extern crate log;
 
 use generators::Generator;
-use registry::Registry;
 
 use std::fmt;
 use std::io;
 
+pub use registry::Registry;
 pub use generators::debug_struct_gen::DebugStructGenerator;
 pub use generators::global_gen::GlobalGenerator;
 pub use generators::static_gen::StaticGenerator;
@@ -102,23 +103,11 @@ pub enum Fallbacks { All, None }
 #[derive(Copy, Clone, PartialEq, Eq)]
 pub enum Profile { Core, Compatibility }
 
-/// Generate OpenGL bindings using the specified generator
-///
-/// # Arguments
-///
-/// - `generator`: The type of loader to generate.
-/// - `api`: The API to generate.
-/// - `profile`: `Profile::Core` will only include all functions supported by the requested API
-///   version, while `Profile::Compatibility` will include all the functions from previous versions
-///   of the API as well.
-/// - `version`: The requested API version. This is usually in the form `"major.minor"`.
-/// - `extensions`: A list of extra extensions to include in the bindings.
-/// - `dest`: Where to write the generated rust source code to
-///
-pub fn generate_bindings<G, W>(generator: G, api: Api, fallbacks: Fallbacks,
-                               extensions: Vec<String>, version: &str, profile: Profile,
-                               dest: &mut W) -> io::Result<()> where G: Generator, W: io::Write
-{
-    let registry = Registry::new(api, fallbacks, extensions, version, profile);
-    generator.write(&registry, dest)
+impl Registry {
+    pub fn write_bindings<W, G>(&self, generator: G, output: &mut W) -> io::Result<()> where
+        G: Generator,
+        W: io::Write,
+    {
+        generator.write(&self, output)
+    }
 }

gl_generator/registry.rs

@@ -98,12 +98,15 @@ pub struct Registry {
 }
 
 impl Registry {
-    /// Generate a registry from the supplied XML string
-    pub fn new(api: Api, fallbacks: Fallbacks, extensions: Vec<String>, version: &str, profile: Profile) -> Registry {
+    pub fn new<'a, Exts>(api: Api, version: (u8, u8), profile: Profile, fallbacks: Fallbacks, extensions: Exts) -> Registry where
+        Exts: AsRef<[&'a str]>,
+    {
+        let (major, minor) = version;
+
         let filter = Filter {
             fallbacks: fallbacks,
             extensions: extensions,
-            version: version.to_string(),
+            version: format!("{}.{}", major, minor),
             profile: profile,
         };
 
@@ -262,9 +265,9 @@ struct RegistryParser<R: io::Read> {
     reader: XmlEventReader<R>,
 }
 
-struct Filter {
+struct Filter<Extensions> {
     fallbacks: Fallbacks,
-    extensions: Vec<String>,
+    extensions: Extensions,
     profile: Profile,
     version: String,
 }
@@ -319,7 +322,9 @@ impl<R: io::Read> RegistryParser<R> {
         }
     }
 
-    fn parse(src: R, api: Api, filter: Filter) -> Registry {
+    fn parse<'a, Exts>(src: R, api: Api, filter: Filter<Exts>) -> Registry where
+        Exts: AsRef<[&'a str]>,
+    {
         let mut parser = RegistryParser {
             api: api,
             reader: XmlEventReader::new(src),
@@ -420,7 +425,7 @@ impl<R: io::Read> RegistryParser<R> {
         }
 
         for extension in extensions.iter() {
-            if filter.extensions.iter().any(|x| x == &extension.name) {
+            if filter.extensions.as_ref().iter().any(|x| x == &extension.name) {
                 if !extension.supported.iter().any(|x| x == &api) {
                     panic!("Requested {}, which doesn't support the {} API", extension.name, api);
                 }

gl_tests/test_gen_symbols/build.rs

@@ -25,28 +25,33 @@ fn main() {
     let mut file = File::create(&Path::new(&dest).join("test_gen_symbols.rs")).unwrap();
 
     writeln!(&mut file, "mod gl {{").unwrap();
-    gl_generator::generate_bindings(GlobalGenerator, Api::Gl, Fallbacks::All,
-                                    vec![], "4.5", Profile::Core, &mut file).unwrap();
+    Registry::new(Api::Gl, (4, 5), Profile::Core, Fallbacks::All, [])
+        .write_bindings(GlobalGenerator, &mut file)
+        .unwrap();
     writeln!(&mut file, "}}").unwrap();
 
     writeln!(&mut file, "mod gles {{").unwrap();
-    gl_generator::generate_bindings(GlobalGenerator, Api::Gles2, Fallbacks::All,
-                                    vec![], "3.1", Profile::Core, &mut file).unwrap();
+    Registry::new(Api::Gles2, (3, 1), Profile::Core, Fallbacks::All, [])
+        .write_bindings(GlobalGenerator, &mut file)
+        .unwrap();
     writeln!(&mut file, "}}").unwrap();
 
     writeln!(&mut file, "mod glx {{").unwrap();
-    gl_generator::generate_bindings(GlobalGenerator, Api::Glx, Fallbacks::All,
-                                    vec![], "1.4", Profile::Core, &mut file).unwrap();
+    Registry::new(Api::Glx, (1, 4), Profile::Core, Fallbacks::All, [])
+        .write_bindings(GlobalGenerator, &mut file)
+        .unwrap();
     writeln!(&mut file, "}}").unwrap();
 
     writeln!(&mut file, "mod wgl {{").unwrap();
-    gl_generator::generate_bindings(GlobalGenerator, Api::Wgl, Fallbacks::All,
-                                    vec![], "1.0", Profile::Core, &mut file).unwrap();
+    Registry::new(Api::Wgl, (1, 0), Profile::Core, Fallbacks::All, [])
+        .write_bindings(GlobalGenerator, &mut file)
+        .unwrap();
     writeln!(&mut file, "}}").unwrap();
 
     writeln!(&mut file, "mod egl {{ {}", build_egl_symbols()).unwrap();
-    gl_generator::generate_bindings(GlobalGenerator, Api::Egl, Fallbacks::All,
-                                    vec![], "1.5", Profile::Core, &mut file).unwrap();
+    Registry::new(Api::Egl, (1, 5), Profile::Core, Fallbacks::All, [])
+        .write_bindings(GlobalGenerator, &mut file)
+        .unwrap();
     writeln!(&mut file, "}}").unwrap();
 }