Various issues with docs and examples

[jarrett]

I've been trying to sort out how Conrod relates to Piston Graphics. Is Conrod an alternative, or are the two intended to be complementary? Currently, Conrod feels like an alternative to Graphics because, e.g., Conrod and Graphics have different Color types.

Should this be explained in the readme? If so, could write that up and do a PR.

[jarrett]

Another possible documentation issue: I'm not sure, but I think the Piston window API has changed since the Conrod examples were written. Per the latest Piston examples, the new way to iterate over events appears to be like this:

for e in window {
}

But Conrod's examples have the following, which I think reflects Piston's old API:

let event_iter = window.events().ups(60).max_fps(60);
for event in event_iter {
}

Unfortunately, this isn't just a stylistic difference. Because the types are different, you can't just do this:

for e in window {
    ui.handle_event(&e);
}

Similarly, handling of GlypheCache in the Conrod examples appears to be out of sync with the current Piston examples. The Conrod examples have this:

type Ui = conrod::Ui<GlyphCache<'static>>;

...which works with opengl_graphics, but not gfx_graphics, the Piston default backend. From the examples and the docs, I haven't been able to figure out the proper type parameter for Ui when using gfx_graphics.

[jarrett]

Also, the examples are currently broken, at least on OS X, apparently due to an outstanding bug in GlutinWindow. See PistonDevelopers/piston#937 for details. I'm not sure what the solution is right now because I haven't yet been able to cobble together a working Conrod application.

[mitchmindtree]

Thanks for the issue @jarrett !

