Commit b34ab30e authored by Philip Trettner's avatar Philip Trettner
Browse files

more docs

parent 5f3fb12e
......@@ -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
-------------
......
......@@ -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
......
......@@ -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
--------------------------
......
......@@ -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];
......@@ -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:
......
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
......@@ -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
-------------
......
......@@ -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;
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment