ic
/
magnum
mirror of https://github.com/mosra/magnum.git
6
0
Fork 0
Code Issues Projects Releases Wiki Activity
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.
10976 Commits
21 Branches
19 Tags
70 MiB
Tree: 723cf155a8
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '723cf155a8'
${ noResults }
magnum/doc/snippets/Trade.cpp

1418 lines
48 KiB
Raw Normal View History Unescape

Split the OpenGL layer out, pt 9: generic pixel formats. This is quite big, so: * There are new Magnum::PixelFormat and Magnum::CompressedPixelFormat enums, which contain generic API-independent formats. In particular, PixelFormat replaces GL::PixelFormat and GL::PixelType with a single value. * There's GL::pixelFormat(), GL::pixelType(), GL::compressedPixelFormat() to convert the generic enums to GL-specific. The mapping is only in one direction, done with a lookup table (generic enums are indices to that table). * GL classes taking the formats directly (such as GL::BufferImage) have overloads that take both the GL-specific and generic format. * The generic Image, CompressedImage, ImageView, CompressedImageView, and Trade::ImageData classes now accept the generic formats first-class. However, it's also possible to store an implementation-specific value to cover cases where a generic format enum doesn't have support for a particular format. This is done by wrapping the value using pixelFormatWrap() or compressedPixelFormatWrap(). Particular GPU APIs then assume it's their implementation-specific value and extract the value back using pixelFormatUnwrap() or compressedPixelFormatUnwrap(). There's also an isPixelFormatImplementationSpecific() and isCompressedPixelFormatImplementationSpecific() that distinguishes these values. * Many operations need pixel size and in order to have it even for implementation-specific formats, a corresponding pixelSize() overload is found via ADL on construction and the calculated size stored along the format. Previously the pixel size was only calculated on demand, but that's not possible now. In case such overload is not available, it's possible to pass pixel size manually as well. * In order to support the GL format+type pair, Image, ImageView and Trade::ImageData, there's now an additional untyped formatExtra() field that holds the second value. * The CompressedPixelStorage class is now unconditionally available on all targets, including OpenGL ES and WebGL. However, on OpenGL ES the GL APIs expect that it's all at default values. I attempted to preserve backwards compatibility as much as possible: * The PixelFormat and CompressedPixelFormat enum now contains generic API-independent values. The GL-specific formats are present there, but marked as deprecated. Use either the generic values or GL::PixelFormat (togehter with GL::PixelType) and GL::CompressedPixelFormat instead. There's a lot of ugliness caused by this, but seems to work well. * *Image::type() functions are deprecated as they were too GL-specific. Use formatExtra() and cast it to GL::PixelType instead. * Image constructors take templated format or format+extra arguments, so passing GL-specific values to them should still work.
8 years ago
/*
This file is part of Magnum.
Updated copyright year.
6 years ago
Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019,
It's 2023 already!
3 years ago
2020, 2021, 2022, 2023 Vladimír Vondruš <mosra@centrum.cz>
Split the OpenGL layer out, pt 9: generic pixel formats. This is quite big, so: * There are new Magnum::PixelFormat and Magnum::CompressedPixelFormat enums, which contain generic API-independent formats. In particular, PixelFormat replaces GL::PixelFormat and GL::PixelType with a single value. * There's GL::pixelFormat(), GL::pixelType(), GL::compressedPixelFormat() to convert the generic enums to GL-specific. The mapping is only in one direction, done with a lookup table (generic enums are indices to that table). * GL classes taking the formats directly (such as GL::BufferImage) have overloads that take both the GL-specific and generic format. * The generic Image, CompressedImage, ImageView, CompressedImageView, and Trade::ImageData classes now accept the generic formats first-class. However, it's also possible to store an implementation-specific value to cover cases where a generic format enum doesn't have support for a particular format. This is done by wrapping the value using pixelFormatWrap() or compressedPixelFormatWrap(). Particular GPU APIs then assume it's their implementation-specific value and extract the value back using pixelFormatUnwrap() or compressedPixelFormatUnwrap(). There's also an isPixelFormatImplementationSpecific() and isCompressedPixelFormatImplementationSpecific() that distinguishes these values. * Many operations need pixel size and in order to have it even for implementation-specific formats, a corresponding pixelSize() overload is found via ADL on construction and the calculated size stored along the format. Previously the pixel size was only calculated on demand, but that's not possible now. In case such overload is not available, it's possible to pass pixel size manually as well. * In order to support the GL format+type pair, Image, ImageView and Trade::ImageData, there's now an additional untyped formatExtra() field that holds the second value. * The CompressedPixelStorage class is now unconditionally available on all targets, including OpenGL ES and WebGL. However, on OpenGL ES the GL APIs expect that it's all at default values. I attempted to preserve backwards compatibility as much as possible: * The PixelFormat and CompressedPixelFormat enum now contains generic API-independent values. The GL-specific formats are present there, but marked as deprecated. Use either the generic values or GL::PixelFormat (togehter with GL::PixelType) and GL::CompressedPixelFormat instead. There's a lot of ugliness caused by this, but seems to work well. * *Image::type() functions are deprecated as they were too GL-specific. Use formatExtra() and cast it to GL::PixelType instead. * Image constructors take templated format or format+extra arguments, so passing GL-specific values to them should still work.
8 years ago
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.
*/
Add macros with plugin interface strings for easier updates. This means I (and people making their own plugins) don't need to go and update each and every plugin once the version in the interface string gets bumped after a (silent) ABI break. Such as when new virtual functions get added, as those often lead to strange crashes if the plugins don't get rebuilt after. The plugins will now use this macro, which means they'll automatically embed an interface string that was present in the base class header at build time. However, when the base class updates, the previous string is still embedded in the plugin binary, which will then fail to load -- this being automatic doesn't mean the original purpose is lost. Subsequently rebuilding the plugins from source will make them pick up the updated interface string again.
3 years ago
/* In order to have the CORRADE_PLUGIN_REGISTER() macro not a no-op. Doesn't
affect anything else. */
#define CORRADE_STATIC_PLUGIN
Trade: support for file loading callbacks in AbstractImporter.
8 years ago
#include <unordered_map>
Trade: high-level documentation for SceneData.
5 years ago
#include <Corrade/Containers/ArrayTuple.h>
Removed std::optional backwards compatibility. This was a dirty mess. Good riddance. Also removing the include from the header now, as it has a forward declaration and thus is not needed.
7 years ago
#include <Corrade/Containers/Optional.h>
Trade: support storing string fields in SceneData. Finally got an idea how to provide various options store these efficiently, so it's implemented now. Five different storage variants times four different type sizes.
3 years ago
#include <Corrade/Containers/StringIterable.h>
Trade: port to the new Utility::Path. For file opening there's no longer an unatomic pair of exists() + read(), but since Path::read() now returns an Optional, it means we can reliably distinguish between empty files and failures. While at it, also added TODOs for removal of the StringStl.h header that's needed in various places for compatibility with APIs still using STL strings.
4 years ago
#include <Corrade/Containers/StringStl.h> /** @todo remove once file callbacks are <string>-free */
Trade: high-level documentation for SceneData.
5 years ago
#include <Corrade/Containers/Pair.h>
Trade: AbstractImporter::doOpenData() now takes a rvalue Array. This allows to better describe memory ownership and transfer it instead of forcing the plugins to allocate their own local copy if the import happens in-place on the imported data. Right now that's mainly for the openFile() use case, which implicitly allocated an Array with file contents only to pass it to openData() which then made a copy because it could not make any assumption about data scope. In other words, certain plugins (TgaImporter, KtxImporter, DdsImporter, CgltfImporter and possibly others) will now have their peak memory usage *halved*.
5 years ago
#include <Corrade/Utility/Algorithms.h>
Trade: high-level documentation for SceneData.
5 years ago
#include <Corrade/Utility/DebugStl.h>
Trade: port to the new Utility::Path. For file opening there's no longer an unatomic pair of exists() + read(), but since Path::read() now returns an Optional, it means we can reliably distinguish between empty files and failures. While at it, also added TODOs for removal of the StringStl.h header that's needed in various places for compatibility with APIs still using STL strings.
4 years ago
#include <Corrade/Utility/Path.h>
doc/snippets: adapt to Corrade header cleanup.
7 years ago
#include <Corrade/Utility/Resource.h>
Trade: support for file loading callbacks in AbstractImporter.
8 years ago
Move Trade::ImporterFileCallbackPolicy to InputFileCallbackPolicy. It'll get used outside of the root namespace and since the callbacks tend to be quite complex, it would be silly to require users to implement one callback for Trade, one for Text and one for Audio, for example.
7 years ago
#include "Magnum/FileCallback.h"
Trade: improve docs for the main importer / converter plugins. Interestingly enough, there were no docs whatsoever for image and scene conversion, and neither it was mentioned what all scene data can be imported. Sigh.
5 years ago
#include "Magnum/Image.h"
De-inline Image headers, remove dependency on ImageView. This means users have to add some more #includes on their side. Sorry but it's for your own good :P
7 years ago
#include "Magnum/ImageView.h"
Trade: a reworked MeshData class. With API analogous to the (relatively) new AnimationData -- with one buffer containing all index data and one buffer containing all vertex data, both meant to be uploaded as-is to the GPU. This will eventually replace MeshData2D and MeshData3D, backwards compatibility and wiring up to other APIs will be done in follow-up commits.
7 years ago
#include "Magnum/Mesh.h"
Split the OpenGL layer out, pt 9: generic pixel formats. This is quite big, so: * There are new Magnum::PixelFormat and Magnum::CompressedPixelFormat enums, which contain generic API-independent formats. In particular, PixelFormat replaces GL::PixelFormat and GL::PixelType with a single value. * There's GL::pixelFormat(), GL::pixelType(), GL::compressedPixelFormat() to convert the generic enums to GL-specific. The mapping is only in one direction, done with a lookup table (generic enums are indices to that table). * GL classes taking the formats directly (such as GL::BufferImage) have overloads that take both the GL-specific and generic format. * The generic Image, CompressedImage, ImageView, CompressedImageView, and Trade::ImageData classes now accept the generic formats first-class. However, it's also possible to store an implementation-specific value to cover cases where a generic format enum doesn't have support for a particular format. This is done by wrapping the value using pixelFormatWrap() or compressedPixelFormatWrap(). Particular GPU APIs then assume it's their implementation-specific value and extract the value back using pixelFormatUnwrap() or compressedPixelFormatUnwrap(). There's also an isPixelFormatImplementationSpecific() and isCompressedPixelFormatImplementationSpecific() that distinguishes these values. * Many operations need pixel size and in order to have it even for implementation-specific formats, a corresponding pixelSize() overload is found via ADL on construction and the calculated size stored along the format. Previously the pixel size was only calculated on demand, but that's not possible now. In case such overload is not available, it's possible to pass pixel size manually as well. * In order to support the GL format+type pair, Image, ImageView and Trade::ImageData, there's now an additional untyped formatExtra() field that holds the second value. * The CompressedPixelStorage class is now unconditionally available on all targets, including OpenGL ES and WebGL. However, on OpenGL ES the GL APIs expect that it's all at default values. I attempted to preserve backwards compatibility as much as possible: * The PixelFormat and CompressedPixelFormat enum now contains generic API-independent values. The GL-specific formats are present there, but marked as deprecated. Use either the generic values or GL::PixelFormat (togehter with GL::PixelType) and GL::CompressedPixelFormat instead. There's a lot of ugliness caused by this, but seems to work well. * *Image::type() functions are deprecated as they were too GL-specific. Use formatExtra() and cast it to GL::PixelType instead. * Image constructors take templated format or format+extra arguments, so passing GL-specific values to them should still work.
8 years ago
#include "Magnum/PixelFormat.h"
Trade: document AnimationData usage. This is the last non-obvious thing that needs to be documented in order to make the API usable.
8 years ago
#include "Magnum/Animation/Player.h"
Trade: deprecate AbstractMaterialData, rewrite PhongMaterialData. AbstractMaterialData is now just a typedef to MaterialData, with all existing public APIs moved to (and marked as deprecated, if they don't make sense anymore). The new class doesn't have a virtual destructor as that's not the desired use anymore -- and AbstractImporter::material() APIs will be returning an Optional instead of a Pointer, which means any potential subclasses will be sliced away. PhongMaterialData is reimplemented using the new key/value store, with no own members anymore -- thus having the same size as MaterialData, and safe to be casted from it to access the helper APIs.
6 years ago
#include "Magnum/Math/Color.h"
Math: make cross() 10x faster in Debug. And the Vector3 version 5% slower in Release, on GCC at least. FFS, what was I thinking with the gather() things. Nice in user code, extremely bad in library code.
6 years ago
#include "Magnum/Math/Swizzle.h"
#include "Magnum/MeshTools/Interleave.h"
Trade: high-level docs for AbstractSceneConverter whole-scene operation.
4 years ago
#include "Magnum/MeshTools/RemoveDuplicates.h"
Trade: document how MeshData can be further transformed.
8 years ago
#include "Magnum/MeshTools/Transform.h"
Trade: improve docs for the main importer / converter plugins. Interestingly enough, there were no docs whatsoever for image and scene conversion, and neither it was mentioned what all scene data can be imported. Sigh.
5 years ago
#include "Magnum/Trade/AbstractImageConverter.h"
Split the OpenGL layer out, pt 9: generic pixel formats. This is quite big, so: * There are new Magnum::PixelFormat and Magnum::CompressedPixelFormat enums, which contain generic API-independent formats. In particular, PixelFormat replaces GL::PixelFormat and GL::PixelType with a single value. * There's GL::pixelFormat(), GL::pixelType(), GL::compressedPixelFormat() to convert the generic enums to GL-specific. The mapping is only in one direction, done with a lookup table (generic enums are indices to that table). * GL classes taking the formats directly (such as GL::BufferImage) have overloads that take both the GL-specific and generic format. * The generic Image, CompressedImage, ImageView, CompressedImageView, and Trade::ImageData classes now accept the generic formats first-class. However, it's also possible to store an implementation-specific value to cover cases where a generic format enum doesn't have support for a particular format. This is done by wrapping the value using pixelFormatWrap() or compressedPixelFormatWrap(). Particular GPU APIs then assume it's their implementation-specific value and extract the value back using pixelFormatUnwrap() or compressedPixelFormatUnwrap(). There's also an isPixelFormatImplementationSpecific() and isCompressedPixelFormatImplementationSpecific() that distinguishes these values. * Many operations need pixel size and in order to have it even for implementation-specific formats, a corresponding pixelSize() overload is found via ADL on construction and the calculated size stored along the format. Previously the pixel size was only calculated on demand, but that's not possible now. In case such overload is not available, it's possible to pass pixel size manually as well. * In order to support the GL format+type pair, Image, ImageView and Trade::ImageData, there's now an additional untyped formatExtra() field that holds the second value. * The CompressedPixelStorage class is now unconditionally available on all targets, including OpenGL ES and WebGL. However, on OpenGL ES the GL APIs expect that it's all at default values. I attempted to preserve backwards compatibility as much as possible: * The PixelFormat and CompressedPixelFormat enum now contains generic API-independent values. The GL-specific formats are present there, but marked as deprecated. Use either the generic values or GL::PixelFormat (togehter with GL::PixelType) and GL::CompressedPixelFormat instead. There's a lot of ugliness caused by this, but seems to work well. * *Image::type() functions are deprecated as they were too GL-specific. Use formatExtra() and cast it to GL::PixelType instead. * Image constructors take templated format or format+extra arguments, so passing GL-specific values to them should still work.
8 years ago
#include "Magnum/Trade/AbstractImporter.h"
Trade: improve docs for the main importer / converter plugins. Interestingly enough, there were no docs whatsoever for image and scene conversion, and neither it was mentioned what all scene data can be imported. Sigh.
5 years ago
#include "Magnum/Trade/AbstractSceneConverter.h"
Trade: document AnimationData usage. This is the last non-obvious thing that needs to be documented in order to make the API usable.
8 years ago
#include "Magnum/Trade/AnimationData.h"
Split the OpenGL layer out, pt 9: generic pixel formats. This is quite big, so: * There are new Magnum::PixelFormat and Magnum::CompressedPixelFormat enums, which contain generic API-independent formats. In particular, PixelFormat replaces GL::PixelFormat and GL::PixelType with a single value. * There's GL::pixelFormat(), GL::pixelType(), GL::compressedPixelFormat() to convert the generic enums to GL-specific. The mapping is only in one direction, done with a lookup table (generic enums are indices to that table). * GL classes taking the formats directly (such as GL::BufferImage) have overloads that take both the GL-specific and generic format. * The generic Image, CompressedImage, ImageView, CompressedImageView, and Trade::ImageData classes now accept the generic formats first-class. However, it's also possible to store an implementation-specific value to cover cases where a generic format enum doesn't have support for a particular format. This is done by wrapping the value using pixelFormatWrap() or compressedPixelFormatWrap(). Particular GPU APIs then assume it's their implementation-specific value and extract the value back using pixelFormatUnwrap() or compressedPixelFormatUnwrap(). There's also an isPixelFormatImplementationSpecific() and isCompressedPixelFormatImplementationSpecific() that distinguishes these values. * Many operations need pixel size and in order to have it even for implementation-specific formats, a corresponding pixelSize() overload is found via ADL on construction and the calculated size stored along the format. Previously the pixel size was only calculated on demand, but that's not possible now. In case such overload is not available, it's possible to pass pixel size manually as well. * In order to support the GL format+type pair, Image, ImageView and Trade::ImageData, there's now an additional untyped formatExtra() field that holds the second value. * The CompressedPixelStorage class is now unconditionally available on all targets, including OpenGL ES and WebGL. However, on OpenGL ES the GL APIs expect that it's all at default values. I attempted to preserve backwards compatibility as much as possible: * The PixelFormat and CompressedPixelFormat enum now contains generic API-independent values. The GL-specific formats are present there, but marked as deprecated. Use either the generic values or GL::PixelFormat (togehter with GL::PixelType) and GL::CompressedPixelFormat instead. There's a lot of ugliness caused by this, but seems to work well. * *Image::type() functions are deprecated as they were too GL-specific. Use formatExtra() and cast it to GL::PixelType instead. * Image constructors take templated format or format+extra arguments, so passing GL-specific values to them should still work.
8 years ago
#include "Magnum/Trade/ImageData.h"
Trade: add attenuation, range and cone angle parameters to LightData. And document how all those go together.
6 years ago
#include "Magnum/Trade/LightData.h"
Trade: usage docs for MaterialData.
6 years ago
#include "Magnum/Trade/MaterialData.h"
Trade: a reworked MeshData class. With API analogous to the (relatively) new AnimationData -- with one buffer containing all index data and one buffer containing all vertex data, both meant to be uploaded as-is to the GPU. This will eventually replace MeshData2D and MeshData3D, backwards compatibility and wiring up to other APIs will be done in follow-up commits.
7 years ago
#include "Magnum/Trade/MeshData.h"
Trade: usage docs for MaterialData.
6 years ago
#include "Magnum/Trade/PbrClearCoatMaterialData.h"
#include "Magnum/Trade/PbrSpecularGlossinessMaterialData.h"
#include "Magnum/Trade/PbrMetallicRoughnessMaterialData.h"
Trade: actually create some useful docs for AbstractImporter.
8 years ago
#include "Magnum/Trade/PhongMaterialData.h"
Trade: high-level documentation for SceneData.
5 years ago
#include "Magnum/Trade/SceneData.h"
#include "Magnum/SceneGraph/Drawable.h"
#include "Magnum/SceneGraph/Scene.h"
#include "Magnum/SceneGraph/Object.h"
#include "Magnum/SceneGraph/MatrixTransformation3D.h"
Split the OpenGL layer out, pt 9: generic pixel formats. This is quite big, so: * There are new Magnum::PixelFormat and Magnum::CompressedPixelFormat enums, which contain generic API-independent formats. In particular, PixelFormat replaces GL::PixelFormat and GL::PixelType with a single value. * There's GL::pixelFormat(), GL::pixelType(), GL::compressedPixelFormat() to convert the generic enums to GL-specific. The mapping is only in one direction, done with a lookup table (generic enums are indices to that table). * GL classes taking the formats directly (such as GL::BufferImage) have overloads that take both the GL-specific and generic format. * The generic Image, CompressedImage, ImageView, CompressedImageView, and Trade::ImageData classes now accept the generic formats first-class. However, it's also possible to store an implementation-specific value to cover cases where a generic format enum doesn't have support for a particular format. This is done by wrapping the value using pixelFormatWrap() or compressedPixelFormatWrap(). Particular GPU APIs then assume it's their implementation-specific value and extract the value back using pixelFormatUnwrap() or compressedPixelFormatUnwrap(). There's also an isPixelFormatImplementationSpecific() and isCompressedPixelFormatImplementationSpecific() that distinguishes these values. * Many operations need pixel size and in order to have it even for implementation-specific formats, a corresponding pixelSize() overload is found via ADL on construction and the calculated size stored along the format. Previously the pixel size was only calculated on demand, but that's not possible now. In case such overload is not available, it's possible to pass pixel size manually as well. * In order to support the GL format+type pair, Image, ImageView and Trade::ImageData, there's now an additional untyped formatExtra() field that holds the second value. * The CompressedPixelStorage class is now unconditionally available on all targets, including OpenGL ES and WebGL. However, on OpenGL ES the GL APIs expect that it's all at default values. I attempted to preserve backwards compatibility as much as possible: * The PixelFormat and CompressedPixelFormat enum now contains generic API-independent values. The GL-specific formats are present there, but marked as deprecated. Use either the generic values or GL::PixelFormat (togehter with GL::PixelType) and GL::CompressedPixelFormat instead. There's a lot of ugliness caused by this, but seems to work well. * *Image::type() functions are deprecated as they were too GL-specific. Use formatExtra() and cast it to GL::PixelType instead. * Image constructors take templated format or format+extra arguments, so passing GL-specific values to them should still work.
8 years ago
#ifdef MAGNUM_TARGET_GL
#include "Magnum/GL/Texture.h"
Trade: use setStorage() in the ImageData doc snippet as well.
6 years ago
#include "Magnum/GL/TextureFormat.h"
Trade: a reworked MeshData class. With API analogous to the (relatively) new AnimationData -- with one buffer containing all index data and one buffer containing all vertex data, both meant to be uploaded as-is to the GPU. This will eventually replace MeshData2D and MeshData3D, backwards compatibility and wiring up to other APIs will be done in follow-up commits.
7 years ago
#include "Magnum/GL/Mesh.h"
Trade: high-level docs for the MeshData class.
6 years ago
#include "Magnum/MeshTools/Compile.h"
Shaders: suffix all existing shaders with GL. To make room for Vulkan shaders. Also renaming the headers, of course everything is still aliased to the old names (and marked as deprecated).
5 years ago
#include "Magnum/Shaders/PhongGL.h"
Split the OpenGL layer out, pt 9: generic pixel formats. This is quite big, so: * There are new Magnum::PixelFormat and Magnum::CompressedPixelFormat enums, which contain generic API-independent formats. In particular, PixelFormat replaces GL::PixelFormat and GL::PixelType with a single value. * There's GL::pixelFormat(), GL::pixelType(), GL::compressedPixelFormat() to convert the generic enums to GL-specific. The mapping is only in one direction, done with a lookup table (generic enums are indices to that table). * GL classes taking the formats directly (such as GL::BufferImage) have overloads that take both the GL-specific and generic format. * The generic Image, CompressedImage, ImageView, CompressedImageView, and Trade::ImageData classes now accept the generic formats first-class. However, it's also possible to store an implementation-specific value to cover cases where a generic format enum doesn't have support for a particular format. This is done by wrapping the value using pixelFormatWrap() or compressedPixelFormatWrap(). Particular GPU APIs then assume it's their implementation-specific value and extract the value back using pixelFormatUnwrap() or compressedPixelFormatUnwrap(). There's also an isPixelFormatImplementationSpecific() and isCompressedPixelFormatImplementationSpecific() that distinguishes these values. * Many operations need pixel size and in order to have it even for implementation-specific formats, a corresponding pixelSize() overload is found via ADL on construction and the calculated size stored along the format. Previously the pixel size was only calculated on demand, but that's not possible now. In case such overload is not available, it's possible to pass pixel size manually as well. * In order to support the GL format+type pair, Image, ImageView and Trade::ImageData, there's now an additional untyped formatExtra() field that holds the second value. * The CompressedPixelStorage class is now unconditionally available on all targets, including OpenGL ES and WebGL. However, on OpenGL ES the GL APIs expect that it's all at default values. I attempted to preserve backwards compatibility as much as possible: * The PixelFormat and CompressedPixelFormat enum now contains generic API-independent values. The GL-specific formats are present there, but marked as deprecated. Use either the generic values or GL::PixelFormat (togehter with GL::PixelType) and GL::CompressedPixelFormat instead. There's a lot of ugliness caused by this, but seems to work well. * *Image::type() functions are deprecated as they were too GL-specific. Use formatExtra() and cast it to GL::PixelType instead. * Image constructors take templated format or format+extra arguments, so passing GL-specific values to them should still work.
8 years ago
#endif
Trade: high-level docs for the MeshData class.
6 years ago
#ifdef MAGNUM_TARGET_VK
#include "Magnum/Vk/Vulkan.h"
#endif
Split the OpenGL layer out, pt 9: generic pixel formats. This is quite big, so: * There are new Magnum::PixelFormat and Magnum::CompressedPixelFormat enums, which contain generic API-independent formats. In particular, PixelFormat replaces GL::PixelFormat and GL::PixelType with a single value. * There's GL::pixelFormat(), GL::pixelType(), GL::compressedPixelFormat() to convert the generic enums to GL-specific. The mapping is only in one direction, done with a lookup table (generic enums are indices to that table). * GL classes taking the formats directly (such as GL::BufferImage) have overloads that take both the GL-specific and generic format. * The generic Image, CompressedImage, ImageView, CompressedImageView, and Trade::ImageData classes now accept the generic formats first-class. However, it's also possible to store an implementation-specific value to cover cases where a generic format enum doesn't have support for a particular format. This is done by wrapping the value using pixelFormatWrap() or compressedPixelFormatWrap(). Particular GPU APIs then assume it's their implementation-specific value and extract the value back using pixelFormatUnwrap() or compressedPixelFormatUnwrap(). There's also an isPixelFormatImplementationSpecific() and isCompressedPixelFormatImplementationSpecific() that distinguishes these values. * Many operations need pixel size and in order to have it even for implementation-specific formats, a corresponding pixelSize() overload is found via ADL on construction and the calculated size stored along the format. Previously the pixel size was only calculated on demand, but that's not possible now. In case such overload is not available, it's possible to pass pixel size manually as well. * In order to support the GL format+type pair, Image, ImageView and Trade::ImageData, there's now an additional untyped formatExtra() field that holds the second value. * The CompressedPixelStorage class is now unconditionally available on all targets, including OpenGL ES and WebGL. However, on OpenGL ES the GL APIs expect that it's all at default values. I attempted to preserve backwards compatibility as much as possible: * The PixelFormat and CompressedPixelFormat enum now contains generic API-independent values. The GL-specific formats are present there, but marked as deprecated. Use either the generic values or GL::PixelFormat (togehter with GL::PixelType) and GL::CompressedPixelFormat instead. There's a lot of ugliness caused by this, but seems to work well. * *Image::type() functions are deprecated as they were too GL-specific. Use formatExtra() and cast it to GL::PixelType instead. * Image constructors take templated format or format+extra arguments, so passing GL-specific values to them should still work.
8 years ago
Trade, MeshTools: deprecate MeshDataXD and everything that uses it.
6 years ago
#ifdef MAGNUM_BUILD_DEPRECATED
#define _MAGNUM_NO_DEPRECATED_MESHDATA /* So it doesn't yell here */
Trade: adapt AbstractImporter for the new SceneData workflow. Same as with MeshData2D/3D, the original ObjectData API and plugin interfaces are preserved to keep existing code as well as existing importer implementations working. As Magnum's own importers will get updated to the new SceneData workflow, a backward compatibility layer provided that translates it to the subset that the legacy ObjectData understands. With this commit, both existing plugin code can build (and test against) the new workflow, and any ports to the new workflow can test against the legacy interfaces. Except that for now the compatibility layer doesn't deal with objects that have more than one mesh or for example a light and a camera attached, this will be done in a separate step.
5 years ago
#define _MAGNUM_NO_DEPRECATED_OBJECTDATA /* So it doesn't yell here */
Trade, MeshTools: deprecate MeshDataXD and everything that uses it.
6 years ago
#include "Magnum/Trade/MeshData2D.h"
#include "Magnum/Trade/MeshData3D.h"
Trade: adapt AbstractImporter for the new SceneData workflow. Same as with MeshData2D/3D, the original ObjectData API and plugin interfaces are preserved to keep existing code as well as existing importer implementations working. As Magnum's own importers will get updated to the new SceneData workflow, a backward compatibility layer provided that translates it to the subset that the legacy ObjectData understands. With this commit, both existing plugin code can build (and test against) the new workflow, and any ports to the new workflow can test against the legacy interfaces. Except that for now the compatibility layer doesn't deal with objects that have more than one mesh or for example a light and a camera attached, this will be done in a separate step.
5 years ago
#include "Magnum/Trade/MeshObjectData3D.h"
#include "Magnum/Trade/ObjectData2D.h"
Trade, MeshTools: deprecate MeshDataXD and everything that uses it.
6 years ago
#endif
doc: rename DOXYGEN_IGNORE() to DOXYGEN_ELLIPSIS(). And use DOXYGEN_IGNORE() for replacing with nothing.
4 years ago
#define DOXYGEN_ELLIPSIS(...) __VA_ARGS__
Trade: high-level documentation for SceneData.
5 years ago
#define DOXYGEN_IGNORE(...) __VA_ARGS__
Trade: usage docs for MaterialData.
6 years ago
Split the OpenGL layer out, pt 9: generic pixel formats. This is quite big, so: * There are new Magnum::PixelFormat and Magnum::CompressedPixelFormat enums, which contain generic API-independent formats. In particular, PixelFormat replaces GL::PixelFormat and GL::PixelType with a single value. * There's GL::pixelFormat(), GL::pixelType(), GL::compressedPixelFormat() to convert the generic enums to GL-specific. The mapping is only in one direction, done with a lookup table (generic enums are indices to that table). * GL classes taking the formats directly (such as GL::BufferImage) have overloads that take both the GL-specific and generic format. * The generic Image, CompressedImage, ImageView, CompressedImageView, and Trade::ImageData classes now accept the generic formats first-class. However, it's also possible to store an implementation-specific value to cover cases where a generic format enum doesn't have support for a particular format. This is done by wrapping the value using pixelFormatWrap() or compressedPixelFormatWrap(). Particular GPU APIs then assume it's their implementation-specific value and extract the value back using pixelFormatUnwrap() or compressedPixelFormatUnwrap(). There's also an isPixelFormatImplementationSpecific() and isCompressedPixelFormatImplementationSpecific() that distinguishes these values. * Many operations need pixel size and in order to have it even for implementation-specific formats, a corresponding pixelSize() overload is found via ADL on construction and the calculated size stored along the format. Previously the pixel size was only calculated on demand, but that's not possible now. In case such overload is not available, it's possible to pass pixel size manually as well. * In order to support the GL format+type pair, Image, ImageView and Trade::ImageData, there's now an additional untyped formatExtra() field that holds the second value. * The CompressedPixelStorage class is now unconditionally available on all targets, including OpenGL ES and WebGL. However, on OpenGL ES the GL APIs expect that it's all at default values. I attempted to preserve backwards compatibility as much as possible: * The PixelFormat and CompressedPixelFormat enum now contains generic API-independent values. The GL-specific formats are present there, but marked as deprecated. Use either the generic values or GL::PixelFormat (togehter with GL::PixelType) and GL::CompressedPixelFormat instead. There's a lot of ugliness caused by this, but seems to work well. * *Image::type() functions are deprecated as they were too GL-specific. Use formatExtra() and cast it to GL::PixelType instead. * Image constructors take templated format or format+extra arguments, so passing GL-specific values to them should still work.
8 years ago
using namespace Magnum;
using namespace Magnum::Math::Literals;
Add macros with plugin interface strings for easier updates. This means I (and people making their own plugins) don't need to go and update each and every plugin once the version in the interface string gets bumped after a (silent) ABI break. Such as when new virtual functions get added, as those often lead to strange crashes if the plugins don't get rebuilt after. The plugins will now use this macro, which means they'll automatically embed an interface string that was present in the base class header at build time. However, when the base class updates, the previous string is still embedded in the plugin binary, which will then fail to load -- this being automatic doesn't mean the original purpose is lost. Subsequently rebuilding the plugins from source will make them pick up the updated interface string again.
3 years ago
namespace MyNamespace {
struct MyImporter: Trade::AbstractImporter {
explicit MyImporter(PluginManager::AbstractManager& manager, Containers::StringView plugin): Trade::AbstractImporter{manager, plugin} {}
Trade::ImporterFeatures doFeatures() const override { return {}; }
bool doIsOpened() const override { return false; }
void doClose() override {}
};
struct MyImageConverter: Trade::AbstractImageConverter {
explicit MyImageConverter(PluginManager::AbstractManager& manager, Containers::StringView plugin): Trade::AbstractImageConverter{manager, plugin} {}
Trade::ImageConverterFeatures doFeatures() const override { return {}; }
};
struct MySceneConverter: Trade::AbstractSceneConverter {
explicit MySceneConverter(PluginManager::AbstractManager& manager, Containers::StringView plugin): Trade::AbstractSceneConverter{manager, plugin} {}
Trade::SceneConverterFeatures doFeatures() const override { return {}; }
};
}
/* [MAGNUM_TRADE_ABSTRACTIMPORTER_PLUGIN_INTERFACE] */
CORRADE_PLUGIN_REGISTER(MyImporter, MyNamespace::MyImporter,
MAGNUM_TRADE_ABSTRACTIMPORTER_PLUGIN_INTERFACE)
/* [MAGNUM_TRADE_ABSTRACTIMPORTER_PLUGIN_INTERFACE] */
/* [MAGNUM_TRADE_ABSTRACTIMAGECONVERTER_PLUGIN_INTERFACE] */
CORRADE_PLUGIN_REGISTER(MyImageConverter, MyNamespace::MyImageConverter,
MAGNUM_TRADE_ABSTRACTIMAGECONVERTER_PLUGIN_INTERFACE)
/* [MAGNUM_TRADE_ABSTRACTIMAGECONVERTER_PLUGIN_INTERFACE] */
/* [MAGNUM_TRADE_ABSTRACTSCENECONVERTER_PLUGIN_INTERFACE] */
CORRADE_PLUGIN_REGISTER(MySceneConverter, MyNamespace::MySceneConverter,
MAGNUM_TRADE_ABSTRACTSCENECONVERTER_PLUGIN_INTERFACE)
/* [MAGNUM_TRADE_ABSTRACTSCENECONVERTER_PLUGIN_INTERFACE] */
doc: work around linker warnings about main() being duplicated.
2 years ago
/* Make sure the name doesn't conflict with any other snippets to avoid linker
warnings, unlike with `int main()` there now has to be a declaration to
avoid -Wmisssing-prototypes */
void mainTrade();
void mainTrade() {
Trade: improve docs for the main importer / converter plugins. Interestingly enough, there were no docs whatsoever for image and scene conversion, and neither it was mentioned what all scene data can be imported. Sigh.
5 years ago
{
Vector2i size;
/* [AbstractImageConverter-usage-file] */
PluginManager::Manager<Trade::AbstractImageConverter> manager;
Containers::Pointer<Trade::AbstractImageConverter> converter =
manager.loadAndInstantiate("AnyImageConverter");
doc: rename DOXYGEN_IGNORE() to DOXYGEN_ELLIPSIS(). And use DOXYGEN_IGNORE() for replacing with nothing.
4 years ago
Image2D image{PixelFormat::RGBA8Unorm, size, DOXYGEN_ELLIPSIS({})};
Trade: improve docs for the main importer / converter plugins. Interestingly enough, there were no docs whatsoever for image and scene conversion, and neither it was mentioned what all scene data can be imported. Sigh.
5 years ago
if(!converter || !converter->convertToFile(image, "image.png"))
Fatal{} << "Can't save image.png with AnyImageConverter";
/* [AbstractImageConverter-usage-file] */
}
Trade: add docs about multi-level image conversion.
5 years ago
{
/* [AbstractImageConverter-usage-file-levels] */
PluginManager::Manager<Trade::AbstractImageConverter> manager;
Containers::Pointer<Trade::AbstractImageConverter> converter =
manager.loadAndInstantiate("AnyImageConverter");
doc: rename DOXYGEN_IGNORE() to DOXYGEN_ELLIPSIS(). And use DOXYGEN_IGNORE() for replacing with nothing.
4 years ago
Image2D level0{PixelFormat::RGBA16F, {256, 256}, DOXYGEN_ELLIPSIS({})};
Image2D level1{PixelFormat::RGBA16F, {128, 128}, DOXYGEN_ELLIPSIS({})};
Image2D level2{PixelFormat::RGBA16F, {64, 64}, DOXYGEN_ELLIPSIS({})};
Trade: add docs about multi-level image conversion.
5 years ago
if(!converter || !converter->convertToFile({level0, level1, level2}, "image.exr"))
Fatal{} << "Can't save image.exr with AnyImageConverter";
/* [AbstractImageConverter-usage-file-levels] */
}
Trade: improve docs for the main importer / converter plugins. Interestingly enough, there were no docs whatsoever for image and scene conversion, and neither it was mentioned what all scene data can be imported. Sigh.
5 years ago
{
Image2D image{{}, {}, {}};
/* [AbstractImageConverter-usage-image] */
PluginManager::Manager<Trade::AbstractImageConverter> manager;
Containers::Pointer<Trade::AbstractImageConverter> converter =
manager.loadAndInstantiate("StbDxtImageConverter");
Containers::Optional<Trade::ImageData2D> compressed;
if(!converter || !(compressed = converter->convert(image)))
Fatal{} << "Can't convert the image with StbDxtImageConverter";
CORRADE_INTERNAL_ASSERT(compressed->isCompressed());
/* [AbstractImageConverter-usage-image] */
}
Trade: actually create some useful docs for AbstractImporter.
8 years ago
{
/* [AbstractImporter-usage] */
PluginManager::Manager<Trade::AbstractImporter> manager;
Get rid of std::unique_ptr.
7 years ago
Containers::Pointer<Trade::AbstractImporter> importer =
Trade: actually create some useful docs for AbstractImporter.
8 years ago
manager.loadAndInstantiate("AnyImageImporter");
if(!importer || !importer->openFile("image.png"))
Fatal{} << "Can't open image.png with AnyImageImporter";
Containers::Optional<Trade::ImageData2D> image = importer->image2D(0);
if(!image) Fatal{} << "Importing the image failed";
// use the image ...
/* [AbstractImporter-usage] */
}
Trade: provide a clear doc snippet for AbstractImporter::openData(). The snippet with callbacks was too heavyweight for this kind of operation and workflow with in-memory data may be non-obvious to some users.
5 years ago
{
doc: suppress useless "this pointer is null" warnings on GCC 11+. Having code snippets in docs compiled and checked for syntax and outdated API errors is great. In theory. In practice the people reading docs have NO IDEA how much needless suffering goes into making the compiler collaborate with me on such a seemingly simple task. UGH.
3 years ago
/* -Wnonnull in GCC 11+ "helpfully" says "this is null" if I don't initialize
the converter pointer. I don't care, I just want you to check compilation
errors, not more! */
PluginManager::Manager<Trade::AbstractImporter> manager;
Containers::Pointer<Trade::AbstractImporter> importer = manager.loadAndInstantiate("SomethingWhatever");
Trade: provide a clear doc snippet for AbstractImporter::openData(). The snippet with callbacks was too heavyweight for this kind of operation and workflow with in-memory data may be non-obvious to some users.
5 years ago
/* [AbstractImporter-usage-data] */
Utility::Resource rs{"data"};
Containers::ArrayView<const char> data = rs.getRaw("image.png");
Trade: ability to open non-temporary memory. Using openMemory() instead of openData() allows the implementation to assume the data will stay in scope for as long as needed, which can prevent unnecessary copies in some plugin implementations. It warranted a new flag, DataFlag::ExternallyOwned, to describe this kind of memory. I couldn't reuse Owned as that's used for allocations owned by the instance, which is too little for certain future use cases. For example returning *Data instances referencing an Owned memory would mean the user has to assume the memory is gone when the importer instance is gone, and that's generally not true for memory passed to openMemory(). Originally I thought I would do this later, but then realized the existing plugin implementations would need to get all updated again to be aware of the new flag, with some being forgotten, and it's just easier to do the whole thing in a single step.
5 years ago
if(!importer->openData(data)) /* or openMemory() */
Trade: provide a clear doc snippet for AbstractImporter::openData(). The snippet with callbacks was too heavyweight for this kind of operation and workflow with in-memory data may be non-obvious to some users.
5 years ago
Fatal{} << "Can't open image data with AnyImageImporter";
// import & use the image like above ...
/* [AbstractImporter-usage-data] */
}
Trade: actually create some useful docs for AbstractImporter.
8 years ago
#if defined(CORRADE_TARGET_UNIX) || (defined(CORRADE_TARGET_WINDOWS) && !defined(CORRADE_TARGET_WINDOWS_RT))
{
doc: suppress useless "this pointer is null" warnings on GCC 11+. Having code snippets in docs compiled and checked for syntax and outdated API errors is great. In theory. In practice the people reading docs have NO IDEA how much needless suffering goes into making the compiler collaborate with me on such a seemingly simple task. UGH.
3 years ago
/* -Wnonnull in GCC 11+ "helpfully" says "this is null" if I don't initialize
the converter pointer. I don't care, I just want you to check compilation
errors, not more! */
PluginManager::Manager<Trade::AbstractImporter> manager;
Containers::Pointer<Trade::AbstractImporter> importer = manager.loadAndInstantiate("SomethingWhatever");
Trade: actually create some useful docs for AbstractImporter.
8 years ago
/* [AbstractImporter-usage-callbacks] */
struct Data {
Trade: port to the new Utility::Path. For file opening there's no longer an unatomic pair of exists() + read(), but since Path::read() now returns an Optional, it means we can reliably distinguish between empty files and failures. While at it, also added TODOs for removal of the StringStl.h header that's needed in various places for compatibility with APIs still using STL strings.
4 years ago
std::unordered_map<std::string, Containers::Optional<
Containers::Array<const char, Utility::Path::MapDeleter>>> files;
Trade: actually create some useful docs for AbstractImporter.
8 years ago
} data;
importer->setFileCallback([](const std::string& filename,
Move Trade::ImporterFileCallbackPolicy to InputFileCallbackPolicy. It'll get used outside of the root namespace and since the callbacks tend to be quite complex, it would be silly to require users to implement one callback for Trade, one for Text and one for Audio, for example.
7 years ago
InputFileCallbackPolicy policy, Data& data)
Trade: redesign importer file callbacks. The original implementation had a few problems: - If a file callback was set, openFile() was unconditionally calling right into doOpenData(), making it impossible for the importer to know the original path for correctly supplying paths to additional files. Now, if the importer supports Feature::FileCallback, doOpenFile() is always called. It's also possible for the importer to save the path and then just delegate to the base doOpenFile() implementation -- it will handle the file callbacks correctly too. - If the importer supported neither FileCallback nor OpenData and callbacks were set, the original doOpenFile() implementation was called without any warning or anything, doing silently a bad thing. Now in this case setFileCallbacks() asserts -- programmer has to check for feature support first. - It was not possible for the file callback to indicate file opening failure -- in general, empty files are valid, so a nullptr ArrayView is also a valid file. Now the callback return an Optional instead.
8 years ago
-> Containers::Optional<Containers::ArrayView<const char>>
{
Trade: actually create some useful docs for AbstractImporter.
8 years ago
auto found = data.files.find(filename);
/* Discard the memory mapping, if not needed anymore */
Move Trade::ImporterFileCallbackPolicy to InputFileCallbackPolicy. It'll get used outside of the root namespace and since the callbacks tend to be quite complex, it would be silly to require users to implement one callback for Trade, one for Text and one for Audio, for example.
7 years ago
if(policy == InputFileCallbackPolicy::Close) {
Trade: actually create some useful docs for AbstractImporter.
8 years ago
if(found != data.files.end()) data.files.erase(found);
Trade: redesign importer file callbacks. The original implementation had a few problems: - If a file callback was set, openFile() was unconditionally calling right into doOpenData(), making it impossible for the importer to know the original path for correctly supplying paths to additional files. Now, if the importer supports Feature::FileCallback, doOpenFile() is always called. It's also possible for the importer to save the path and then just delegate to the base doOpenFile() implementation -- it will handle the file callbacks correctly too. - If the importer supported neither FileCallback nor OpenData and callbacks were set, the original doOpenFile() implementation was called without any warning or anything, doing silently a bad thing. Now in this case setFileCallbacks() asserts -- programmer has to check for feature support first. - It was not possible for the file callback to indicate file opening failure -- in general, empty files are valid, so a nullptr ArrayView is also a valid file. Now the callback return an Optional instead.
8 years ago
return {};
Trade: actually create some useful docs for AbstractImporter.
8 years ago
}
Trade: port to the new Utility::Path. For file opening there's no longer an unatomic pair of exists() + read(), but since Path::read() now returns an Optional, it means we can reliably distinguish between empty files and failures. While at it, also added TODOs for removal of the StringStl.h header that's needed in various places for compatibility with APIs still using STL strings.
4 years ago
/* Load if not there yet. If the mapping fails, remember that to not
attempt to load the same file again next time. */
Trade: actually create some useful docs for AbstractImporter.
8 years ago
if(found == data.files.end()) found = data.files.emplace(
Trade: port to the new Utility::Path. For file opening there's no longer an unatomic pair of exists() + read(), but since Path::read() now returns an Optional, it means we can reliably distinguish between empty files and failures. While at it, also added TODOs for removal of the StringStl.h header that's needed in various places for compatibility with APIs still using STL strings.
4 years ago
filename, Utility::Path::mapRead(filename)).first;
Trade: actually create some useful docs for AbstractImporter.
8 years ago
Trade: port to the new Utility::Path. For file opening there's no longer an unatomic pair of exists() + read(), but since Path::read() now returns an Optional, it means we can reliably distinguish between empty files and failures. While at it, also added TODOs for removal of the StringStl.h header that's needed in various places for compatibility with APIs still using STL strings.
4 years ago
if(!found->second) return {};
return Containers::arrayView(*found->second);
Trade: actually create some useful docs for AbstractImporter.
8 years ago
}, data);
importer->openFile("scene.gltf"); // memory-maps all files
/* [AbstractImporter-usage-callbacks] */
}
#endif
Trade: support for file loading callbacks in AbstractImporter.
8 years ago
{
doc: suppress useless "this pointer is null" warnings on GCC 11+. Having code snippets in docs compiled and checked for syntax and outdated API errors is great. In theory. In practice the people reading docs have NO IDEA how much needless suffering goes into making the compiler collaborate with me on such a seemingly simple task. UGH.
3 years ago
/* -Wnonnull in GCC 11+ "helpfully" says "this is null" if I don't initialize
the converter pointer. I don't care, I just want you to check compilation
errors, not more! */
PluginManager::Manager<Trade::AbstractImporter> manager;
Containers::Pointer<Trade::AbstractImporter> importer = manager.loadAndInstantiate("SomethingWhatever");
Trade: support for file loading callbacks in AbstractImporter.
8 years ago
/* [AbstractImporter-setFileCallback] */
importer->setFileCallback([](const std::string& filename,
Move Trade::ImporterFileCallbackPolicy to InputFileCallbackPolicy. It'll get used outside of the root namespace and since the callbacks tend to be quite complex, it would be silly to require users to implement one callback for Trade, one for Text and one for Audio, for example.
7 years ago
InputFileCallbackPolicy, void*) {
Trade,Text: this is a much better example for template file callbacks.
6 years ago
Utility::Resource rs{"data"};
Trade: redesign importer file callbacks. The original implementation had a few problems: - If a file callback was set, openFile() was unconditionally calling right into doOpenData(), making it impossible for the importer to know the original path for correctly supplying paths to additional files. Now, if the importer supports Feature::FileCallback, doOpenFile() is always called. It's also possible for the importer to save the path and then just delegate to the base doOpenFile() implementation -- it will handle the file callbacks correctly too. - If the importer supported neither FileCallback nor OpenData and callbacks were set, the original doOpenFile() implementation was called without any warning or anything, doing silently a bad thing. Now in this case setFileCallbacks() asserts -- programmer has to check for feature support first. - It was not possible for the file callback to indicate file opening failure -- in general, empty files are valid, so a nullptr ArrayView is also a valid file. Now the callback return an Optional instead.
8 years ago
return Containers::optional(rs.getRaw(filename));
Trade: support for file loading callbacks in AbstractImporter.
8 years ago
});
/* [AbstractImporter-setFileCallback] */
}
{
doc: suppress useless "this pointer is null" warnings on GCC 11+. Having code snippets in docs compiled and checked for syntax and outdated API errors is great. In theory. In practice the people reading docs have NO IDEA how much needless suffering goes into making the compiler collaborate with me on such a seemingly simple task. UGH.
3 years ago
/* -Wnonnull in GCC 11+ "helpfully" says "this is null" if I don't initialize
the converter pointer. I don't care, I just want you to check compilation
errors, not more! */
PluginManager::Manager<Trade::AbstractImporter> manager;
Containers::Pointer<Trade::AbstractImporter> importer = manager.loadAndInstantiate("SomethingWhatever");
Trade: support for file loading callbacks in AbstractImporter.
8 years ago
/* [AbstractImporter-setFileCallback-template] */
Trade,Text: this is a much better example for template file callbacks.
6 years ago
const Utility::Resource rs{"data"};
Trade: support for file loading callbacks in AbstractImporter.
8 years ago
importer->setFileCallback([](const std::string& filename,
Trade,Text: this is a much better example for template file callbacks.
6 years ago
InputFileCallbackPolicy, const Utility::Resource& rs) {
return Containers::optional(rs.getRaw(filename));
}, rs);
Trade: support for file loading callbacks in AbstractImporter.
8 years ago
/* [AbstractImporter-setFileCallback-template] */
}
Trade: AbstractImporter::doOpenData() now takes a rvalue Array. This allows to better describe memory ownership and transfer it instead of forcing the plugins to allocate their own local copy if the import happens in-place on the imported data. Right now that's mainly for the openFile() use case, which implicitly allocated an Array with file contents only to pass it to openData() which then made a copy because it could not make any assumption about data scope. In other words, certain plugins (TgaImporter, KtxImporter, DdsImporter, CgltfImporter and possibly others) will now have their peak memory usage *halved*.
5 years ago
{
struct: Trade::AbstractImporter {
Trade::ImporterFeatures doFeatures() const override { return {}; }
bool doIsOpened() const override { return false; }
void doClose() override {}
Containers::Array<char> _in;
/* [AbstractImporter-doOpenData-ownership] */
void doOpenData(Containers::Array<char>&& data, Trade::DataFlags dataFlags) override
{
/* Take over the existing array or copy the data if we can't */
Trade: ability to open non-temporary memory. Using openMemory() instead of openData() allows the implementation to assume the data will stay in scope for as long as needed, which can prevent unnecessary copies in some plugin implementations. It warranted a new flag, DataFlag::ExternallyOwned, to describe this kind of memory. I couldn't reuse Owned as that's used for allocations owned by the instance, which is too little for certain future use cases. For example returning *Data instances referencing an Owned memory would mean the user has to assume the memory is gone when the importer instance is gone, and that's generally not true for memory passed to openMemory(). Originally I thought I would do this later, but then realized the existing plugin implementations would need to get all updated again to be aware of the new flag, with some being forgotten, and it's just easier to do the whole thing in a single step.
5 years ago
if(dataFlags & (Trade::DataFlag::Owned|Trade::DataFlag::ExternallyOwned)) {
Trade: AbstractImporter::doOpenData() now takes a rvalue Array. This allows to better describe memory ownership and transfer it instead of forcing the plugins to allocate their own local copy if the import happens in-place on the imported data. Right now that's mainly for the openFile() use case, which implicitly allocated an Array with file contents only to pass it to openData() which then made a copy because it could not make any assumption about data scope. In other words, certain plugins (TgaImporter, KtxImporter, DdsImporter, CgltfImporter and possibly others) will now have their peak memory usage *halved*.
5 years ago
_in = std::move(data);
} else {
_in = Containers::Array<char>{NoInit, data.size()};
Utility::copy(data, _in);
}
doc: rename DOXYGEN_IGNORE() to DOXYGEN_ELLIPSIS(). And use DOXYGEN_IGNORE() for replacing with nothing.
4 years ago
DOXYGEN_ELLIPSIS()
Trade: AbstractImporter::doOpenData() now takes a rvalue Array. This allows to better describe memory ownership and transfer it instead of forcing the plugins to allocate their own local copy if the import happens in-place on the imported data. Right now that's mainly for the openFile() use case, which implicitly allocated an Array with file contents only to pass it to openData() which then made a copy because it could not make any assumption about data scope. In other words, certain plugins (TgaImporter, KtxImporter, DdsImporter, CgltfImporter and possibly others) will now have their peak memory usage *halved*.
5 years ago
}
/* [AbstractImporter-doOpenData-ownership] */
} importer;
}
Trade: improve docs for the main importer / converter plugins. Interestingly enough, there were no docs whatsoever for image and scene conversion, and neither it was mentioned what all scene data can be imported. Sigh.
5 years ago
{
Trade: high-level docs for AbstractSceneConverter whole-scene operation.
4 years ago
/* [AbstractSceneConverter-usage-mesh-file] */
Trade: improve docs for the main importer / converter plugins. Interestingly enough, there were no docs whatsoever for image and scene conversion, and neither it was mentioned what all scene data can be imported. Sigh.
5 years ago
PluginManager::Manager<Trade::AbstractSceneConverter> manager;
Containers::Pointer<Trade::AbstractSceneConverter> converter =
manager.loadAndInstantiate("AnySceneConverter");
doc: rename DOXYGEN_IGNORE() to DOXYGEN_ELLIPSIS(). And use DOXYGEN_IGNORE() for replacing with nothing.
4 years ago
Trade::MeshData mesh = DOXYGEN_ELLIPSIS(Trade::MeshData{{}, {}});
Trade: improve docs for the main importer / converter plugins. Interestingly enough, there were no docs whatsoever for image and scene conversion, and neither it was mentioned what all scene data can be imported. Sigh.
5 years ago
if(!converter || !converter->convertToFile(mesh, "mesh.ply"))
Fatal{} << "Can't save mesh.ply with AnySceneConverter";
Trade: high-level docs for AbstractSceneConverter whole-scene operation.
4 years ago
/* [AbstractSceneConverter-usage-mesh-file] */
Trade: improve docs for the main importer / converter plugins. Interestingly enough, there were no docs whatsoever for image and scene conversion, and neither it was mentioned what all scene data can be imported. Sigh.
5 years ago
}
{
Trade::MeshData mesh{{}, {}};
/* [AbstractSceneConverter-usage-mesh] */
PluginManager::Manager<Trade::AbstractSceneConverter> manager;
Containers::Pointer<Trade::AbstractSceneConverter> converter =
manager.loadAndInstantiate("MeshOptimizerSceneConverter");
Containers::Optional<Trade::MeshData> optimized;
if(!converter || !(optimized = converter->convert(mesh)))
Fatal{} << "Can't optimize the mesh with MeshOptimizerSceneConverter";
/* [AbstractSceneConverter-usage-mesh] */
}
{
Trade::MeshData mesh{{}, {}};
Containers::Pointer<Trade::AbstractSceneConverter> converter;
/* [AbstractSceneConverter-usage-mesh-in-place] */
if(!converter || !converter->convertInPlace(mesh))
Fatal{} << "Can't optimize the mesh with MeshOptimizerSceneConverter";
/* [AbstractSceneConverter-usage-mesh-in-place] */
}
Trade: high-level docs for AbstractSceneConverter whole-scene operation.
4 years ago
{
/* [AbstractSceneConverter-usage-multiple-file] */
PluginManager::Manager<Trade::AbstractImporter> importerManager;
Containers::Pointer<Trade::AbstractImporter> importer =
importerManager.loadAndInstantiate("AnySceneImporter");
if(!importer || importer->openFile("file.dae"))
Fatal{} << "Can't open the input file";
PluginManager::Manager<Trade::AbstractSceneConverter> manager;
Containers::Pointer<Trade::AbstractSceneConverter> converter =
manager.loadAndInstantiate("AnySceneConverter");
if(!converter->beginFile("file.gltf") ||
!converter->addSupportedImporterContents(*importer) ||
!converter->endFile())
Fatal{} << "Can't save the output file";
/* [AbstractSceneConverter-usage-multiple-file] */
}
{
Containers::Pointer<Trade::AbstractImporter> importer;
Containers::Pointer<Trade::AbstractSceneConverter> converter;
/* [AbstractSceneConverter-usage-multiple-file-selective] */
if(!converter->beginFile("file.gltf"))
Fatal{} << "Can't begin the output file";
/* Add meshes manually, removing duplicates in each in the process */
for(UnsignedInt i = 0; i != importer->meshCount(); ++i) {
Containers::Optional<Trade::MeshData> mesh = importer->mesh(i);
if(!mesh ||
!converter->add(MeshTools::removeDuplicates(*mesh), importer->meshName(i)))
Fatal{} << "Can't add mesh" << i;
}
/* Add the rest of the input file and finish */
if(!converter->addSupportedImporterContents(*importer, ~Trade::SceneContent::Meshes) ||
!converter->endFile())
Fatal{} << "Can't save the output file";
/* [AbstractSceneConverter-usage-multiple-file-selective] */
}
Trade: document AnimationData usage. This is the last non-obvious thing that needs to be documented in order to make the API usable.
8 years ago
{
UnsignedInt id{};
Get rid of std::unique_ptr.
7 years ago
Containers::Pointer<Trade::AbstractImporter> importer;
Trade: document AnimationData usage. This is the last non-obvious thing that needs to be documented in order to make the API usable.
8 years ago
/* [AnimationData-usage] */
Containers::Optional<Trade::AnimationData> data = importer->animation(id);
Animation::Player<Float> player;
Containers::Array<Vector3> positions; /* Translations for all objects */
for(UnsignedInt i = 0; i != data->trackCount(); ++i) {
Trade: rename AnimationTrackTargetType to AnimationTrackTarget. The `Type` was suggesting it'd be some C++ type, definitely not values like Scaling3D or Translation2D, resulting in a significant "brain autocompletion error" every time I was using that type. Unfortunately on AnimationData the trackTargetType() couldn't similarly get renamed to trackTarget() as there's already trackTarget() that contains the node ID the target points to, so it's trackTargetName() instead. Renaming trackTarget() to trackTargetId() wasn't an option as that would be inconsistent with everything else (TextureTools::image(), MaterialAttribute::BaseColorTexture, SceneField::Mesh are all IDs but they don't have an `Id` suffix); renaming to AnimationTrackTargetName would keep it insanely long and wouldn't make it consistent either (MeshAttribute, SceneFIeld, MaterialAttribute are all referred to as "names" yet they don't have a `Name` suffix).
3 years ago
if(data->trackTargetName(i) == Trade::AnimationTrackTarget::Translation3D) {
Trade: document AnimationData usage. This is the last non-obvious thing that needs to be documented in order to make the API usable.
8 years ago
CORRADE_INTERNAL_ASSERT(data->trackType(i) ==
Trade::AnimationTrackType::Vector3);
Trade: change animation track target to target type and target ID to target. This is in line with how the other APIs are named (for example ObjectDataXD have instance type and instance). This would be very hard to change later without breaking backwards compatibility, so I'm doing it now, until the animation APIs get widely used.
8 years ago
player.add(data->track<Vector3>(i), positions[data->trackTarget(i)]);
Trade: document AnimationData usage. This is the last non-obvious thing that needs to be documented in order to make the API usable.
8 years ago
}
// similarly for rotation / scaling ...
}
Containers::Array<char> animationData = data->release(); /* Take ownership */
/* [AnimationData-usage] */
}
Trade: mutable access in AnimationData. Follows the change done in MeshData.
7 years ago
{
Trade::AnimationData data{nullptr, {}};
/* [AnimationData-usage-mutable] */
for(UnsignedInt i = 0; i != data.trackCount(); ++i) {
Trade: rename AnimationTrackTargetType to AnimationTrackTarget. The `Type` was suggesting it'd be some C++ type, definitely not values like Scaling3D or Translation2D, resulting in a significant "brain autocompletion error" every time I was using that type. Unfortunately on AnimationData the trackTargetType() couldn't similarly get renamed to trackTarget() as there's already trackTarget() that contains the node ID the target points to, so it's trackTargetName() instead. Renaming trackTarget() to trackTargetId() wasn't an option as that would be inconsistent with everything else (TextureTools::image(), MaterialAttribute::BaseColorTexture, SceneField::Mesh are all IDs but they don't have an `Id` suffix); renaming to AnimationTrackTargetName would keep it insanely long and wouldn't make it consistent either (MeshAttribute, SceneFIeld, MaterialAttribute are all referred to as "names" yet they don't have a `Name` suffix).
3 years ago
if(data.trackTargetName(i) != Trade::AnimationTrackTarget::Translation3D)
Trade: mutable access in AnimationData. Follows the change done in MeshData.
7 years ago
continue;
/* Check prerequisites */
if(!(data.dataFlags() & Trade::DataFlag::Mutable) ||
data.trackType(i) != Trade::AnimationTrackType::Vector2)
Fatal{} << "Oops";
MeshTools::transformVectorsInPlace(Matrix4::scaling(Vector3::yScale(-1.0f)),
data.mutableTrack<Vector3>(i).values());
}
/* [AnimationData-usage-mutable] */
}
Split the OpenGL layer out, pt 9: generic pixel formats. This is quite big, so: * There are new Magnum::PixelFormat and Magnum::CompressedPixelFormat enums, which contain generic API-independent formats. In particular, PixelFormat replaces GL::PixelFormat and GL::PixelType with a single value. * There's GL::pixelFormat(), GL::pixelType(), GL::compressedPixelFormat() to convert the generic enums to GL-specific. The mapping is only in one direction, done with a lookup table (generic enums are indices to that table). * GL classes taking the formats directly (such as GL::BufferImage) have overloads that take both the GL-specific and generic format. * The generic Image, CompressedImage, ImageView, CompressedImageView, and Trade::ImageData classes now accept the generic formats first-class. However, it's also possible to store an implementation-specific value to cover cases where a generic format enum doesn't have support for a particular format. This is done by wrapping the value using pixelFormatWrap() or compressedPixelFormatWrap(). Particular GPU APIs then assume it's their implementation-specific value and extract the value back using pixelFormatUnwrap() or compressedPixelFormatUnwrap(). There's also an isPixelFormatImplementationSpecific() and isCompressedPixelFormatImplementationSpecific() that distinguishes these values. * Many operations need pixel size and in order to have it even for implementation-specific formats, a corresponding pixelSize() overload is found via ADL on construction and the calculated size stored along the format. Previously the pixel size was only calculated on demand, but that's not possible now. In case such overload is not available, it's possible to pass pixel size manually as well. * In order to support the GL format+type pair, Image, ImageView and Trade::ImageData, there's now an additional untyped formatExtra() field that holds the second value. * The CompressedPixelStorage class is now unconditionally available on all targets, including OpenGL ES and WebGL. However, on OpenGL ES the GL APIs expect that it's all at default values. I attempted to preserve backwards compatibility as much as possible: * The PixelFormat and CompressedPixelFormat enum now contains generic API-independent values. The GL-specific formats are present there, but marked as deprecated. Use either the generic values or GL::PixelFormat (togehter with GL::PixelType) and GL::CompressedPixelFormat instead. There's a lot of ugliness caused by this, but seems to work well. * *Image::type() functions are deprecated as they were too GL-specific. Use formatExtra() and cast it to GL::PixelType instead. * Image constructors take templated format or format+extra arguments, so passing GL-specific values to them should still work.
8 years ago
{
Improve docs of image classes. It looked like it was last touched in 2012. Not great. Also, with this I can finally stop explaining the four-byte-aligned-row defaults to people and can just point them to docs.
3 years ago
/* [ImageData-populating] */
Containers::Array<char> uncompressedData = DOXYGEN_ELLIPSIS({});
Trade::ImageData2D uncompressed{PixelFormat::RGB8Unorm,
{32, 32}, std::move(uncompressedData)};
Containers::Array<char> compressedData = DOXYGEN_ELLIPSIS({});
Trade::ImageData2D compressed{CompressedPixelFormat::Bc1RGBUnorm,
{32, 32}, std::move(compressedData)};
/* [ImageData-populating] */
Split the OpenGL layer out, pt 9: generic pixel formats. This is quite big, so: * There are new Magnum::PixelFormat and Magnum::CompressedPixelFormat enums, which contain generic API-independent formats. In particular, PixelFormat replaces GL::PixelFormat and GL::PixelType with a single value. * There's GL::pixelFormat(), GL::pixelType(), GL::compressedPixelFormat() to convert the generic enums to GL-specific. The mapping is only in one direction, done with a lookup table (generic enums are indices to that table). * GL classes taking the formats directly (such as GL::BufferImage) have overloads that take both the GL-specific and generic format. * The generic Image, CompressedImage, ImageView, CompressedImageView, and Trade::ImageData classes now accept the generic formats first-class. However, it's also possible to store an implementation-specific value to cover cases where a generic format enum doesn't have support for a particular format. This is done by wrapping the value using pixelFormatWrap() or compressedPixelFormatWrap(). Particular GPU APIs then assume it's their implementation-specific value and extract the value back using pixelFormatUnwrap() or compressedPixelFormatUnwrap(). There's also an isPixelFormatImplementationSpecific() and isCompressedPixelFormatImplementationSpecific() that distinguishes these values. * Many operations need pixel size and in order to have it even for implementation-specific formats, a corresponding pixelSize() overload is found via ADL on construction and the calculated size stored along the format. Previously the pixel size was only calculated on demand, but that's not possible now. In case such overload is not available, it's possible to pass pixel size manually as well. * In order to support the GL format+type pair, Image, ImageView and Trade::ImageData, there's now an additional untyped formatExtra() field that holds the second value. * The CompressedPixelStorage class is now unconditionally available on all targets, including OpenGL ES and WebGL. However, on OpenGL ES the GL APIs expect that it's all at default values. I attempted to preserve backwards compatibility as much as possible: * The PixelFormat and CompressedPixelFormat enum now contains generic API-independent values. The GL-specific formats are present there, but marked as deprecated. Use either the generic values or GL::PixelFormat (togehter with GL::PixelType) and GL::CompressedPixelFormat instead. There's a lot of ugliness caused by this, but seems to work well. * *Image::type() functions are deprecated as they were too GL-specific. Use formatExtra() and cast it to GL::PixelType instead. * Image constructors take templated format or format+extra arguments, so passing GL-specific values to them should still work.
8 years ago
}
{
Improve docs of image classes. It looked like it was last touched in 2012. Not great. Also, with this I can finally stop explaining the four-byte-aligned-row defaults to people and can just point them to docs.
3 years ago
/* [ImageData-populating-non-owned] */
Color3ub uncompressedData[]{DOXYGEN_ELLIPSIS({})};
Trade::ImageData2D uncompressed{PixelFormat::RGB8Unorm,
{32, 32}, Trade::DataFlag::Mutable, uncompressedData};
Containers::ArrayView<const char> compressedData = DOXYGEN_ELLIPSIS({});
Trade::ImageData2D compressed{CompressedPixelFormat::Bc1RGBUnorm,
{32, 32}, Trade::DataFlags{}, compressedData};
/* [ImageData-populating-non-owned] */
}
{
/* [ImageData-populating-padding] */
PixelFormat format = DOXYGEN_ELLIPSIS({});
Vector2i size = DOXYGEN_ELLIPSIS({});
std::size_t rowStride = 4*((size.x()*pixelFormatSize(format) + 3)/4);
Containers::Array<char> data{ValueInit, std::size_t(size.y()*rowStride)};
DOXYGEN_ELLIPSIS()
Trade::ImageData2D image{format, size, std::move(data)};
/* [ImageData-populating-padding] */
}
{
/* [ImageData-populating-alignment] */
PixelFormat format = DOXYGEN_ELLIPSIS({});
Vector2i size = DOXYGEN_ELLIPSIS({});
std::size_t rowLength = size.x()*pixelFormatSize(format);
Containers::Array<char> data{ValueInit, std::size_t(size.y()*rowLength)};
DOXYGEN_ELLIPSIS()
Trade::ImageData2D image{
PixelStorage{}.setAlignment(rowLength % 4 == 0 ? 4 : 1),
format, size, std::move(data)};
/* [ImageData-populating-alignment] */
Split the OpenGL layer out, pt 9: generic pixel formats. This is quite big, so: * There are new Magnum::PixelFormat and Magnum::CompressedPixelFormat enums, which contain generic API-independent formats. In particular, PixelFormat replaces GL::PixelFormat and GL::PixelType with a single value. * There's GL::pixelFormat(), GL::pixelType(), GL::compressedPixelFormat() to convert the generic enums to GL-specific. The mapping is only in one direction, done with a lookup table (generic enums are indices to that table). * GL classes taking the formats directly (such as GL::BufferImage) have overloads that take both the GL-specific and generic format. * The generic Image, CompressedImage, ImageView, CompressedImageView, and Trade::ImageData classes now accept the generic formats first-class. However, it's also possible to store an implementation-specific value to cover cases where a generic format enum doesn't have support for a particular format. This is done by wrapping the value using pixelFormatWrap() or compressedPixelFormatWrap(). Particular GPU APIs then assume it's their implementation-specific value and extract the value back using pixelFormatUnwrap() or compressedPixelFormatUnwrap(). There's also an isPixelFormatImplementationSpecific() and isCompressedPixelFormatImplementationSpecific() that distinguishes these values. * Many operations need pixel size and in order to have it even for implementation-specific formats, a corresponding pixelSize() overload is found via ADL on construction and the calculated size stored along the format. Previously the pixel size was only calculated on demand, but that's not possible now. In case such overload is not available, it's possible to pass pixel size manually as well. * In order to support the GL format+type pair, Image, ImageView and Trade::ImageData, there's now an additional untyped formatExtra() field that holds the second value. * The CompressedPixelStorage class is now unconditionally available on all targets, including OpenGL ES and WebGL. However, on OpenGL ES the GL APIs expect that it's all at default values. I attempted to preserve backwards compatibility as much as possible: * The PixelFormat and CompressedPixelFormat enum now contains generic API-independent values. The GL-specific formats are present there, but marked as deprecated. Use either the generic values or GL::PixelFormat (togehter with GL::PixelType) and GL::CompressedPixelFormat instead. There's a lot of ugliness caused by this, but seems to work well. * *Image::type() functions are deprecated as they were too GL-specific. Use formatExtra() and cast it to GL::PixelType instead. * Image constructors take templated format or format+extra arguments, so passing GL-specific values to them should still work.
8 years ago
}
#ifdef MAGNUM_TARGET_GL
{
/* [ImageData-usage] */
Improve docs of image classes. It looked like it was last touched in 2012. Not great. Also, with this I can finally stop explaining the four-byte-aligned-row defaults to people and can just point them to docs.
3 years ago
Trade::ImageData2D image = DOXYGEN_ELLIPSIS(Trade::ImageData2D{PixelFormat{}, {}, nullptr});
Split the OpenGL layer out, pt 9: generic pixel formats. This is quite big, so: * There are new Magnum::PixelFormat and Magnum::CompressedPixelFormat enums, which contain generic API-independent formats. In particular, PixelFormat replaces GL::PixelFormat and GL::PixelType with a single value. * There's GL::pixelFormat(), GL::pixelType(), GL::compressedPixelFormat() to convert the generic enums to GL-specific. The mapping is only in one direction, done with a lookup table (generic enums are indices to that table). * GL classes taking the formats directly (such as GL::BufferImage) have overloads that take both the GL-specific and generic format. * The generic Image, CompressedImage, ImageView, CompressedImageView, and Trade::ImageData classes now accept the generic formats first-class. However, it's also possible to store an implementation-specific value to cover cases where a generic format enum doesn't have support for a particular format. This is done by wrapping the value using pixelFormatWrap() or compressedPixelFormatWrap(). Particular GPU APIs then assume it's their implementation-specific value and extract the value back using pixelFormatUnwrap() or compressedPixelFormatUnwrap(). There's also an isPixelFormatImplementationSpecific() and isCompressedPixelFormatImplementationSpecific() that distinguishes these values. * Many operations need pixel size and in order to have it even for implementation-specific formats, a corresponding pixelSize() overload is found via ADL on construction and the calculated size stored along the format. Previously the pixel size was only calculated on demand, but that's not possible now. In case such overload is not available, it's possible to pass pixel size manually as well. * In order to support the GL format+type pair, Image, ImageView and Trade::ImageData, there's now an additional untyped formatExtra() field that holds the second value. * The CompressedPixelStorage class is now unconditionally available on all targets, including OpenGL ES and WebGL. However, on OpenGL ES the GL APIs expect that it's all at default values. I attempted to preserve backwards compatibility as much as possible: * The PixelFormat and CompressedPixelFormat enum now contains generic API-independent values. The GL-specific formats are present there, but marked as deprecated. Use either the generic values or GL::PixelFormat (togehter with GL::PixelType) and GL::CompressedPixelFormat instead. There's a lot of ugliness caused by this, but seems to work well. * *Image::type() functions are deprecated as they were too GL-specific. Use formatExtra() and cast it to GL::PixelType instead. * Image constructors take templated format or format+extra arguments, so passing GL-specific values to them should still work.
8 years ago
GL::Texture2D texture;
doc: rename DOXYGEN_IGNORE() to DOXYGEN_ELLIPSIS(). And use DOXYGEN_IGNORE() for replacing with nothing.
4 years ago
DOXYGEN_ELLIPSIS()
Improve docs of image classes. It looked like it was last touched in 2012. Not great. Also, with this I can finally stop explaining the four-byte-aligned-row defaults to people and can just point them to docs.
3 years ago
texture.setStorage(1, GL::textureFormat(image.format()), image.size());
if(!image.isCompressed())
texture.setSubImage(0, {}, image);
Split the OpenGL layer out, pt 9: generic pixel formats. This is quite big, so: * There are new Magnum::PixelFormat and Magnum::CompressedPixelFormat enums, which contain generic API-independent formats. In particular, PixelFormat replaces GL::PixelFormat and GL::PixelType with a single value. * There's GL::pixelFormat(), GL::pixelType(), GL::compressedPixelFormat() to convert the generic enums to GL-specific. The mapping is only in one direction, done with a lookup table (generic enums are indices to that table). * GL classes taking the formats directly (such as GL::BufferImage) have overloads that take both the GL-specific and generic format. * The generic Image, CompressedImage, ImageView, CompressedImageView, and Trade::ImageData classes now accept the generic formats first-class. However, it's also possible to store an implementation-specific value to cover cases where a generic format enum doesn't have support for a particular format. This is done by wrapping the value using pixelFormatWrap() or compressedPixelFormatWrap(). Particular GPU APIs then assume it's their implementation-specific value and extract the value back using pixelFormatUnwrap() or compressedPixelFormatUnwrap(). There's also an isPixelFormatImplementationSpecific() and isCompressedPixelFormatImplementationSpecific() that distinguishes these values. * Many operations need pixel size and in order to have it even for implementation-specific formats, a corresponding pixelSize() overload is found via ADL on construction and the calculated size stored along the format. Previously the pixel size was only calculated on demand, but that's not possible now. In case such overload is not available, it's possible to pass pixel size manually as well. * In order to support the GL format+type pair, Image, ImageView and Trade::ImageData, there's now an additional untyped formatExtra() field that holds the second value. * The CompressedPixelStorage class is now unconditionally available on all targets, including OpenGL ES and WebGL. However, on OpenGL ES the GL APIs expect that it's all at default values. I attempted to preserve backwards compatibility as much as possible: * The PixelFormat and CompressedPixelFormat enum now contains generic API-independent values. The GL-specific formats are present there, but marked as deprecated. Use either the generic values or GL::PixelFormat (togehter with GL::PixelType) and GL::CompressedPixelFormat instead. There's a lot of ugliness caused by this, but seems to work well. * *Image::type() functions are deprecated as they were too GL-specific. Use formatExtra() and cast it to GL::PixelType instead. * Image constructors take templated format or format+extra arguments, so passing GL-specific values to them should still work.
8 years ago
else
Improve docs of image classes. It looked like it was last touched in 2012. Not great. Also, with this I can finally stop explaining the four-byte-aligned-row defaults to people and can just point them to docs.
3 years ago
texture.setCompressedSubImage(0, {}, image);
Split the OpenGL layer out, pt 9: generic pixel formats. This is quite big, so: * There are new Magnum::PixelFormat and Magnum::CompressedPixelFormat enums, which contain generic API-independent formats. In particular, PixelFormat replaces GL::PixelFormat and GL::PixelType with a single value. * There's GL::pixelFormat(), GL::pixelType(), GL::compressedPixelFormat() to convert the generic enums to GL-specific. The mapping is only in one direction, done with a lookup table (generic enums are indices to that table). * GL classes taking the formats directly (such as GL::BufferImage) have overloads that take both the GL-specific and generic format. * The generic Image, CompressedImage, ImageView, CompressedImageView, and Trade::ImageData classes now accept the generic formats first-class. However, it's also possible to store an implementation-specific value to cover cases where a generic format enum doesn't have support for a particular format. This is done by wrapping the value using pixelFormatWrap() or compressedPixelFormatWrap(). Particular GPU APIs then assume it's their implementation-specific value and extract the value back using pixelFormatUnwrap() or compressedPixelFormatUnwrap(). There's also an isPixelFormatImplementationSpecific() and isCompressedPixelFormatImplementationSpecific() that distinguishes these values. * Many operations need pixel size and in order to have it even for implementation-specific formats, a corresponding pixelSize() overload is found via ADL on construction and the calculated size stored along the format. Previously the pixel size was only calculated on demand, but that's not possible now. In case such overload is not available, it's possible to pass pixel size manually as well. * In order to support the GL format+type pair, Image, ImageView and Trade::ImageData, there's now an additional untyped formatExtra() field that holds the second value. * The CompressedPixelStorage class is now unconditionally available on all targets, including OpenGL ES and WebGL. However, on OpenGL ES the GL APIs expect that it's all at default values. I attempted to preserve backwards compatibility as much as possible: * The PixelFormat and CompressedPixelFormat enum now contains generic API-independent values. The GL-specific formats are present there, but marked as deprecated. Use either the generic values or GL::PixelFormat (togehter with GL::PixelType) and GL::CompressedPixelFormat instead. There's a lot of ugliness caused by this, but seems to work well. * *Image::type() functions are deprecated as they were too GL-specific. Use formatExtra() and cast it to GL::PixelType instead. * Image constructors take templated format or format+extra arguments, so passing GL-specific values to them should still work.
8 years ago
/* [ImageData-usage] */
}
#endif
Trade: mutable access in ImageData consistent with Animation/MeshData.
7 years ago
{
Trade::ImageData2D data{PixelFormat::RGB8Unorm, {}, nullptr};
/* [ImageData-usage-mutable] */
if(data.isCompressed() ||
data.format() != PixelFormat::RGB8Unorm ||
!(data.dataFlags() & Trade::DataFlag::Mutable))
Fatal{} << ":(";
for(auto&& row: data.mutablePixels<Color3ub>())
for(Color3ub& pixel: row)
pixel = Math::gather<'b', 'g', 'r'>(pixel);
/* [ImageData-usage-mutable] */
}
Trade: add attenuation, range and cone angle parameters to LightData. And document how all those go together.
6 years ago
{
/* [LightData-populating-range] */
Trade: deprecate LightData::Type in favor of LightType. Enums in classes are bad, can't forward-declare them.
3 years ago
Trade::LightData data{Trade::LightType::Point,
Trade: add attenuation, range and cone angle parameters to LightData. And document how all those go together.
6 years ago
0xfff3d6_srgbf, 1.0f,
15.0f};
/* [LightData-populating-range] */
}
{
/* [LightData-populating-attenuation] */
Trade: deprecate LightData::Type in favor of LightType. Enums in classes are bad, can't forward-declare them.
3 years ago
Trade::LightData data{Trade::LightType::Spot,
Trade: add attenuation, range and cone angle parameters to LightData. And document how all those go together.
6 years ago
0xf3d6ff_srgbf, 10.0f,
{0.01f, 0.5f, 2.0f},
25.0_degf, 55.0_degf};
/* [LightData-populating-attenuation] */
}
{
/* [LightData-populating-none] */
Trade: deprecate LightData::Type in favor of LightType. Enums in classes are bad, can't forward-declare them.
3 years ago
Trade::LightData data{Trade::LightType::Directional,
Trade: add attenuation, range and cone angle parameters to LightData. And document how all those go together.
6 years ago
0xd6fff3_srgbf, 0.25f};
/* [LightData-populating-none] */
}
Trade: usage docs for MaterialData.
6 years ago
{
/* [MaterialAttributeData-name] */
Trade::MaterialAttributeData a{
doc: slowly switch over to sRGB. Because PBR can't be done without being *correct*.
6 years ago
Trade::MaterialAttribute::DiffuseColor, 0x3bd267ff_srgbaf};
Trade::MaterialAttributeData b{"DiffuseColor", 0x3bd267ff_srgbaf};
Trade: usage docs for MaterialData.
6 years ago
/* [MaterialAttributeData-name] */
}
{
/* [MaterialData-usage] */
doc: rename DOXYGEN_IGNORE() to DOXYGEN_ELLIPSIS(). And use DOXYGEN_IGNORE() for replacing with nothing.
4 years ago
Trade::MaterialData data = DOXYGEN_ELLIPSIS(Trade::MaterialData{{}, {}});
Trade: usage docs for MaterialData.
6 years ago
// Assumes the attribute exists
Float roughness = data.attribute<Float>(Trade::MaterialAttribute::Roughness);
// Optional access
Color4 color = data.attributeOr(Trade::MaterialAttribute::BaseColor,
doc: slowly switch over to sRGB. Because PBR can't be done without being *correct*.
6 years ago
0x3bd267ff_srgbaf);
Trade: usage docs for MaterialData.
6 years ago
if(Containers::Optional<UnsignedInt> texture =
Trade: port away from deprecated MaterialData::tryAttribute().
4 years ago
data.findAttribute<UnsignedInt>(Trade::MaterialAttribute::BaseColorTexture))
Trade: usage docs for MaterialData.
6 years ago
{
// ...
}
/* [MaterialData-usage] */
static_cast<void>(roughness);
static_cast<void>(color);
}
{
Trade::MaterialData data{{}, {}};
/* [MaterialData-usage-types] */
Trade: um.
5 years ago
/* Prefer a specular/glossiness workflow, if present */
Trade: usage docs for MaterialData.
6 years ago
if(data.types() & Trade::MaterialType::PbrSpecularGlossiness) {
const auto& pbr = data.as<Trade::PbrSpecularGlossinessMaterialData>();
Color4 diffuse = pbr.diffuseColor();
Color4 specular = pbr.specularColor();
Float glossiness = pbr.glossiness();
doc: rename DOXYGEN_IGNORE() to DOXYGEN_ELLIPSIS(). And use DOXYGEN_IGNORE() for replacing with nothing.
4 years ago
DOXYGEN_ELLIPSIS(static_cast<void>(diffuse), static_cast<void>(specular), static_cast<void>(glossiness);)
Trade: usage docs for MaterialData.
6 years ago
/* Otherwise use metallic/roughness (or defaults if no attributes present) */
} else {
const auto& pbr = data.as<Trade::PbrMetallicRoughnessMaterialData>();
Color4 base = pbr.baseColor();
Float metalness = pbr.metalness();
Float roughness = pbr.roughness();
doc: rename DOXYGEN_IGNORE() to DOXYGEN_ELLIPSIS(). And use DOXYGEN_IGNORE() for replacing with nothing.
4 years ago
DOXYGEN_ELLIPSIS(static_cast<void>(base), static_cast<void>(metalness), static_cast<void>(roughness);)
Trade: usage docs for MaterialData.
6 years ago
}
/* [MaterialData-usage-types] */
}
{
Trade: rethink common material texture coordinate transform/sets. There's actually a lot of code involved in checking if all textures use the same transform or coordinate set, especially when considering all fallback variants and potential future expansion with separate texture offset/scale/rotation attributes. A lot of the complexity was thus hidden in plugin implementations, which were each trying to find a common value for all textures to save the user from doing the same. All that code can now be removed and left up to the material APIs themselves -- now it's just about checking hasCommonTextureTransformation() and then retrieving that one common transformation, independently on how the material actually defines it.
6 years ago
/* [MaterialData-usage-texture-complexity] */
doc: rename DOXYGEN_IGNORE() to DOXYGEN_ELLIPSIS(). And use DOXYGEN_IGNORE() for replacing with nothing.
4 years ago
Trade::PbrSpecularGlossinessMaterialData data = DOXYGEN_ELLIPSIS(Trade::PbrSpecularGlossinessMaterialData{{}, {}});
Trade: usage docs for MaterialData.
6 years ago
Trade: rethink common material texture coordinate transform/sets. There's actually a lot of code involved in checking if all textures use the same transform or coordinate set, especially when considering all fallback variants and potential future expansion with separate texture offset/scale/rotation attributes. A lot of the complexity was thus hidden in plugin implementations, which were each trying to find a common value for all textures to save the user from doing the same. All that code can now be removed and left up to the material APIs themselves -- now it's just about checking hasCommonTextureTransformation() and then retrieving that one common transformation, independently on how the material actually defines it.
6 years ago
/* Simple case for diffuse + packed specular/glossiness texture, the default
coordinate set and a common coordinate transformation for all textures */
if(data.hasAttribute(Trade::MaterialAttribute::DiffuseTexture) &&
data.hasSpecularGlossinessTexture() &&
data.hasCommonTextureTransformation() && !data.hasTextureCoordinates())
{
UnsignedInt diffuse = data.diffuseTexture();
Trade: rework metallic/roughness packing. Turns out glTF doesn't actually put metalness into R and roughness into G, even though the naming suggests that. This was done originally, but then they changed that in order to be compatible with UE4 and allow for a more efficient storage of an occlusion map. Because this feels extremely arbitrary, the docs have added rationale for each of the packing variants, and I'm also renaming the packed attribute and checks to imply the red channel isn't used.
6 years ago
UnsignedInt specularGlossiness = data.specularTexture();
Trade: rethink common material texture coordinate transform/sets. There's actually a lot of code involved in checking if all textures use the same transform or coordinate set, especially when considering all fallback variants and potential future expansion with separate texture offset/scale/rotation attributes. A lot of the complexity was thus hidden in plugin implementations, which were each trying to find a common value for all textures to save the user from doing the same. All that code can now be removed and left up to the material APIs themselves -- now it's just about checking hasCommonTextureTransformation() and then retrieving that one common transformation, independently on how the material actually defines it.
6 years ago
Matrix3 textureMatrix = data.commonTextureMatrix();
Trade: usage docs for MaterialData.
6 years ago
doc: rename DOXYGEN_IGNORE() to DOXYGEN_ELLIPSIS(). And use DOXYGEN_IGNORE() for replacing with nothing.
4 years ago
DOXYGEN_ELLIPSIS(static_cast<void>(diffuse), static_cast<void>(specularGlossiness), static_cast<void>(textureMatrix);)
Trade: usage docs for MaterialData.
6 years ago
Trade: rethink common material texture coordinate transform/sets. There's actually a lot of code involved in checking if all textures use the same transform or coordinate set, especially when considering all fallback variants and potential future expansion with separate texture offset/scale/rotation attributes. A lot of the complexity was thus hidden in plugin implementations, which were each trying to find a common value for all textures to save the user from doing the same. All that code can now be removed and left up to the material APIs themselves -- now it's just about checking hasCommonTextureTransformation() and then retrieving that one common transformation, independently on how the material actually defines it.
6 years ago
/* Extra work needed when using a non-default texture coordinate set */
} else if(data.hasTextureCoordinates() && data.hasCommonTextureCoordinates()) {
doc: rename DOXYGEN_IGNORE() to DOXYGEN_ELLIPSIS(). And use DOXYGEN_IGNORE() for replacing with nothing.
4 years ago
DOXYGEN_ELLIPSIS()
Trade: rethink common material texture coordinate transform/sets. There's actually a lot of code involved in checking if all textures use the same transform or coordinate set, especially when considering all fallback variants and potential future expansion with separate texture offset/scale/rotation attributes. A lot of the complexity was thus hidden in plugin implementations, which were each trying to find a common value for all textures to save the user from doing the same. All that code can now be removed and left up to the material APIs themselves -- now it's just about checking hasCommonTextureTransformation() and then retrieving that one common transformation, independently on how the material actually defines it.
6 years ago
/* Etc... */
} else Fatal{} << "Material too complex, giving up";
/* [MaterialData-usage-texture-complexity] */
Trade: usage docs for MaterialData.
6 years ago
}
{
Trade::MaterialData data{{}, {}};
/* [MaterialData-usage-layers] */
if(data.hasLayer(Trade::MaterialLayer::ClearCoat)) {
Float clearCoatFactor = data.attributeOr(Trade::MaterialLayer::ClearCoat,
Trade::MaterialAttribute::LayerFactor, 1.0f);
Float clearCoatRoughness = data.attributeOr(Trade::MaterialLayer::ClearCoat,
Trade::MaterialAttribute::Roughness, 0.0f);
doc: rename DOXYGEN_IGNORE() to DOXYGEN_ELLIPSIS(). And use DOXYGEN_IGNORE() for replacing with nothing.
4 years ago
DOXYGEN_ELLIPSIS(static_cast<void>(clearCoatFactor), static_cast<void>(clearCoatRoughness);)
Trade: usage docs for MaterialData.
6 years ago
}
/* [MaterialData-usage-layers] */
}
{
Trade::MaterialData data{{}, {}};
/* [MaterialData-usage-layers-types] */
if(data.types() & Trade::MaterialType::PbrClearCoat) {
const auto& clearCoat = data.as<Trade::PbrClearCoatMaterialData>();
Float clearCoatFactor = clearCoat.layerFactor();
Float clearCoatRoughness = clearCoat.roughness();
doc: rename DOXYGEN_IGNORE() to DOXYGEN_ELLIPSIS(). And use DOXYGEN_IGNORE() for replacing with nothing.
4 years ago
DOXYGEN_ELLIPSIS(static_cast<void>(clearCoatFactor), static_cast<void>(clearCoatRoughness);)
Trade: usage docs for MaterialData.
6 years ago
}
/* [MaterialData-usage-layers-types] */
}
Trade: mutable access to MaterialData attribute values. Hah, so many overloads. Not providing mutable access to keys or layer offsets as that would break the invariant of the internal array always being sorted.
5 years ago
{
Trade::MaterialData data{{}, {}};
/* [MaterialData-usage-mutable] */
Color4& color = data.mutableAttribute<Color4>(Trade::MaterialAttribute::BaseColor);
ColorHsv hsv = color.toHsv();
color.rgb() = Color3::fromHsv({hsv.hue, hsv.saturation*0.85f, hsv.value});
/* [MaterialData-usage-mutable] */
}
Trade: usage docs for MaterialData.
6 years ago
{
/* [MaterialData-populating] */
Trade::MaterialData data{Trade::MaterialType::PbrMetallicRoughness, {
{Trade::MaterialAttribute::DoubleSided, true},
{Trade::MaterialAttribute::BaseColor, 0x3bd267ff_srgbaf},
{Trade::MaterialAttribute::BaseColorTexture, 17u},
{Trade::MaterialAttribute::TextureMatrix, Matrix3::scaling({0.5f, 1.0f})}
}};
/* [MaterialData-populating] */
}
{
/* [MaterialData-populating-non-owned] */
using namespace Containers::Literals;
constexpr Trade::MaterialAttributeData attributes[]{
{"BaseColor"_s, Color4{0.043735f, 0.64448f, 0.135633f, 1.0f}},
{"BaseColorTexture"_s, 5u},
Trade: various doc fixes.
6 years ago
{"DoubleSided"_s, true},
Trade: usage docs for MaterialData.
6 years ago
{"TextureMatrix"_s, Matrix3{{0.5f, 0.0f, 0.0f},
{0.0f, 1.0f, 0.0f},
{0.0f, 0.0f, 1.0f}}}
};
Trade::MaterialData data{Trade::MaterialType::Phong, {}, attributes};
/* [MaterialData-populating-non-owned] */
}
#ifdef MAGNUM_TARGET_GL
{
GL::Texture2D baseColorTexture;
/* [MaterialData-populating-custom] */
Trade: add MaterialDataType::Buffer. Because storing arbitrary data as a string was not good: - It *never* followed alignment requirements due to the last byte being used for size. Instead the size is now stored before the data, and thus the data is always on the 64 byte boundary. - As it could contain arbitrary binary data, it could cause magnum-sceneconverter --material-info to print garbage, corrupt the terminal or, worst case, crash. Not good. - It stored an implicit \0, which was unnecessary.
4 years ago
char sha1[20]{DOXYGEN_ELLIPSIS()};
Trade: usage docs for MaterialData.
6 years ago
Trade::MaterialData data{Trade::MaterialType::PbrMetallicRoughness, {
{Trade::MaterialAttribute::BaseColor, 0x3bd267ff_srgbaf},
{Trade::MaterialAttribute::TextureMatrix, Matrix3::scaling({0.5f, 1.0f})},
{"baseColorTexturePointer", &baseColorTexture},
{"highlightColor", 0x00ffff_srgbf},
Trade: add MaterialDataType::Buffer. Because storing arbitrary data as a string was not good: - It *never* followed alignment requirements due to the last byte being used for size. Instead the size is now stored before the data, and thus the data is always on the 64 byte boundary. - As it could contain arbitrary binary data, it could cause magnum-sceneconverter --material-info to print garbage, corrupt the terminal or, worst case, crash. Not good. - It stored an implicit \0, which was unnecessary.
4 years ago
{"name", "Canary Green Plastic, really ugly"},
{"hash", Containers::ArrayView<const void>{sha1}},
Trade: usage docs for MaterialData.
6 years ago
}};
// Retrieving the texture pointer
GL::Texture2D* texture = data.attribute<GL::Texture2D*>("baseColorTexturePointer");
/* [MaterialData-populating-custom] */
static_cast<void>(texture);
}
#endif
{
/* [MaterialData-populating-layers] */
Trade::MaterialData data{
Trade::MaterialType::PbrMetallicRoughness|Trade::MaterialType::PbrClearCoat,
{
{Trade::MaterialAttribute::BaseColor, 0xffcc33_srgbf},
Trade: rework metallic/roughness packing. Turns out glTF doesn't actually put metalness into R and roughness into G, even though the naming suggests that. This was done originally, but then they changed that in order to be compatible with UE4 and allow for a more efficient storage of an occlusion map. Because this feels extremely arbitrary, the docs have added rationale for each of the packing variants, and I'm also renaming the packed attribute and checks to imply the red channel isn't used.
6 years ago
{Trade::MaterialAttribute::NoneRoughnessMetallicTexture, 0u},
Trade: usage docs for MaterialData.
6 years ago
{Trade::MaterialLayer::ClearCoat},
{Trade::MaterialAttribute::LayerFactorTexture, 1u},
{Trade::MaterialAttribute::RoughnessTexture, 1u},
{Trade::MaterialAttribute::RoughnessTextureSwizzle,
Trade::MaterialTextureSwizzle::G}
},
{2, 6}
};
/* [MaterialData-populating-layers] */
}
{
UnsignedInt a, b, c, d, sandTile, grassTile, rockTile;
/* [MaterialData-populating-layers-custom] */
Trade::MaterialData proceduralLandscape{
Trade::MaterialTypes{}, // Doesn't match any builtin material type
{
// Rock layer
{Trade::MaterialAttribute::LayerFactorTexture, a},
{Trade::MaterialAttribute::BaseColorTexture, rockTile},
// Sand layer
{Trade::MaterialAttribute::LayerFactorTexture, b},
{"blendType", "mix"},
{Trade::MaterialAttribute::BaseColorTexture, sandTile},
// Grass layer
{Trade::MaterialAttribute::LayerFactorTexture, c},
{"blendType", "overlay"},
{"strandLengthTexture", d},
{Trade::MaterialAttribute::BaseColorTexture, grassTile},
},
// There's no base material, everything is in layers
{0, 2, 5, 9}
};
/* [MaterialData-populating-layers-custom] */
}
Trade: high-level docs for the MeshData class.
6 years ago
{
/* [MeshIndexData-usage] */
Containers::ArrayView<const UnsignedShort> indices;
Trade::MeshIndexData data{indices};
/* [MeshIndexData-usage] */
}
Trade: implement support for tangents and bitangents in MeshData. Originally wanted to offload this to someone else, but then realized I need those for generic vertex attribute definitions, which I need for instancing, which I need now. So here it is, at the bottom of the dependency chain.
6 years ago
{
Vector3 normal;
Vector4 tangent;
/* [MeshAttribute-bitangent-from-tangent] */
Vector3 bitangent = Math::cross(normal, tangent.xyz())*tangent.w();
/* [MeshAttribute-bitangent-from-tangent] */
static_cast<void>(bitangent);
}
Trade: high-level docs for the MeshData class.
6 years ago
{
/* [MeshAttributeData-usage] */
Containers::StridedArrayView1D<const Vector3> positions;
Trade::MeshAttributeData data{Trade::MeshAttribute::Position, positions};
/* [MeshAttributeData-usage] */
}
{
Trade: improve MeshData, SceneData and MaterialData population docs. Especially the part about non-owned data was lacking, with basically no information about what are offset-only attributes and fields actually good for.
3 years ago
UnsignedInt vertexCount{};
Trade: high-level docs for the MeshData class.
6 years ago
/* [MeshAttributeData-usage-offset-only] */
struct Vertex {
Vector3 position;
Vector4 color;
};
Trade: improve MeshData, SceneData and MaterialData population docs. Especially the part about non-owned data was lacking, with basically no information about what are offset-only attributes and fields actually good for.
3 years ago
Trade::MeshAttributeData positions{Trade::MeshAttribute::Position,
VertexFormat::Vector3, offsetof(Vertex, position), vertexCount, sizeof(Vertex)};
Trade::MeshAttributeData colors{Trade::MeshAttribute::Color,
VertexFormat::Vector4, offsetof(Vertex, color), vertexCount, sizeof(Vertex)};
Trade: high-level docs for the MeshData class.
6 years ago
/* [MeshAttributeData-usage-offset-only] */
Trade: improve MeshData, SceneData and MaterialData population docs. Especially the part about non-owned data was lacking, with basically no information about what are offset-only attributes and fields actually good for.
3 years ago
static_cast<void>(positions);
static_cast<void>(colors);
Trade: high-level docs for the MeshData class.
6 years ago
}
#ifdef MAGNUM_TARGET_VK
{
Containers::StridedArrayView1D<const void> data;
/* [MeshAttributeData-custom-vertex-format] */
Trade::MeshAttributeData normals{Trade::MeshAttribute::Normal,
vertexFormatWrap(VK_FORMAT_B10G11R11_UFLOAT_PACK32),
data};
/* [MeshAttributeData-custom-vertex-format] */
}
#endif
Trade: a reworked MeshData class. With API analogous to the (relatively) new AnimationData -- with one buffer containing all index data and one buffer containing all vertex data, both meant to be uploaded as-is to the GPU. This will eventually replace MeshData2D and MeshData3D, backwards compatibility and wiring up to other APIs will be done in follow-up commits.
7 years ago
#ifdef MAGNUM_TARGET_GL
Trade: refresh MeshData docs slightly. It was rather discouraging to start "Basic usage" with a boring-ass long snippet. On the other hand showing just compile() first would lead people to think it's all some opaque magic, so trying to balance that a bit. Also why the hell was the compile() snippet showing the horrendous GL way of specifying attribute formats? This is not great either but at least not redundant.
5 years ago
{
GL: refresh Mesh and Buffer docs to be less shit. Looking at the snippets, these seem to have been written back when there was no builtin shaders yet, it seems, not to mention MeshTools::compile(), Trade::MeshData or any of the other high-level APIs. Rather overwhelming to just throw huge code snippets at the user, explaining a workflow with a custom-made mesh that's going to be drawn with a custom-made shader, which is like level 999 of using the GL library.
5 years ago
/* This snippet is also used by GL::Mesh, bear that in mind when updating */
Trade: refresh MeshData docs slightly. It was rather discouraging to start "Basic usage" with a boring-ass long snippet. On the other hand showing just compile() first would lead people to think it's all some opaque magic, so trying to balance that a bit. Also why the hell was the compile() snippet showing the horrendous GL way of specifying attribute formats? This is not great either but at least not redundant.
5 years ago
/* [MeshData-usage-compile] */
doc: rename DOXYGEN_IGNORE() to DOXYGEN_ELLIPSIS(). And use DOXYGEN_IGNORE() for replacing with nothing.
4 years ago
Trade::MeshData data = DOXYGEN_ELLIPSIS(Trade::MeshData{MeshPrimitive::Points, 0});
Trade: refresh MeshData docs slightly. It was rather discouraging to start "Basic usage" with a boring-ass long snippet. On the other hand showing just compile() first would lead people to think it's all some opaque magic, so trying to balance that a bit. Also why the hell was the compile() snippet showing the horrendous GL way of specifying attribute formats? This is not great either but at least not redundant.
5 years ago
GL::Mesh mesh = MeshTools::compile(data);
/* [MeshData-usage-compile] */
}
Trade: a reworked MeshData class. With API analogous to the (relatively) new AnimationData -- with one buffer containing all index data and one buffer containing all vertex data, both meant to be uploaded as-is to the GPU. This will eventually replace MeshData2D and MeshData3D, backwards compatibility and wiring up to other APIs will be done in follow-up commits.
7 years ago
{
Trade::MeshData data{MeshPrimitive::Points, 0};
/* [MeshData-usage] */
/* Check that we have at least positions and normals */
GL::Mesh mesh{data.primitive()};
if(!data.hasAttribute(Trade::MeshAttribute::Position) ||
!data.hasAttribute(Trade::MeshAttribute::Normal))
Fatal{} << "Oh well";
/* Interleave vertex data */
GL::Buffer vertices;
vertices.setData(MeshTools::interleave(data.positions3DAsArray(),
data.normalsAsArray()));
mesh.addVertexBuffer(std::move(vertices), 0,
Shaders: suffix all existing shaders with GL. To make room for Vulkan shaders. Also renaming the headers, of course everything is still aliased to the old names (and marked as deprecated).
5 years ago
Shaders::PhongGL::Position{}, Shaders::PhongGL::Normal{});
Trade: a reworked MeshData class. With API analogous to the (relatively) new AnimationData -- with one buffer containing all index data and one buffer containing all vertex data, both meant to be uploaded as-is to the GPU. This will eventually replace MeshData2D and MeshData3D, backwards compatibility and wiring up to other APIs will be done in follow-up commits.
7 years ago
Trade: refresh MeshData docs slightly. It was rather discouraging to start "Basic usage" with a boring-ass long snippet. On the other hand showing just compile() first would lead people to think it's all some opaque magic, so trying to balance that a bit. Also why the hell was the compile() snippet showing the horrendous GL way of specifying attribute formats? This is not great either but at least not redundant.
5 years ago
/* Set up an index buffer, if the mesh is indexed */
Trade: a reworked MeshData class. With API analogous to the (relatively) new AnimationData -- with one buffer containing all index data and one buffer containing all vertex data, both meant to be uploaded as-is to the GPU. This will eventually replace MeshData2D and MeshData3D, backwards compatibility and wiring up to other APIs will be done in follow-up commits.
7 years ago
if(data.isIndexed()) {
GL::Buffer indices;
indices.setData(data.indicesAsArray());
mesh.setIndexBuffer(std::move(indices), 0, MeshIndexType::UnsignedInt)
.setCount(data.indexCount());
} else mesh.setCount(data.vertexCount());
/* [MeshData-usage] */
}
{
Trade::MeshData data{MeshPrimitive::Points, 0};
GL::Mesh mesh{data.primitive()};
/* [MeshData-usage-advanced] */
/* Upload the original packed vertex data */
GL::Buffer vertices;
vertices.setData(data.vertexData());
GL: allow to construct DynamicAttribute from VertexFormat.
6 years ago
/* Set up the position and normal attributes */
Trade: a reworked MeshData class. With API analogous to the (relatively) new AnimationData -- with one buffer containing all index data and one buffer containing all vertex data, both meant to be uploaded as-is to the GPU. This will eventually replace MeshData2D and MeshData3D, backwards compatibility and wiring up to other APIs will be done in follow-up commits.
7 years ago
mesh.addVertexBuffer(vertices,
data.attributeOffset(Trade::MeshAttribute::Position),
GL: allow to construct DynamicAttribute from VertexFormat.
6 years ago
data.attributeStride(Trade::MeshAttribute::Position),
Shaders: suffix all existing shaders with GL. To make room for Vulkan shaders. Also renaming the headers, of course everything is still aliased to the old names (and marked as deprecated).
5 years ago
GL::DynamicAttribute{Shaders::PhongGL::Position{},
GL: allow to construct DynamicAttribute from VertexFormat.
6 years ago
data.attributeFormat(Trade::MeshAttribute::Position)});
mesh.addVertexBuffer(vertices,
data.attributeOffset(Trade::MeshAttribute::Normal),
data.attributeStride(Trade::MeshAttribute::Normal),
Shaders: suffix all existing shaders with GL. To make room for Vulkan shaders. Also renaming the headers, of course everything is still aliased to the old names (and marked as deprecated).
5 years ago
GL::DynamicAttribute{Shaders::PhongGL::Normal{},
GL: allow to construct DynamicAttribute from VertexFormat.
6 years ago
data.attributeFormat(Trade::MeshAttribute::Normal)});
Trade: a reworked MeshData class. With API analogous to the (relatively) new AnimationData -- with one buffer containing all index data and one buffer containing all vertex data, both meant to be uploaded as-is to the GPU. This will eventually replace MeshData2D and MeshData3D, backwards compatibility and wiring up to other APIs will be done in follow-up commits.
7 years ago
/* Upload the original packed index data */
if(data.isIndexed()) {
GL::Buffer indices;
indices.setData(data.indexData());
mesh.setIndexBuffer(std::move(indices), 0, data.indexType())
.setCount(data.indexCount());
} else mesh.setCount(data.vertexCount());
/* [MeshData-usage-advanced] */
}
#endif
Trade: implement mutable data access in MeshData. Turns out the design wasn't so simple after all. AnimationData and ImageData classes will follow with similar changes.
7 years ago
{
Trade::MeshData data{MeshPrimitive::Points, 0};
/* [MeshData-usage-mutable] */
/* Check prerequisites */
if(!(data.vertexDataFlags() & Trade::DataFlag::Mutable) ||
!data.hasAttribute(Trade::MeshAttribute::Position) ||
data.attributeFormat(Trade::MeshAttribute::Position) != VertexFormat::Vector3)
Fatal{} << "Oh well";
/* Scale the mesh two times */
MeshTools::transformPointsInPlace(Matrix4::scaling(Vector3{2.0f}),
data.mutableAttribute<Vector3>(Trade::MeshAttribute::Position));
/* [MeshData-usage-mutable] */
}
Trade: support morph targets in MeshData. Attributes that are morph targets are marked with a morph target ID, those then get treated separately in name-based lookups.
3 years ago
{
Trade::MeshData data{MeshPrimitive::Points, 0};
/* [MeshData-usage-morph-targets] */
Float weights[]{0.25f, 0.5f};
/* Calculate morphed positions with the above weights, assuming the mesh has
a Vector3 Position attribute in morph targets 0 and 1 */
Containers::Array<Vector3> positions = data.positions3DAsArray(0, -1);
for(Int morphTargetId: {0, 1}) {
Containers::StridedArrayView1D<const Vector3> morphed =
data.attribute<Vector3>(Trade::MeshAttribute::Position, 0, morphTargetId);
for(std::size_t i = 0; i != data.vertexCount(); ++i)
positions[i] += morphed[i]*weights[morphTargetId];
}
/* [MeshData-usage-morph-targets] */
}
Trade: support zero and negative strides in mesh attribute data. This is not something the classic GPU vertex pipeline can handle (except maybe Vulkan, which can handle zero strides for instanced attributes?), but useful for other scenarios. This means existing code needs to be aware of and handle the new corner case.
4 years ago
{
Trade::MeshData data{MeshPrimitive::Points, 0};
/* [MeshData-usage-special-layouts] */
if(data.attributeStride(Trade::MeshAttribute::Position) <= 0 ||
Trade: support strided index buffers in MeshData. Also not something the classic GPU vertex pipeline can handle, but useful for other scenarios. Subsequently a support for array indices will be added, allowing to directly represent for example OBJ files, where each attribute has its own index buffer.
4 years ago
data.attributeStride(Trade::MeshAttribute::Normal) <= 0 ||
(data.isIndexed() && !data.indices().isContiguous()))
Trade: support zero and negative strides in mesh attribute data. This is not something the classic GPU vertex pipeline can handle (except maybe Vulkan, which can handle zero strides for instanced attributes?), but useful for other scenarios. This means existing code needs to be aware of and handle the new corner case.
4 years ago
Fatal{} << "Uh oh";
Trade: support strided index buffers in MeshData. Also not something the classic GPU vertex pipeline can handle, but useful for other scenarios. Subsequently a support for array indices will be added, allowing to directly represent for example OBJ files, where each attribute has its own index buffer.
4 years ago
// Now it's safe to use the Position and Normal attributes and the index buffer
// in a GPU mesh
Trade: support zero and negative strides in mesh attribute data. This is not something the classic GPU vertex pipeline can handle (except maybe Vulkan, which can handle zero strides for instanced attributes?), but useful for other scenarios. This means existing code needs to be aware of and handle the new corner case.
4 years ago
/* [MeshData-usage-special-layouts] */
}
Trade: high-level docs for the MeshData class.
6 years ago
{
std::size_t vertexCount{}, indexCount{};
/* [MeshData-populating] */
struct Vertex {
Vector3 position;
Vector4 color;
};
Containers::Array<char> indexData{indexCount*sizeof(UnsignedShort)};
Containers::Array<char> vertexData{vertexCount*sizeof(Vertex)};
doc: rename DOXYGEN_IGNORE() to DOXYGEN_ELLIPSIS(). And use DOXYGEN_IGNORE() for replacing with nothing.
4 years ago
DOXYGEN_ELLIPSIS()
Trade: improve MeshData, SceneData and MaterialData population docs. Especially the part about non-owned data was lacking, with basically no information about what are offset-only attributes and fields actually good for.
3 years ago
Containers::StridedArrayView1D<const Vertex> vertices =
Containers::arrayCast<const Vertex>(vertexData);
Containers::ArrayView<const UnsignedShort> indices =
Containers::arrayCast<const UnsignedShort>(indexData);
Trade: high-level docs for the MeshData class.
6 years ago
Trade::MeshData data{MeshPrimitive::Triangles,
std::move(indexData), Trade::MeshIndexData{indices},
std::move(vertexData), {
Trade::MeshAttributeData{Trade::MeshAttribute::Position,
Trade: improve MeshData, SceneData and MaterialData population docs. Especially the part about non-owned data was lacking, with basically no information about what are offset-only attributes and fields actually good for.
3 years ago
vertices.slice(&Vertex::position)},
Trade: high-level docs for the MeshData class.
6 years ago
Trade::MeshAttributeData{Trade::MeshAttribute::Color,
Trade: improve MeshData, SceneData and MaterialData population docs. Especially the part about non-owned data was lacking, with basically no information about what are offset-only attributes and fields actually good for.
3 years ago
vertices.slice(&Vertex::color)}
Trade: high-level docs for the MeshData class.
6 years ago
}};
/* [MeshData-populating] */
}
{
struct Vertex {
Vector3 position;
Vector4 color;
};
/* [MeshData-populating-non-owned] */
Trade: improve MeshData, SceneData and MaterialData population docs. Especially the part about non-owned data was lacking, with basically no information about what are offset-only attributes and fields actually good for.
3 years ago
const UnsignedShort indices[]{
DOXYGEN_ELLIPSIS(0)
};
Vertex vertices[]{
DOXYGEN_ELLIPSIS({})
Trade: high-level docs for the MeshData class.
6 years ago
};
Trade::MeshData data{MeshPrimitive::Triangles,
Trade::DataFlags{}, indices, Trade::MeshIndexData{indices},
Trade::DataFlag::Mutable, vertices, {
Trade::MeshAttributeData{Trade::MeshAttribute::Position,
Trade: improve MeshData, SceneData and MaterialData population docs. Especially the part about non-owned data was lacking, with basically no information about what are offset-only attributes and fields actually good for.
3 years ago
Containers::stridedArrayView(vertices).slice(&Vertex::position)},
Trade: high-level docs for the MeshData class.
6 years ago
Trade::MeshAttributeData{Trade::MeshAttribute::Color,
Trade: improve MeshData, SceneData and MaterialData population docs. Especially the part about non-owned data was lacking, with basically no information about what are offset-only attributes and fields actually good for.
3 years ago
Containers::stridedArrayView(vertices).slice(&Vertex::color)}
Trade: high-level docs for the MeshData class.
6 years ago
}};
/* [MeshData-populating-non-owned] */
}
Trade: improve MeshData, SceneData and MaterialData population docs. Especially the part about non-owned data was lacking, with basically no information about what are offset-only attributes and fields actually good for.
3 years ago
{
UnsignedInt vertexCount{};
/* [MeshData-populating-offset-only] */
struct Vertex {
Vector3 position;
Vector4 color;
};
/* Layout known in advance, except for vertex count */
constexpr Trade::MeshAttributeData attributes[]{
Trade::MeshAttributeData{Trade::MeshAttribute::Position,
VertexFormat::Vector3, offsetof(Vertex, position), 0, sizeof(Vertex)},
Trade::MeshAttributeData{Trade::MeshAttribute::Color,
VertexFormat::Vector4, offsetof(Vertex, color), 15, sizeof(Vertex)}
};
/* Actual data populated later */
Containers::Array<char> vertexData{vertexCount*sizeof(Vertex)};
DOXYGEN_ELLIPSIS()
/* Using the statically defined attribute layout together with explicitly
passed vertex count */
Trade::MeshData mesh{MeshPrimitive::Triangles, std::move(vertexData),
Trade::meshAttributeDataNonOwningArray(attributes), vertexCount};
/* [MeshData-populating-offset-only] */
}
Trade: high-level docs for the MeshData class.
6 years ago
{
/* [MeshData-populating-custom] */
/* Each face can consist of 15 triangles at most, triangleCount says how many
indices in triangleIds are valid */
struct Face {
UnsignedShort triangleIds[15];
UnsignedByte triangleCount;
};
constexpr Trade::MeshAttribute TriangleIds = Trade::meshAttributeCustom(0x01);
constexpr Trade::MeshAttribute TriangleCount = Trade::meshAttributeCustom(0x02);
Containers::Array<char> vertexData;
auto faces = Containers::arrayCast<const Face>(vertexData);
Trade::MeshData data{MeshPrimitive::Faces, std::move(vertexData), {
Trade::MeshAttributeData{TriangleIds,
Containers::StridedArrayView2D<const UnsignedShort>{faces,
&faces[0].triangleIds[0],
{faces.size(), 15},
{sizeof(Face), sizeof(UnsignedShort)}}},
Trade::MeshAttributeData{TriangleCount,
Containers::StridedArrayView1D<const UnsignedByte>{faces,
&faces[0].triangleCount, faces.size(), sizeof(Face)}}
}};
/* [MeshData-populating-custom] */
/* [MeshData-populating-custom-retrieve] */
Containers::StridedArrayView2D<const UnsignedShort> triangleIds =
data.attribute<UnsignedShort[]>(TriangleIds);
Containers::StridedArrayView1D<const UnsignedByte> triangleCounts =
data.attribute<UnsignedByte>(TriangleCount);
/* [MeshData-populating-custom-retrieve] */
static_cast<void>(triangleIds);
static_cast<void>(triangleCounts);
}
Trade: implement support for Weights & JointIds in MeshData. This is the first builtin array attribute, with one of the objectives being an ability to support an arbitrary count of per-vertex weights in a single contiguous attribute without the complexity of having to go through several four-component attributes. On the shader side it still needs to get cut into at most four components per attribute, but there's no reason for such limitation to get propagated here as well. Co-authored-by: Vladimír Vondruš <mosra@centrum.cz>
4 years ago
{
/* [MeshData-jointIdsAsArray] */
Trade::MeshData data = DOXYGEN_ELLIPSIS(Trade::MeshData{{}, 0});
Containers::Array<UnsignedInt> array = data.jointIdsAsArray();
Containers::StridedArrayView2D<UnsignedInt> array2D{array,
{data.vertexCount(), data.attributeArraySize(Trade::MeshAttribute::JointIds)}};
for(Containers::StridedArrayView1D<UnsignedInt> i: array2D) {
for(UnsignedInt j: i) {
DOXYGEN_IGNORE(static_cast<void>(j);)// do something with joint ID j in vertex i
}
}
/* [MeshData-jointIdsAsArray] */
}
Trade, MeshTools: deprecate MeshDataXD and everything that uses it.
6 years ago
#ifdef MAGNUM_BUILD_DEPRECATED
Trade: support separate translation/rotation/scaling in ObjectData. Doesn't make any backwards-incompatible change -- plugins can still export the transformation as matrix and users can still access the combined one even if separate transformations are used. Yay!
8 years ago
{
Trade, MeshTools: deprecate MeshDataXD and everything that uses it.
6 years ago
CORRADE_IGNORE_DEPRECATED_PUSH
Trade: document how MeshData can be further transformed.
8 years ago
Trade::MeshData2D& foo();
Trade::MeshData2D& data = foo();
/* [MeshData2D-transform] */
Matrix3 transformation =
Matrix3::translation({3.0f, -2.0f})*
Matrix3::scaling(Vector2{2.0f})*
Matrix3::rotation(45.0_degf);
MeshTools::transformPointsInPlace(transformation, data.positions(0));
/* [MeshData2D-transform] */
Trade, MeshTools: deprecate MeshDataXD and everything that uses it.
6 years ago
CORRADE_IGNORE_DEPRECATED_POP
Trade: document how MeshData can be further transformed.
8 years ago
}
{
Trade: adapt AbstractImporter for the new SceneData workflow. Same as with MeshData2D/3D, the original ObjectData API and plugin interfaces are preserved to keep existing code as well as existing importer implementations working. As Magnum's own importers will get updated to the new SceneData workflow, a backward compatibility layer provided that translates it to the subset that the legacy ObjectData understands. With this commit, both existing plugin code can build (and test against) the new workflow, and any ports to the new workflow can test against the legacy interfaces. Except that for now the compatibility layer doesn't deal with objects that have more than one mesh or for example a light and a camera attached, this will be done in a separate step.
5 years ago
CORRADE_IGNORE_DEPRECATED_PUSH
Trade: document how MeshData can be further transformed.
8 years ago
Trade::ObjectData2D& baz();
Trade::ObjectData2D& data = baz();
Trade: support separate translation/rotation/scaling in ObjectData. Doesn't make any backwards-incompatible change -- plugins can still export the transformation as matrix and users can still access the combined one even if separate transformations are used. Yay!
8 years ago
/* [ObjectData2D-transformation] */
Matrix3 transformation =
Matrix3::from(data.rotation().toMatrix(), data.translation())*
Matrix3::scaling(data.scaling());
/* [ObjectData2D-transformation] */
static_cast<void>(transformation);
Trade: adapt AbstractImporter for the new SceneData workflow. Same as with MeshData2D/3D, the original ObjectData API and plugin interfaces are preserved to keep existing code as well as existing importer implementations working. As Magnum's own importers will get updated to the new SceneData workflow, a backward compatibility layer provided that translates it to the subset that the legacy ObjectData understands. With this commit, both existing plugin code can build (and test against) the new workflow, and any ports to the new workflow can test against the legacy interfaces. Except that for now the compatibility layer doesn't deal with objects that have more than one mesh or for example a light and a camera attached, this will be done in a separate step.
5 years ago
CORRADE_IGNORE_DEPRECATED_POP
Trade: support separate translation/rotation/scaling in ObjectData. Doesn't make any backwards-incompatible change -- plugins can still export the transformation as matrix and users can still access the combined one even if separate transformations are used. Yay!
8 years ago
}
{
Trade, MeshTools: deprecate MeshDataXD and everything that uses it.
6 years ago
CORRADE_IGNORE_DEPRECATED_PUSH
Trade: document how MeshData can be further transformed.
8 years ago
Trade::MeshData3D& bar();
Trade::MeshData3D& data = bar();
/* [MeshData3D-transform] */
Matrix4 transformation =
Matrix4::translation({3.0f, 1.5f, -2.0f})*
Matrix4::rotationX(45.0_degf);
MeshTools::transformPointsInPlace(transformation, data.positions(0));
MeshTools::transformVectorsInPlace(transformation, data.normals(0));
/* [MeshData3D-transform] */
Trade, MeshTools: deprecate MeshDataXD and everything that uses it.
6 years ago
CORRADE_IGNORE_DEPRECATED_POP
Trade: document how MeshData can be further transformed.
8 years ago
}
{
Trade: adapt AbstractImporter for the new SceneData workflow. Same as with MeshData2D/3D, the original ObjectData API and plugin interfaces are preserved to keep existing code as well as existing importer implementations working. As Magnum's own importers will get updated to the new SceneData workflow, a backward compatibility layer provided that translates it to the subset that the legacy ObjectData understands. With this commit, both existing plugin code can build (and test against) the new workflow, and any ports to the new workflow can test against the legacy interfaces. Except that for now the compatibility layer doesn't deal with objects that have more than one mesh or for example a light and a camera attached, this will be done in a separate step.
5 years ago
CORRADE_IGNORE_DEPRECATED_PUSH
Trade: document how MeshData can be further transformed.
8 years ago
Trade::ObjectData3D& fizz();
Trade::ObjectData3D& data = fizz();
Trade: support separate translation/rotation/scaling in ObjectData. Doesn't make any backwards-incompatible change -- plugins can still export the transformation as matrix and users can still access the combined one even if separate transformations are used. Yay!
8 years ago
/* [ObjectData3D-transformation] */
Matrix4 transformation =
Matrix4::from(data.rotation().toMatrix(), data.translation())*
Matrix4::scaling(data.scaling());
/* [ObjectData3D-transformation] */
static_cast<void>(transformation);
Trade: adapt AbstractImporter for the new SceneData workflow. Same as with MeshData2D/3D, the original ObjectData API and plugin interfaces are preserved to keep existing code as well as existing importer implementations working. As Magnum's own importers will get updated to the new SceneData workflow, a backward compatibility layer provided that translates it to the subset that the legacy ObjectData understands. With this commit, both existing plugin code can build (and test against) the new workflow, and any ports to the new workflow can test against the legacy interfaces. Except that for now the compatibility layer doesn't deal with objects that have more than one mesh or for example a light and a camera attached, this will be done in a separate step.
5 years ago
CORRADE_IGNORE_DEPRECATED_POP
Trade: support separate translation/rotation/scaling in ObjectData. Doesn't make any backwards-incompatible change -- plugins can still export the transformation as matrix and users can still access the combined one even if separate transformations are used. Yay!
8 years ago
}
Trade: adapt AbstractImporter for the new SceneData workflow. Same as with MeshData2D/3D, the original ObjectData API and plugin interfaces are preserved to keep existing code as well as existing importer implementations working. As Magnum's own importers will get updated to the new SceneData workflow, a backward compatibility layer provided that translates it to the subset that the legacy ObjectData understands. With this commit, both existing plugin code can build (and test against) the new workflow, and any ports to the new workflow can test against the legacy interfaces. Except that for now the compatibility layer doesn't deal with objects that have more than one mesh or for example a light and a camera attached, this will be done in a separate step.
5 years ago
#endif
Trade: support separate translation/rotation/scaling in ObjectData. Doesn't make any backwards-incompatible change -- plugins can still export the transformation as matrix and users can still access the combined one even if separate transformations are used. Yay!
8 years ago
Trade: high-level documentation for SceneData.
5 years ago
{
/* [SceneFieldData-usage] */
Containers::StridedArrayView1D<UnsignedInt> transformationMapping = DOXYGEN_ELLIPSIS({});
Containers::StridedArrayView1D<Matrix4> transformations = DOXYGEN_ELLIPSIS({});
Trade::SceneFieldData field{Trade::SceneField::Transformation,
transformationMapping, transformations};
/* [SceneFieldData-usage] */
}
{
Trade: improve MeshData, SceneData and MaterialData population docs. Especially the part about non-owned data was lacking, with basically no information about what are offset-only attributes and fields actually good for.
3 years ago
std::size_t objectCount = 120;
Trade: high-level documentation for SceneData.
5 years ago
/* [SceneFieldData-usage-offset-only] */
struct Node {
Trade: improve MeshData, SceneData and MaterialData population docs. Especially the part about non-owned data was lacking, with basically no information about what are offset-only attributes and fields actually good for.
3 years ago
UnsignedInt mapping;
Trade: high-level documentation for SceneData.
5 years ago
Int parent;
Trade: improve MeshData, SceneData and MaterialData population docs. Especially the part about non-owned data was lacking, with basically no information about what are offset-only attributes and fields actually good for.
3 years ago
Matrix4 transformation;
Trade: high-level documentation for SceneData.
5 years ago
};
Trade: improve MeshData, SceneData and MaterialData population docs. Especially the part about non-owned data was lacking, with basically no information about what are offset-only attributes and fields actually good for.
3 years ago
Trade::SceneFieldData parents{Trade::SceneField::Parent, objectCount,
Trade::SceneMappingType::UnsignedInt, offsetof(Node, mapping), sizeof(Node),
Trade: high-level documentation for SceneData.
5 years ago
Trade::SceneFieldType::Int, offsetof(Node, parent), sizeof(Node)};
Trade: improve MeshData, SceneData and MaterialData population docs. Especially the part about non-owned data was lacking, with basically no information about what are offset-only attributes and fields actually good for.
3 years ago
Trade::SceneFieldData transformations{Trade::SceneField::Transformation, objectCount,
Trade::SceneMappingType::UnsignedInt, offsetof(Node, mapping), sizeof(Node),
Trade::SceneFieldType::Matrix4x4, offsetof(Node, transformation), sizeof(Node)};
Trade: high-level documentation for SceneData.
5 years ago
/* [SceneFieldData-usage-offset-only] */
Trade: improve MeshData, SceneData and MaterialData population docs. Especially the part about non-owned data was lacking, with basically no information about what are offset-only attributes and fields actually good for.
3 years ago
static_cast<void>(parents);
static_cast<void>(transformations);
Trade: high-level documentation for SceneData.
5 years ago
}
Trade: support storing string fields in SceneData. Finally got an idea how to provide various options store these efficiently, so it's implemented now. Five different storage variants times four different type sizes.
3 years ago
{
/* [SceneFieldData-usage-strings] */
Containers::StridedArrayView1D<UnsignedInt> mapping = DOXYGEN_ELLIPSIS({});
Containers::StringView string = DOXYGEN_ELLIPSIS({});
Containers::StridedArrayView1D<Containers::Pair<UnsignedInt, UnsignedInt>> ranges = DOXYGEN_ELLIPSIS({});
Trade::SceneFieldData field{Trade::sceneFieldCustom(35), mapping,
string.data(), Trade::SceneFieldType::StringRange32, ranges};
/* [SceneFieldData-usage-strings] */
}
Trade: high-level documentation for SceneData.
5 years ago
{
typedef SceneGraph::Scene<SceneGraph::MatrixTransformation3D> Scene3D;
typedef SceneGraph::Object<SceneGraph::MatrixTransformation3D> Object3D;
/* [SceneData-usage1] */
Trade::SceneData data = DOXYGEN_ELLIPSIS(Trade::SceneData{{}, 0, nullptr, nullptr});
if(!data.is3D() ||
!data.hasField(Trade::SceneField::Parent) ||
!data.hasField(Trade::SceneField::Mesh))
Fatal{} << "Oh noes!";
Scene3D scene;
Containers::Array<Object3D*> objects{std::size_t(data.mappingBound())};
/* [SceneData-usage1] */
/* [SceneData-usage2] */
auto parents = data.parentsAsArray();
for(Containers::Pair<UnsignedInt, Int>& parent: parents)
objects[parent.first()] = new Object3D{};
/* [SceneData-usage2] */
/* [SceneData-usage3] */
for(Containers::Pair<UnsignedInt, Int>& parent: parents)
objects[parent.first()]->setParent(
parent.second() == -1 ? &scene : objects[parent.second()]
);
/* [SceneData-usage3] */
/* [SceneData-usage4] */
for(Containers::Pair<UnsignedInt, Matrix4>& transformation:
data.transformations3DAsArray())
{
if(Object3D* const object = objects[transformation.first()])
object->setTransformation(transformation.second());
}
/* [SceneData-usage4] */
/* [SceneData-usage5] */
class Drawable: public SceneGraph::Drawable3D {
public:
explicit Drawable(Object3D& object, UnsignedInt mesh, Int material, DOXYGEN_ELLIPSIS(int))DOXYGEN_IGNORE(: SceneGraph::Drawable3D{object} {
static_cast<void>(mesh);
static_cast<void>(material);
} int foo);
DOXYGEN_ELLIPSIS(void draw(const Matrix4&, SceneGraph::Camera3D&) override {})
};
for(const Containers::Pair<UnsignedInt, Containers::Pair<UnsignedInt, Int>>&
meshMaterial: data.meshesMaterialsAsArray())
{
if(Object3D* const object = objects[meshMaterial.first()])
new Drawable{*object, meshMaterial.second().first(),
meshMaterial.second().second(), DOXYGEN_ELLIPSIS(0)};
}
/* [SceneData-usage5] */
/* [SceneData-usage-advanced] */
Containers::StridedArrayView1D<const UnsignedInt> transformationMapping =
data.mapping<UnsignedInt>(Trade::SceneField::Transformation);
Containers::StridedArrayView1D<const Matrix4> transformations =
data.field<Matrix4>(Trade::SceneField::Transformation);
for(std::size_t i = 0; i != transformationMapping.size(); ++i) {
if(Object3D* const object = objects[transformationMapping[i]])
object->setTransformation(transformations[i]);
}
/* [SceneData-usage-advanced] */
}
{
Trade::SceneData data{{}, 0, nullptr, nullptr};
/* [SceneData-per-object] */
Containers::Pointer<Trade::AbstractImporter> importer = DOXYGEN_ELLIPSIS({});
for(const Containers::Pair<UnsignedInt, Int>& meshMaterial:
data.meshesMaterialsFor(importer->objectForName("Chair")))
{
Debug{} << "Mesh:" << importer->meshName(meshMaterial.first());
if(meshMaterial.second() != -1)
Debug{} << "With a material:" << importer->materialName(meshMaterial.second());
}
/* [SceneData-per-object] */
}
{
Trade::SceneData data{{}, 0, nullptr, nullptr};
typedef SceneGraph::Object<SceneGraph::MatrixTransformation3D> Object3D;
Containers::Array<Object3D*> objects;
/* [SceneData-usage-mutable] */
Containers::StridedArrayView1D<const UnsignedInt> transformationMapping =
data.mapping<UnsignedInt>(Trade::SceneField::Transformation);
Containers::StridedArrayView1D<Matrix4> mutableTransformations =
data.mutableField<Matrix4>(Trade::SceneField::Transformation);
for(std::size_t i = 0; i != transformationMapping.size(); ++i) {
if(Object3D* const object = objects[transformationMapping[i]])
mutableTransformations[i] = object->transformation();
}
/* [SceneData-usage-mutable] */
}
{
const std::size_t nodeCount{}, meshAssignmentCount{};
/* [SceneData-populating] */
struct Common {
Trade: improve MeshData, SceneData and MaterialData population docs. Especially the part about non-owned data was lacking, with basically no information about what are offset-only attributes and fields actually good for.
3 years ago
UnsignedShort mapping;
Trade: high-level documentation for SceneData.
5 years ago
Short parent;
Matrix4 transformation;
};
Containers::StridedArrayView1D<Common> common;
Containers::ArrayView<UnsignedShort> meshMaterialMapping;
Containers::ArrayView<UnsignedShort> meshes;
Containers::ArrayView<UnsignedShort> meshMaterials;
Containers::Array<char> data = Containers::ArrayTuple{
{nodeCount, common},
{meshAssignmentCount, meshMaterialMapping},
{meshAssignmentCount, meshes},
{meshAssignmentCount, meshMaterials}
};
// populate the views ...
Trade::SceneData scene{
Trade::SceneMappingType::UnsignedShort, nodeCount,
std::move(data), {
Trade::SceneFieldData{Trade::SceneField::Parent,
Trade: improve MeshData, SceneData and MaterialData population docs. Especially the part about non-owned data was lacking, with basically no information about what are offset-only attributes and fields actually good for.
3 years ago
common.slice(&Common::mapping),
common.slice(&Common::parent)},
Trade: high-level documentation for SceneData.
5 years ago
Trade::SceneFieldData{Trade::SceneField::Transformation,
Trade: improve MeshData, SceneData and MaterialData population docs. Especially the part about non-owned data was lacking, with basically no information about what are offset-only attributes and fields actually good for.
3 years ago
common.slice(&Common::mapping), common.slice(&Common::transformation)},
Trade: high-level documentation for SceneData.
5 years ago
Trade::SceneFieldData{Trade::SceneField::Mesh,
Trade: improve MeshData, SceneData and MaterialData population docs. Especially the part about non-owned data was lacking, with basically no information about what are offset-only attributes and fields actually good for.
3 years ago
meshMaterialMapping,
meshes},
Trade: high-level documentation for SceneData.
5 years ago
Trade::SceneFieldData{Trade::SceneField::MeshMaterial,
Trade: improve MeshData, SceneData and MaterialData population docs. Especially the part about non-owned data was lacking, with basically no information about what are offset-only attributes and fields actually good for.
3 years ago
meshMaterialMapping,
meshMaterials}
Trade: high-level documentation for SceneData.
5 years ago
}};
/* [SceneData-populating] */
}
Trade: improve MeshData, SceneData and MaterialData population docs. Especially the part about non-owned data was lacking, with basically no information about what are offset-only attributes and fields actually good for.
3 years ago
{
constexpr std::size_t objectCount = 1;
/* [SceneData-populating-non-owned] */
constexpr struct Data {
UnsignedShort mapping;
Short parent;
Matrix4 transformation;
} data[objectCount]{
DOXYGEN_ELLIPSIS({})
};
Trade::SceneData scene{
Trade::SceneMappingType::UnsignedShort, objectCount,
Trade::DataFlag::Global, data, {
Trade::SceneFieldData{Trade::SceneField::Parent,
Containers::stridedArrayView(data).slice(&Data::mapping),
Containers::stridedArrayView(data).slice(&Data::parent)},
DOXYGEN_ELLIPSIS()
}};
/* [SceneData-populating-non-owned] */
}
{
constexpr std::size_t objectCount = 1;
/* [SceneData-populating-offset-only] */
struct Data {
UnsignedInt mapping;
Int parent;
Matrix4 transformation;
};
/* Layout defined statically */
constexpr Trade::SceneFieldData fields[]{
Trade::SceneFieldData{Trade::SceneField::Parent, objectCount,
Trade::SceneMappingType::UnsignedInt, offsetof(Data, mapping), sizeof(Data),
Trade::SceneFieldType::Int, offsetof(Data, parent), sizeof(Data)},
Trade::SceneFieldData{Trade::SceneField::Transformation, objectCount,
Trade::SceneMappingType::UnsignedInt, offsetof(Data, mapping), sizeof(Data),
Trade::SceneFieldType::Matrix4x4, offsetof(Data, transformation), sizeof(Data)}
};
/* Actual data populated later */
Containers::Array<char> data{objectCount*sizeof(Data)};
DOXYGEN_ELLIPSIS()
/* Using the statically defined field layout */
Trade::SceneData scene{Trade::SceneMappingType::UnsignedInt, objectCount,
std::move(data), Trade::sceneFieldDataNonOwningArray(fields)};
/* [SceneData-populating-offset-only] */
}
Trade: high-level documentation for SceneData.
5 years ago
{
std::size_t nodeCount{};
/* [SceneData-populating-custom1] */
DOXYGEN_ELLIPSIS()
Containers::ArrayView<UnsignedShort> cellMapping;
Containers::ArrayView<Matrix4> cellFrustums;
Containers::StridedArrayView2D<Int> cellLights;
Containers::Array<char> data = Containers::ArrayTuple{
DOXYGEN_ELLIPSIS()
{32*24, cellMapping},
{32*24, cellFrustums},
{{32*24, 8}, cellLights},
};
for(std::size_t i = 0; i != cellMapping.size(); ++i) {
cellMapping[i] = nodeCount + i;
cellFrustums[i] = DOXYGEN_ELLIPSIS({});
for(std::size_t j = 0; j != cellLights[i].size(); ++j)
cellLights[i][j] = DOXYGEN_ELLIPSIS({});
}
/* [SceneData-populating-custom1] */
/* [SceneData-populating-custom2] */
doc: use the now-common naming scheme for custom SceneField IDs.
3 years ago
constexpr Trade::SceneField SceneFieldCellFrustum = Trade::sceneFieldCustom(0);
constexpr Trade::SceneField SceneFieldCellLights = Trade::sceneFieldCustom(1);
Trade: high-level documentation for SceneData.
5 years ago
Trade::SceneData scene{
Trade::SceneMappingType::UnsignedShort, nodeCount + cellMapping.size(),
std::move(data), {
DOXYGEN_ELLIPSIS()
doc: use the now-common naming scheme for custom SceneField IDs.
3 years ago
Trade::SceneFieldData{SceneFieldCellFrustum, cellMapping, cellFrustums},
Trade::SceneFieldData{SceneFieldCellLights, cellMapping, cellLights},
Trade: high-level documentation for SceneData.
5 years ago
}};
/* [SceneData-populating-custom2] */
}
{
doc: use the now-common naming scheme for custom SceneField IDs.
3 years ago
constexpr Trade::SceneField SceneFieldCellFrustum = Trade::sceneFieldCustom(0);
constexpr Trade::SceneField SceneFieldCellLights = Trade::sceneFieldCustom(1);
Trade: high-level documentation for SceneData.
5 years ago
Trade::SceneData scene{{}, 0, nullptr, nullptr};
/* [SceneData-populating-custom-retrieve] */
Containers::StridedArrayView1D<const Matrix4> cellFrustums =
doc: use the now-common naming scheme for custom SceneField IDs.
3 years ago
scene.field<Matrix4>(SceneFieldCellFrustum);
Trade: high-level documentation for SceneData.
5 years ago
Containers::StridedArrayView2D<const Int> cellLights =
doc: use the now-common naming scheme for custom SceneField IDs.
3 years ago
scene.field<Int[]>(SceneFieldCellLights);
Trade: high-level documentation for SceneData.
5 years ago
/* [SceneData-populating-custom-retrieve] */
static_cast<void>(cellFrustums);
static_cast<void>(cellLights);
}
Trade: support storing string fields in SceneData. Finally got an idea how to provide various options store these efficiently, so it's implemented now. Five different storage variants times four different type sizes.
3 years ago
{
using namespace Containers::Literals;
/* [SceneData-populating-strings] */
constexpr Containers::StringView CategoryStrings =
"wall\0furniture\0lighting\0artwork"_s;
constexpr UnsignedByte CategoryWall = 0;
constexpr UnsignedByte CategoryFurniture = 5;
constexpr UnsignedByte CategoryLighting = 15;
constexpr UnsignedByte CategoryArtwork = 24;
Containers::MutableStringView categoryStrings;
Containers::ArrayView<UnsignedInt> mapping;
Containers::ArrayView<UnsignedByte> categories;
Containers::ArrayTuple data{
{CategoryStrings.size(), categoryStrings},
{DOXYGEN_ELLIPSIS(5), mapping},
{DOXYGEN_ELLIPSIS(5), categories},
};
Utility::copy(CategoryStrings, categoryStrings);
mapping[0] = 7;
categories[0] = CategoryWall;
mapping[1] = 19;
categories[1] = CategoryFurniture;
DOXYGEN_ELLIPSIS(static_cast<void>(CategoryLighting); static_cast<void>(CategoryArtwork);)
constexpr Trade::SceneField SceneFieldCategory = Trade::sceneFieldCustom(25);
Trade::SceneData scene{Trade::SceneMappingType::UnsignedInt, DOXYGEN_ELLIPSIS(5), std::move(data), {
Trade::SceneFieldData{SceneFieldCategory, mapping,
categoryStrings.data(), Trade::SceneFieldType::StringRangeNullTerminated8,
categories}
}};
/* [SceneData-populating-strings] */
}
{
constexpr Trade::SceneField SceneFieldCategory = Trade::sceneFieldCustom(25);
Trade::SceneData scene{{}, 0, nullptr, nullptr};
/* [SceneData-populating-strings-retrieve] */
Containers::StringIterable categories = scene.fieldStrings(SceneFieldCategory);
// Prints "furniture"
Debug{} << categories[scene.fieldObjectOffset(SceneFieldCategory, 19)];
/* [SceneData-populating-strings-retrieve] */
}
Split the OpenGL layer out, pt 9: generic pixel formats. This is quite big, so: * There are new Magnum::PixelFormat and Magnum::CompressedPixelFormat enums, which contain generic API-independent formats. In particular, PixelFormat replaces GL::PixelFormat and GL::PixelType with a single value. * There's GL::pixelFormat(), GL::pixelType(), GL::compressedPixelFormat() to convert the generic enums to GL-specific. The mapping is only in one direction, done with a lookup table (generic enums are indices to that table). * GL classes taking the formats directly (such as GL::BufferImage) have overloads that take both the GL-specific and generic format. * The generic Image, CompressedImage, ImageView, CompressedImageView, and Trade::ImageData classes now accept the generic formats first-class. However, it's also possible to store an implementation-specific value to cover cases where a generic format enum doesn't have support for a particular format. This is done by wrapping the value using pixelFormatWrap() or compressedPixelFormatWrap(). Particular GPU APIs then assume it's their implementation-specific value and extract the value back using pixelFormatUnwrap() or compressedPixelFormatUnwrap(). There's also an isPixelFormatImplementationSpecific() and isCompressedPixelFormatImplementationSpecific() that distinguishes these values. * Many operations need pixel size and in order to have it even for implementation-specific formats, a corresponding pixelSize() overload is found via ADL on construction and the calculated size stored along the format. Previously the pixel size was only calculated on demand, but that's not possible now. In case such overload is not available, it's possible to pass pixel size manually as well. * In order to support the GL format+type pair, Image, ImageView and Trade::ImageData, there's now an additional untyped formatExtra() field that holds the second value. * The CompressedPixelStorage class is now unconditionally available on all targets, including OpenGL ES and WebGL. However, on OpenGL ES the GL APIs expect that it's all at default values. I attempted to preserve backwards compatibility as much as possible: * The PixelFormat and CompressedPixelFormat enum now contains generic API-independent values. The GL-specific formats are present there, but marked as deprecated. Use either the generic values or GL::PixelFormat (togehter with GL::PixelType) and GL::CompressedPixelFormat instead. There's a lot of ugliness caused by this, but seems to work well. * *Image::type() functions are deprecated as they were too GL-specific. Use formatExtra() and cast it to GL::PixelType instead. * Image constructors take templated format or format+extra arguments, so passing GL-specific values to them should still work.
8 years ago
}