Add documentation

Use GraphicsAPI instead of CurrentGraphicsAPI

Signed-off-by: Matias N. Goldberg <dark_sylinc@yahoo.com.ar>

src/plugins/minimal_scene/EngineToQtInterface.cc

@@ -17,6 +17,7 @@
 
 #include "EngineToQtInterface.hh"
 
+#include <ignition/common/Console.hh>
 #include <ignition/rendering/Camera.hh>
 #include <ignition/rendering/RenderEngine.hh>
 
@@ -31,7 +32,7 @@ namespace gui
 {
 namespace plugins
 {
- /// \brief Private data class for IgnRenderer
+ /// \brief Private data class for EngineToQtInterfacePrivate
  class EngineToQtInterfacePrivate
  {
  /// \brief FBO texture. Stores uploaded GPU -> CPU.
@@ -41,6 +42,8 @@ namespace plugins
  /// \brief Stores downloaded GPU -> CPU. Used only during fallback
  public: ignition::rendering::ImagePtr fallbackImage;
 
+ /// \brief Qt's OpenGL context. Used only during fallback.
+ /// We need it to render using Qt's context.
  public: QOpenGLContext *glContext = nullptr;
  };
 }
@@ -53,9 +56,9 @@ using namespace gui;
 using namespace plugins;
 
 /////////////////////////////////////////////////
-EngineToQtInterface::EngineToQtInterface(QOpenGLContext *_glContext)
+EngineToQtInterface::EngineToQtInterface(QOpenGLContext *_glContext) :
+ dataPtr(std::make_unique<EngineToQtInterfacePrivate>())
 {
- this->dataPtr.reset(new EngineToQtInterfacePrivate);
  this->dataPtr->glContext = _glContext;
 }
 
@@ -68,6 +71,17 @@ EngineToQtInterface::~EngineToQtInterface()
 /////////////////////////////////////////////////
 void EngineToQtInterface::CreateFallbackTexture()
 {
+ static bool bWarnedOnce = false;
+
+ if (!bWarnedOnce)
+ {
+ ignwarn
+ << "Using fallback method to render to Qt. Things will be SLOW.\n"
+ "Try another API (e.g. OpenGL vs Vulkan) or build against a newer "
+ "Qt version\n";
+ bWarnedOnce = true;
+ }
+
  this->DestroyFallbackTexture();
 
  IGN_ASSERT(this->dataPtr->fallbackTexture == 0, "Invalid State!");
@@ -109,10 +123,8 @@ void EngineToQtInterface::DestroyFallbackTexture()
 bool EngineToQtInterface::NeedsFallback(ignition::rendering::CameraPtr &_camera)
 {
  auto *renderEngine = _camera->Scene()->Engine();
- if (renderEngine->CurrentGraphicsAPI() !=
- ignition::rendering::GraphicsAPI::OPENGL &&
- renderEngine->CurrentGraphicsAPI() !=
- ignition::rendering::GraphicsAPI::METAL)
+ if (renderEngine->GraphicsAPI() != ignition::rendering::GraphicsAPI::OPENGL &&
+ renderEngine->GraphicsAPI() != ignition::rendering::GraphicsAPI::METAL)
  {
  return true;
  }

src/plugins/minimal_scene/EngineToQtInterface.hh

@@ -33,6 +33,34 @@ namespace plugins
  class EngineToQtInterfacePrivate;
 
  /// \brief
+ ///
+ /// This class is in charge of delivering data to Qt in a format
+ /// it can understand.
+ ///
+ /// Ideally, this is a simple call. e.g. if Qt wants an OpenGL
+ /// texture handle, and we're rendering to a texture; we simply
+ /// give Qt the texture handle (i.e. that's what
+ /// ignition::rendering::Camera::RenderTextureGLId does)
+ ///
+ /// If Qt wants an OpenGL texture handle, and we're rendering to Metal,
+ /// ask Metal to convert it to an OpenGL handle and give it that.
+ ///
+ /// However there are cases where this isn's so straightforward, either
+ /// because the API doesn't have an interface for converting handles
+ /// between rendering systems, the underlying engine (i.e. Ogre) hasn't
+ /// yet implemented it, or simply because there's a lot of driver bugs
+ /// around it.
+ ///
+ /// Or perhaps the Qt version being compiled against is too old and doesn't
+ /// have support (e.g. Qt is too old to have a Vulkan renderer mode or it's
+ /// buggy)
+ ///
+ /// For all these cases, we use a fallback method where we download the
+ /// data from GPU into CPU and then upload it again to GPU using Qt's OpenGL.
+ ///
+ /// This is slow, but it's almost certain guaranteed to work.
+ /// A warning will be issued once when fallback is used, as it has
+ /// an important performance impact.
  class EngineToQtInterface
  {
  /// \brief Constructor
@@ -41,13 +69,19 @@ namespace plugins
  /// \brief Destructor
  public: ~EngineToQtInterface();
 
+ /// \brief Creates the fallback OpenGL texture we will be
+ /// giving to Qt
  private: void CreateFallbackTexture();
 
+ /// \brief Destroys the texture created by CreateFallbackTexture
  private: void DestroyFallbackTexture();
 
  /// \brief
- /// \param[in] _camera
- /// \return
+ /// Returns the texture handle that Qt wants, whether it's the
+ /// fallback or native one
+ /// \param[in] _camera The camera doing rendering that should be shown
+ /// on Qt
+ /// \return Texture handle for Qt
  public: GLuint TextureId(ignition::rendering::CameraPtr &_camera);
 
  /// \brief