diff --git a/README.md b/README.md index e45cc14a5..2815f0303 100644 --- a/README.md +++ b/README.md @@ -86,12 +86,16 @@ The best way to get started is to read the thorough [download, build, install and start using Magnum](https://doc.magnum.graphics/magnum/getting-started.html) in your project. There is also a complete [building documentation](https://doc.magnum.graphics/magnum/building.html) — we -provide packages for many platforms, including Windows, Linux and macOS. - -After that, there are various [tutorials and examples](https://doc.magnum.graphics/magnum/example-index.html) +provide packages for many platforms, including Windows, Linux and macOS. After +that, there are various [tutorials and examples](https://doc.magnum.graphics/magnum/example-index.html) and a complete [feature guide](https://doc.magnum.graphics/magnum/features.html) explaining all aspects of the library. +Apart from that, various Magnum functionality is available through +[single-header libraries](https://doc.magnum.graphics/magnum/singles.html). +Just download a file, `#include` it in your project and you're ready to go! No +buildsystem wrangling needed. + RELATED PROJECTS ================ diff --git a/doc/getting-started.dox b/doc/getting-started.dox index 7b13b49b8..634561b8b 100644 --- a/doc/getting-started.dox +++ b/doc/getting-started.dox @@ -252,6 +252,7 @@ experimenting on your own! - @subpage cmake-plugins --- @copybrief cmake-plugins - @subpage cmake-integration --- @copybrief cmake-integration - @subpage cmake-extras --- @copybrief cmake-extras +- @subpage singles --- @copybrief singles - @subpage custom-buildsystems --- @copybrief custom-buildsystems */ diff --git a/doc/mainpage.dox b/doc/mainpage.dox index 67af844c8..a6b5d3260 100644 --- a/doc/mainpage.dox +++ b/doc/mainpage.dox @@ -47,11 +47,13 @@ Curious about what was added or improved recently? Check out the The best way to get started is to read the thorough @ref getting-started "guide to download, build, install and start using Magnum" in your project. There is also a complete @ref building documentation --- we -provide packages for many platforms, including Windows, Linux and macOS. +provide packages for many platforms, including Windows, Linux and macOS. After +that, there are various @ref example-index "tutorials and examples" and a +complete @ref features "feature guide" explaining all aspects of the library. -After that, there are various @ref example-index "tutorials and examples" -and a complete @ref features "feature guide" explaining all aspects of the -library. +Apart from that, various Magnum functionality is available through +@ref singles "single-header libraries". Just download a file, @cpp #include @ce +it in your project and you're ready to go! No buildsystem wrangling needed. @section mainpage-contact Contact & support diff --git a/doc/namespaces.dox b/doc/namespaces.dox index 7855100db..68477bd09 100644 --- a/doc/namespaces.dox +++ b/doc/namespaces.dox @@ -42,7 +42,9 @@ find_package(Magnum REQUIRED) target_link_libraries(your-app Magnum::Magnum) @endcode -See @ref building and @ref cmake for more information. +Parts of this library are additionally available in a form of +@ref singles "single-header libraries". See @ref building and @ref cmake for +more information. */ /** @dir Magnum/Platform @@ -93,6 +95,29 @@ target_link_libraries(your-app Magnum::Magnum) See @ref building, @ref cmake, @ref matrix-vector and @ref transformations for more information. + +@m_class{m-block m-success} + +@par Single-header version + This library is also available as a single-header, dependency-less + [MagnumMath.h](https://github.com/mosra/magnum-singles/tree/master/MagnumMath.h) + library in the Magnum Singles repository for easier integration into your + projects. See @ref singles for more information. Everything except contents + of the @ref Magnum/Math/FunctionsBatch.h and @ref Magnum/Math/Algorithms/Svd.h + headers is included. The library has a separate non-inline implementation + part, enable it *just once* like this: +@par + @code{.cpp} + #define MAGNUM_MATH_IMPLEMENTATION + #include + @endcode +@par + In addition, contents of the @ref GlmIntegration and @ref EigenIntegration + libraries are included as well --- opt-in by specifying either + @cpp #define MAGNUM_MATH_GLM_INTEGRATION @ce or + @cpp #define MAGNUM_MATH_EIGEN_INTEGRATION @ce before including the file. + Including it multiple times with different macros defined works as well. + */ /** @namespace Magnum::Math::Literals @brief Math literals @@ -111,6 +136,14 @@ target_link_libraries(your-app Magnum::Magnum) @endcode See @ref building, @ref cmake and @ref types for more information. + +@m_class{m-block m-success} + +@par Single-header version + This library is available as a part of the single-header, dependency-less + [MagnumMath.h](https://github.com/mosra/magnum-singles/tree/master/MagnumMath.h) + library in the Magnum Singles repository for easier integration into your + projects. See @ref singles and @ref Math for more information. */ /** @dir Magnum/Math/Algorithms @@ -133,6 +166,14 @@ target_link_libraries(your-app Magnum::Magnum) @endcode See @ref building and @ref cmake for more information. + +@m_class{m-block m-success} + +@par Single-header version + This library is available as a part of the single-header, dependency-less + [MagnumMath.h](https://github.com/mosra/magnum-singles/tree/master/MagnumMath.h) + library in the Magnum Singles repository for easier integration into your + projects. See @ref singles and @ref Math for more information. */ /** @dir Magnum/Math/Geometry @@ -160,6 +201,14 @@ target_link_libraries(your-app Magnum::Magnum) @endcode See @ref building and @ref cmake for more information. + +@m_class{m-block m-success} + +@par Single-header version + This library is available as a part of the single-header, dependency-less + [MagnumMath.h](https://github.com/mosra/magnum-singles/tree/master/MagnumMath.h) + library in the Magnum Singles repository for easier integration into your + projects. See @ref singles and @ref Math for more information. */ /** @namespace Magnum::Math::Intersection @@ -177,6 +226,14 @@ target_link_libraries(your-app Magnum::Magnum) @endcode See @ref building and @ref cmake for more information. + +@m_class{m-block m-success} + +@par Single-header version + This library is available as a part of the single-header, dependency-less + [MagnumMath.h](https://github.com/mosra/magnum-singles/tree/master/MagnumMath.h) + library in the Magnum Singles repository for easier integration into your + projects. See @ref singles and @ref Math for more information. */ /** @dir Magnum/Animation diff --git a/doc/singles.dox b/doc/singles.dox new file mode 100644 index 000000000..e375d6477 --- /dev/null +++ b/doc/singles.dox @@ -0,0 +1,102 @@ +/* + This file is part of Magnum. + + Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019 + Vladimír Vondruš + + Permission is hereby granted, free of charge, to any person obtaining a + copy of this software and associated documentation files (the "Software"), + to deal in the Software without restriction, including without limitation + the rights to use, copy, modify, merge, publish, distribute, sublicense, + and/or sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL + THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER + DEALINGS IN THE SOFTWARE. +*/ + +namespace Magnum { + +/** @page singles Single-header libraries +@brief Magnum functionality exposed in easy-to-integrate single-header libraries + +@m_footernavigation + +Selected Magnum functionality is also available as single-header libraries, +with the goal of providing significantly smaller, faster-compiling and +generally better alternatives to commonly available implementations while being +as easy as possible to integrate into existing projects. The general rule is +having preprocessed size not not exceeding 10k lines --- to put this in +perspective, not even the `` header can fit there. + +So far, the following classes and libraries are provided as single-header libs, +all of them available for download through the [magnum-singles](https://github.com/mosra/magnum-singles) +repository. Each of them is automatically generated from unmodified Magnum +sources using the builtin @ref acme "single-header generator tool". + +@m_class{m-fullwidth m-flat} + +Class or library | Single-header version +--------------------------- | ---------------------------- +@ref Math, \n @ref EigenIntegration, \n @ref GlmIntegration | [MagnumMath.hpp](https://github.com/mosra/magnum-singles/tree/master/MagnumMath.hpp) + +There are also @ref corrade-singles "single-header libraries for Corrade APIs". + +@section singles-behavior Behavior + +To keep file size small, the single-header versions have all the comments and +documentation stripped away, except for a short description and a single +top-level license block, containing also credit information for all +contributors. Documentation is meant to be retrieved online, the wrapping +namespaces and all API naming stay completely the same as when using Magnum +directly. + +The files retain their own include guards, which makes it possible to mix them +together. However, when combining more than one, make sure to have all files +from the same revision to avoid API mismatches. The concrete revision that was +used to generate each library is printed in its header comment. + +There are two kinds of libraries, distinguished with file extension: + +
  • + The `*.h` extension denotes libraries that have everything inline in the + header. A simple @cpp #include @ce is all you need. +
  • + The `*.hpp` extension denotes libraries that have a separate implementation + part with non-inline definitions. Desired usage is to build the + implementation *just once* by defining a macro before including the library + header: + + @code{cpp} + #define MAGNUM_LIBRARYNAME_IMPLEMENTATION + #include + @endcode + + In all other files the library is meant to be included without defining the + macro. Thanks to this approach, complex implementation details don't + inflate compile times while still keeping the library as a single file. +
+ +@section singles-customization Customization points + +All headers above are created with @ref CORRADE_STANDARD_ASSERT enabled to +avoid dragging the whole @ref Corrade::Utility::Debug class along. Apart from +that, every header includes only the assertion macros it actually needs and +it's possible to override them by providing e.g. your own +@cpp #define CORRADE_ASSERT @ce before including the file. See the +@ref Corrade/Utility/Assert.h file documentation for more information. + +Some files contain additional disabled-by-default functionality (for example +integration with GLM and Eigen for @ref Math types), see documentation of each +library for detailed library-specific behavior. +*/ + +} diff --git a/src/singles/MagnumMath.hpp b/src/singles/MagnumMath.hpp new file mode 100644 index 000000000..c056c28a4 --- /dev/null +++ b/src/singles/MagnumMath.hpp @@ -0,0 +1,213 @@ +/* + Magnum::Math + — a graphics-focused vector math library + + https://doc.magnum.graphics/magnum/namespaceMagnum_1_1Math.html + https://doc.magnum.graphics/magnum/namespaceMagnum_1_1EigenIntegration.html + https://doc.magnum.graphics/magnum/namespaceMagnum_1_1GlmIntegration.html + + This is a single-header library generated from the Magnum project. With the + goal being easy integration, it's deliberately free of all comments to keep + the file size small. More info, changelogs and full docs here: + + - Project homepage — https://magnum.graphics/magnum/ + - Documentation — https://doc.magnum.graphics/ + - GitHub project page — https://github.com/mosra/magnum + - GitHub Singles repository — https://github.com/mosra/magnum-singles + + Generated from Corrade {{revision:corrade/src}}, + Magnum {{revision:magnum/src}} and + Magnum Integration {{revision:magnum-integration/src}}, {{stats:loc}} / {{stats:preprocessed}} LoC +*/ + +#include "base.h" +// {{includes}} +#if (!defined(CORRADE_ASSERT) || !defined(CORRADE_CONSTEXPR_ASSERT) || !defined(CORRADE_INTERNAL_ASSERT_OUTPUT) || !defined(CORRADE_ASSERT_UNREACHABLE)) && !defined(NDEBUG) +#include +#endif + +/* We're taking stuff from integration as well */ +#pragma ACME path ../../../magnum-integration/src +#pragma ACME revision magnum-integration/src echo "$(git describe --match 'v*') ($(date -d @$(git log -1 --format=%at) +%Y-%m-%d))" + +/* Disable asserts that are not used. CORRADE_ASSERT, CORRADE_CONSTEXPR_ASSERT, + CORRADE_INTERNAL_ASSERT_OUTPUT and CORRADE_ASSERT_UNREACHABLE are used, + wrapping the #include above. When enabling additional asserts, be + sure to update them above as well. */ +#pragma ACME enable CORRADE_ASSERT_OUTPUT +#pragma ACME enable CORRADE_INTERNAL_ASSERT +#pragma ACME enable CORRADE_INTERNAL_CONSTEXPR_ASSERT + +/* We don't need anything from configure.h here */ +#pragma ACME enable Corrade_configure_h +#pragma ACME enable Magnum_configure_h +#if defined(_MSC_VER) && _MSC_VER <= 1920 +#define CORRADE_MSVC2017_COMPATIBILITY +#endif +#if defined(_MSC_VER) && _MSC_VER <= 1910 +#define CORRADE_MSVC2015_COMPATIBILITY +#endif +#ifdef _WIN32 +#define CORRADE_TARGET_WINDOWS +#endif +#ifdef __EMSCRIPTEN__ +#define CORRADE_TARGET_EMSCRIPTEN +#endif +#ifdef __ANDROID__ +#define CORRADE_TARGET_ANDROID +#endif + +/* Our own subset of visibility macros */ +#pragma ACME enable Magnum_visibility_h +#pragma ACME enable Corrade_Utility_VisibilityMacros_h +#ifndef MAGNUM_EXPORT +#define MAGNUM_EXPORT +#endif + +/* Our own subset of Containers.h and Magnum.h */ +#pragma ACME enable Corrade_Containers_Containers_h +#pragma ACME enable Magnum_Magnum_h +#include "Magnum/Math/Math.h" +#ifndef MagnumMath_hpp +#define MagnumMath_hpp + +namespace Magnum { + +typedef Math::Half Half; +typedef Math::Vector2 Vector2; +typedef Math::Vector3 Vector3; +typedef Math::Vector4 Vector4; +typedef Math::Vector2 Vector2ui; +typedef Math::Vector3 Vector3ui; +typedef Math::Vector4 Vector4ui; +typedef Math::Vector2 Vector2i; +typedef Math::Vector3 Vector3i; +typedef Math::Vector4 Vector4i; +typedef Math::Color3 Color3; +typedef Math::Color4 Color4; +typedef Math::Color3 Color3ub; +typedef Math::Color4 Color4ub; +typedef Math::Matrix3 Matrix3; +typedef Math::Matrix4 Matrix4; +typedef Math::Matrix2x2 Matrix2x2; +typedef Math::Matrix3x3 Matrix3x3; +typedef Math::Matrix4x4 Matrix4x4; +typedef Math::Matrix2x3 Matrix2x3; +typedef Math::Matrix3x2 Matrix3x2; +typedef Math::Matrix2x4 Matrix2x4; +typedef Math::Matrix4x2 Matrix4x2; +typedef Math::Matrix3x4 Matrix3x4; +typedef Math::Matrix4x3 Matrix4x3; +typedef Math::QuadraticBezier2D QuadraticBezier2D; +typedef Math::QuadraticBezier3D QuadraticBezier3D; +typedef Math::CubicBezier2D CubicBezier2D; +typedef Math::CubicBezier3D CubicBezier3D; +typedef Math::CubicHermite1D CubicHermite1D; +typedef Math::CubicHermite2D CubicHermite2D; +typedef Math::CubicHermite3D CubicHermite3D; +typedef Math::CubicHermiteComplex CubicHermiteComplex; +typedef Math::CubicHermiteQuaternion CubicHermiteQuaternion; +typedef Math::Complex Complex; +typedef Math::DualComplex DualComplex; +typedef Math::Quaternion Quaternion; +typedef Math::DualQuaternion DualQuaternion; +typedef Math::Constants Constants; +typedef Math::Deg Deg; +typedef Math::Rad Rad; +typedef Math::Range1D Range1D; +typedef Math::Range2D Range2D; +typedef Math::Range3D Range3D; +typedef Math::Range1D Range1Di; +typedef Math::Range2D Range2Di; +typedef Math::Range3D Range3Di; +typedef Math::Frustum Frustum; +typedef Math::Vector2 Vector2d; +typedef Math::Vector3 Vector3d; +typedef Math::Vector4 Vector4d; +typedef Math::Matrix3 Matrix3d; +typedef Math::Matrix4 Matrix4d; +typedef Math::Matrix2x2 Matrix2x2d; +typedef Math::Matrix3x3 Matrix3x3d; +typedef Math::Matrix4x4 Matrix4x4d; +typedef Math::Matrix2x3 Matrix2x3d; +typedef Math::Matrix3x2 Matrix3x2d; +typedef Math::Matrix2x4 Matrix2x4d; +typedef Math::Matrix4x2 Matrix4x2d; +typedef Math::Matrix3x4 Matrix3x4d; +typedef Math::Matrix4x3 Matrix4x3d; +typedef Math::QuadraticBezier2D QuadraticBezier2Dd; +typedef Math::QuadraticBezier3D QuadraticBezier3Dd; +typedef Math::CubicBezier2D CubicBezier2Dd; +typedef Math::CubicBezier3D CubicBezier3Dd; +typedef Math::CubicHermite1D CubicHermite1Dd; +typedef Math::CubicHermite2D CubicHermite2Dd; +typedef Math::CubicHermite3D CubicHermite3Dd; +typedef Math::CubicHermiteComplex CubicHermiteComplexd; +typedef Math::CubicHermiteQuaternion CubicHermiteQuaterniond; +typedef Math::Complex Complexd; +typedef Math::DualComplex DualComplexd; +typedef Math::Quaternion Quaterniond; +typedef Math::DualQuaternion DualQuaterniond; +typedef Math::Constants Constantsd; +typedef Math::Deg Degd; +typedef Math::Rad Radd; +typedef Math::Range1D Range1Dd; +typedef Math::Range2D Range2Dd; +typedef Math::Range3D Range3Dd; +typedef Math::Frustum Frustumd; + +} + +#endif +#include "Magnum/Magnum.h" +#include "Magnum/Math/Angle.h" +#include "Magnum/Math/Bezier.h" +#include "Magnum/Math/Color.h" +#include "Magnum/Math/Complex.h" +#include "Magnum/Math/Constants.h" +#include "Magnum/Math/CubicHermite.h" +#include "Magnum/Math/Distance.h" +#include "Magnum/Math/Dual.h" +#include "Magnum/Math/DualComplex.h" +#include "Magnum/Math/DualQuaternion.h" +#include "Magnum/Math/Frustum.h" +#include "Magnum/Math/Functions.h" +#include "Magnum/Math/Half.h" +#include "Magnum/Math/Intersection.h" +#include "Magnum/Math/Matrix.h" +#include "Magnum/Math/Matrix3.h" +#include "Magnum/Math/Matrix4.h" +#include "Magnum/Math/Packing.h" +#include "Magnum/Math/Quaternion.h" +#include "Magnum/Math/Range.h" +#include "Magnum/Math/RectangularMatrix.h" +#include "Magnum/Math/StrictWeakOrdering.h" +#include "Magnum/Math/Swizzle.h" +#include "Magnum/Math/Tags.h" +#include "Magnum/Math/TypeTraits.h" +#include "Magnum/Math/Unit.h" +#include "Magnum/Math/Vector.h" +#include "Magnum/Math/Vector2.h" +#include "Magnum/Math/Vector3.h" +#include "Magnum/Math/Vector4.h" +#include "Magnum/Math/Algorithms/GaussJordan.h" +#include "Magnum/Math/Algorithms/GramSchmidt.h" +#include "Magnum/Math/Algorithms/KahanSum.h" +#include "Magnum/Math/Algorithms/Qr.h" +//#include "Magnum/Math/Algorithms/Svd.h" // TODO: uses +#ifdef MAGNUM_MATH_GLM_INTEGRATION +// {{includes}} +#include "Magnum/GlmIntegration/Integration.h" +#include "Magnum/GlmIntegration/GtcIntegration.h" +#include "Magnum/GlmIntegration/GtxIntegration.h" +#endif +#ifdef MAGNUM_MATH_EIGEN_INTEGRATION +// {{includes}} +#include "Magnum/EigenIntegration/Integration.h" +#include "Magnum/EigenIntegration/GeometryIntegration.h" +#endif +#ifdef MAGNUM_MATH_IMPLEMENTATION +// {{ includes }} +#include "Magnum/Math/Functions.cpp" +#include "Magnum/Math/Packing.cpp" +#endif diff --git a/src/singles/base.h b/src/singles/base.h new file mode 100644 index 000000000..a1c0ae7d3 --- /dev/null +++ b/src/singles/base.h @@ -0,0 +1,54 @@ +/* + This file is part of Magnum. + + {{copyright}} + + Permission is hereby granted, free of charge, to any person obtaining a + copy of this software and associated documentation files (the "Software"), + to deal in the Software without restriction, including without limitation + the rights to use, copy, modify, merge, publish, distribute, sublicense, + and/or sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL + THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER + DEALINGS IN THE SOFTWARE. +*/ + +// {{includes}} + +#pragma ACME comments off + +#pragma ACME path ../ +#pragma ACME path ../../../corrade/src +#pragma ACME local Corrade +#pragma ACME local Magnum + +/* For Corrade/configure.h and Magnum/configure.h */ +#pragma ACME path ../../build/src +#pragma ACME path ../../../corrade/build/src + +#pragma ACME disable CORRADE_BUILD_DEPRECATED +#pragma ACME disable MAGNUM_BUILD_DEPRECATED + +#pragma ACME disable CORRADE_NO_ASSERT +#pragma ACME enable CORRADE_STANDARD_ASSERT +#pragma ACME enable CORRADE_NO_DEBUG +#pragma ACME enable CORRADE_NO_TWEAKABLE +#pragma ACME disable CORRADE_GRACEFUL_ASSERT +#pragma ACME disable DOXYGEN_GENERATING_OUTPUT + +/* Make it possible to include Assert.h multiple times */ +#pragma ACME disable Corrade_Utility_Assert_h + +#pragma ACME revision corrade/src echo "$(git describe --match 'v*') ($(date -d @$(git log -1 --format=%at) +%Y-%m-%d))" +#pragma ACME revision magnum/src echo "$(git describe --match 'v*') ($(date -d @$(git log -1 --format=%at) +%Y-%m-%d))" +#pragma ACME stats loc wc -l +#pragma ACME stats preprocessed g++ -std=c++11 -P -E -x c++ - | wc -l diff --git a/src/singles/generate.sh b/src/singles/generate.sh new file mode 100755 index 000000000..7d565eaa7 --- /dev/null +++ b/src/singles/generate.sh @@ -0,0 +1,3 @@ +set -e + +../../../corrade/src/acme/acme.py MagnumMath.hpp --output ../../../magnum-singles