more docs

docs/algorithms.rst

@@ -201,6 +201,8 @@ An incomplete collection of algorithms that reorder the internal memory layout t
 .. doxygenfunction:: polymesh::optimize_for_vertex_traversal
 
 
+.. _algo-triangulation:
+
 Triangulation
 -------------
 

docs/conf.py

@@ -56,6 +56,8 @@ pygments_style = 'sphinx'
 primary_domain = "cpp"
 highlight_language = "cpp"
 
+todo_include_todos = True
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for

docs/cookbook.rst

@@ -4,6 +4,8 @@ Polymesh Cookbook
 This chapter collects various simple recipes and samples that answer common "How do I do XYZ?" questions.
 `Typed Geometry <https://graphics.rwth-aachen.de:9000/ptrettner/typed-geometry>`_ is used as math library.
 
+.. note:: Many examples are already given in the :doc:`algorithms` and  :doc:`objects` chapters.
+
 
 Loading a Mesh from a File
 --------------------------

docs/faq.rst

@@ -8,3 +8,20 @@ FAQ
         #include <polymesh/properties.hh>
 
         pm::halfedge_handle h = pm::halfedge_from_to(v_from, v_to);
+
+
+.. topic:: How do I get the (numerical) index of a vertex / edge / face / halfedge?
+
+    ::
+
+        pm::vertex_handle v = ...;
+        int idx = int(v); // explicit conversion
+
+
+.. topic:: How do I get a handle given the (numerical) index?
+
+    ::
+
+        pm::Mesh m;
+        int idx = ...;
+        pm::vertex_handle v = m.vertices()[idx];

docs/misc.rst

@@ -4,7 +4,23 @@ Misc
 Assertions
 ----------
 
-TODO
+::
+
+    #include <polymesh/assert.hh>
+
+    POLYMESH_ASSERT(1 + 2 == 3);
+
+These assertions are a slightly improved version of the `C++ Assertions <https://en.cppreference.com/w/cpp/error/assert>`_.
+By default, they are available in ``Debug`` and in ``Release with Debug Info`` modes, only disabled in a pure ``Release``.
+Using ``unlikely`` and ``cold`` functions, each assertion has minimal impact on the non-error code path.
+The only overhead is evaluating the condition and a single, perfectly predicted conditional branch.
+The assembly for the "assertion failed" path is generated outside of the usual function code.
+
+Behavior on assertion failure can be customized using:
+
+.. doxygenfunction:: polymesh::set_assertion_handler
+
+
 
 .. _simple-graphs-ref:
 

docs/objects.rst

 Objects
 =======
 
