[Suggestion] Add a step-by-step guide on including it into an existing project.

[jmorez]

I have tried for hours to start with an empty project and then adding nanogui to it but it did not work. I tried mirroring the configuration properties, but the included examples are so different from a default empty project, so if I want to add it to an existing project I am affraid I will mess up other parts.

I have no idea what the issue could be or what I should pay attention to. This makes troubleshooting very difficult. I expected it to be straightforward (adding header and library directories, including nanogui/nanogui.h and linking nanogui.lib) but it is not. Perhaps someone could add a HOWTO on adding it to a VS project to get a minimal working example?

[dupred16]

I have to agree, I think I am running into the same problem, it has to do with using glew in an existing project. I have tried static and dynamic linking, and I can get everything to link, I can get nanogui to init fine, but inside my application code none of the glew extensions are initialized. So I tried to make a glfw window first, but as soon as nanogui tries to a use a glew bound call it fails.

[jmorez]

Yes! My project also uses GLEW and they seem to conflict. (ignore the closing/reopening, pressed the wrong button on mobile).

[BennetLeff]

PatronBernard, it's been a while since you opened this issue but if you're still interested I will be working on a way to add some documentation because I just got a build working with nanogui (although not 100% pretty code or seamless with my outside of library OpenGL calls). After I improve my projects code quality considerably I can offer some samples in addition to the provided ones. Does anyone have anything against using something like sphinx to at least get the documentation process started?

[wjakob]

Using Sphinx sounds good to me.
(BTW: In the meantime, NanoGUI has switched from GLEW to GLAD)

[darrenmothersele]

@PatronBernard this is how I got up and running...

$ mkdir nanogui-test
$ cd nanogui-test
$ git init
$ git submodule add https://github.com/wjakob/nanogui.git lib/nanogui
$ git submodule update --init --recursive

Then I have a CMakeLists.txt file that looks like this:

cmake_minimum_required(VERSION 3.5)
project(nanogui_test)

set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++14")

add_subdirectory(lib/nanogui)
include_directories(lib/nanogui/include)
include_directories(${NANOGUI_EXTRA_INCS})
add_definitions(${NANOGUI_EXTRA_DEFS})

set(SOURCE_FILES main.cpp)
add_executable(nanogui_test ${SOURCE_FILES})
target_link_libraries(nanogui_test nanogui ${NANOGUI_EXTRA_LIBS})

And my main.cpp looks like this:

#include <iostream>
#include <nanogui/screen.h>
#include <nanogui/window.h>
#include <nanogui/layout.h>
#include <nanogui/button.h>

using namespace std;
using nanogui::Screen;
using nanogui::Window;
using nanogui::GroupLayout;
using nanogui::Button;

int main() {
    nanogui::init();

    Screen screen{{600, 420}, "Screen"};
    Window window{&screen, "Window"};
    window.setPosition({15, 15});
    window.setLayout(new GroupLayout());
    Button *b =new Button(&window, "My Button");
    b->setCallback([] { cout << "Button pressed!" << endl; });

    screen.performLayout();

    screen.drawAll();
    screen.setVisible(true);

    nanogui::mainloop();

    nanogui::shutdown();
    exit(EXIT_SUCCESS);
}

I'm working on a better example

[svenevs]

@darrenmothersele nice example, cool demo but still relatively simple / compact -- excellent for a tutorial. I have some ideas / suggestions and have benefited really from NanoGUI and would love to help. I'll move the discussion to that repo so this doesn't get too cluttered.

@BennetLeff with respect to Sphinx, are you only doing that for the python side or are you using doxygen and breathe (or something else) for the C++?

[BennetLeff]

As far as I can tell, Sphinx can generate C++ docs as well.

[svenevs]

Oh nice I guess I was looking at the old Sphinx docs! So it seems that Sphinx is expecting restructured text documentation, most of the stuff in this project is doxygen style. E.g. the difference between \ref SomeClass and SomeClass. I'm not too familiar with either of these tools, though, and it could be that Sphinx already supports doxygen comments?

