This issue is a central reference for the design decisions of Handmade Math 2.0.

Naming

Handmade Math is too verbose right now. We want our names to be distinct and not conflict with other libraries, but nobody wants to read math expressions full of HMM_MultiplyMat4ByVec4. We should follow a more terse naming scheme, for example:

• HMM_MultiplyMat4ByVec4 -> HMM_MulM4V4
• HMM_MultiplyVec3f -> HMM_MulV3F
• HMM_EqualsVec4 -> HMM_EqV4

Issues:

• Make naming more consistent and concise #146

Angles

All functions must use the same representation of angles - mixing degrees/radians/turns makes it impossible to remember which function uses which.

Handmade Math should provide simple conversion constants like myDegrees * HMM_DegToRad, myRadians * HMM_Rad2Turn, etc. for each permutation of degrees, radians, and turns. It should also provide the macros HMM_AngleDeg, HMM_AngleRad, and HMM_AngleTurn which convert the specified unit into Handmade Math's preferred angle representation. By default this is radians, but you can #define HMM_USE_DEGREES or #define HMM_USE_TURNS to change this (changing the implementation of the previous macros in the process).

This is more configuration than we allow anywhere else in the library, but I think this is a place where the cost of flexibility is very small (conceptual cost and otherwise). It also has no effect on the majority of users, who just want to use radians everywhere.

Past work (not necessarily to be used):

• Inconsistent use of radians vs. degrees #31
• Make everything use radians #107

Handedness

Any functions involving handedness should have separate left-handed and right-handed versions, which must have an explicit _LH or _RH in their name. There will be no global preference and no configuration via #defines.

Issues:

• Make coordinate system more clear in function naming (LH, RH, NO, ZO) #75
• Orthographic matrix clip plane math wrong? #115

Matrix inverses

By far the most frequently-requested feature is better matrix inverses. We should add this, but with emphasis on common matrix inverses used for games. We are not a general-purpose linear algebra library.

Issues:

• Add support for matrix inverses #68

Mat2 and Mat3

We should support 2x2 and 3x3 matrices. The basics (add, subtract, multiply, scalar multiply, rotation) are all easy to provide. In particular this would make Vec2 a lot more useful. (3D workflows will still gravitate to Vec4 because come on)

Issues:

• mat3 #123

Overloads

We will preserve the C++ function overloads, but they will be much nicer due to the new naming scheme. For example, HMM_Mul instead of HMM_Multiply. Many users may still opt to make their own overloads that can also be extended to types outside Handmade Math; this is fine and not worth adding configuration for.

Operator overloads will obviously still be preserved.

We could perhaps also add _Generic support to give C11+ users function overloads. See #148.

Documentation

We should add doc comments to each function in a way most editors can recognize (e.g. simple comments or perhaps doxygen, but we probably don't need doxygen). In addition, we should consume those doc comments to automatically produce simple Markdown documentation that can be placed in a GitHub Wiki via CI and perhaps on a static site someday.

We also need better README documentation explaining the purpose, scope, and conventions of the library. I don't want to hear any more confused comments about whether we're really column major or whatever.

Examples

FInally, it would be really great to have some Hello Triangle example projects in the repo (or some similar). Enough 3D graphics to demonstrate that the math works and give people a starting point and a simple example of the library. A spinning cube or whatever. I dunno. GL and DX would be nice; that way we can demonstrate the use of two different API conventions.