Implement IDL based generators

[Diggsey]

Example generated bindings:
https://gist.github.com/Diggsey/c8a4cb93c7d5643d20203401ead178a7

This can't be merged until:

1. I've tested it beyond the bindings compiling
2. The next version of stdweb is released, which will contain the CanvasElement type

[Diggsey]

I've just implemented a massive rework of the type-generation - it's now really powerful, and will generate borrowed versions of types for arguments and will generate generic methods when appropriate.

[Diggsey]

[brendanzab]

Woo! This is looking great!

[brendanzab]

I'm wondering if it might actually make sense to create a new crate instead under this repository, called webgl_generator?

[Diggsey]

Yeah, I don't really mind, is that what you'd prefer?

[tomaka]

I personally don't think it's worth creating a new repo.

[brendanzab]

Wasn't talking about creating a new repo, just a new crate as a directory in this repo. If I'm not mistaken it seems like gl_generator and webgl_generator are orthogonal in their implementations and their dependencies?

[tomaka]

Oh sorry, yes that would make sense!

[edwin0cheng]

@Diggsey As i mentioned in koute/stdweb#92, will it works in Firefox ?

[Diggsey]

@edwin0cheng not right now - at least not if you try do anything complex. I think this can (and should) be fixed from the stdweb side though.

[brendanzab]

Looking great so far! Let me know when this can progress forward!

[Diggsey]

@brendanzab I've realised that the IDL files are missing information on extensions - these are described via separate IDL embedded in XML in the Khronos WebGL repo.

I would like to expose a mapping from "<extension name>" => "<IDL contents>" in the khronos_api crate - this will involve a build step to extract the IDL from the XML and will need to be stored as a static array of type &'static [(&'static str, &'static str)]. Does that sound reasonable to you?

[Diggsey]

I've opened a separate PR to add extension support to khronos_api, and I've rebased this PR on top.

The generated bindings are now up to 10,000 lines, and include support for all accepted WebGL extensions. There's also a "version-less" GLContext type to make it easier to write code which can work with multiple versions.

I've uploaded the generated documentation as I think it's quite interesting to read:
http://awesome-davinci-d3197a.bitballoon.com/webgl_stdweb/index.html

[brendanzab]

I would like to expose a mapping from "" => "" in the khronos_api crate - this will involve a build step to extract the IDL from the XML and will need to be stored as a static array of type &'static [(&'static str, &'static str)]. Does that sound reasonable to you?

Oh, missed this comment! Would have been helpful if you had have linked to it in the PR of #451! Yes, that sounds great.

[Diggsey]

One thing that might be cool would be to pull out the "summary" and "function" sections from the XML files and attach them as doc-comments to the generated code.

[brendanzab]

Ooooh! Wondering if we could do that for all the generators 😮

[Diggsey]

@brendanzab stdweb 0.4.0 was released, and I've updated the PR to use that. It should be ready for you to review now!

[brendanzab]

Woo, looking now!

[brendanzab]

Should we be using unimplemented! here? Are you planning to add support for this later?

[Diggsey]

BufferSource is not currently used in the WebGL IDL files, so I haven't bothered implementing it.

[brendanzab]

itertools has join if you wanted to use that to skip the intermediate collect!

[Diggsey]

Didn't seem worth it - this only happens at build time, and the cost of the extra dependency would outweigh any minor performance improvements.

[brendanzab]

Has this been forgotten?

[Diggsey]

Just not needed for WebGL

[brendanzab]

Why does this need to be an Option?

[brendanzab]

Would be nice to Run rustfmt on this if you don't mind!

[Diggsey]

@brendanzab done

[Diggsey]

@brendanzab hey is this good to go?

[brendanzab]

Ack - left this one sit around in my notifications making me feel guilty for too long! Merging!

[Diggsey]

Thanks! Are you happy to publish the new crate(s) to crates.io?

[brendanzab]

Yup, will do. I'll add you to the crate owners too.

[brendanzab]

What needs to be published - just the new crates?

[brendanzab]

Hum, when publishing I get:

error[E0425]: cannot find value `WEBGL_EXT_XML` in module `khronos_api`
  --> webgl_registry/mod.rs:69:38
   |
69 |         for &ext_xml in khronos_api::WEBGL_EXT_XML {
   |                                      ^^^^^^^^^^^^^ not found in `khronos_api`

error: aborting due to previous error

For more information about this error, try `rustc --explain E0425`.
error: failed to verify package tarball

Caused by:
  Could not compile `webgl_generator`.

[brendanzab]

Oh, I think I need to bump the khronos_api version 🤔

[brendanzab]

Oh, and probably also publish those changes

[Diggsey]

Yes, I think so?

[brendanzab]

Done!