EDIT: The library can be found on github. If you would like to test the library, I built a simple raytracer here.
Hello everyone. I'm a PhD student working on computational soft matter. One of my group's interests is the equilibrium properties of hard particle systems (e.g. particles without any interactions), and as such, we frequently use collision detection algorithms in simulations.
I have written such code myself, and would like to write a library with a nice API which is easy to use, perhaps even make it a single file library. I always find it difficult designing a good API, and I seek your advice for this matter. In this gist, I have written two simple examples of what the API could look like for the GJK algorithm. In the first case, the user has to explicitly cast his shapes to convex_t, while in the latter case, there is one more level of indirection, i.e. a shape_t. The advantage of the second case, is that the user doesn't have to explicitly cast the shape, he can store all shapes in a single array, and since the type is stored using an enum, we can specialise algorithms for different types (e.g. for spheres GJK is overkill). On the other hand, in the second case the user cannot directly view the content of the struct, and the extra level of indirection, could hurt readability and performance slightly.
Another issue is memory allocation. Most shapes I'm intending to implement, don't need any allocations, but meshes need to store the vertices, faces, and vertex neighbours for faster support functions. I think it would be inconvenient if you have to i.e. call '_destroy()' on all types of shape structs even though only one meshes need to be freed. I know that stb libraries avoid memory allocations by e.g. preallocating enough memory, but I think this can be cumbersome since you can either exceed the memory limit, or allocate too much memory for a very small mesh. There is also this question on stack overflow, which discusses a similar API design issue.