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.
With the intention that those will eventually contain also things like
YUp / YDown, PremultipliedAlpha and such.
This commit is mostly just busywork, wiring this into [Compressed]Image,
[Compressed]ImageView and Trade::ImageData and ensuring the flags get
correctly propagated during moves and conversions. Unfortunately in case
of Trade::ImageData it meant deprecating the current set of constructor
in order to insert an ImageFlags parameter before the importer state
pointer.
The only non-trivial piece of logic is when a 2D
[Compressed]ImageView gets converted to a 3D one, then the Array bit is
implicitly dropped, as 2D arrays of 1D images are not really a thing.
Instead, it's now possible to add new flags when doing the conversion --
for example to turn a 2D image to a (single-layer) 2D array image.
Ahem, missed those in 36ee7835d6. Yes,
putting compressed images into atlases is a desirable thing to do as
well, although it's now rather shitty due to lack of slicing.
For consistency with how VertexFormat and other enum helpers are named.
The compressedBlockSize() and compressedBlockDataSize() is also renamed
to compressedPixelFormatBlockSize() and
compressedPixelFormatBlockDataSize().
While backwards compatibility aliases are in place, a breaking change
is that Image classes now look for pixelFormatSize() instead of
pixelSize(). This is used e.g. when passing GL::PixelFormat /
GL::PixelType to the image classes, instead of the generic PixelFormat.
While useful, it's unlikely that any project was defining their own
pixel format enum and pixelSize() for a D3D or Metal renderer or
whatnot, so the breakage should have no practical impact.
Allows creating a StridedArrayView slice on the sizes to feed them to
various algorithms, instead of first having to copy the sizes out to a
freshly allocated array.
Apparently "pixel size" could have meant "image size in pixels" as well.
Additionally also clarify what image size means, since it might be
unclear especially for the block-compressed images.
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.
This one returned a raw pointer, losing all size information, One should
instead use the non-templated data() along with Containers::arrayCast()
for a properly type-checked conversion.
There's *a lot* of tests using the deprecated functionality. I need to
change one more thing before updating those.
It's potentially dangerous because the user is responsible for choosing
a correct type, on the other hand forcing them to do it verbosely
through arrayCast() is both too annoying and too hard to explain.
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.).
It was returning either pixel size or compressed block size, which is
now available directly via other means.
This is a breaking change, but I don't expect these functions to be
used widely beyond Magnum internals.
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.
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.
Makes it far easier to detect pixel storage misconfigurations and
improperly sized data arrays. Data owning classes (Image,
Trade::ImageData) accept Containers::Array<char> while wrappers
(ImageView, BufferImage) accept Containers::ArrayView<const void>.
ImageView reinterprets the passed array as const char to enable pointer
arithmetic on the data.
The old way (constructor/setData() call accepting void*) is now marked as
deprecated and will be removed in some future release. Because decay of
fixed-size arrays to void* is preferred to calling Containers::ArrayView
constructor, there are two more overloads to have proper handling of
const T(&)[n] and std::nullptr_t arguments.
Currently the TgaImporter and TgaImageConverter fail on images with row
length not aligned to 4, will fix that in followup commits.
Removed *Image::dataSize() and added *Image::dataProperties(), which
returns all properties separately for better introspection. This function
is now just an convenience alias to PixelStorage::dataProperties(), which
takes into account proper alignment and all other storage properties.
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).
I hoped to use them to store pixel pack/unpack configuration, but I have
better solution now.
The AbstractImage.h header is now removed along with the base classes,
I'm not expecting that anyone used these empty classes, so I'm not doing
anything to preserve backwards compatibility.
Added (now empty) AbstractCompressedImage class that inherits (now also
empty) AbstractImage class.
Added CompressedBufferImage, CompressedImage and CompressedImageView
classes, which are just copies of BufferImage, Image and ImageView
classes with format/type pair replaced by just format, but they
additionally need data size parameter.
Because of different use cases in Trade, the Trade::ImageData class now
handles both uncompressed and compressed format, checking the API
usage with runtime assertions. The reason for this is that a material
could just reference a image file by ID and we need to be able to
extract image of that ID without prior knowledge whether it is
compressed or not. Requiring prior knowledge of image format from the
user would make both the API and the usage far more complicated than
having Trade::ImageData which handles both cases.
On the other hand, the Image*/CompressedImage* distinction is done for
easier usage and type-safe APIs in all other cases.
Vladimír Vondruš