Hi,
I'm trying to understand how Piston::Graphics work, but there are lot of things that are not clear to me.
Concept contradiction in example and documentation
If I got it right this library has been thought in order to write back-end agnostic code, so if you use only the stuff defined in graphics crate you will be sure that you can switch to a back-end to another without rewrite/fix/debugging drawing code.
As I understood the graphics trait is the main entry point for all drawing operations, so in order to draw you have to use graphics or call the draw method on one of the possible basic shape provided (such as: Rectangle, Line, ...).
That's a wonderful idea, I do love it.
But then I opened some of the beginner tutorial and I saw something like:
...
// Where gl is an instance GlGraphics
self.gl.draw(args.viewport(), |c, gl| {
...
So this example is explicitly calling a method (draw) defined in GlGraphics and not defined in the agnostic Graphics trait. It seems to call something specific of that implementation instead of a generic and agnostic method from graphics trait.
Also in documentation of graphics trait is written:
When drawing, use this trait as generic constraint:
fn draw<G: Graphics>(c: &Context, g: &mut G) { ... }
But I cannot find where this method draw is defined, and actually I cannot even clearly understand what the sentence means (maybe also because I am not a native English speaker 
)
Context struct
It is used in a lot of example and cited in the Graphics documentation, but there is not public methods of graphics trait that it is using or returning, so I am wondering how I can use it (apart of calling custom draw implementation, that are not agnostic).
Documentation
In general I think that maybe this crate is lacking of detailed and clear documentation. Probably all these questions would be not necessary if there were a good introduction and good explanation of all methods and struct.
Sorry, I am not blaming nobody, it is incredible and admirable the work that you have done, but we (including myself) have to understand that good documentation is crucial to make a language or its libraries becoming popular and used in a proper way.
Also the little things are important, for example if you check documentation of: Transformed trait it states that Matrix2d implements it, but if you check the documentation of Matrix2d there is no mention about, this little things sometime cost much time for who has to use the library because he/she could spend hours to re-implement something that was already there, but in someway hidden/lost in documentation.
Again, this (last part on documentation) is not a blaming or a finger-pointing to anybody, it is just a shared thought about how it is important to document library in a proper way (even if it takes more than developing it).
I hope to clarify my understanding about this library and use it in a proper way, since I do love its concept and I think it should be (as it will be more solid) included in the Rust STD.