Update documentation with recent changes

docs/pages/api.rst

@@ -94,8 +94,8 @@ Record coordinates
 .. doxygenvariable:: llama::recordCoordCommonPrefixIsBigger
 .. doxygenvariable:: llama::recordCoordCommonPrefixIsSame
 
-View creation
--------------
+Views
+-----
 
 .. _label-api-allocView:
 .. doxygenfunction:: llama::allocView
@@ -105,6 +105,9 @@ View creation
 .. doxygentypedef:: llama::One
 .. doxygenfunction:: llama::copyRecord
 
+.. doxygenfunction:: transformBlobs
+.. doxygenfunction:: shallowCopy
+
 .. _label-api-bloballocators:
 
 Blob allocators
@@ -120,33 +123,51 @@ Blob allocators
 Mappings
 --------
 
-.. doxygentypedef:: llama::mapping::AlignedAoS
-.. doxygentypedef:: llama::mapping::PackedAoS
 .. doxygenstruct:: llama::mapping::AoS
    :members:
+.. doxygentypedef:: llama::mapping::AlignedAoS
+.. doxygentypedef:: llama::mapping::MinAlignedAoS
+.. doxygentypedef:: llama::mapping::PackedAoS
 .. doxygentypedef:: llama::mapping::SingleBlobSoA
 .. doxygentypedef:: llama::mapping::MultiBlobSoA
-.. doxygenstruct:: llama::mapping::SoA
-   :members:
-.. doxygenstruct:: llama::mapping::One
-   :members:
 .. doxygenstruct:: llama::mapping::AoSoA
    :members:
 .. doxygenvariable:: llama::mapping::maxLanes
-.. doxygenstruct:: llama::mapping::Split
-   :members:
-.. doxygenstruct:: llama::mapping::Trace
+.. doxygenstruct:: llama::mapping::BitPackedIntSoA
    :members:
-.. doxygenstruct:: llama::mapping::Heatmap
+.. doxygenstruct:: llama::mapping::BitPackedFloatSoA
    :members:
 .. doxygenstruct:: llama::mapping::Bytesplit
    :members:
+.. doxygenstruct:: llama::mapping::Byteswap
+   :members:
 .. doxygenstruct:: llama::mapping::ChangeType
    :members:
-.. doxygenstruct:: llama::mapping::BitPackedIntSoA
+.. doxygenstruct:: llama::mapping::Heatmap
    :members:
-.. doxygenstruct:: llama::mapping::BitPackedFloatSoA
+.. doxygenstruct:: llama::mapping::Null
+   :members:
+.. doxygenstruct:: llama::mapping::One
+   :members:
+.. doxygenstruct:: llama::mapping::Projection
+   :members:
+.. doxygenstruct:: llama::mapping::SoA
    :members:
+.. doxygenstruct:: llama::mapping::Split
+   :members:
+.. doxygenstruct:: llama::mapping::Trace
+   :members:
+
+Acessors
+^^^^^^^^
+
+.. doxygenstruct:: llama::accessor::Default
+.. doxygenstruct:: llama::accessor::ReadOnlyByValue
+.. doxygenstruct:: llama::accessor::Const
+.. doxygenstruct:: llama::accessor::Restrict
+.. doxygenstruct:: llama::accessor::Atomic
+
+.. doxygenfunction:: withAccessor
 
 RecordDim flattener
 ^^^^^^^^^^^^^^^^^^^

docs/pages/mappings.rst

@@ -228,10 +228,10 @@ but not how often the program reads/writes to those locations.
     ...
     mapping.printFieldHits(); // print report with number of computed memory locations
 
+
 Null
 ----
 
-
 The Null mappings is a fully computed mapping that maps all elements to nothing.
 Writing data through a reference obtained from the Null mapping discards the value.
 Reading through such a reference returns a default constructed object.
@@ -250,11 +250,28 @@ It transforms the record dimension by replacing each field type by a byte array
 
 .. code-block:: C++
 
+    template <typename RecordDim, typename ArrayExtents>
     using InnerMapping = ...;
+
     llama::mapping::Bytesplit<ArrayExtents, RecordDim, InnerMapping>
             mapping{extents};
 
 
