Documenting

- Buffer_objects
- Edge_container
- Io_plugins
- Primitive_container
- Scene_group_item
- Scene_interface
- Scene_item
- Triangle_container
- Viewer Interface

Author: maxGimeno

Polyhedron/demo/Polyhedron/Edge_container.cpp

@@ -27,6 +27,8 @@ void Edge_container::initGL(const Scene_item& item, Viewer_interface *viewer) co
         VBOs[Indices] =
             new CGAL::Three::Vbo("indices",
                                  QOpenGLBuffer::IndexBuffer);
+      if(VAOs[viewer])
+        delete VAOs[viewer];
       VAOs[viewer] = new CGAL::Three::Vao(item.getShaderProgram(program_id, viewer));
       VAOs[viewer]->addVbo(VBOs[Vertices]);
       VAOs[viewer]->addVbo(VBOs[Indices]);

Polyhedron/demo/Polyhedron/resources/exit.png

@@ -85,7 +85,7 @@ private Q_SLOTS:
   }
   //! [action]
   //! [closure]
-  void closure()Q_DECL_OVERRIDE
+  void closure() Q_DECL_OVERRIDE
   {
     dock_widget->hide();
   }

Polyhedron/demo/Polyhedron/resources/menu.png

@@ -11,13 +11,21 @@ namespace CGAL {
 namespace Three {
 
 struct Vbo;
-
+//!
+//! \brief The Vao struct is a wrapper for the `QOpenGLVertexArrayObject`.
+//! They are context dependent, most of the time it means `Viewer` dependent.
+//!
 struct Vao{
 
   QOpenGLVertexArrayObject* vao;
   QOpenGLShaderProgram* program;
   std::vector<Vbo*> vbos;
-
+  //!
+  //! \brief Creates a `Vao`.
+  //! \param program the `QOpenGLShaderProgram` associated with this `Vao`.
+  //! \attention This must be called within a valid OpenGLContext.
+  //! Most of the time, initGL() functions are safe places to do so.
+  //!
   Vao( QOpenGLShaderProgram* program)
     :vao(new QOpenGLVertexArrayObject()),
       program(program)
@@ -30,25 +38,31 @@ struct Vao{
     delete vao;
   }
 
+  //!Adds a `Vbo` to the list of Vbos.
   void addVbo(Vbo* vbo)
   {
     vbos.push_back(vbo);
   }
 
+  //!Makes the `Vao` and its program active until `release()` is called.
   void bind()
   {
     program->bind();
     vao->bind();
   }
 
+  //!Makes the `Vao` and its program not active.
   void release()
   {
     vao->release();
     program->release();
   }
 };
 
-
+//!
+//! \brief The Vbo struct is a wrapper for the `QOpenGLBufferObject` item.
+//! It contains the data necessary for the rendering of any displayed entity.
+//! A Vbo can be shared between Vaos of the same context.
 struct Vbo
 {
 
@@ -62,7 +76,19 @@ struct Vbo
   int tupleSize;
   int stride;
   bool allocated;
-
+  //!
+  //! \brief Creates a `Vbo`.
+  //! \param attribute the name of the corresponding data in the shader.
+  //! \param vbo_type is almost always `QOpenGLBuffer::VertexBuffer` but can be `QOpenGLBuffer::IndexBuffer`
+  //! if it contains the indices for an indexed rendering.
+  //! \param data_type the GL data type. Mostly GL_FLOAT.
+  //! \param offset the offset in the buffer. See OpenGL documentation.
+  //! \param tupleSize the size of the tuple. If it contains vector_3s, then tuple_size is 3.
+  //! \param stride the stride for the buffer. See OpenGL documentation.
+
+  //! \attention This must be called within a valid OpenGLContext.
+  //! Most of the time, initGL() functions are safe places to do so.
+  //!
   Vbo(
       const char* attribute,
       QOpenGLBuffer::Type vbo_type = QOpenGLBuffer::VertexBuffer,
@@ -88,16 +114,23 @@ struct Vbo
     vbo.destroy();
   }
 
+  //! Makes the `Vbo` active until `release()` is called.
   bool bind()
   {
     return vbo.bind();
   }
 
+  //!Makes the `Vbo` and its program not active.
   void release()
   {
     vbo.release();
   }
 
+  //!
+  //! \brief allocate gives CPU data to the GPU.
+  //! \param data the content of the buffer.
+  //! \param datasize the number of bytes in `data`.
+  //!
   void allocate(void* data, int datasize)
   {
     this->data = data;

Three/demo/Three/Example_plugin/Dock_widget_plugin.cpp

@@ -37,26 +37,65 @@ using namespace CGAL::Three;
 namespace CGAL {
 namespace Three {
 
+//!
+//! \brief The Edge_container struct wraps the OpenGL data for drawing lines.
+//!
 struct DEMO_FRAMEWORK_EXPORT Edge_container :public Primitive_container
 {
 
+  //!
+  //! \brief The vbosName enum
+  //!
+  //! Holds the `Vbo` Ids of this container.
+  //!
   enum vbosName {
-    Vertices = 0,
-    Indices,
-    Normals,
-    Colors,
-    Radius,
-    Barycenters,
-    NbOfVbos
+    Vertices = 0, //! Designates the buffer that contains the vertex coordinates.
+    Indices, //! Designates the buffer that contains the vertex indices.
+    Normals, //! Designates the buffer that contains the normal coordinates.
+    Colors, //! Designates the buffer that contains the color components.
+    Radius, //! Designates the buffer that contains the radius of wire spheres.
+    Barycenters, //! Designates the buffer that contains the barycenter of c3t3 facets or the center of wire spheres, for example.
+    NbOfVbos //! Designates the size of the VBOs vector for `Edge_containers`s
   };
 
+  //!
+  //! \brief The constructor.
+  //! \param program is the `QOpenGLShaderProgram` that is used by this `Edge_container` `Vao`.
+  //! \param indexed must be `true` if the data is indexed, `false` otherwise. If `true`, VBOs[Indices] must be filled.
+  //!
     Edge_container(int program, bool indexed);
+
+    //!
+    //! \brief initGL creates the `Vbo`s and `Vao`s of this `Edge_container`.
+    //! \attention It must be called within a valid OpenGL context. The `draw()` function of an item is always a safe place to call this.
+    //!
+    //! \todo Is it a good idea to call InitGL of each item in the scene so the developper doesn't have to worry about this in each draw() of each item ?
+    //!
+    //! \param item the `Scene_item` that uses this `Edge_container`.
+    //! \param viewer the active `Viewer_interface`.
+    //!
     void initGL(const Scene_item &item, Viewer_interface *viewer) const Q_DECL_OVERRIDE;
+
+    //!
+    //! \brief draw is the function that actually renders the data.
+    //! \param item the `Scene_item` that uses this `Edge_container`.
+    //! \param viewer the active `Viewer_interface`.
+    //! \param is_color_uniform must be `false` if `VBOs`[`Colors`] is not empty, `true` otherwise.
+    //!
     void draw(const Scene_item &item, CGAL::Three::Viewer_interface* viewer,
               bool is_color_uniform,
               QOpenGLFramebufferObject* = NULL) const Q_DECL_OVERRIDE;
     //drawing variables
+    //!
+    //! \brief plane contains the coefficients of the plane used in some programs :
+    //! - `PROGRAM_CUTPLANE_SPHERES`
+    //! - `PROGRAM_C3T3_EDGES`
+    //!
     QVector4D plane;
+    //!
+    //! \brief f_matrix is a Matrix4x4 used in some programs:
+    //! - PROGRAM_WITHOUT_LIGHT
+    //!
     QMatrix4x4 f_matrix;
 }; //end of class Triangle_container
 }

Three/include/CGAL/Three/Buffer_objects.h

@@ -59,9 +59,16 @@ class Polyhedron_demo_io_plugin_interface
   //! Specifies if the io_plugin is able to load an item or not.
   //! This must be overriden.
   virtual bool canLoad() const = 0;
-  //!  Loads an item from a file.
-  //! This must be overriden.
-  virtual Scene_item* load(QFileInfo fileinfo, CGAL::Three::Scene_interface* scene, QMainWindow*) = 0;
+
+  //! \brief Loads an item from a file.
+  //!
+  //! //! This must be overriden.
+  //! \param fileinfo the path to the item file.
+  //! \param scene the `Scene_interface` that will hold the item. Mostly used for group_items.
+  //! \param mw the application `MainWindow`. Mostly used for getting the `is_polyhedron_mode` property.
+  //! \return the loaded `Scene_item`
+  //!
+  virtual Scene_item* load(QFileInfo fileinfo, CGAL::Three::Scene_interface* scene, QMainWindow* mw) = 0;
   //!Specifies if the io_plugin can save the item or not.
   //!This must be overriden.
   virtual bool canSave(const Scene_item*) = 0;

Three/include/CGAL/Three/Edge_container.h

@@ -38,9 +38,17 @@ class QOpenGLFramebufferObject;
 namespace CGAL {
 namespace Three {
 
+//!
+//! \brief The Primitive_container struct provides a base for the OpenGL data wrappers.
+//!
 struct DEMO_FRAMEWORK_EXPORT Primitive_container
 {
 
+  //!
+  //! \brief Primitive_container constructor.
+  //! \param program the `QOpenGLShaderProgram` used by the VAOs.
+  //! \param indexed must be `true` if the data is indexed, `false` otherwise.
+  //!
     Primitive_container(int program, bool indexed)
       : program_id(program), indexed(indexed),
         flat_size(0), idx_size(0)
@@ -56,17 +64,42 @@ struct DEMO_FRAMEWORK_EXPORT Primitive_container
         removeViewer(viewer);
       }
     }
+
+    //!
+    //! \brief initGL initializes the OpenGL containers.
+    //! \attention It must be called within a valid OpenGL context. The `draw()` function of an item is always a safe place to call this.
+    //!
+    //! \param item the `Scene_item` that uses this container.
+    //! \param viewer the active `Viewer_interface`.
     virtual void initGL(const CGAL::Three::Scene_item& item, CGAL::Three::Viewer_interface* viewer) const = 0;
+
+    //!
+    //! \brief removeViewer deletes and removes the Vao assigned to `viewer` from `Vaos`.
+    //! \param viewer the `Viewer_interface` to remove.
+    //!
     void removeViewer(CGAL::Three::Viewer_interface* viewer) const
     {
       delete VAOs[viewer];
       VAOs.remove(viewer);
     }
 
+    //!
+    //! \brief draw is the function that actually renders the data.
+    //! \param item the `Scene_item` that uses this container.
+    //! \param viewer the active `Viewer_interface`.
+    //! \param is_color_uniform should be `true` if the item is unicolor.
+    //! \param fbo holds the texture that is used for transparency.
+    //!
     virtual void draw(const Scene_item &item, CGAL::Three::Viewer_interface* viewer,
                       bool is_color_uniform,
                       QOpenGLFramebufferObject* fbo = NULL) const = 0;
 
+    //!
+    //! \brief initializeBuffers sends the data to the GPU memory.
+    //!
+    //! It actually fills up the buffers with the data provided by `Vbo::allocate()`;
+    //! \param viewer the active `Viewer_interface`.
+    //!
     void initializeBuffers(CGAL::Three::Viewer_interface* viewer) const
     {
       if(!VAOs[viewer])
@@ -102,6 +135,9 @@ struct DEMO_FRAMEWORK_EXPORT Primitive_container
       is_init[viewer] = true;
     }
 
+    //!
+    //! \brief reset_vbos de-allocates the `Vbo`s. It must be called when the `Vbo`s data is updated.
+    //!
     void reset_vbos()
     {
       Q_FOREACH(CGAL::Three::Vbo* vbo, VBOs)
@@ -112,16 +148,46 @@ struct DEMO_FRAMEWORK_EXPORT Primitive_container
       }
     }
 
+    //!
+    //! \brief VAOs holds the `Vao`s for each `Viewer_interface`. As a `Vao` is context dependent, there must be one Vao for each `Viewer_interface`.
+    //!
     mutable QMap<CGAL::Three::Viewer_interface*, Vao*> VAOs;
+    //!
+    //! \brief VBOs holds the `Vbo`s containing the data for this container.
+    //!
     mutable std::vector<Vbo*> VBOs;
+    //!
+    //! \brief program_id is the `OpenGL_program_IDs` used with this container.
+    //!
     int program_id;
+    //!
+    //! \brief indexed specifies if the data is indexed or not. This matters for the internal drawing functions.
+    //!
     bool indexed;
     mutable QMap<CGAL::Three::Viewer_interface*, bool> is_init;
     mutable QMap<CGAL::Three::Viewer_interface*, bool> is_gl_init;
+
+    //!
+    //! \brief is_selected must be filled with the selected state of the item that holds this container everytime this state changes.
+    //! If program_id doesn't use this property, it can be ignored.
+    //!
     mutable bool is_selected;
+    //!
+    //! \brief flat_size contains the number of units contained in the vertex buffer.
+    //! You can ignore it if `indexed` is true.
+    //!
     mutable std::size_t flat_size;
+    //! \brief flat_size contains the number of units contained in the barycenter buffer.
+    //! You can ignore it if `program_id` is not an instanced program (like PROGRAM_SPHERES, PROGRAM_CUTPLANE_SPHERES,
+    //! PROGRAM_INSTANCED_WIRE or PROGRAM_INSTANCED).
     mutable std::size_t center_size;
+    //!
+    //! \brief idx_size contains the number of indices in an `Index_buffer`. You can ignore it if `indexed` is `false`.
+    //!
     mutable std::size_t idx_size;
+    //!
+    //! \brief color contains the color of the data. Ignore it if `is_color_uniform` is `false` in `draw()`.
+    //!
     mutable QColor color;
 }; //end of class Triangle_container
 

Three/include/CGAL/Three/Polyhedron_demo_io_plugin_interface.h

@@ -47,6 +47,11 @@ class DEMO_FRAMEWORK_EXPORT Scene_group_item : public Scene_item
 {
     Q_OBJECT
 public :
+  //!
+  //! \brief The `Scene_group_item` constructor.
+  //! \param name The name of this item.
+  //! \param scene the scene that will hold this item.
+  //!
     Scene_group_item(QString name,Scene_interface *scene);
     ~Scene_group_item() {}
     //!Sets the scene;
@@ -122,23 +127,20 @@ public :
     ///@{
     //!\brief draws all the children
     //!
-    //! Calls `Scene_item::draw()`, then calls `Scene_item::drawEdges()`
-    //! and `Scene_item::drawPoints` for each child if its current
+    //! Calls `Scene_item::draw()`for each child if its current
     //! rendering mode is adequat.
     //! @see #RenderingMode
     virtual void draw(CGAL::Three::Viewer_interface*, int pass,
                       bool is_writing, QOpenGLFramebufferObject*fbo) const;
     //!\brief draws all the children
     //!
-    //! Calls `Scene_item::drawEdges()`, then calls `Scene_item::draw()`
-    //! and `Scene_item::drawPoints` for each child if its current
+    //! Calls `Scene_item::drawEdges()`for each child if its current
     //! rendering mode is adequat.
     //! @see #RenderingMode
     virtual void drawEdges(CGAL::Three::Viewer_interface*) const;
     //!\brief draws all the children
     //!
-    //! Calls `Scene_item::drawPoints()`, then calls `Scene_item::draw()`
-    //! and `Scene_item::drawEdges()` for each child if its current
+    //! Calls `Scene_item::drawPoints()`for each child if its current
     //! rendering mode is adequat.
     //! @see #RenderingMode
     virtual void drawPoints(CGAL::Three::Viewer_interface*) const;
@@ -224,6 +226,10 @@ public :
     void moveDown(int);
 
 public Q_SLOTS:
+    //!
+    //! \brief adjustIds maintains the list of children up to date when an item has been erased.
+    //! \param removed_id the index of the item that has been erased.
+    //!
     void adjustIds(Scene_interface::Item_id removed_id)
     {
       for(int i = 0; i < children.size(); ++i)

Three/include/CGAL/Three/Primitive_container.h

@@ -129,6 +129,9 @@ class Scene_interface {
   virtual Item_id selectionBindex() const = 0;
 
   //!\brief The scene's Bbox
+  //!\param all detemines if the items that are not visible
+  //! should be taken into account in the resulting Bbox.
+  //! `true` means they should.
   //!@returns the scene's bounding box
   //! @see Scene_interface::Bbox
   virtual Bbox bbox(bool all = false) const = 0;