I have the same issue (i'm also on osx) - the window problem is that when the window is resized the graphics warp and skew right? I think it also bugs out when moving the window between screens with different resolutions.

re piston-graphics: Not sure if you've noticed yet, but conrod uses elmesque for its graphics internally (it does this so that it can compose graphics together a little easier) which is also quite a new library and may be a bit buggy. Still haven't come up with a smooth way of inter-operating between both just yet! Conrod specifically just handles gui widgets at the moment (no freeform graphics, will probably work towards an easier integration with either piston-graphics or elmesque in the future).

Also, I think each of the different examples use different backends as we were testing that each work.

I finally have another day to work on Conrod - was going to get around to adding general scroll-ability and tabbed canvasses, but I think we should address these bugs first. Might make a day of it!

Will be back on in ~ hour

[mitchmindtree]

Added an issue for the window resizing problem #521

[jarrett]

Thanks! Yep, the problem is with resizing, as far as I know. Just now, I was able to get Conrod running. I discovered that the bug can be worked around by using Sdl2Window:

let window: PistonWindow<(), Sdl2Window> =
    WindowSettings::new(
        "Title",
        [1200, 800]
    )
    .opengl(opengl_version)
    .exit_on_esc(true)
    .into();

Other backends probably work as well, though I haven't tried.

It's been my experience thus far that theUi::draw method only works with GlGraphics. It didn't work when I tried to use the GfxGraphics that PistonWindows gives you by default. (It produced a rather labyrinthine type error that I didn't take the time to fully understand.) I don't know if that's necessary or intentional.

Anyhow, given that Conrod is using elmesque, does that mean it's an alternative to Piston Graphics? Or are the two meant to go hand-in-hand? My current approach is to use both in the same app, with Conrod doing the widgets and Piston Graphics doing the arbitrary drawing.

[mitchmindtree]

Interesting, so the resizing problem is with the glutin_window backend specifically? Maybe we should open up an issue there.

Hmm have you managed to get the canvas.rs example working at all? It uses the piston_window crate and compiles/works fine on my OSX machine (other than the resizing issue).

elmesque is a wrapper around piston-graphics that is aimed at being a little more composable and functionally oriented. You probably only need to use one or the other (if elmesque is missing any features that piston-graphics has, let me know as we should add them).

[jarrett]

I think there are a few open issues on glutin_window about this: rust-windowing/glutin#445, rust-windowing/glutin#503. I don't know if it's one bug or several interacting. It's unfortunate, because glutin_window is the Piston default at the moment.

So far, I haven't had any problem compiling or executing the examples. The issue is just that the coordinates are always wonky due to the aforementioned glutin_window bugs.

I'm glad to hear that elmesque is a wrapper around piston-graphics. That's good news. I'll have to take a look at it. Maybe I can use it for all my drawing. Thanks!

At some point, I'd be interested in contributing an update to the docs and examples reflecting recent changes to Piston's API. Though maybe it would be wise to let these glutin_window issues settle first.

[mitchmindtree]

So I just had a go at resizing all of the conrod examples and they're actually working fine for me! Same goes for the coordinates. Are you sure you're using the latest conrod? What exactly is the example or code on which the resizing issue occurs?

One issue I do have is when moving the from one screen to another when both have different resolutions (they don't re-adjust their scale until I resize them).

[jarrett]

cargo run --example all_widgets

For me, this has the same GlutinWindow errors where things are offset and warped. The mouse events appear to be using a different coordinate system than the rendered widgets, because in a number of cases, I have to move my mouse some distance from the widget to activate it.

[mitchmindtree]

Hmmm strange, I just ran

cargo update; cargo run --example all_widgets

on my osx machine and everything renders and interacts fine?

Can you

git clone https://github.com/PistonDevelopers/conrod.git

and build that? Just trying to make sure you're running the latest version of conrod (0.7.0).

The mouse events appear to be using a different coordinate system than the rendered widgets...

Conrod uses elmesque's coordinate system ((0, 0) in the middle, y pointing up) whereas the coordinates given by glutin_window are (0, 0) in the top left with y pointing down.

You should almost never have to use absolute coordinates in conrod as there are heaps of positioning methods supplied via the Positionable trait (see here), however there's also a ticket open for adding a method which will allow a user to position a widget via the screen coords (see here).

Sorry about the lack of docs for all this! There's an open issue with plans to write a proper, full guide soon, I just won't have time to do it at the moment (happy to merge PRs if someone wants to get started on it of course 😸 ).

[jarrett]

I cloned and ran again, but no change. On the bright side, I tried this out on the same computer with a non-retina monitor plugged in, and it worked. That led me to rust-windowing/glutin#287 and got me thinking again about rust-windowing/glutin#503. So I think this is a glutin_window issue that's confined to retina monitors.

[jarrett]

Anyhow, regarding the documentation: My original confusion stemmed from the fact that Piston's API has changed. It now uses Glutin and Gfx by default, and the event loop looks a little different, per the above. I finally managed to get a complete example working using Glutin and Gfx (sans-retina, for now). I would have found such an example helpful yesterday. If I cleaned it up, might it be a welcome addition to Conrod's examples folder?

Another quick question: The new Piston API has organized events slightly differently, so handle_event apparently has to be called like this:

for e in window {
    ui.handle_event(&e.event.clone().unwrap());
}

Do you recommend that, or is there a cleaner way?

[liquidmetal]

I tried using suggestions from this thread. I'm currently running into issues:

let opengl = OpenGL::V3_2;
let window: PistonWindow<(), Sdl2Window> =
         WindowSettings::new(
             "Title",
             [1200, 800]
         )
         .opengl(opengl)
         .exit_on_esc(true)
         .into();

The error I'm seeing looks like this:

%> cargo build
   Compiling <something> v0.1.0 (file:///some/file)
src/main.rs:167:10: 167:16 error: the trait `core::convert::From<window::WindowSettings>` is not implemented for the type `piston_window::PistonWindow<(), sdl2_window::Sdl2Window>` [E0277]
src/main.rs:167         .into();
                         ^~~~~~
error: aborting due to previous error

[xaviershay]

I ran into that same error, ended up going off to work on something else though so haven't got back around to it.

[bvssvni]

@liquidmetal Use .build().unwrap()

[mitchmindtree]

Going to close this issue as it's getting too broad - if anyone still has issues related to any of the above topics feel free to open up another issue more specific to your exact problem 👍