+Byteswap
+---------
+
+The Byteswap mapping is a computed meta mapping that wraps over an inner mapping.
+It swaps the bytes of all values when reading/writing.
+
+.. code-block:: C++
+
+    template <typename RecordDim, typename ArrayExtents>
+    using InnerMapping = ...;
+
+    llama::mapping::Byteswap<ArrayExtents, RecordDim, InnerMapping>
+            mapping{extents};
+
+
 ChangeType
 ----------
 
@@ -263,7 +280,9 @@ and mapping the adapted record dimension with a further mapping.
 
 .. code-block:: C++
 
+    template <typename RecordDim, typename ArrayExtents>
     using InnerMapping = ...;
+
     using ReplacementMap = mp_list<
         mp_list<int, short>,
         mp_list<double, float>
@@ -275,6 +294,40 @@ In this example, all fields of type :cpp:`int` in the record dimension will be s
 and all fields of type :cpp:`double` will be stored as :cpp:`float`.
 Conversion between the data types is done on loading and storing through a proxy reference returned from the mapping.
 
+
+Projection
+----------
+
+The Projection mapping is a computed meta mapping that allows to apply a function on load/store from/two selected fields in the record dimension.
+These functions are allowed to change the data type of fields in the record dimension.
+The modified record dimension is then mapped with a further mapping.
+
+.. code-block:: C++
+
+    template <typename RecordDim, typename ArrayExtents>
+    using InnerMapping = ...;
+
+    struct Sqrt {
+        static auto load(float v) -> double {
+            return std::sqrt(v);
+        }
+
+        static auto store(double d) -> float {
+            return static_cast<float>(d * d);
+        }
+    };
+
+    using ReplacementMap = mp_list<
+        mp_list<double, Sqrt>,
+        mp_list<RecordCoord<0, 1>, Sqrt>
+    >;
+    llama::mapping::ChangeType<ArrayExtents, RecordDim, InnerMapping, ReplacementMap>
+            mapping{extents};
+
+In this example, all fields of type :cpp:`double`, and the field at coordinate RecordCoord<0, 1>, in the record dimension will store the product with itself as :cpp:`float`.
+The load/store functions are called on loading and storing through a proxy reference returned from the mapping.
+
+
 BitPackedIntSoA
 ---------------
 

docs/pages/views.rst

@@ -68,6 +68,31 @@ These record coordinates are zero-based, nested indices reflecting the nested tu
 Notice that the :cpp:`operator()` is invoked twice in the last example and that an intermediate object is needed for this to work.
 This object is a :cpp:`llama::RecordRef`.
 
+
+Accessors
+---------
+
+An Accessor is a callable that a view invokes on the mapped memory reference returned from a mapping.
+Accessors can be specified when a view is created or changed later.
+
+.. code-block:: C++
+
+    auto view  = llama::allocView(mapping, llama::bloballoc::Vector{},
+                     llama::accessor::Default{});
+    auto view2 = llama::withAccessor(view,
+                     llama::accessor::Const{}); // view2 is a copy!
+
+Switching an accessor changes the type of a view, so a new object needs to be created as a copy of the old one.
+To prevent the blobs to be copied, either use a corresponding blob allocator,
+or shallow copy the view before changing its accessor.
+
+.. code-block:: C++
+
+    auto view3 = llama::withAccessor(std::move(view),
+                     llama::accessor::Const{}); // view3 contains blobs of view now
+    auto view4 = llama::withAccessor(llama::shallowCopy(view3),
+                     llama::accessor::Const{}); // view4 shares blobs with view3
+
 .. _label-virtualview:
 
 VirtualView

include/llama/View.hpp

@@ -54,10 +54,11 @@ namespace llama
     LLAMA_FN_HOST_ACC_INLINE auto allocViewUninitialized(
         Mapping mapping = {},
         const Allocator& alloc = {},
-        Accessor = {}) -> View<Mapping, internal::AllocatorBlobType<Allocator, typename Mapping::RecordDim>, Accessor>
+        Accessor accessor = {})
+        -> View<Mapping, internal::AllocatorBlobType<Allocator, typename Mapping::RecordDim>, Accessor>
     {
         auto blobs = internal::makeBlobArray(alloc, mapping, std::make_index_sequence<Mapping::blobCount>{});
-        return {std::move(mapping), std::move(blobs)};
+        return {std::move(mapping), std::move(blobs), std::move(accessor)};
     }
 
     namespace internal