1. @BennetLeff Is there some repo somewhere that you are already working on this? In other words, is there a specific comment format / sphinx project you already have that works? I'd like to help document some of the classes I know, and can also help convert document style if we need to.
2. @wjakob Is there a suggested / preferred workflow? Something like "work in a forked repository that stays up to date with nanogui. As documentation gets added, make a pull request"? Should we submit PRs against master? That would enable hosting of partial docs while it is being completed, but perhaps it would be better to only do this once when they are complete?

[wjakob]

PRs for partial docs are perfectly fine -- even something partial is better than nothing at this point, and none of it impacts functionality.

[svenevs]

Haha fair enough. Is it safe to assume that the ultimate destination of the resultant website will be a gh-pages branch on this repo?

[wjakob]

If you write sphinx docs, readthedocs.org would be the natural destination. It can automatically fetch and build the docs from github repositories.

[wjakob]

(You can take a look at my pybind11 project for reference)

[svenevs]

Understood. docs/conf.py approach it is.

[BennetLeff]

Agreed. I haven't had the time to start this on my own so whatever approach gains momentum works for me :)

[AlwaysGeeky]

I would also be interested to help out with this effort if this is still required and help needed?

One thing I would suggest is looking into how we can document and improve the process of getting nanogui working and integrated in a project that already has GLFW and GLEW integrated.

Honestly this project is great and I really love the potential here but relying on people using the project with all the dependecy and init code that the project brings is pretty limiting really. I dont really see the massive userbase of people wanting to take the project and rely on nanogui handling the glfw functionality and all the opengl rendering pipeline. The most likely users for this project are people that already have their own rendering engine and windows management code using glfw and would like to integrate a simple and effective gui that nanogui provides.

As it stands now there is very little support for this use-case in the code and also the documentation, in fact its very hard for someone to find out how to create Screen objects and the steps required to get nanogui running if you want to manage glfw yourself. Maybe we can focus a bit on this?

[AlwaysGeeky]

If anyone is interested I have created a new example that shows how to integrate nanogui in an existing project that manages glfw and context itself, without having to rely on the nanogui init and main loop.

This is demonstrated in the pull request: #91

[BennetLeff]

That's a great example. I was looking for just the thing when I got started and had to write my own.

[svenevs]

@AlwaysGeeky I actually did spend a decent amount of time getting the documentation going, but ultimately got really frustrated by the workflow. Sphinx has (in my opinion) an unacceptable format. With how large this library is, putting EVERY class and every method on one page is arguably less helpful than just reading the comments in the code. Doxygen has a great hierarchy built, but looks like it's a website straight out of the nineties...

I'm at a conference this week but had slated working on finishing that up afterward. The sphinx C++ support requires manual annotation of anything you want documented, so my workflow is Doxygen -> Breathe, but I wrote a little parser to then auto-generate the Library API based off the Breathe index tree that is built. There are a couple loose ends wrt files etc, but it's relatively close.

Since this is all Sphinx, a new jinja template had to accompany it as well. But the good news: other than the Library API, things like an Overview page or "How to Build" or like your example "How to use if you initialize GLFW yourself" articles can all be written in a single Restructured Text document.

So if you would want to start writing up any of those pages, that would be great! I'll get back on the documentation generation as soon as I leave Anaheim

[AlwaysGeeky]

@svenevs Thanks, I will probably put some effort into this shortly, for the moment I am just getting to grips with the library a little since I just got it working in my own project. I have identified and noticed a few improvements and essentials that are needed when you want to add nanogui into your own project in this way and will be working on these first, and contributing to that side, before diving into the documentation, since I think this is a required first step.

Right now I have got my own managed glfw project, that can render its own nanovg separatly and also integrated nanogui and got it working with rendering well and also all the input and callback handling working properly.

If anyone wants to see my current design approach the code is here: https://github.com/AlwaysGeeky/Qube/

[AlwaysGeeky]

Had to also do some fiddling around to share the nanovg context with my main application after nanogui is initialized and also write some code to handle mouse input between interacting with the GUI and also when not interacting with the GUI. (Since my application is an interactive 3d application so mouse controls usually control stuff like camera and movement, which you dont want to do when you are interacting with GUI widgets)

Screenshot:

[wjakob]

Thanks to the efforts of Stephen McDowell (@svenevs), we now have documentation including a getting started guide!

-> http://nanogui.readthedocs.io/en/latest/?badge=latest