Add a chapter on adding nannou to existing projects

[freesig]

So a question / confusion I have noticed is that people are stuck on how do they add nannou to an existing application. Do they have to change the whole structure of their app to use nannou.
I think a good solution is to just spin nannou up on another thread and then communicate with it using channels but it could be cool to have an example of how this would look.

[mitchmindtree]

nannou pretty much requires running on the main thread if you want to use its windowing and application events, as macos requires calling a whole lot of their windowing/application event api on the main thread (a giant PITA).

That said, it should now be possible to integrate anything laser/audio/osc related quite easily as they each have their own standalone crates. All the graphics stuff we currently expose is quite integrated with the nannou loop though I guess.

Come to think of it, you could import the nannou crate just to use the Draw API if you wanted - the Draw API is fairly self contained, allows you to draw basic shapes/meshes etc and then output them as triangulated vertices and indices that should be compatible with just about any graphics backend. Bringing in the whole nannou crate (and its 200+ deps) just for that though would be quite a big hit just for the draw API. Will have a think on this some more!

[freesig]

Would this apply to Linux?

[mitchmindtree]

I don't think so, I think macOS is the main culprit. I think if you search for "main thread macos" in the winit issues you might find lots of old discussion on the topic.

[freesig]

I guess in my mind and the way I was interpreting the question from a few people was:
You have some project that you've been working on for a while, lets say its a physics engine for example. You hear about nannou and think ah that would be great to visualize my engine.
But you don't want to push all your application into the nannou loop (ie you physics engine might be running at 500fps for accuracy) so you just spin up nannou on another thread and send it updates to the Model across a channel or something.

MacOs really ruins this vision haha.
The best we can do is suggest they spin their application up on another thread in the model function.
I tried to answer this stackoverflow question by showing these options.

I think we should still make a section on how to do this but maybe just show the option of putting the existing application on a thread spawned from the model fn. What are your thoughts?

[mitchmindtree]

The best we can do is suggest they spin their application up on another thread in the model function.

Yeah I think this is much more reasonable in the case of a physics engine! I don't think the physics engine gains anything in particular from running on the main thread - it should in theory be simple to move something like that onto another thread. Yeah I agree maybe a demo of spawning a thread like this for processing that you don't want to block the main app thread would be useful?

It would be more of a problem if the user already had their own application loop and windows running, and wanted to run an instance of nannou side-by-side for some reason, maybe in a separate window or something. I don't think there's any way you could let both the original application and the nannou application run on the main thread (which would be necessary on macos) - they'd have to run as separate processes I think.

Checking out that stackoverflow issue, it looks like the user had checked out an example that only used the nannou::sketch API and thought that that was the only way that nannou works and that there was no way to store or update data over time. Which is a fair assumption if they only happen to look at examples that use nannou::sketch, which is easy to do as there are a few of them! As a result, they were struggling to work out how to add some additional data (the image buffer) that they wanted access to in the view. I think your answer in the SO thread is good! This is definitely something I can see happening again and I agree it would be nice to address it.

The Create A Project chapter and the first basics tutorial of the guide both demonstrate the more flexible yet slightly more verbose nannou::app approach, and the latter has a section on the purpose of the model. Maybe another tutorial that actually demonstrates adding some state to the Model, updating it with update and displaying it with view would help?

Perhaps another approach for solving the case that this user ran into is to more visibly demonstrate that there are two ways to start a nannou project, nannou::sketch and nannou::app, and very clearly describe that sketch is only for stateless and app is for when you want to store and update your own data over time? The docs entries for sketch and app already kind of mention this but could probably also mention each other to make it clearer that there may be a better option for the reader.