[core] example 010 shows how to define a new user optional component

Author: alemuntoni

examples/core/010-mesh-new-user-component/bar_component.h

@@ -23,6 +23,8 @@
 #ifndef BAR_COMPONENT_H
 #define BAR_COMPONENT_H
 
+#include <vclib/concepts/const_correctness.h>
+#include <vclib/concepts/mesh/components/component.h>
 #include <vclib/mesh/components/bases/component.h>
 #include <vclib/types.h>
 
@@ -32,28 +34,27 @@
  * Due to the complexity of this class, VCLib provides a vcl::Component class
  * that can be used as a base class.
  *
- * In this example, the component stores two values: an integer that can be
- * accessed trough the member function `foo()`, and a double that can be
- * accessed trough the member function `bar()`.
+ * In this example, the component stores two values: a double that can be
+ * accessed trough the member function `bar()`, and a vector of uint that can be
+ * accessed trough the member function `barVector()`.
  */
 
 // a component needs a concept, that allows to test if other elements/meshes
 // have the same component.
 // the concept should just check if the element/mesh has the member functions
 // that are part of the component class.
 template<typename T>
-concept HasBarComponent = requires (T t, const T& ct) {
-    // accessor to the int value of the bar component, returns int&
-    { t.foo() } -> std::same_as<int&>;
-
-    // const accessor to the int value of the bar component
-    { ct.foo() } -> std::same_as<int>;
-
-    // accessor to the double value of the bar component, returns int&
-    { t.bar() } -> std::same_as<double&>;
-
-    // const accessor to the double value of the bar component
-    { ct.bar() } -> std::same_as<double>;
+concept HasBarComponent = requires (T&& obj) {
+    // accessors to the bar component, for const and non-const objects
+    { obj.bar() } -> std::convertible_to<double>;
+    { obj.barVector() } -> std::convertible_to<std::vector<uint>>;
+
+    // non const requirements
+    requires vcl::IsConst<T> || requires {
+        // non-const accessors, return references
+        { obj.bar() } -> std::same_as<double&>;
+        { obj.barVector() } -> std::same_as<std::vector<uint>&>;
+    };
 };
 
 // if you want, you can also define a concept that checks if an element has
@@ -65,17 +66,17 @@ concept HasOptionalColor =
 
 // define a constant uint that identifies the component (same idea used for
 // COMPONENT_ID in the FooComponent)
-inline static const uint BAR_COMPONENT = vcl::COMPONENTS_NUMBER + 0;
+inline static const uint BAR_COMPONENT = vcl::CompId::COMPONENTS_NUMBER + 1;
 
 namespace detail {
 
 // we wrap all the data stored by the component in a struct.
-// in this case we could use also a std::pair, but it doesn't matter
+// in this case we could use also a std::pair, but it doesn't matter.
 // the only important thing is to have all the data wrapped in a single type
 struct BarData
 {
-    int    foo;
     double bar;
+    std::vector<uint> barVector;
 };
 
 } // namespace detail
@@ -93,20 +94,26 @@ bool isBarComponentAvailableOn(const vcl::ElementOrMeshConcept auto& element);
 // we called it BarComponentT because BarComponent will be aliased without
 // template arguments later (and will be the horizontal component).
 //
-// template arguments are two:
-// - ElementType: void if the component will be horizontal, or the type of the
-//   Element that will have the component if vertical;
-// - OPTIONAL: true if the component will be optional. Will be valid only if
+// template arguments are three:
+// - ElementType: the type of the Element that will have the component (could
+//   be void if the component will always be horizontal and does not need to
+//   access the derived Element type)
+// - VERTICAL: true if the component will be vertical. Will be valid only if
 //   ElementType != void
+// - OPTIONAL: true if the component will be optional. Will be valid only if
+//   VERTICAL == true
 //
 // The class inherits from the vcl::comp::Component class, that has a list of
 // template arguments.
-template<typename ElementType = void, bool OPTIONAL = false>
+template<
+    typename ElementType = void,
+    bool VERTICAL        = false,
+    bool OPTIONAL        = false>
 class BarComponentT :
         public vcl::comp::Component<
 
             // CRTP: the first argument is always the component class itself
-            BarComponentT<ElementType, OPTIONAL>,
+            BarComponentT<ElementType, VERTICAL, OPTIONAL>,
 
             // ID of the component, same used in the FooComponent, but in this
             // case it is a template argument of the vcl::comp::Component class
@@ -119,16 +126,20 @@ class BarComponentT :
             // Same ElementType argument of the BarComponentT class
             ElementType,
 
+            // Same VERTICAL argument of the BarComponentT class
+            VERTICAL,
+
             // Same OPTIONAL argument of the BarComponentT class
             OPTIONAL>
 {
     // alias of the base vcl::comp::Component class - just for detail use
     // to access the member functions of the base class
     using Base = vcl::comp::Component<
-        BarComponentT<ElementType, OPTIONAL>,
+        BarComponentT<ElementType, VERTICAL, OPTIONAL>,
         BAR_COMPONENT,
         detail::BarData,
         ElementType,
+        VERTICAL,
         OPTIONAL>;
 
 public:
@@ -137,25 +148,28 @@ class BarComponentT :
     // we access the data stored by calling Base::data(). The returned type
     // is the same of the third template argument of the vcl::comp::Component
     // class -- in this case, detail::BarData
-    int& foo() { return Base::data().foo; }
-
-    int foo() const { return Base::data().foo; }
-
     double& bar() { return Base::data().bar; }
 
     double bar() const { return Base::data().bar; }
 
+    std::vector<uint>& barVector() { return Base::data().barVector; }
+
+    const std::vector<uint>& barVector() const
+    {
+        return Base::data().barVector;
+    }
+
 protected:
-    // first requirement: a protected `importFrom` member function
+    // the protected `importFrom` member function
     template<typename Element> // another element, maybe from another mesh type
     void importFrom(const Element& e, bool = true)
     {
         // will import the bar component from the element e only if it also has
         // the bar component
         if constexpr (HasBarComponent<Element>) { // compile time check
             if (isBarComponentAvailableOn(e)) {   // runtime check
-                foo() = e.foo();
                 bar() = e.bar();
+                barVector() = e.barVector();
             }
         }
     }
@@ -173,10 +187,14 @@ bool isBarComponentAvailableOn(const vcl::ElementOrMeshConcept auto& element)
 using BarComponent = BarComponentT<>; // horizontal component
 
 template<typename ElementType>
-using VerticalBarComponent = BarComponentT<ElementType>; // vertical component
+using VerticalBarComponent = BarComponentT<ElementType, true>; // vertical
 
 template<typename ElementType>
-using OptionalBarComponent = BarComponentT<ElementType, true>; // optional
+using OptionalBarComponent = BarComponentT<ElementType, true, true>; // optional
+
+static_assert(
+    vcl::comp::ComponentConcept<BarComponent>,
+    "Make sure that the BarComponent satisfies the ComponentConcept.");
 
 static_assert(
     HasBarComponent<BarComponent>,

examples/core/010-mesh-new-user-component/bar_mesh.h

@@ -0,0 +1,76 @@
+/*****************************************************************************
+ * VCLib                                                                     *
+ * Visual Computing Library                                                  *
+ *                                                                           *
+ * Copyright(C) 2021-2025                                                    *
+ * Visual Computing Lab                                                      *
+ * ISTI - Italian National Research Council                                  *
+ *                                                                           *
+ * All rights reserved.                                                      *
+ *                                                                           *
+ * This program is free software; you can redistribute it and/or modify      *
+ * it under the terms of the Mozilla Public License Version 2.0 as published *
+ * by the Mozilla Foundation; either version 2 of the License, or            *
+ * (at your option) any later version.                                       *
+ *                                                                           *
+ * This program is distributed in the hope that it will be useful,           *
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of            *
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the              *
+ * Mozilla Public License Version 2.0                                        *
+ * (https://www.mozilla.org/en-US/MPL/2.0/) for more details.                *
+ ****************************************************************************/
+
+#ifndef BAR_MESH_H
+#define BAR_MESH_H
+
+#include <vclib/mesh/mesh.h>
+#include <vclib/mesh/requirements.h>
+
+#include "bar_component.h"
+
+/*
+ * This file defines a BarMesh class that uses the optional BarComponent in the
+ * Vertex Element.
+ */
+
+class BarMesh;
+
+namespace barmesh {
+
+class Vertex;
+
+class Face;
+
+class Vertex :
+        public vcl::Vertex<
+            BarMesh,
+            vcl::vert::BitFlags,
+            vcl::vert::Coordinate3d,
+            vcl::vert::Normal3d,
+            vcl::vert::Color,
+            OptionalBarComponent<Vertex>> // the optional BarComponent
+{
+};
+
+class Face :
+        public vcl::Face<
+            BarMesh,
+            vcl::face::TriangleBitFlags,
+            vcl::face::TriangleVertexPtrs<Vertex, Face>,
+            vcl::face::Normal3d>
+{
+};
+
+} // namespace barmesh
+
+class BarMesh :
+        public vcl::Mesh<
+            vcl::mesh::VertexContainer<barmesh::Vertex>,
+            vcl::mesh::FaceContainer<barmesh::Face>,
+            vcl::mesh::BoundingBox3d>
+{
+public:
+    using ScalarType = double;
+};
+
+#endif // BAR_MESH_H

examples/core/010-mesh-new-user-component/foo_component.h

@@ -23,6 +23,8 @@
 #ifndef FOO_COMPONENT_H
 #define FOO_COMPONENT_H
 
+#include <vclib/concepts/const_correctness.h>
+#include <vclib/concepts/mesh/components/component.h>
 #include <vclib/types.h>
 
 /*
@@ -36,12 +38,15 @@
 // the concept should just check if the element/mesh has the member functions
 // that are part of the component class.
 template<typename T>
-concept HasFooComponent = requires (T t, const T& ct) {
-    // accessor to the foo component, returns int&
-    { t.foo() } -> std::same_as<int&>;
+concept HasFooComponent = requires (T&& obj) {
+    // accessor to the foo component, for const and non-const objects
+    { obj.foo() } -> std::convertible_to<int>;
 
-    // const accessor to the foo component
-    { ct.foo() } -> std::same_as<int>;
+    // non const requirements
+    requires vcl::IsConst<T> || requires {
+        // non-const accessor, returns int&
+        { obj.foo() } -> std::same_as<int&>;
+    };
 };
 
 // class of the Foo component
@@ -78,6 +83,21 @@ class FooComponent
     int data;
 };
 
+namespace vcl {
+
+// specialize the ComponentString for the FooComponent
+template<>
+struct ComponentString<FooComponent::COMPONENT_ID>
+{
+    const char* str = "FooComponent";
+};
+
+} // namespace vcl
+
+static_assert(
+    vcl::comp::ComponentConcept<FooComponent>,
+    "Make sure that the FooComponent satisfies the ComponentConcept.");
+
 static_assert(
     HasFooComponent<FooComponent>,
     "Make sure that the concept is satisfied with its component.");

examples/core/010-mesh-new-user-component/foo_mesh.h

@@ -27,6 +27,7 @@
 #include <vclib/mesh/requirements.h>
 
 #include "foo_component.h"
+#include "bar_component.h"
 
 /*
  * This file defines a FooMesh class that uses the FooComponent in the Vertex

examples/core/010-mesh-new-user-component/main.cpp

@@ -21,11 +21,13 @@
  ****************************************************************************/
 
 #include "foo_mesh.h"
+#include "bar_mesh.h"
 
 #include <vclib/meshes/tri_mesh.h>
 
 int main(int argc, char** argv)
 {
+    // A mesh with a Vertex that has a FooComponent
     FooMesh m;
 
     m.addVertices(10);
@@ -42,4 +44,27 @@ int main(int argc, char** argv)
 
     // reverse importFrom, to assert that everything builds correctly
     m.importFrom(tm);
+
+    // A mesh with a Vertex that has a optional BarComponent
+    BarMesh bm;
+
+    bm.addVertices(10);
+
+    // enable the bar component in the vertices
+    bm.enablePerElementComponent<vcl::ElemId::VERTEX, BAR_COMPONENT>();
+
+    for (auto& v : bm.vertices()) {
+        v.bar() = bm.index(v) + 42;
+        v.barVector() = {1, 2, 3};
+    }
+
+    for (auto& v : bm.vertices()) {
+        std::cout << "Vertex: " << v.index() << std::endl;
+        std::cout << "Bar: " << v.bar() << std::endl;
+        std::cout << "Bar vector: ";
+        for (auto i : v.barVector()) {
+            std::cout << i << ' ';
+        }
+        std::cout << std::endl;
+    }
 }

vclib/core/todo.md

@@ -62,3 +62,5 @@
   - [ ] look for a json header only library that is compatible with c++20 modules
 - Documentation:
   - [ ] How to implement a user component
+- Examples: 
+  - [ ] Create an example for new custom element (similar to 010-mesh-new-user-component)