gfx-rs / gfx_gl

An OpenGL loader tailored to gfx-rs's needs.

Getting Started | Documentation | Blog | Funding

gfx-rs

gfx-rs is a low-level, cross-platform graphics and compute abstraction library in Rust. It consists of the following components:

gfx-hal deprecation

As of the v0.9 release, gfx-hal is now in maintenance mode. gfx-hal development was mainly driven by wgpu, which has now switched to its own GPU abstraction called wgpu-hal. For this reason, gfx-hal development has switched to maintenance only, until the developers figure out the story for gfx-portability. Read more about the transition in #3768.

hal

• gfx-hal which is gfx's hardware abstraction layer: a Vulkan-ic mostly unsafe API which translates to native graphics backends.
• gfx-backend-* which contains graphics backends for various platforms:
  • Vulkan (runs on Linux, Windows, and Android)
  • DirectX 12 and DirectX 11
  • Metal (runs on macOS and iOS)
  • OpenGL ES3 (runs on Linux/BSD, Android, and WASM/WebGL2)
• gfx-warden which is a data-driven reference test framework, used to verify consistency across all graphics backends.

gfx-rs is hard to use, it's recommended for performance-sensitive libraries and engines. If that's not your domain, take a look at wgpu-rs for a safe and simple alternative.

Hardware Abstraction Layer

The Hardware Abstraction Layer (HAL), is a thin, low-level graphics and compute layer which translates API calls to various backends, which allows for cross-platform support. The API of this layer is based on the Vulkan API, adapted to be more Rust-friendly.

Currently HAL has backends for Vulkan, DirectX 12/11, Metal, and OpenGL/OpenGL ES/WebGL.

The HAL layer is consumed directly by user applications or libraries. HAL is also used in efforts such as gfx-portability.

See the Big Picture blog post for connections.

The old gfx crate (pre-ll)

This repository was originally home to the gfx crate, which is now deprecated. You can find the latest versions of the code for that crate in the pre-ll branch of this repository.

The master branch of this repository is now focused on developing gfx-hal and its associated backend and helper libraries, as described above. gfx-hal is a complete rewrite of gfx, but it is not necessarily the direct successor to gfx. Instead, it serves a different purpose than the original gfx crate, by being "lower level" than the original. Hence, the name of gfx-hal was originally ll, which stands for "lower level", and the original gfx is now referred to as pre-ll.

The spiritual successor to the original gfx is actually wgpu, which stands on a similar level of abstraction to the old gfx crate, but with a modernized API that is more fit for being used over Vulkan/DX12/Metal. If you want something similar to the old gfx crate that is being actively developed, wgpu is probably what you're looking for, rather than gfx-hal.

Contributing

We are actively looking for new contributors and aim to be welcoming and helpful to anyone that is interested! We know the code base can be a bit intimidating in size and depth at first, and to this end we have a label on the issue tracker which marks issues that are new contributor friendly and have some basic direction for completion in the issue comments. If you have any questions about any of these issues (or any other issues) you may want to work on, please comment on GitHub and/or drop a message in our Matrix chat!

License

This repository is licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

gfx_gl's Issues

Library does not work with new gl_generator

The compilation now fails with an undefined macro:

