More WIP how it works

Author: williamhaarhoff

docs/how_it_works.md

@@ -3,7 +3,91 @@
 
 This document is meant to clearly show the principles on which archetype works without you having to decipher the macro heavy archetype.h file. The intention is to show how the principles have been combined, and provide a rationale for why I have implemented archetype this way. 
 
-Underneath the hood Archetype uses manual vtables to acheive type erasure and run time polymorphism. This is not dissimilar from how virtual functions in traditional inheritance work. Vtables and surrounding infrastructure require a lot of boiler plate. The point of Archetype is to automate manual vtable generation, in a modular/composable way.
+Underneath the hood `Archetype` uses manual vtables to acheive type erasure and run time polymorphism. This is not dissimilar from how virtual functions in traditional inheritance work. Vtables and surrounding infrastructure require a lot of boiler plate. The point of `Archetype` is to automate manual `vtable` generation, in a modular/composable way.
+
+### The basic vtable 
+A `vtable` is a structure containing free function pointers (non member function pointers). For example, this is a `vtable` structure containing function pointers for `func_a` and `func_b`.
+
+```cpp
+struct vtable
+{
+  int (*func_a)(int);
+  float (*func_b)(float);
+};
+```
+We can now assign any function that matches this signature to the vtable. For example:
+
+```cpp
+int func_a(int a) { return a + 5; }
+float func_b(float b) { return b + 5.3; }
+
+vtable mytable;
+mytable.func_a = &func_a;
+mytable.func_b = &func_b;
+```
+we can now call these functions through the vtable:
+```cpp
+mytable.func_a(5);    //returns 10;
+mytable.func_b(5.f);  //returns 10.3;
+```
+### The object facing vtable
+In Archetype the goal is binding objects/classes, not free functions. Member function pointers (non static) are not free functions. They have to point to both the correct function, and the object instance, which mean they don't have the size of a free function pointer.
+
+Lets say we want a vtable that can call objects of the following type:
+```cpp
+struct A
+{
+  int func_a(int a) { return a + internal_int++; }
+  float func_b(float b) { return b + (internal_float += 1.3f); }
+  int internal_int = 5;
+  int internal_float = 5.3;
+};
+```
+
+We can get around this by storing free functions that can be called with an object pointer. For example our vtable becomes:
+
+```cpp
+struct vtable
+{
+  int (*func_a)(A *, int);
+  float (*func_b)(A *, float);
+};
+```
+We can then assign this vtable to call an object of type `A's` functions. 
+```cpp
+A obj;
+vtable vtbl;
+vtbl.func_a = [](A * ptr, int a) { return ptr->func_a(a); };
+vtbl.func_b = [](A * ptr, float b) { return ptr->func_b(b); };
+
+vtbl.func_a(obj, 5);    // call func_a on obj
+vtbl.func_b(obj, 6.4);  // call func_b on obj
+```
+
+This implementation is not very generic. As our vtable depends on type A. We can make the vtable type agnostic by passing in the object as a void pointer instead. We can push the type specific handling into the lambda. 
+
+```cpp
+struct vtable
+{
+  int (*func_a)(void *, int);
+  float (*func_b)(void *, float);
+};
+
+vtbl.func_a = [](void * ptr, int a) { 
+  return static_cast<A*>(ptr)->func_a(a); 
+};
+
+vtbl.func_a(static_cast<void*>(obj), 5);
+```
+
+### The view
+
+
+
+
+
+
+
 
 
 ```cpp