Commit 114d531c authored by Philip Trettner's avatar Philip Trettner
Browse files

more documentation work

parent 63532be3
Contributing
============
Function parameter order guide
How to Build the Documentation
------------------------------
* navigate to ``docs/``
* execute ``doxygen`` to generate from-source part of the documentation
* execute ``make html`` to build the Sphinx docs
* open ``docs/_build/index.html``
Function Parameter Order Guide
------------------------------
The following types of parameters exist:
......
......@@ -50,9 +50,30 @@ Assuming that polymesh was cloned or copied into ``extern/polymesh``, the follow
A math library is optional but recommended (see :doc:`vector-math`).
Philosophy
----------
Polymesh provides a mesh data structure (:class:`polymesh::Mesh`) that contains and manages the mesh topology in a half-edge data structure (see :doc:`mesh-topology`).
A mesh has no positions or normals, no attributes in general.
Instead, attributes are separate value types that behave like a ``std::vector`` but in a type-safe manner with automatic resize on topology change (see :doc:`attributes`).
Algorithms are kept as generic as possible, most are templated on the type of the position.
Polymesh is designed to work with a broad class of math libraries (see :doc:`vector-math` and :doc:`algorithms`).
Except for some core functionality, :doc:`algorithms` and :doc:`properties` are implemented as free functions.
This makes it easy to extend and favors an include-what-you-use approach, reducing compile times in the process.
Working with meshes and attributes involves a lot of iteration.
Often, aggregate statistics like averages, minimums, maximums, and mapped/filtered ranges are needed.
Thus, polymesh provides a clean, composable, and powerful range API (see :doc:`mesh-topology` and :doc:`smart-ranges`).
Header Structure
----------------
A quick guide for which ``#include <...>`` directives are commonly needed:
``polymesh/fwd.hh``
Forward declarations of all important types.
......@@ -92,3 +113,45 @@ Header Structure
Documentation Structure
-----------------------
:doc:`mesh-topology`
Describes how mesh topology is stored in the :class:`polymesh::Mesh` class, how primitives are accessed via handles and indices, how topological iteration works, how memory is managed, and how the low-level API can be used to manipulate the internal half-edge data structure.
:doc:`attributes`
Introduces the "external, smart attributes" design and more advanced topics like flags, partitionings, sparse attributes, and views.
:doc:`vector-math`
Polymesh does not provide its own math library but assumes an external one is used.
This section describes which math libraries are recommended and tested and what requirements must be met if a custom math library is to be used.
:doc:`smart-ranges`
Geometry processing involves a lot of iteration and polymesh supports this with a clean, functional, and powerful "smart range" approach.
:doc:`properties`
Many topological and geometrical properties like edge lengths, valences, areas, etc. are free functions usable in a composable and generic manner.
:doc:`algorithms`
Polymesh is mostly "batteries included" and provides many important algorithms and basic operations like edge splits, decimation, smoothing, triangulation, subdivision, and many more.
:doc:`serialization`
Saving and loading meshes is supported for several popular file formats.
There are also type-erased ways to store arbitrary attributes.
:doc:`objects`
Sometimes, meshes are not loaded from file but created from primitives like cubes, spheres, cylinders, etc.
Many primitive objects are supported out-of-the-box.
:doc:`misc`
Polymesh provides some miscellaneous support code like custom high-performance assertions or a ``span`` type.
:doc:`cookbook`
The "Polymesh Cookbook" contains several recipes for common problems/operations in a "how do I do XYZ?"-fashion.
:doc:`faq`
A collection of common questions or misconceptions.
:doc:`reference`
Class reference generated mainly by Doxygen that documents noteworthy individual functions and classes.
:doc:`contributing`
A small guide of code style, philosophy, and tips should anyone want to contribute to polymesh (which we heavily welcome!).
......@@ -3,3 +3,15 @@ Class Reference
.. doxygenclass:: polymesh::Mesh
:members:
.. doxygenstruct:: polymesh::vertex_attribute
:members:
.. doxygenstruct:: polymesh::face_attribute
:members:
.. doxygenstruct:: polymesh::edge_attribute
:members:
.. doxygenstruct:: polymesh::halfedge_attribute
:members:
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