-TODO
+The headers located in ``polymesh/objects/*`` or included by ``polymesh/objects.hh`` contain built-in objects that can be added to a polymesh.
+As these objects may not be piecewise linear, they tend to include tessellation factors.
+Many objects generated quads, not triangles.
+See :ref:`algo-triangulation` if you need a triangle mesh.
+
+A reference of all built-in objects can be found in :ref:`objects-ref`.
+
+.. note:: the collection of objects still has many missing / improvable parts. :doc:`contributing` is heavily welcome.
+
+
+Quad
+----
+
+A regularly subdivided quad.
+
+::
+
+    #include <polymesh/objects/quad.hh>
+
+    pm::Mesh m;
+    auto pos = m.vertices().make_attribute<tg::pos3>();
+
+    // creates a 32x32 quad from xz coordinates -1..1
+    pm::objects::add_cube(m, [&](pm::vertex_handle v, float x, float y) {
+        pos[v] = {x * 2 - 1, 0, y * 2 - 1};
+    }, 32, 32);
+
+.. doxygenfunction:: polymesh::objects::add_quad
+
+
+Cube
+----
+
+A simple cube consisting of 6 quads.
+
+::
+
+    #include <polymesh/objects/cube.hh>
+
+    pm::Mesh m;
+    auto pos = m.vertices().make_attribute<tg::pos3>();
+
+    // create cube from -1..1
+    pm::objects::add_cube(m, [&](pm::vertex_handle v, float x, float y, float z) {
+        pos[v] = tg::pos3(x, y, z) * 2 - 1;
+    });
+
+.. doxygenfunction:: polymesh::objects::add_cube(Mesh&, CubeF&&)
+
+.. doxygenfunction:: polymesh::objects::add_cube(Mesh&, vertex_attribute<Pos3>&)
+
+
+Sphere
+------
+
+A UV Sphere consisting of rings of quads and two rings of triangles (for top and bottom).
+
+::
+
+    #include <polymesh/objects/uv_sphere.hh>
+
+    pm::Mesh m;
+    auto pos = m.vertices().make_attribute<tg::pos3>();
+
+    // create a unit sphere (using 32 rings in each dir)
+    pm::objects::add_uv_sphere(m, [&](pm::vertex_handle v, float x, float y) {
+        auto [sx, cx] = tg::sin_cos(360_deg * x);
+        auto [sy, cy] = tg::sin_cos(180_deg * y);
+        pos[v] = {
+            sy * cx,
+            cy,
+            sy * sx
+        };
+    }, 32, 32);
+
+.. doxygenfunction:: polymesh::objects::add_uv_sphere
+
+
+Cylinder
+--------
+
+A regularly subdivided cylinder, optionally with caps.
+
+::
+
+    #include <polymesh/objects/cylinder.hh>
+
+    pm::Mesh m;
+    auto pos = m.vertices().make_attribute<tg::pos3>();
+
+    // create a unit cylinder (using 32 segments, with caps)
+    pm::objects::add_cylinder(m, [&](pm::vertex_handle v, float x, float y) {
+        auto [sx, cx] = tg::sin_cos(360_deg * x);
+        pos[v] = {sx, y * 2 - 1, cx};
+    }, 32, true);
+
+.. doxygenfunction:: polymesh::objects::add_cylinder
+
+
+Cone
+----
+
+A regularly subdivided cone, optionally with a base cap.
+
+::
+
+    #include <polymesh/objects/cone.hh>
+
+    pm::Mesh m;
+    auto pos = m.vertices().make_attribute<tg::pos3>();
+
+    // create a unit cone (using 32 segments, with base cap)
+    pm::objects::add_cone(m, [&](pm::vertex_handle v, float x, float y) {
+        auto [sx, cx] = tg::sin_cos(360_deg * x);
+        pos[v] = {sx, y, cx};
+    }, 32, true);
+
+.. doxygenfunction:: polymesh::objects::add_cone
+
+
+.. todo:: add graphical examples of the objects
\ No newline at end of file

docs/reference.rst

@@ -263,6 +263,24 @@ Algorithms
 
 .. doxygenfunction:: polymesh::decimate_up_to_error
 
+.. _objects-ref:
+
+Objects
+-------
+
+.. doxygenfunction:: polymesh::objects::add_quad
+
+.. doxygenfunction:: polymesh::objects::add_cube(Mesh&, CubeF&&)
+
+.. doxygenfunction:: polymesh::objects::add_cube(Mesh&, vertex_attribute<Pos3>&)
+
+.. doxygenfunction:: polymesh::objects::add_uv_sphere
+
+.. doxygenfunction:: polymesh::objects::add_cylinder
+
+.. doxygenfunction:: polymesh::objects::add_cone
+
+
 
 Low-Level API
 -------------

src/polymesh/objects/cube.hh

@@ -14,7 +14,7 @@ namespace objects
 template <class CubeF>
 auto add_cube(Mesh& m, CubeF&& cf) -> decltype(cf(vertex_handle{}, int{}, int{}, int{}), vertex_handle{});
 
-/// same as before but directly fills a position attribute
+/// same as add_cube but directly fills a position attribute
 template <class Pos3>
 auto add_cube(Mesh& m, vertex_attribute<Pos3>& pos) -> vertex_handle;