Doxygen 1.8.17 *finally* fixes enum value linking and so linking to
Enum::Value via TotallyArbitraryString::Value no longer works. That
uncovered a ton of documentation errors.
A welcome improvement, for once.
Should make new things more discoverable, avoid confusion when a
documented API isn't there and reduce the need for maintaining multiple
separate versions of the docs.
The image() queries were using getCubeLevelParameterivImplementation()
but the subImage() were inherited from AbstractTexture, using a slightly
different implementation. Since we'll need to apply workarounds to all
cubemap APIs, this needs to be consistent.
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.).
In particular, the AbstractTexture and AbstractQuery subclasses didn't
have that. I can't remember the rules about noexcept (and the users even
less), so let's make that explicit.
The Sampler class was split into GL::Sampler (which is now mostly just a
placeholder for implementing OpenGL sampler objects), pairs of generic /
GL-specific SamplerFormat / GL::SamplerFormat, SamplerMipmap /
GL::SamplerMipmap, SamplerWrapping / GL::SamplerWrapping enums and the
GL-specific GL::SamplerCompareMode, GL::SamplerCompareFunction,
GL::SamplerDepthStencilMode enums.
The old Sampler class is marked as deprecated and aliases its enum to
the generic enums (or to the GL-specific ones in case the generic
versions are not available).
The general part stays in the root namespace, while the GL-specific
stuff goes to the GL namespace. Also all GL-specific documentation was
moved to relevant APIs in the GL namespace. This finally allows me to
build PixelStorage.cpp as part of the root namespace.
The PixelStorage::pixelSize() function and
PixelStorage::dataProperties() taking a pair of GL::PixelFormat /
GL::PixelType enums is deprecated, use GL::pixelSize() and
dataProperties() taking pixel size directly instead. A lot of code is
still using these, including images; the deprecated aliases are inlined
in the header to avoid a compile-time dependency on the GL library.
At the moment just the GL library itself w/o the tests, and without
backwards compatibility aliases. The following types were left in the
root namespace, despite being in the GL/ directory, as they will get
moved back soon:
* Image, CompressedImage and their dimensional typedefs
* ImageView, CompressedImageView and their dimensional typedefs
* PixelStorage
Not PixelFormat etc., that one will stay in the GL namespace and a
completely new PixelFormat enum will be provided in the root namespace.
Minimal updates (just the include guards) so Git is hopefully able to
detect the rename and track the history properly.
Everything except Magnum::GL doesn't compile now.
SVGA3D has broken handling of glTex[ture][Sub]Image*D() for 1D arrays,
2D arrays, 3D textures and cube map textures where it uploads just the
first slice in the last dimension. This is only with copies from host
memory, not with buffer images. Seems to be fixed in Mesa 13, but I have
no such system to verify that on. Relevant commit in the Mesa sources:
2aa9ff0cda
This is one of the uglier workarounds -- I had to reintroduce multiple
code paths for glTexImage() which were removed when implementing ARB_DSA
and the workaround consists of basically a bunch of functions that are
slicing the image and calling the original implementations with each
slice.
The GL queries are needed only if the user-provided pixel storage
doesn't contain enough information, in particular dimensions and byte
size of compression block.
So in case they are present, no query for compressed image size is done
for full image queries (just saving one API call) and no queries for
block dimensions and byte size for subimage queries (saving four API
calls and not requiring ARB_internalformat_query2).
The documentation was fixed and tests were updated to take the
ARB_internalformat_query2 requirement into account.
Followup to previous commit -- links to opengl.org are now redirected to
khronos.org and the extension links have the same format for both GL and
GLES. That allows me to remove some of the Doxygen aliases and use just
a single set of the functions for both GL and GLES.
Allows to break the dependency on the <Magnum/CubeMapTexture.h> header
in Framebuffer, TextureState and elsewhere. The old
CubeMapTexture::Coordinate enum is now just an alias, is marked as
deprecated and will be removed in a future release.
I expect the drivers to return size of *one* face when I'm querying that
particular face using the pre-DSA or EXT_DSA API and size of *all* six
faces when I'm querying whole texture using DSA API.
One can dream, eh?
It appears that, at least on my NVidia, the returned value does not
depend on whether I'm querying all faces or a single one, but RATHER
is based on whether the texture is immutable or not. How's that
predictable at all?! Workaround in the next commit.
Pre-DSA code paths need to specify for which face we are querying the
level parameters, which meant that all other calls had to specify the
(implicit) target too. I'm also preparing to put a cubemap-specific
workaround in the level parameter query and that really shouldn't be
present in the generic implementation for all texture types.
The other place where a specific target is needed is in setImage()
implementations, but these are rather big chunks of code and I don't
feel like copying these verbatim to cubemap implementation just to
isolate the workaround in one place.
Pre-DSA code path needs to pass specific slice of a cube map to all
getters instead of just GL_TEXTURE_CUBE_MAP. I did that properly for
image size query, which weirdly enough, had its own implementation, but
forgot to do that in compressed image getters and, because I have DSA
drivers, never tested that on pre-DSA contexts.
Using single implementation of image size with explicit target
parameter now.
Pain and misery. Majority of functionality for 3D compressed images now
suddenly fails the test -- this is either very vaguely specified or I am
very bad at understanding things or there are bugs in my NVidia drivers.
This was awful feature. Kill me now.
Yeah, sorry, I know, the enums are renamed for second or third time in a
row, first they were Image::Format, then ImageFormat, then ColorFormat
and now PixelFormat. But this time it's final and last time they are
renamed and now everything is finally consistent:
* ColorFormat::DepthComponent -- depth is not a color, thus
PixelFormat::DepthComponent makes a lot more sense.
* There will be PixelStorage classes, which will be stored in images
alonside PixelFormat/PixelType enums, making everything nicely
aligned.
* The GL documentation about glTexImage2D() etc. denotes the <format>
and <type> parameters as format and type of *pixel* data, so now we
are _finally_ consistent with the official naming.
I wonder why did I not choose PixelFormat originally. Anyway, the old
<Magnum/ColorFormat.h> header, ColorFormat, ColorType and
CompressedColorFormat types are now aliases to the new ones, are marked
as deprecated and will be removed in some future release (as always, I'm
waiting at least six months before removing the deprecated
functionality).
Vladimír Vondruš