Announcing vsgQt - a library for integration VulkanSceneGraph with Qt Windowing

[Robert Osfield]

HI All,

One of the tasks I've been juggling over the past week has been creating vsgQt - a library for integrating VulkanSceneGraph with Qt Windowing.

   https://github.com/vsg-dev/vsgQt

It's C++17, CMake, and MIT licenses, and hosted on github.com/vsg-dev just like the rest of VulkanSceneGraph family.

vsgQt library builds upon the initial work on vsgQtViewer done by Andre Normann, and taking on board refinements done in the various forks of vsgQtViewer.  vsgQt differs in that it's been in parts restructured and rewritten to work as a library that you can customize the set up and rendering using vsg::Viewer to do the actual rendering.

There is only one example, vsgqtviewer, so far that mirrors a subset of what vsgviewer does, it's entirely C++.

I'm not a Qt expert, I've learned what was required from the vsgQtViewer and the various forks.  I still have more to learn, and more functionality to add to vsgQt, and more examples to write to illustrate different usage cases.  

I welcome input from the community on further improving/debugging vsgQt, and porting to various platforms.  So far I've tested under Linux. but hopefully it should be relatively straight forward to get working under Windows and macOS.

On the debugging front, if you run vsgqtviewer with the Vulkan debug layer, enabled with -d command line option, there are some debug errors  relating to renderArea and destruction of VkSwapchain after the VkSurface has been destructed. 

The later problem looks due to Qt destroying the VkSurface it manages before the QWindow/vsgQt::ViewerWidow destructor gets called.  I presume there must be some clean up convention that Qt uses that I'm note yet aware of.

Thanks to Andre, Oleg and Ralf for their work on the various forks of vsgQtViewer, this was all very useful in creation of vsgQt.

Cheers,

Robert.

[Robert Osfield]

Hi All,

Since the announcement of vsgQt last week I've been busy generalizing the implementation and making fixes. 

   https://github.com/vsg-dev/vsgQt

The biggest change is support for Qt5 versions prior to 5.10, which means versions before Vulkan support was added.  This is achieved by providing a different vsgQt::ViewerWindow setup path that uses the VSG's native windowing integration to provide the required vkSurface, rather than adapting one created by Qt as previously done in vsgQt.  The original QSuface based code path is still available, so if you compiling against Qt 5.10 or later than you can select between the two backends by calling:

   viewerWindow->setSurfaceType(QSurface::VulkanSurface);

For Qt versions prior to 5.10 there is no QSurface::VulkanSurface enum so this won't compile.  To help application code decide what code path is suported the include/vsgQt/ViewerWindow.h provides the #define:

    #define QT_HAS_VULKAN_SUPPORT (QT_VERSION >= QT_VERSION_CHECK(5, 10, 0))

In the vsgQt/examples/vsgqtviewer/main.cpp example it protects this call thus:

  auto* viewerWindow = new vsgQt::ViewerWindow();

   #if QT_HAS_VULKAN_SUPPORT
   // if required set the QWindow's SurfaceType to QSurface::VulkanSurface.
   if (useQtSurface) viewerWindow->setSurfaceType(QSurface::VulkanSurface);
   #endif

If you application always compiles against 5.10 or later than these extra checks won't be required.

To aid testing I've added a --vsg command line option to the vsgqtviewer example to allow you to toggle between which backend you want to use.

     vsgqtviewer models/lz.vsgt --vsg  # Use VSG's windowing integration to create the platform specific vk/vsg::Surface

     vsgqtviewer models/lz.vsgt # Use QWindow to create set up vkSurface and pass this to vsg::Surface

Which building against Qt versions older than 5.10 you'll have the vsg::Surface code path. so there is no command line toggling between the two.

Visually the two backends behave the same, and the public API and usage of vsgQt::ViewerWindow is identical, the ABI of vsgQt for the two variants is also the same.

--

The is gotcha though... I am only implemented the window inheritance required for the VSG created vsg::Surface codepath for Xcb_Widnow.cpp.  I don't have Windows or maxOS systems available to me, and I have no expertise with either Win32 or macOS windowing APIs so I need members of the VSG community with access to these platforms to pitch in a update the VulkanSceneGraph/src/vsg/platforms/win32/Win32_Window.cpp and VulkanSceneGraph/src/vsg/platforms/macOS/macOS_Window.mm to support inheriting the native Window created by Qt and passed into the vsg::Window:create(vsg::WindowTraits*) method. 

The work I did on implementing support for inheriting native Window's via WindowTraits.nativeWindow and WindowTraits.systemConnection is essentially bypassing the normal xcb_connection and xcb window creation found in the Xcb_Window constructor.  My expectation is something similar will be required for Win32_Window.cpp and MacOS_Window.mm.  The commit with the changes to Xcb_Window.cpp is:

    https://github.com/vsg-dev/VulkanSceneGraph/commit/e60868fc7e3c833736371dbe5ae233827da627e2

As well as modifications to the respective constructors the Win32_Window and MacOS_Window classes will also need to implement the new Window::releaseWindow() and releaseConnection() methods that simply reset the respective internal variables use to track the associated Windowing resources so that they aren't deleted in the respective destructors.  This release of the resources is required as Qt (or other Windowing toolkit) will be doing the creation and deletion of the resources so the Window::release*() methods avoid the *_Window destructors from doing a double deletion.

--

Another change since last week is that I have added Surface::release() method to reset the local vkSurface variable to null to prevent the vsg::Surface destructor from deleting the Vulkan Surface object, again as Qt will be doing this. This change allows us to dispense with the vsgQt::ProxySurface class that vsgQt originally had to tackle this issue.

In the same vein I've implemented a general purpose vsg::WindowAdapter subclass from vsg::Window that enables 3rd party created windows to be used with vsg::Viewer etc. without need for creating a platform specific Xcb_Window etc.  For those familiar with the OpenSceneGraph, this is similar in principle with osgViewer::GraphicsWindowEmbedded, and opens the door to more than just adapting Qt windows.  The new vsg::WindowAdapter replaces vsgQt::ProxyWindow usage. 

With these two new classes in the core VulkanSceneGraph the vsgQt headers are now simplified down to just the ViewerWindow and KeyboardMap classes.  This should avoid confusion and misuse.

--

All these changes together move osgQt substantially closer to a form that should be useable in real-world applications.  No doubt there will still be much more work to do as we start using vsgQt for different usage cases, I'll be pushing on with some of these usage cases, but I expect the community to push it even hard - especially as I'm still a Qt newbie.

Thanks in advance for your help refining the missing elements of VulkanSceneGraph/vsgQt.

Robert.