Add comments on Matrix capnp and NdMatrix functions.
Signed-off-by: Keith Rothman <537074+litghost@users.noreply.github.com>
diff --git a/libs/libvtrcapnproto/matrix.capnp b/libs/libvtrcapnproto/matrix.capnp
index 14250a4..9c6f28d 100644
--- a/libs/libvtrcapnproto/matrix.capnp
+++ b/libs/libvtrcapnproto/matrix.capnp
@@ -1,9 +1,19 @@
@0xafffc9c1f309bc00;
+# Cap'n proto representation of vtr::NdMatrix
+#
+# Note due to design constraints for Cap'n proto, the template type Value
+# must also be a struct, see https://capnproto.org/language.html#generic-types
struct Matrix(Value) {
+ # Container struct for values.
struct Entry {
value @0 :Value;
}
+
+ # Dimension list for matrix.
dims @0 :List(Int64);
+
+ # Flatten data array. Data appears in the same order that NdMatrix stores
+ # data in memory.
data @1 :List(Entry);
}
diff --git a/libs/libvtrcapnproto/ndmatrix_serdes.h b/libs/libvtrcapnproto/ndmatrix_serdes.h
index 5525c0b..0282d45 100644
--- a/libs/libvtrcapnproto/ndmatrix_serdes.h
+++ b/libs/libvtrcapnproto/ndmatrix_serdes.h
@@ -1,6 +1,61 @@
#ifndef NDMATRIX_SERDES_H_
#define NDMATRIX_SERDES_H_
-
+// Provide generic functions for serializing vtr::NdMatrix to and from Cap'n
+// proto Matrix.
+//
+// Functions:
+// ToNdMatrix - Converts Matrix capnproto message to vtr::NdMatrix
+// FromNdMatrix - Converts vtr::NdMatrix to Matrix capnproto
+//
+// Example:
+//
+// Schema:
+//
+// using Matrix = import "matrix.capnp";
+//
+//
+// struct Test {
+// struct Vec2 {
+// x @0 :Float32;
+// y @1 :Float32;
+// }
+// vectors @0 :Matrix.Matrix(Vec2)
+// }
+//
+// C++:
+//
+// struct Vec2 {
+// float x;
+// float y;
+// };
+//
+// static void ToVec2(Vec2 *out, const Test::Vec2::Reader& in) {
+// out->x = in.getX();
+// out->y = in.getY();
+// }
+//
+// static void FromVec2(Test::Vec2::Builder* out, const Vec2 &in) {
+// out->setX(in.x);
+// out->setY(in.y);
+// }
+//
+// void example(std::string file) {
+// vtr::NdMatrix<Vec2, 3> mat_in({3, 3, 3}, {2, 3});
+//
+// ::capnp::MallocMessageBuilder builder;
+// auto test = builder.initRoot<Test>();
+// auto vectors = test.getVectors();
+//
+// FromNdMatrix<3, Test::Vec2, Vec2>(&vectors, mat_in, FromVec2);
+// writeMessageToFile(file, &builder);
+//
+// MmapFile f(file);
+// ::capnp::FlatArrayMessageReader reader(f.getData());
+// auto test = reader.getRoot<Test>();
+//
+// vtr::NdMatrix<Vec2, 3> mat_out;
+// ToNdMatrix<3, Test::Vec2, Vec2>(&mat_out, test.getVectors(), FromVec2);
+// }
#include <functional>
#include "vtr_ndmatrix.h"
#include "vpr_error.h"
@@ -18,7 +73,6 @@
// m_out = Target vtr::NdMatrix.
// m_in = Source capnproto message reader.
// copy_fun = Function to convert from CapType to CType.
-//
template<size_t N, typename CapType, typename CType>
void ToNdMatrix(
vtr::NdMatrix<CType, N>* m_out,