src/lib.rs:30:1: 30:21 error: macro undefined: 'generate_gl_bindings!'
src/lib.rs:30 generate_gl_bindings!{
              ^~~~~~~~~~~~~~~~~~~~

crates.io version (0.1.4) is behind master (0.1.5)

If you could publish the latest, that'd be great :)

Update version on crates.io

If 0.3.1 is ready can it be uploaded to crates.io?

Update in crates.io

Now package in crates.io doesn't compile, unlike master.

Build failing with 'can't find crate for `gl_generator`'

Both when trying to compile gfx-rs and then building gfx_gl by itself I am receiving the following error:

$ pwd
/home/guy/code/rust/gfx_gl

$ rustc --version
rustc 0.13.0-nightly (96a3c7c6a 2014-12-23 22:21:10 +0000)

$ cargo --version
cargo 0.0.1-pre-nightly (e11c317 2014-12-21 20:43:45 +0000)

$ cargo build --verbose
   Compiling gfx_gl v0.1.0 (file:///home/guy/code/rust/gfx_gl)
     Running `rustc build.rs --crate-name build-script-build --crate-type bin -C prefer-dynamic -g --out-dir /home/guy/code/rust/gfx_gl/target/build/gfx_gl-97b9a2a3dbbf7312 --emit=dep-info,link -L /home/guy/code/rust/gfx_gl/target -L /home/guy/code/rust/gfx_gl/target/deps`
build.rs:1:1: 1:27 error: can't find crate for `gl_generator`
build.rs:1 extern crate gl_generator;
           ^~~~~~~~~~~~~~~~~~~~~~~~~~
error: aborting due to previous error
Could not compile `gfx_gl`.

Caused by:
  Process didn't exit successfully: `rustc build.rs --crate-name build-script-build --crate-type bin -C prefer-dynamic -g --out-dir /home/guy/code/rust/gfx_gl/target/build/gfx_gl-97b9a2a3dbbf7312 --emit=dep-info,link -L /home/guy/code/rust/gfx_gl/target -L /home/guy/code/rust/gfx_gl/target/deps` (status=101)

creates.io links give 404

I assume that the create at https://crates.io/crates/gfx_gl is meant to be this one. However, the links over there ("Repository", "Homepage") give a 404.

Relicense under dual MIT/Apache-2.0

This issue was automatically generated. Feel free to close without ceremony if
you do not agree with re-licensing or if it is not possible for other reasons.
Respond to @cmr with any questions or concerns, or pop over to
#rust-offtopic on IRC to discuss.

You're receiving this because someone (perhaps the project maintainer)
published a crates.io package with the license as "MIT" xor "Apache-2.0" and
the repository field pointing here.

TL;DR the Rust ecosystem is largely Apache-2.0. Being available under that
license is good for interoperation. The MIT license as an add-on can be nice
for GPLv2 projects to use your code.

Why?

The MIT license requires reproducing countless copies of the same copyright
header with different names in the copyright field, for every MIT library in
use. The Apache license does not have this drawback. However, this is not the
primary motivation for me creating these issues. The Apache license also has
protections from patent trolls and an explicit contribution licensing clause.
However, the Apache license is incompatible with GPLv2. This is why Rust is
dual-licensed as MIT/Apache (the "primary" license being Apache, MIT only for
GPLv2 compat), and doing so would be wise for this project. This also makes
this crate suitable for inclusion and unrestricted sharing in the Rust
standard distribution and other projects using dual MIT/Apache, such as my
personal ulterior motive, the Robigalia project.

Some ask, "Does this really apply to binary redistributions? Does MIT really
require reproducing the whole thing?" I'm not a lawyer, and I can't give legal
advice, but some Google Android apps include open source attributions using
this interpretation. Others also agree with
it.
But, again, the copyright notice redistribution is not the primary motivation
for the dual-licensing. It's stronger protections to licensees and better
interoperation with the wider Rust ecosystem.

How?

To do this, get explicit approval from each contributor of copyrightable work
(as not all contributions qualify for copyright, due to not being a "creative
work", e.g. a typo fix) and then add the following to your README:

## License

Licensed under either of

 * Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
 * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)

at your option.

### Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any
additional terms or conditions.

and in your license headers, if you have them, use the following boilerplate
(based on that used in Rust):

// Copyright 2016 gfx_gl developers
//
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
// option. This file may not be copied, modified, or distributed
// except according to those terms.

It's commonly asked whether license headers are required. I'm not comfortable
making an official recommendation either way, but the Apache license
recommends it in their appendix on how to use the license.

Be sure to add the relevant LICENSE-{MIT,APACHE} files. You can copy these
from the Rust repo for a plain-text
version.

And don't forget to update the license metadata in your Cargo.toml to:

license = "MIT/Apache-2.0"

I'll be going through projects which agree to be relicensed and have approval
by the necessary contributors and doing this changes, so feel free to leave
the heavy lifting to me!

Contributor checkoff

To agree to relicensing, comment with :

I license past and future contributions under the dual MIT/Apache-2.0 license, allowing licensees to chose either at their option.

Or, if you're a contributor, you can check the box in this repo next to your
name. My scripts will pick this exact phrase up and check your checkbox, but
I'll come through and manually review this issue later as well.

• @bjz
• @csherratt
• @kvark
• @vickenty
• @mitsuhiko
• @bvssvni
• @Potpourri
• @cmr
• @MaikKlein
• @indiv0