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*.
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.
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.
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.
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.
The plugin interface version got bumped to avoid ABI issues when loading
plugins that weren't updated for the change, but apart from that this
shouldn't be a breaking change, as the API returns a type that can be
both an Optional and a Pointer.
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.
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.
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.
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.
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.
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.
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.
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!
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.
Forward declarations of templated types don't have named template
parameters and thus Doxygen (sometimes) used these for documentation. It
then looked like this:
Magnum::Math::RectangularMatrix<std::size_t, std::size_t, class>
which isn't helpful at all. After the change it looks like this (much
better):
Magnum::Math::RectangularMatrix<cols, rows, T>
Vladimír Vondruš