Future usability wishlist

[ghost]

linalg.h was my first formal introduction to linear algebra, and most of my current game projects depend on it. Thank you. I feel that the library can be further improved for n00b-friendliness. Here is my current usability wishlist, for the next release that has breaking changes.

Change linalg namespace to alg

It's shorter.

Global precision qualifier macro

#define alg::FLOAT float #define alg::FLOAT double #define alg::FLOAT long double

Similar to GLSL behavior, i.e. GLSL's precision mediump. Precision qualifiers would only affect the following new types.

GLSL types

alg::mat2 / alg::mat3 / alg::mat4 alg::vec2 / alg::vec3 / alg::vec4 alg::FLOAT

These types are set to the precision specified by alg::FLOAT.

GLM-style matrix multiplication

4x4 matrix multiplication is one of the most common things graphics programmers do. Having to type linalg::mul for each operation is crazy, and Lobster has gone ahead and adapted linalg's syntax to use * multiplication.

[sgorsten]

Thank you for your interest in linalg.

Change linalg namespace to alg

The existing namespace was chosen to minimize chance of collisions. If you prefer a shorter one, you can always add the following line to your source text:

namespace alg = linalg;

Note that if almost all linalg functions will be picked up through argument-dependent lookup, so it's extremely rare to have to type the linalg:: namespace qualifier, particularly if you are using aliases for the specific linalg types you want (via using namespace linalg::aliases, or any other mechanism).

Global precision qualifier macro

Unfortunately, your specified syntax does not exist in C++. #define statements are executed by the C preprocessor and have no knowledge of C++ namespaces. Providing a macro substitution for the token FLOAT would be an egregious overreach and would bring linalg.h into name collision with many, many libraries. A more verbose LINALG_FLOAT could be provided, but would serve little purpose. The float and double keywords do not exist anywhere in the text of linalg.h except for the contents of the linalg::aliases namespace.

GLSL types

The existing aliases were based off of the conventions chosen by Cg/HLSL/OpenCL/Metal, but they are a completely optional part of the library and you can easily introduce your own preferred typedefs, with whatever precision qualification scheme you prefer.

I have considered introducing a linalg::glsl_aliases namespace providing aliases that match the standard types in GLSL, but it's not clear to me there would be tremendous benefit. It has always been my opinion that Cg/HLSL/OpenCL/Metal chose a more consistent and extensible naming scheme for linear algebra types than GLSL did, and as we move into a SPIR-V-centric world it's not clear to me there's a tremendous benefit to emulating GLSL design choices.

GLM-style matrix multiplication

You don't have to type linalg::mul, you only have to type mul, and as long as one of your arguments is a linalg::mat the function will be found by ADL. This is consistent with the syntax of HLSL, in which operators always apply element-wise, and short named functions like dot, cross, and mul are used to represent the various sorts of algebraic products in linear algebra.

The change from mul to operator * was planned for the original v3 release, however, implementing it requires introducing an astonishing amount of special casing and inconsistency with the rest of the library. I'm on the fence about whether to make this change as planned or to keep the existing behavior.

[ghost]

ADL and using namespace don't feel pedantic to me except for symbol operators. The only way someone reading the source code would know which library a function comes from would be to trace it back to its declaration, which makes sense for common knowledge stuff like single-value (scalar) arithmetic and strings. Linear algebra is really black box stuff, at least to me, and a lot of people have the concept of shaders as effects without even knowing what a pipeline is, so common knowledge includes GLSL syntax within e.g. the GameMaker and Unity communities. SPIR-V is here to stay, but GLSL is included in Vulkan to make the transition easier.

I did not know that linalg.h is to HLSL as GLM is to GLSL. That is an important distinction. It only gets weird for me because HLSL is commonly used with DirectX which uses Z-forwards coordinate space while I use OpenGL which uses Z-backwards coordinate space. Mixing and matching causes a mental translation step to occur when reading source code, which is a good exercise I suppose. I can't help you make the decision on whether or not to change the syntax; that's up to you.

Thanks for responding.

[sgorsten]

Heh, it gets worse. OpenGL is widely perceived as being a z-back coordinate space, but aside from the z-flip incorporated into the definition of the long deprecated glFrustum, gluPerspective, and gluLookAt functions, this is not true.

OpenGL (by default) uses an x-right, y-up, z-forward normalized device coordinate system with a negative one to positive one depth range. DirectX and Metal use an x-right, y-up, z-forward normalized device coordinate system with a zero to one depth range. Vulkan uses an x-right, y-down, z-forward normalized device coordinate system with a zero to one depth range. Modern OpenGL provides the glClipControl(...) call allowing you to respecify your coordinate system to match the other APIs.

While I'd argue that Vulkan got this one right, linalg allows you to configure the z-axis and depth range behaviors of the frustum_matrix(...) and perspective_matrix(...) calls.

Conventions are hard. I've tried to pick and follow good ones where I can, but you do wind up making tradeoffs between familiarity and consistency.

[ghost]

My point was that all the coordinate spaces are different. You're right of course, Vulkan's clip space sounds like the optimal setup for putting graphics on present day computer displays.

As for OpenGL's clip space, I move the camera forwards by subtracting from the Z position. I don't know how that's supposed to work, but coordinate spaces are confusing and I'm having a hell of a time converting one of my old games to OpenGL, and I'm sure going from OpenGL to Vulkan will be just as fun...