Deprecated for 2018.04, it's been almost a year since. Whoever is using
Magnum regularly updated already, and who not can always upgrade
gradually (2018.02, 2018.04, 2018.10, 2019.01 etc.).
Basically mirroring the API of Trade::AbstractImporter, as that proved
to be useful. The old crazy openSingleData() and openData(horribleStuff)
are deprecated and will be removed in a future release.
No backwards compatibility is provided for font plugins, these need to
be adapted.
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.
Note that I don't mean all possible underlying types, just all possible
vector classes. This is needed for splines etc. which may be templated
and have result type a generic vector, for example.
This reduces the templated code a bit, as I moved the index assertion to
the *.cpp file. Also the function now returns a reference to avoid
needless copies -- it's a view, but still quite a heavy view.
Moreover, this will prevent from passing e.g. integer-based keys to
Trade::AnimationData. And this also now allows me to add duration() to
Trade::AnimationData. I also moved all accessors that don't need a
concrete value type to this base class.