Merge pull request #717 from maxGimeno/Document_the_programs

Polyhedron_Demo : Documentation update

Three/include/CGAL/Three/Scene_item.h

@@ -53,18 +53,26 @@ class SCENE_ITEM_EXPORT Scene_item : public QObject {
   Q_ENUMS(RenderingMode)
   Q_PROPERTY(RenderingMode renderingMode READ renderingMode WRITE setRenderingMode)
 public:
-  enum OpenGL_program_IDs { PROGRAM_WITH_LIGHT,
+ /*!
-                            PROGRAM_WITHOUT_LIGHT,
+   * \brief The OpenGL_program_IDs enum
-                            PROGRAM_NO_SELECTION,
+   * This enum holds the OpenGL programs IDs that are given to getShaderProgram() and attrib_buffers().
-                            PROGRAM_WITH_TEXTURE,
+   *@see getShaderProgram
-                            PROGRAM_PLANE_TWO_FACES,
+   * @see attrib_buffers
-                            PROGRAM_WITH_TEXTURED_EDGES,
+   */
-                            PROGRAM_INSTANCED,
+ enum OpenGL_program_IDs
-                            PROGRAM_INSTANCED_WIRE,
+ {
-                            PROGRAM_C3T3,
+  PROGRAM_WITH_LIGHT = 0,      /** Used to render a surface or edge affected by the light. It uses a per fragment lighting model, and renders brighter the selected item.*/
-                            PROGRAM_C3T3_EDGES,
+  PROGRAM_WITHOUT_LIGHT,       /** Used to render a polygon edge or points. It renders in a uniform color and is not affected by light. It renders the selected item in black.*/
-                            NB_OF_PROGRAMS };
+  PROGRAM_NO_SELECTION,        /** Used to render a polyline or a surface that is not affected by light, like a cutting plane. It renders in a uniform color that does not change with selection.*/
-
+  PROGRAM_WITH_TEXTURE,        /** Used to render a textured polyhedron. Affected by light.*/
+  PROGRAM_PLANE_TWO_FACES,     /** Used to render a two-faced plane. The two faces have a different color. Not affected by light.*/
+  PROGRAM_WITH_TEXTURED_EDGES, /** Used to render the edges of a textured polyhedorn. Not affected by light.*/
+  PROGRAM_INSTANCED,           /** Used to display instanced rendered spheres.Affected by light.*/
+  PROGRAM_INSTANCED_WIRE,      /** Used to display instanced rendered wired spheres. Not affected by light.*/
+  PROGRAM_C3T3,                /** Used to render a c3t3_item. It discards any fragment on a side of a plane, meaning that nothing is displayed on this side of the plane. Affected by light.*/
+  PROGRAM_C3T3_EDGES,          /** Used to render the edges of a c3t3_item. It discards any fragment on a side of a plane, meaning that nothing is displayed on this side of the plane. Not affected by light.*/
+  NB_OF_PROGRAMS               /** Holds the number of different programs in this enum.*/
+ };
   typedef CGAL::Three::Scene_interface::Bbox Bbox;
   typedef qglviewer::ManipulatedFrame ManipulatedFrame;
   //! The default color of a scene_item.

Three/include/CGAL/Three/Viewer_interface.h

@@ -43,17 +43,26 @@ class VIEWER_EXPORT Viewer_interface : public QGLViewer, public QOpenGLFunctions
   Q_OBJECT
 
 public:
-  enum OpenGL_program_IDs { PROGRAM_WITH_LIGHT,
+ /*!
-                            PROGRAM_WITHOUT_LIGHT,
+   * \brief The OpenGL_program_IDs enum
-                            PROGRAM_NO_SELECTION,
+   * This enum holds the OpenGL programs IDs that are given to getShaderProgram() and attrib_buffers().
-                            PROGRAM_WITH_TEXTURE,
+   *@see getShaderProgram
-                            PROGRAM_PLANE_TWO_FACES,
+   * @see attrib_buffers
-                            PROGRAM_WITH_TEXTURED_EDGES,
+   */
-                            PROGRAM_INSTANCED,
+  enum OpenGL_program_IDs
-                            PROGRAM_INSTANCED_WIRE,
+  {
-                            PROGRAM_C3T3,
+   PROGRAM_WITH_LIGHT = 0,      /** Used to render a surface or edge affected by the light. It uses a per fragment lighting model, and renders brighter the selected item.*/
-                            PROGRAM_C3T3_EDGES,
+   PROGRAM_WITHOUT_LIGHT,       /** Used to render a polygon edge or points. It renders in a uniform color and is not affected by light. It renders the selected item in black.*/
-                            NB_OF_PROGRAMS };
+   PROGRAM_NO_SELECTION,        /** Used to render a polyline or a surface that is not affected by light, like a cutting plane. It renders in a uniform color that does not change with selection.*/
+   PROGRAM_WITH_TEXTURE,        /** Used to render a textured polyhedron. Affected by light.*/
+   PROGRAM_PLANE_TWO_FACES,     /** Used to render a two-faced plane. The two faces have a different color. Not affected by light.*/
+   PROGRAM_WITH_TEXTURED_EDGES, /** Used to render the edges of a textured polyhedorn. Not affected by light.*/
+   PROGRAM_INSTANCED,           /** Used to display instanced rendered spheres.Affected by light.*/
+   PROGRAM_INSTANCED_WIRE,      /** Used to display instanced rendered wired spheres. Not affected by light.*/
+   PROGRAM_C3T3,                /** Used to render a c3t3_item. It discards any fragment on a side of a plane, meaning that nothing is displayed on this side of the plane. Affected by light.*/
+   PROGRAM_C3T3_EDGES,          /** Used to render the edges of a c3t3_item. It discards any fragment on a side of a plane, meaning that nothing is displayed on this side of the plane. Not affected by light.*/
+   NB_OF_PROGRAMS               /** Holds the number of different programs in this enum.*/
+  };
 
   Viewer_interface(QWidget* parent) : QGLViewer(CGAL::Qt::createOpenGLContext(), parent) {}
   virtual ~Viewer_interface() {}
@@ -74,18 +83,13 @@ public:
 
   /*! Passes all the uniform data to the shaders.
    * According to program_name, this data may change.
+   * @see OpenGL_program_IDs
    */
   virtual void attrib_buffers(int program_name) const = 0;
 
   /*! Returns a program according to name.
    * If the program does not exist yet, it is created and stored in shader_programs.
-   * name cans be :
+   * @see OpenGL_program_IDs
-   * - PROGRAM_WITH_LIGHT : used for the facets
-   * - PROGRAM_WITHOUT_LIGHT : used for the points and lines
-   * - PROGRAM_WITH_TEXTURE : used for textured facets
-   * - PROGRAM_WITH_TEXTURED_EDGES : use dfor textured edges
-   * - PROGRAM_INSTANCED : used for items that have to be rendered numerous times(spheres)
-   * - PROGRAM_INSTANCED_WIRE : used for the wireframe mode of PROGRAM_INSTANCED
    * @returns a pointer to the corresponding program.*/
   virtual QOpenGLShaderProgram* getShaderProgram(int name) const = 0;