mirror of https://github.com/mosra/magnum.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
102 lines
4.7 KiB
102 lines
4.7 KiB
/* |
|
This file is part of Magnum. |
|
|
|
Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, |
|
2020, 2021, 2022, 2023 Vladimír Vondruš <mosra@centrum.cz> |
|
|
|
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 `<string>` 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: |
|
|
|
<ul><li> |
|
The `*.h` extension denotes libraries that have everything inline in the |
|
header. A simple @cpp #include @ce is all you need. |
|
</li><li> |
|
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 <MagnumLibraryName.hpp> |
|
@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. |
|
</li></ul> |
|
|
|
@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. |
|
*/ |
|
|
|
}
|
|
|