:last-update-label!:
:icons: font
:prewrap!:
:docinfo: shared
:stylesheet: zajo-dark.css
:source-highlighter: rouge
ifdef::backend-pdf[]
= QVM
endif::[]
ifndef::backend-pdf[]
= QVM pass:[
]
endif::[]
Quaternion / Vector / Matrix Library for {CPP}-11 | Emil Dotchevski
ifndef::backend-pdf[]
:toc: left
:toclevels: 3
:toc-title:
[.text-right]
https://github.com/boostorg/qvm[GitHub] | link:./qvm.pdf[PDF]
endif::[]
[abstract]
== Abstract
QVM is a generic library for working with Quaternions, Vectors and Matrices of static size. Features:
====
* Emphasis on 2, 3 and 4-dimensional operations needed in graphics, video games and simulation applications.
* Free function templates operate on any compatible user-defined quaternion, vector or matrix type.
* Quaternion, vector and matrix types from different libraries or subsystems can be safely mixed in the same expression.
* Type-safe mapping between compatible lvalue types with no temporary objects; e.g. transpose remaps the elements, rather than transforming the matrix.
====
ifndef::backend-pdf[]
[.text-right]
<> | <> | <>
endif::[]
[[tutorial]]
== Tutorial
=== Quaternions, Vectors, Matrices
Out of the box QVM defines generic yet simple <>, <> and <> types. For example, the following snippet creates a quaternion object that rotates around the X axis:
[source,c++]
----
quat rx = rotx_quat(3.14159f);
----
Similarly, a matrix that translates by a given vector can be created as follows:
[source,c++]
----
vec v = {0,0,7};
mat tr = translation_mat(v);
----
The usual quaternion, vector and matrix operations work on these QVM types, however the operations are decoupled from any specific type: they work on any suitable type that has been registered by specializing the <>, <> and <> templates.
For example, a user-defined 3D vector type `float3` can be introduced to QVM as follows:
[source,c++]
----
struct float3 { float a[3]; };
namespace boost { namespace qvm {
template <>
struct vec_traits {
static int const dim=3;
typedef float scalar_type;
template
static inline scalar_type & write_element( float3 & v ) {
return v.a[I];
}
template
static inline scalar_type read_element( float3 const & v ) {
return v.a[I];
}
static inline scalar_type & write_element_idx( int i, float3 & v ) {
return v.a[i];
} //optional
static inline scalar_type read_element_idx( int i, float3 const & v ) {
return v.a[i];
} //optional
};
} }
----
Equivalently, using the <> template the above can be shortened to:
[source,c++]
----
namespace boost { namespace qvm {
template <>
struct vec_traits: vec_traits_defaults {
template
static inline scalar_type & write_element( float3 & v ) {
return v.a[I];
}
static inline scalar_type & write_element_idx( int i, float3 & v ) {
return v.a[i];
} //optional
};
} }
----
After a similar specialization of the <> template for a user-defined 3x3 matrix type `float33`, the full range of vector and matrix operations defined by QVM headers becomes available automatically:
[source,c++]
----
float3 v;
X(v) = 0;
Y(v) = 0;
Z(v) = 7;
float vmag = mag(v);
float33 m = rotx_mat<3>(3.14159f);
float3 vrot = m * v;
----
User-defined quaternion types are similarly introduced to QVM by specializing the <> template.
'''
=== C Arrays
In <>, <> and <> QVM defines appropriate <>, <> and <> specializations that allow QVM functions to operate directly on plain old C arrays:
[source,c++]
----
float v[3] = {0,0,7};
float3 vrot = rotx_mat<3>(3.14159f) * v;
----
Naturally, operator overloads cannot kick in if all elements of an expression are of built-in types. The following is still illegal:
[source,c++]
----
float v[3] = {0,0,7};
v *= 42;
----
The <> and <> function templates can be used to work around this issue:
[source,c++]
----
float v[3] = {0,0,7};
vref(v) *= 42;
----
'''
[[view_proxy]]
=== View proxies
QVM defines various function templates that provide static mapping between (possibly user-defined) quaternion, vector and matrix types. The example below multiplies column 1 (QVM indexes are always zero-based) of the matrix `m` by a scalar:
[source,c++]
----
void multiply_column1( float33 & m, float scalar ) {
col<1>(m) *= scalar;
}
----
The expression <(m)`>> is an lvalue of an unspecified 3D vector type that refers to column 1 of `m`. Note however that this does not create any temporary objects; instead `operator*=` above works directly with a reference to `m`.
Here is another example, multiplying a transposed view of a matrix by a vector of some user-defined type `float3`:
[source,c++]
----
float3 v = {0,0,7};
float3 vrot = transposed(rotx_mat<3>(3.14159f)) * v;
----
In general, the various view proxy functions return references of unspecified, non-copyable types that refer to the original object. They can be assigned from or converted to any compatible vector or matrix type.
'''
=== Swizzling
QVM allows accessing vector elements by swizzling, exposing vector views of different dimensions, and/or views with reordered elements. The example below rotates `v` around the X axis, and stores the resulting vector back in `v` but with the X and Y elements swapped:
[source,c++]
----
float3 v = {0,0,7};
YXZ(v) = rotx_mat<3>(3.14159f) * v;
----
A special case of swizzling provides next-dimension-view of a vector object, adding either 0 or 1 as its last component. Assuming `float3` is a 3D vector type, and `float4` is a 4D vector type, the following statements are valid:
[source,c++]
----
float3 v = {0,0,7};
float4 point = XYZ1(v); //{0,0,7,1}
float4 vector = XYZ0(v); //{0,0,7,0}
----
It is also valid for swizzling to address vector elements more than once:
[source,c++]
----
float3 v = {0,0,7};
float4 v1 = ZZZZ(v); //{7,7,7,7}
----
QVM defines all permutations of `X`, `Y`, `Z`, `W` for 1D, 2D, 3D and 4D swizzling, plus each dimension defines variants with 0 or 1 used at any position (if 0 or 1 appear at the first position, the swizzling function name begins with underscore, e.g. `_1XY`).
The swizzling syntax can also be used to bind scalars as vectors. For example:
[source,c++]
----
float3 v = _00X(42.0f); //{0,0,42}
----
'''
[[enable_if]]
=== SFINAE/enable_if
SFINAE stands for Substitution Failure Is Not An Error. This refers to a situation in {CPP} where an invalid substitution of template parameters (including when those parameters are deduced implicitly as a result of an unqualified call) is not in itself an error.
In absence of concepts support, SFINAE can be used to disable function template overloads that would otherwise present a signature that is too generic. More formally, this is supported by the Boost `enable_if` library.
For example, QVM defines `operator*` overload which works with any user-defined matrix and vector types. The naive approach would be to declare this overload as follows:
[source,c++]
----
template
Vector operator*( Matrix const & m, Vector const & v );
----
Even if the function definition might contain code that would compile only for `Matrix` and `Vector` types, because the function declaration itself is valid, it will participate in overload rezolutions when multiplying objects of any two types whatsoever. This typically renders overload resolutions ambiguous and the compiler (correctly) issues an error.
Using `enable_if`, QVM declares such overloads in a way that preserves their generic signature but only participate in overload resolutions if the passed parameters make sense depending on the semantics of the operation being defined:
[source,c++]
----
template
typename enable_if_c<
is_mat::value && is_vec::value && mat_traits::cols==vec_traits::dim, //Condition
B>::type //Return type
operator*( A const & a, B const & b );
----
For brevity, function declarations throughout this documentation specify the condition which controls whether they are enabled or not without specifying exactly what `enable_if` construct is used to achieve this effect.
'''
=== Interoperability
An important design goal of QVM is that it works seamlessly with 3rd-party quaternion, vector and matrix types and libraries. Even when such libraries overload the same {CPP} operators as QVM, it is safe to bring the entire `boost::qvm` namespace in scope by specifying:
[source,c++]
----
using namespace boost::qvm;
----
The above using directive does not introduce ambiguities with function and operator overloads defined by a 3rd-party library because:
- Most `boost::qvm` function overloads and all operator overloads use SFINAE/`enable_if`, which makes them "disappear" unless an expression uses types that have the appropriate QVM-specific type traits defined;
- Whenever such overloads are compatible with a given expression, their signature is extremely generic, which means that any other (user-defined) compatible overload will be a better match in any overload resolution.
NOTE: Bringing the entire boost::qvm namespace in scope may introduce ambiguities when accessing types (as opposed to functions) defined by 3rd-party libraries. In that case, you can safely bring namespace `boost::qvm::sfinae` in scope instead, which contains only function and operator overloads that use SFINAE/`enable_if`.
==== Specifying return types for binary operations
Bringing the `boost::qvm` namespace in scope lets you mix vector and matrix types that come from different APIs into a common, type-safe framework. In this case however, it should be considered what types should be returned by binary operations that return an object by value. For example, if you multiply a 3x3 matrix `m1` of type `user_matrix1` by a 3x3 matrix `m2` of type `user_matrix2`, what type should that operation return?
The answer is that by default, QVM returns some kind of compatible matrix type, so it is always safe to write:
[source,c++]
----
auto & m = m1 * m2;
----
However, the type deduced by default converts implicitly to any compatible matrix type, so the following is also valid, at the cost of a temporary:
[source,c++]
----
user_matrix1 m = m1 * m2;
----
While the temporary object can be optimized away by many compilers, it can be avoided altogether by specializing the <> template. For example, to specify that multiplying a `user_matrix1` by a `user_matrix2` should always produce a `user_matrix1` object, you could write:
[source,c++]
----
namespace boost { namespace qvm {
template <>
struct deduce_mat2 {
typedef user_matrix1 type;
};
template <>
struct deduce_mat2 {
typedef user_matrix1 type;
};
} }
----
[WARNING]
====
Be mindful of potential ODR violation when using <>, <> and <> in independent libraries. For example, this could happen if `lib1` defines `deduce_vec2::type` as `lib1::vec` and in the same program `lib2` defines `deduce_vec2::type` as `lib2::vec`.
It is best to keep such specializations out of `lib1` and `lib2`. Of course, it is always safe for `lib1` and `lib2` to use <> to convert between the `lib1::vec` and `lib2::vec` types as needed.
====
==== Specifying return types for unary operations
Perhaps surprisingly, unary operations that return an object by value have a similar, though simpler issue. That's because the argument they're called with may not be copyable, as in:
[source,c++]
----
float m[3][3];
auto & inv = inverse(m);
----
Above, the object returned by <> and captured by `inv` can not be of type `float[3][3]`, because that type isn't copyable. By default, QVM "just works", returning an object of suitable matrix type that is copyable. This deduction process can be controlled, by specializing the <> template.
==== Converting between different quaternion, vector and matrix types
Any time you need to create a matrix of a particular {CPP} type from any other compatible matrix type, you can use the <> function:
[source,c++]
----
user_matrix2 m=convert_to(m1 * m2);
----
[[reference]]
== Reference
=== Header Files
QVM is split into multiple headers to allow different compilation units to `#include` only the components they need. Each function in this document specifies the exact header that must be `#included` in order to use it.
The tables below list commonly used components and the headers they're found in. Header names containing a number define functions that only work with objects of that dimension; e.g. `vec_operations2.hpp` contains only functions for working with 2D vectors.
The header `boost/qvm/all.hpp` is provided for convenience. It includes all other QVM headers.
.Quaternion header files
[cols="1,2l"]
|====
| Quaternion traits |#include
#include
#include
| Quaternion element access |#include
| Quaternion operations |#include
| <> class template |#include
|====
.Vector header files
[cols="1,2l"]
|====
| Vector traits |#include
#include
#include
| Vector element access |#include
| Vector <> |#include
#include
#include
#include
| Vector operations |#include
#include
#include
#include
| Quaternion-vector operations |#include
| Vector-matrix operations |#include
| Vector-matrix <> |#include
| <> class template |#include
|====
.Matrix header files
[cols="1,2l"]
|====
| Matrix traits |#include
#include
#include
| Matrix element access |#include
| Matrix operations |#include
#include
#include
#include
| Matrix-matrix <> |#include
| Matrix-vector <> |#include
| <> class template |#include
|====
[[type_traits]]
=== Type Traits System
QVM is designed to work with user-defined quaternion, vector and matrix types, as well as user-defined scalar types. This section formally defines the way such types can be integrated.
'''
[[scalar_requirements]]
==== Scalar Requirements
A valid scalar type `S` must have accessible destructor, default constructor, copy constructor and assignment operator, and must support the following operations:
[source,c++]
----
S operator*( S, S );
S operator/( S, S );
S operator+( S, S );
S operator-( S, S );
S & operator*=( S &, S );
S & operator/=( S &, S );
S & operator+=( S &, S );
S & operator-=( S &, S );
bool operator==( S, S );
bool operator!=( S, S );
----
In addition, the expression `S(0)` should construct a scalar of value zero, and `S(1)` should construct a scalar of value one, or else the <> template must be specialized appropriately.
'''
[[is_scalar]]
==== `is_scalar`
.#include
[source,c++]
----
namespace boost { namespace qvm {
template
struct is_scalar {
static bool const value=false;
};
template <> struct is_scalar { static bool const value=true; };
template <> struct is_scalar { static bool const value=true; };
template <> struct is_scalar { static bool const value=true; };
template <> struct is_scalar { static bool const value=true; };
template <> struct is_scalar { static bool const value=true; };
template <> struct is_scalar { static bool const value=true; };
template <> struct is_scalar { static bool const value=true; };
template <> struct is_scalar { static bool const value=true; };
template <> struct is_scalar { static bool const value=true; };
template <> struct is_scalar { static bool const value=true; };
template <> struct is_scalar { static bool const value=true; };
template <> struct is_scalar { static bool const value=true; };
} }
----
This template defines a compile-time boolean constant value which can be used to determine whether a type `T` is a valid scalar type. It must be specialized together with the <> template in order to introduce a user-defined scalar type to QVM. Such types must satisfy the <>.
'''
[[scalar_traits]]
==== `scalar_traits`
.#include
[source,c++]
----
namespace boost { namespace qvm {
template
struct scalar_traits {
BOOST_QVM_INLINE_CRITICAL
static Scalar value( int v ) {
return Scalar(v);
}
};
} }
----
This template may be specialized for user-defined scalar types to define the appropriate conversion from `int`; this is primarily used whenever QVM needs to deduce a zero or one value.
'''
[[deduce_scalar]]
==== `deduce_scalar`
.#include
[source,c++]
----
namespace boost { namespace qvm {
template
struct deduce_scalar
{
typedef typename impl::type type;
};
} }
----
Requires: :: `A` and `B` satisfy the <>.
Returns: ::
If `A` and `B` are the same type, `impl::type` returns that type. Otherwise, `impl::type` is well defined for the following types only: `signed`/`unsigned char`, `signed`/`unsigned short`, `signed`/`unsigned int`, `signed`/`unsigned long`, `float` and `double`. The deduction logic is as follows:
- if either of `A` and `B` is `double`, the result is `double`;
- else, if one of `A` or `B` is an integer type and the other is `float`, the result is `float`;
- else, if one of `A` or `B` is a signed integer and the other type is unsigned integer, the signed type is changed to unsigned, and then the lesser of the two integers is promoted to the other.
NOTE: This template is used by generic binary operations that return a scalar, to deduce the return type based on the (possibly different) scalars of their arguments.
'''
[[scalar]]
==== `scalar`
.#include
[source,c++]
----
namespace boost { namespace qvm {
template
struct scalar {
typedef /*exact definition unspecified*/ type;
};
} }
----
The expression <::scalar_type`>> evaluates to the scalar type of the quaternion type `T` (if <::value`>> is `true`).
The expression <::scalar_type`>> evaluates to the scalar type of the vector type `T` (if <::value`>> is `true`).
The expression <::scalar_type`>> evaluates to the scalar type of the matrix type `T` (if <::value`>> is `true`).
The expression `scalar::type` is similar, except that it automatically detects whether `T` is a vector or a matrix or a quaternion type.
'''
[[is_quat]]
==== `is_quat`
.#include
[source,c++]
----
namespace boost { namespace qvm {
template
struct is_quat {
static bool const value = false;
};
} }
----
This type template defines a compile-time boolean constant value which can be used to determine whether a type `T` is a quaternion type. For quaternion types, the <> template can be used to access their elements generically, or to obtain their `scalar type`.
'''
[[quat_traits]]
==== `quat_traits`
.#include
[source,c++]
----
namespace boost { namespace qvm {
template
struct quat_traits {
/*main template members unspecified*/
};
/*
User-defined (possibly partial) specializations:
template <>
struct quat_traits {
typedef <> scalar_type;
template
static inline scalar_type read_element( Quaternion const & q );
template
static inline scalar_type & write_element( Quaternion & q );
};
*/
} }
----
The `quat_traits` template must be specialized for (user-defined) quaternion types in order to enable quaternion operations defined in QVM headers for objects of those types.
NOTE: QVM quaternion operations do not require that quaternion types are copyable.
The main `quat_traits` template members are not specified. Valid specializations are required to define the following members:
- `scalar_type`: the expression `quat_traits::scalar_type` must be a value type which satisfies the <>.
In addition, valid specializations of the `quat_traits` template must define at least one of the following access functions as static members, where `q` is an object of type `Quaternion`, and `I` is compile-time integer constant:
- `read_element`: the expression `quat_traits::read_element(q)` returns either a copy of or a `const` reference to the `I`-th element of `q`.
- `write_element`: the expression `quat_traits::write_element(q)` returns mutable reference to the `I`-th element of `q`.
NOTE: For the quaternion `a + bi + cj + dk`, the elements are assumed to be in the following order: `a`, `b`, `c`, `d`; that is, `I`=`0`/`1`/`2`/`3` would access `a`/`b`/`c`/`d`.
It is illegal to call any of the above functions unless `is_quat::value` is true. Even then, quaternion types are allowed to define only a subset of the access functions.
Below is an example of a user-defined quaternion type, and its corresponding specialization of the quat_traits template:
[source,c++]
----
#include
struct fquat { float a[4]; };
namespace boost { namespace qvm {
template <>
struct quat_traits {
typedef float scalar_type;
template
static inline scalar_type & write_element( fquat & q ) {
return q.a[I];
}
template
static inline scalar_type read_element( fquat const & q ) {
return q.a[I];
}
};
} }
----
Equivalently, using the <> template the above can be shortened to:
[source,c++]
----
namespace boost { namespace qvm {
template <>
struct quat_traits: quat_traits_defaults {
template
static inline scalar_type & write_element( fquat & q ) {
return q.a[I];
}
};
} }
----
'''
[[quat_traits_defaults]]
==== `quat_traits_defaults`
.#include
[source,c++]
----
namespace boost { namespace qvm {
template
struct quat_traits_defaults {
typedef QuatType quat_type;
typedef ScalarType scalar_type;
template
static BOOST_QVM_INLINE_CRITICAL
scalar_type read_element( quat_type const & x ) {
return quat_traits::template
write_element(const_cast(x));
}
};
} }
----
The `quat_traits_defaults` template is designed to be used as a public base for user-defined specializations of the <> template, to easily define the required members. If it is used, the only member that must be defined by the user in a `quat_traits` specialization is `write_element`; the `quat_traits_defaults` base will define `read_element`, as well as `scalar_type` automatically.
'''
[[deduce_quat]]
==== `deduce_quat`
.#include
[source,c++]
----
namespace boost { namespace qvm {
template
struct deduce_quat {
typedef Q type;
};
} }
----
Requires: ::
- `<>::value` is `true`;
- `<>::type>::value` must be `true`;
- `deduce_quat::type` must be copyable.
This template is used by QVM whenever it needs to deduce a copyable quaternion type from a single user-supplied function parameter of quaternion type. Note that `Q` itself may be non-copyable.
The main template definition returns `Q`, which means that it is suitable only for copyable quaternion types. QVM also defines (partial) specializations for the non-copyable quaternion types it produces. Users can define other (partial) specializations for their own types.
A typical use of the `deduce_quat` template is for specifying the preferred quaternion type to be returned by the generic function template overloads in QVM depending on the type of their arguments.
'''
[[deduce_quat2]]
==== `deduce_quat2`
.#include
[source,c++]
----
namespace boost { namespace qvm {
template
struct deduce_quat2 {
typedef /*unspecified*/ type;
};
} }
----
Requires: ::
- Both `<>::type` and `scalar::type` are well defined;
- `<>::value` || `is_quat::value` is `true`;
- `is_quat::type>::value` must be `true`;
- `deduce_quat2::type` must be copyable.
This template is used by QVM whenever it needs to deduce a quaternion type from the types of two user-supplied function parameters. The returned type must have accessible copy constructor (the `A` and `B` types themselves could be non-copyable, and either one of them may not be a quaternion type.)
The main template definition returns an unspecified quaternion type with <> obtained by `<>::type`, except if `A` and `B` are the same quaternion type `Q`, in which case `Q` is returned, which is only suitable for copyable types. QVM also defines (partial) specializations for the non-copyable quaternion types it produces. Users can define other (partial) specializations for their own types.
A typical use of the `deduce_quat2` template is for specifying the preferred quaternion type to be returned by the generic function template overloads in QVM depending on the type of their arguments.
'''
[[is_vec]]
==== `is_vec`
.#include
[source,c++]
----
namespace boost { namespace qvm {
template
struct is_vec {
static bool const value = false;
};
} }
----
This type template defines a compile-time boolean constant value which can be used to determine whether a type `T` is a vector type. For vector types, the <> template can be used to access their elements generically, or to obtain their dimension and `scalar type`.
'''
[[vec_traits]]
==== `vec_traits`
.#include
[source,c++]
----
namespace boost { namespace qvm {
template
struct vec_traits {
/*main template members unspecified*/
};
/*
User-defined (possibly partial) specializations:
template <>
struct vec_traits {
static int const dim = <>;
typedef <> scalar_type;
template
static inline scalar_type read_element( Vector const & v );
template
static inline scalar_type & write_element( Vector & v );
static inline scalar_type read_element_idx( int i, Vector const & v );
static inline scalar_type & write_element_idx( int i, Vector & v );
};
*/
} }
----
The `vec_traits` template must be specialized for (user-defined) vector types in order to enable vector and matrix operations defined in QVM headers for objects of those types.
NOTE: QVM vector operations do not require that vector types are copyable.
The main `vec_traits` template members are not specified. Valid specializations are required to define the following members:
- `dim`: the expression `vec_traits::dim` must evaluate to a compile-time integer constant greater than 0 that specifies the vector size.
- `scalar_type`: the expression `vec_traits::scalar_type` must be a value type which satisfies the <>.
In addition, valid specializations of the `vec_traits` template may define the following access functions as static members, where `v` is an object of type `Vector`, `I` is a compile-time integer constant, and `i` is a variable of type `int`:
- `read_element`: the expression `vec_traits::read_element(v)` returns either a copy of or a const reference to the `I`-th element of `v`.
- `write_element`: the expression `vec_traits::write_element(v)` returns mutable reference to the `I`-th element of `v`.
- `read_element_idx`: the expression `vec_traits::read_element_idx(i,v)` returns either a copy of or a `const` reference to the `i`-th element of `v`.
- `write_element_idx`: the expression `vec_traits::write_element_idx(i,v)` returns mutable reference to the `i`-th element of `v`.
It is illegal to call any of the above functions unless `is_vec::value` is true. Even then, vector types are allowed to define only a subset of the access functions. The general requirements are:
- At least one of `read_element` or `write_element` must be defined;
- If `read_element_idx` is defined, `read_element` must also be defined;
- If `write_element_idx` is defined, `write_element` must also be defined.
Below is an example of a user-defined 3D vector type, and its corresponding specialization of the `vec_traits` template:
[source,c++]
----
#include
struct float3 { float a[3]; };
namespace boost { namespace qvm {
template <>
struct vec_traits {
static int const dim=3;
typedef float scalar_type;
template
static inline scalar_type & write_element( float3 & v ) {
return v.a[I];
}
template
static inline scalar_type read_element( float3 const & v ) {
return v.a[I];
}
static inline scalar_type & write_element_idx( int i, float3 & v ) {
return v.a[i];
} //optional
static inline scalar_type read_element_idx( int i, float3 const & v ) {
return v.a[i];
} //optional
};
} }
----
Equivalently, using the <> template the above can be shortened to:
[source,c++]
----
namespace boost { namespace qvm {
template <>
struct vec_traits: vec_traits_defaults
{
template
static inline scalar_type & write_element( float3 & v ) {
return v.a[I];
}
static inline scalar_type & write_element_idx( int i, float3 & v ) {
return v.a[i];
} //optional
};
} }
----
'''
[[vec_traits_defaults]]
==== `vec_traits_defaults`
.#include
[source,c++]
----
namespace boost { namespace qvm {
template
struct vec_traits_defaults {
typedef VecType vec_type;
typedef ScalarType scalar_type;
static int const dim=Dim;
template
static BOOST_QVM_INLINE_CRITICAL
scalar_type write_element( vec_type const & x ) {
return vec_traits::template write_element(const_cast(x));
}
static BOOST_QVM_INLINE_CRITICAL
scalar_type read_element_idx( int i, vec_type const & x ) {
return vec_traits::write_element_idx(i,const_cast(x));
}
protected:
static BOOST_QVM_INLINE_TRIVIAL
scalar_type & write_element_idx( int i, vec_type & m ) {
/* unspecified */
}
};
} }
----
The `vec_traits_defaults` template is designed to be used as a public base for user-defined specializations of the <> template, to easily define the required members. If it is used, the only member that must be defined by the user in a `vec_traits` specialization is `write_element`; the `vec_traits_defaults` base will define `read_element`, as well as `scalar_type` and `dim` automatically.
Optionally, the user may also define `write_element_idx`, in which case the `vec_traits_defaults` base will provide a suitable `read_element_idx` definition automatically. If not, `vec_traits_defaults` defines a protected implementation of `write_element_idx` which may be made publicly available by the deriving `vec_traits` specialization in case the vector type for which it is being specialized can not be indexed efficiently. This `write_element_idx` function is less efficient (using meta-programming), implemented in terms of the required user-defined `write_element`.
'''
[[deduce_vec]]
==== `deduce_vec`
.#include
[source,c++]
----
namespace boost { namespace qvm {
template ::dim>
struct deduce_vec {
typedef /*unspecified*/ type;
};
} }
----
Requires: ::
- `<>::value` is `true`;
- `is_vec::type>::value` must be `true`;
- `deduce_vec::type` must be copyable;
- `vec_traits::type>::dim==Dim`.
This template is used by QVM whenever it needs to deduce a copyable vector type of certain dimension from a single user-supplied function parameter of vector type. The returned type must have accessible copy constructor. Note that `V` may be non-copyable.
The main template definition returns an unspecified copyable vector type of size `Dim`, except if `<>::dim==Dim`, in which case it returns `V`, which is suitable only if `V` is a copyable type. QVM also defines (partial) specializations for the non-copyable vector types it produces. Users can define other (partial) specializations for their own types.
A typical use of the `deduce_vec` template is for specifying the preferred vector type to be returned by the generic function template overloads in QVM depending on the type of their arguments.
'''
[[deduce_vec2]]
==== `deduce_vec2`
.#include
[source,c++]
----
namespace boost { namespace qvm {
template
struct deduce_vec2 {
typedef /*unspecified*/ type;
};
} }
----
Requires: ::
- Both `<>::type` and `scalar::type` are well defined;
- `<>::value || is_vec::value` is `true`;
- `is_vec::type>::value` must be `true`;
- `deduce_vec2::type` must be copyable;
- `vec_traits::type>::dim==Dim`.
This template is used by QVM whenever it needs to deduce a vector type of certain dimension from the types of two user-supplied function parameters. The returned type must have accessible copy constructor (the `A` and `B` types themselves could be non-copyable, and either one of them may not be a vector type.)
The main template definition returns an unspecified vector type of the requested dimension with <> obtained by `<>::type`, except if `A` and `B` are the same vector type `V` of dimension `Dim`, in which case `V` is returned, which is only suitable for copyable types. QVM also defines (partial) specializations for the non-copyable vector types it produces. Users can define other (partial) specializations for their own types.
A typical use of the `deduce_vec2` template is for specifying the preferred vector type to be returned by the generic function template overloads in QVM depending on the type of their arguments.
'''
[[is_mat]]
==== `is_mat`
.#include
[source,c++]
----
namespace boost { namespace qvm {
template
struct is_mat {
static bool const value = false;
};
} }
----
This type template defines a compile-time boolean constant value which can be used to determine whether a type `T` is a matrix type. For matrix types, the <> template can be used to access their elements generically, or to obtain their dimensions and scalar type.
'''
[[mat_traits]]
==== `mat_traits`
.#include
[source,c++]
----
namespace boost { namespace qvm {
template
struct mat_traits {
/*main template members unspecified*/
};
/*
User-defined (possibly partial) specializations:
template <>
struct mat_traits {
static int const rows = <>;
static int const cols = <>;
typedef <> scalar_type;
template
static inline scalar_type read_element( Matrix const & m );
template
static inline scalar_type & write_element( Matrix & m );
static inline scalar_typeread_element_idx( int r, int c, Matrix const & m );
static inline scalar_type & write_element_idx( int r, int c, Matrix & m );
};
*/
} }
----
The `mat_traits` template must be specialized for (user-defined) matrix types in order to enable vector and matrix operations defined in QVM headers for objects of those types.
NOTE: The matrix operations defined by QVM do not require matrix types to be copyable.
The main `mat_traits` template members are not specified. Valid specializations are required to define the following members:
- `rows`: the expression `mat_traits::rows` must evaluate to a compile-time integer constant greater than 0 that specifies the number of rows in a matrix.
- `cols` must evaluate to a compile-time integer constant greater than 0 that specifies the number of columns in a matrix.
- `scalar_type`: the expression `mat_traits::scalar_type` must be a value type which satisfies the scalar requirements.
In addition, valid specializations of the `mat_traits` template may define the following access functions as static members, where `m` is an object of type `Matrix`, `R` and `C` are compile-time integer constants, and `r` and `c` are variables of type `int`:
- `read_element`: the expression `mat_traits::read_element(m)` returns either a copy of or a const reference to the element at row `R` and column `C` of `m`.
- `write_element`: the expression `mat_traits::write_element(m)` returns mutable reference to the element at row `R` and column `C` of `m`.
- `read_element_idx`: the expression `mat_traits::read_element_idx(r,c,m)` returns either a copy of or a const reference to the element at row `r` and column `c` of `m`.
- `write_element_idx`: the expression `mat_traits::write_element_idx(r,c,m)` returns mutable reference to the element at row `r` and column `c` of `m`.
It is illegal to call any of the above functions unless `is_mat