@@ -407,7 +408,6 @@ namespace llama
 #endif
     {
         static_assert(!std::is_const_v<TMapping>);
-        static_assert(std::is_empty_v<TAccessor>, "Stateful accessors are not implemented");
         using Mapping = TMapping;
         using BlobType = TBlobType;
         using ArrayExtents = typename Mapping::ArrayExtents;
@@ -432,8 +432,9 @@ namespace llama
         View() = default;
 
         LLAMA_FN_HOST_ACC_INLINE
-        View(Mapping mapping, Array<BlobType, Mapping::blobCount> storageBlobs)
+        View(Mapping mapping, Array<BlobType, Mapping::blobCount> storageBlobs, Accessor accessor = {})
             : Mapping(std::move(mapping))
+            , Accessor(std::move(accessor))
             , storageBlobs(std::move(storageBlobs))
         {
         }
@@ -629,8 +630,8 @@ namespace llama
             std::make_index_sequence<blobCount>{});
         return llama::View<typename View::Mapping, typename decltype(blobs)::value_type, typename View::Accessor>{
             view.mapping(),
-            std::move(blobs)/*,
-            view.accessor()*/};
+            std::move(blobs),
+            view.accessor()};
     }
 
     /// Creates a shallow copy of a view. This copy must not outlive the view, since it references its blob array.
@@ -659,9 +660,12 @@ namespace llama
     // \param view A view which's mapping and blobs are copied into a new view with the different accessor. If you no
     // longer need the old view, consider moving it into the argument of this function.
     template<typename NewAccessor, typename Mapping, typename BlobType, typename OldAccessor>
-    LLAMA_FN_HOST_ACC_INLINE auto withAccessor(View<Mapping, BlobType, OldAccessor> view)
+    LLAMA_FN_HOST_ACC_INLINE auto withAccessor(View<Mapping, BlobType, OldAccessor> view, NewAccessor newAccessor = {})
     {
-        return View<Mapping, BlobType, NewAccessor>{std::move(view.mapping()), std::move(view.storageBlobs)};
+        return View<Mapping, BlobType, NewAccessor>{
+            std::move(view.mapping()),
+            std::move(view.storageBlobs),
+            std::move(newAccessor)};
     }
 
     /// Like a \ref View, but array indices are shifted.

tests/view.cpp

@@ -429,4 +429,39 @@ TEMPLATE_TEST_CASE("view.withAccessor.shallowCopy.Restrict", "", llama::bloballo
     auto view2 = llama::withAccessor<llama::accessor::Restrict>(llama::shallowCopy(view));
     iotaFillView(view2);
     iotaCheckView(view);
-}
+}
+
+namespace
+{
+    struct OffsetFloatAccessor
+    {
+        float offset;
+
+        template<typename T>
+        auto operator()(T& ref) -> decltype(auto)
+        {
+            if constexpr(std::is_same_v<T, float>)
+                return ref + offset;
+            else
+                return ref;
+        }
+    };
+} // namespace
+
+TEST_CASE("view.withAccessor.OffsetFloatAccessor")
+{
+    auto view
+        = llama::allocView(llama::mapping::AoS{llama::ArrayExtents{4}, Particle{}}, llama::bloballoc::SharedPtr{});
+    view(0)(tag::Pos{})(tag::X{}) = 2.0;
+    view(0)(tag::Mass{}) = 2.0f;
+
+    auto view2 = llama::withAccessor(view, OffsetFloatAccessor{3});
+
+    CHECK(view2(0)(tag::Pos{})(tag::X{}) == 2.0);
+    CHECK(view2(0)(tag::Mass{}) == 5.0f);
+
+    view2.accessor().offset = 10;
+
+    CHECK(view2(0)(tag::Pos{})(tag::X{}) == 2.0);
+    CHECK(view2(0)(tag::Mass{}) == 12.0f);
+}