Skip to content
Snippets Groups Projects
Commit 6364a377 authored by Philip Trettner's avatar Philip Trettner
Browse files

improved documentation

parent dc4cc7b7
Branches
No related tags found
No related merge requests found
......@@ -29,10 +29,44 @@ Motivating example: ::
v_normals[v] = normalize(n);
}
// compute bounding box
auto [min, max] = pos.aabb();
External Attributes
-------------------
Polymesh stores in separate objects with value semantics:
* :cpp:struct:`polymesh::vertex_attribute\<T>` stores a ``T`` per vertex
* :cpp:struct:`polymesh::face_attribute\<T>` stores a ``T`` per face
* :cpp:struct:`polymesh::edge_attribute\<T>` stores a ``T`` per edge
* :cpp:struct:`polymesh::halfedge_attribute\<T>` stores a ``T`` per halfedge
These types behave similar to a ``std::vector<T>``, i.e. moving is cheap and copy is a deep copy.
Each attribute stores a reference to the mesh which can be retrieved via :cpp:func:`polymesh::primitive_attribute_base::mesh`.
While a ``std::vector<T>`` can be accessed via ``int`` (or ``size_t``), polymesh attributes can only be accessed via the corresponding primitive ``_handle`` or ``_index`` (e.g. ``my_vertex_attribute[v]`` for :cpp:struct:`polymesh::vertex_handle` ``v``).
The only exception is an edge attribute which can also be accessed via :cpp:struct:`polymesh::halfedge_handle` or :cpp:struct:`polymesh::halfedge_index` because each halfedge belongs to exactly one edge.
If attributes are accessed via handles, a ``POLYMESH_ASSERT`` checks that the handle belongs to the same mesh as the attribute.
This is a security feature and can be circumvented by casting to the appropriate ``_index``.
Usually, attributes are created via their corresponding :ref:`primitive-collection`, e.g. ``m.vertices().make_attribute<int>()`` creates an ``int``-valued attribute for vertices.
Alternatively, the constructors can be used directly, e.g. ``auto pos = pm::vertex_attribute<tg::pos3>(m);``.
Attributes have default values (defaults to ``T{}``) that can be set when creating the attribute.
These are not only the value of all preexisting primitives but also the values of newly created primitives.
All attributes are :doc:`smart-ranges`.
In contrast to the normal topological ranges (such as :func:`polymesh::Mesh::vertices`), attributes do not know which primitives are deleted and thus iterating over an attribute will iterate over *all* values, even those belonging to primitives that are marked for deletion.
This is done for performance reasons.
If only values belonging to valid primitives are desired, either :func:`polymesh::Mesh::compactify` the mesh or iterate over the primitive and use the handle to access the value.
Attributes not only overload ``operator[]`` for their primitive index and handle but also ``operator()``.
Thus, each attributes is also a function object that can map primitives to their stored value.
This makes attributes easy-to-use in a functional context.
For example, ``m.vertices().avg(pos)`` computes the average vertex position.
Integrating Mesh and Attributes
-------------------------------
......
......@@ -19,11 +19,13 @@ Polymesh Documentation
algorithms
serialization
objects
performance
misc
cookbook
faq
reference
contributing
roadmap
Indices and tables
......
......@@ -93,6 +93,7 @@ For example, given a ``face_handle f``, ``f.vertices()`` returns an iterable sma
For all operations, see class references for :class:`polymesh::vertex_handle`, :class:`polymesh::face_handle`, :class:`polymesh::edge_handle`, and :class:`polymesh::halfedge_handle`.
For more information about the ranges, see :doc:`smart-ranges`.
.. _primitive-collection:
Primitive Collections
---------------------
......
......@@ -4,6 +4,7 @@ Misc
Assertions
----------
TODO
Simple Graphs
-------------
......
Performance
===========
TODO
TODO: describe internal data structure
TODO: describe implementation tradeoffs
TODO: describe debug vs relwithdebinfo vs release (especially range checks and assertions)
......@@ -79,6 +79,9 @@ Attributes
.. doxygenstruct:: polymesh::primitive_attribute
:members:
.. doxygenstruct:: polymesh::primitive_attribute_base
:members:
Low-Level API
-------------
......
Roadmap
=======
TODO
Refactorings
------------
* simplify ``make_attribute`` variants and remove the one that is achieved via ``map``
* provide a ``span`` type
* remove ``std`` dependencies where appropriate to reduce compile times
Long Term
---------
* add more algorithms
* add more formats
* add more objects
* re-add binary polymesh format with arbitrary attributes
......@@ -53,6 +53,12 @@ public:
deregister_attr();
}
Mesh const& mesh() const { return *mMesh; }
/// returns the mesh that this attribute is attached to.
/// NOTE: must only be called if the attribute is properly attached
Mesh const& mesh() const
{
POLYMESH_ASSERT(mMesh && "not attached to a mesh");
return *mMesh;
}
};
} // namespace polymesh
......@@ -88,7 +88,9 @@ public:
// methods
public:
/// sets all attribute values to the provided value
void clear(AttrT const& value);
/// sets all attribute values to the default value
void clear();
/// returns a new attribute where the given function was applied to each entry
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment