This repository contains single-header libraries from the Magnum engine.
- Project homepage — https://magnum.graphics/
- Documentation — https://doc.magnum.graphics/
- GitHub project page — https://github.com/mosra/magnum-singles
LIBRARIES
There are the following single-header libraries at the moment. This list will grow with more Magnum features being exposed this way.
| Library | LoC | PpLoC[1] | Description |
|---|---|---|---|
| CorradeArrayView.h | 705 | 2628 | Containers::ArrayView and Containers::StaticArrayView, lightweight alternatives to std::span |
| CorradeStridedArrayView.h | 911[2] | 3245 | Containers::StridedArrayView, multi-dimensional strided array view. Depends on CorradeArrayView.h. |
| CorradeArray.h | 754[2] | 3208 | Containers::Array and Containers::StaticArray, lightweight alternatives to std::vector and std::array. Depends on CorradeArrayView.h. |
| CorradeOptional.h | 358 | 2554 | Containers::Optional, a lightweight alternative to std::optional |
| CorradePointer.h | 273 | 2437 | Containers::Pointer, a lightweight alternative to std::unique_ptr |
| CorradeReference.h | 115 | 1739 | Containers::Reference, a lightweight alternative to std::reference_wrapper |
| CorradeScopeGuard.h | 131 | 34 | Containers::ScopeGuard, a lightweight alternative to std::unique_ptr with a custom deleter |
| CorradeCpu.h | 1652 | 2088 | Cpu library, compile-time and runtime CPU feature detection and dispatch |
| CorradeStlForwardArray.h | 67 | 2318[3] | Corrade's forward declaration for std::array, a lightweight alternative to the full <array> (15k PpLOC[1]) where supported |
| CorradeStlForwardString.h | 74 | 50 | Corrade's forward declaration for std::string, a lightweight alternative to the full <string> (11k PpLOC[1]) where supported |
| CorradeStlForwardTuple.h | 78 | 1714 | Corrade's forward declaration for std::tuple, a lightweight alternative to the full <tuple> (13k PpLOC[1]) where supported |
| CorradeStlForwardVector.h | 62 | 859[3] | Corrade's forward declaration for std::vector, a lightweight alternative to the full <vector> (9k PpLOC[1]) where supported |
| CorradeStlMath.h | 57 | 3164[4] | Corrade's optimized <cmath>, without the heavy C++17 additions (which is otherwise 11k PpLOC[4]) |
| MagnumMath.hpp | 7748 | 10066 | Math namespace, a full-featured graphics-oriented linear algebra library |
[1] — lines of code after a preprocessor run, with system includes expanded. Gathered using GCC 11.2 and libstdc++, unless said otherwise.
[2] — not a total size due to inter-library dependencies
[3] — gathered using Clang 13.0 and libc++, since libstdc++ doesn't
have a forward declaration for std::array / std::vector
[4] — gathered using GCC 11.2, libstdc++ and -std=c++17
Where is the documentation?
Single-header libraries provided here are generated from multi-file sources in the Magnum project. This is done for two reasons — first, documentation and test coverage is much easier to maintain in the setting of a bigger project, avoiding any redundancy or duplicated efforts. Second, because the resulting files are generated with non-essential parts stripped away, there's no need to worry about bloating them due to original implementations having extensive documentation or rarely used features.
With the goal being easy integration, the files are deliberately free of all comments and documentation blocks to keep their size small. Documentation for each library is provided in the official Magnum documentation, linked from the table above. Each library file contains the same documentation link, together with a concrete Git revision it was generated from a changelog for a few versions back for easier overview when updating.
For more information read the single-header library docs. The libraries are generated
using acme.py, which is a part of Corrade.
See its documentation, if you
are interested. Particular libraries are introduced on the Magnum blog:
- Lightweight but still STL-compatible unique pointer (Jan 16, 2019)
- Array view implementations in Magnum (Feb 18, 2019)
- Forward-declaring STL container types (Mar 28, 2019)
- Multi-dimensional strided array views in Magnum (Apr 30, 2019)
- Convenient CPU feature detection and dispatch (Aug 2, 2022)
What about test coverage?
Testing done in this repository is mainly to ensure the libraries are generated correctly. Extensive testing on variety of compilers and OSes with > 99% test coverage is done in the Magnum Project itself. See the Build Status page for more information.
Reporting bugs and contributing
As always, bug reports, feature requests and code contributions are very
welcome. However again please note the files in this repository are generated
from original sources in the corrade and
magnum repositories, meaning that ideally
all PRs should go there instead, as there's a better infrastructure for
documentation and testing. We don't enforce this rule though — if you have an
important bugfix, it's better if you submit it here than not at all
SUPPORTED PLATFORMS
All libraries are tested on these platforms:
- Linux and embedded Linux
- Windows, Windows RT (Store/Phone)
- macOS, iOS
- Android
- Web (asm.js or WebAssembly), through Emscripten
And on these compilers:
- GCC 4.8.1 and newer (and equivalent MinGW-w64 version)
- Clang 6.0 and newer (or AppleClang 10.0 and newer), both
libstdc++andlibc++ - MSVC 2015 and newer
CONTACT & SUPPORT
- Project homepage — https://magnum.graphics/
- Documentation — https://doc.magnum.graphics/
- GitHub — https://github.com/mosra/magnum-singles and the #magnum topic
- GitLab — https://gitlab.com/mosra/magnum-singles
- Gitter community chat — https://gitter.im/mosra/magnum
- E-mail — [email protected]
- Google Groups mailing list — [email protected] (archive)
- Twitter — https://twitter.com/czmosra and the #MagnumEngine hashtag
See also the Magnum Project Contact & Support page for further information.
Credits
Libraries presented here are a result of a dedicated work by many community members. List of all contributors to the Magnum Project can be found in the documentation.
License
Magnum is licensed under the MIT/Expat license, see the COPYING file for details.