Magnum::TextureTools::AtlasLandfill class new in Git master

#include <Magnum/TextureTools/Atlas.h>

Example usage

The following snippets shows packing a list of images into an atlas with the width set to 1024 and height unbounded. The algorithm by default makes all images the same orientation as that significantly improves the layout efficiency while not making any difference for texture mapping.

Containers::ArrayView<const ImageView2D> images = …;
Containers::Array<Vector2i> offsets{NoInit, images.size()};
Containers::BitArray rotations{NoInit, images.size()};

/* Fill the atlas with an unbounded height */
TextureTools::AtlasLandfill atlas{{1024, 0}};
atlas.add(stridedArrayView(images).slice(&ImageView2D::size), offsets, rotations);

/* Copy the image data to the atlas, assuming all are RGBA8Unorm as well */
Image2D output{PixelFormat::RGBA8Unorm, atlas.filledSize().xy(),
    Containers::Array<char>{ValueInit, std::size_t(atlas.filledSize().product()*4)}};
Containers::StridedArrayView2D<Color4ub> dst = output.pixels<Color4ub>();
for(std::size_t i = 0; i != images.size(); ++i) {
    /* Rotate 90° counterclockwise if the image is rotated in the atlas */
    Containers::StridedArrayView2D<const Color4ub> src = rotations[i] ?
        images[i].pixels<Color4ub>().flipped<1>().transposed<0, 1>() :
        images[i].pixels<Color4ub>();
    Utility::copy(src, dst.sliceSize(
        {std::size_t(offsets[i].y()),
         std::size_t(offsets[i].x())}, src.size()));
}

Calculating a texture coordinate transformation matrix for a particular image can then be done with atlasTextureCoordinateTransformation(), see its documentation for an example of how to calculate and apply the matrix to either the mesh directly or to a material / shader.

If rotations are undesirable, for example if the resulting atlas is used by a linear rasterizer later, they can be disabled by clearing appropriate AtlasLandfillFlags. The process can then also use the add(const Containers::StridedArrayView1D<const Vector2i>&, const Containers::StridedArrayView1D<Vector2i>&) overload without the rotations argument.

atlas.clearFlags(TextureTools::AtlasLandfillFlag::RotatePortrait|
                 TextureTools::AtlasLandfillFlag::RotateLandscape)
     .add(stridedArrayView(images).slice(&ImageView2D::size), offsets);

/* Copy the image data to the atlas, assuming all are RGBA8Unorm as well */
Image2D output{PixelFormat::RGBA8Unorm, atlas.filledSize().xy(),
    Containers::Array<char>{ValueInit, std::size_t(atlas.filledSize().product()*4)}};
Containers::StridedArrayView2D<Color4ub> dst = output.pixels<Color4ub>();
for(std::size_t i = 0; i != images.size(); ++i) {
    Containers::StridedArrayView2D<const Color4ub> src = images[i].pixels<Color4ub>();
    Utility::copy(src, dst.sliceSize(
        {std::size_t(offsets[i].y()),
         std::size_t(offsets[i].x())}, src.size()));
}

Containers::ArrayView<const ImageView2D> images = …;
Containers::Array<Vector3i> offsets{NoInit, images.size()};
Containers::BitArray rotations{NoInit, images.size()};

/* Fill the atlas with an unbounded depth */
TextureTools::AtlasLandfill atlas{{1024, 1024, 0}};
atlas.add(stridedArrayView(images).slice(&ImageView2D::size), offsets, rotations);

/* Copy the image data to the atlas, assuming all are RGBA8Unorm as well */
Image3D output{PixelFormat::RGBA8Unorm, atlas.filledSize(),
    Containers::Array<char>{ValueInit, std::size_t(atlas.filledSize().product()*4)}};
Containers::StridedArrayView3D<Color4ub> dst = output.pixels<Color4ub>();
for(std::size_t i = 0; i != images.size(); ++i) {
    /* Rotate 90° counterclockwise if the image is rotated in the atlas */
    Containers::StridedArrayView3D<const Color4ub> src = rotations[i] ?
        images[i].pixels<Color4ub>().flipped<1>().transposed<0, 1>() :
        images[i].pixels<Color4ub>();
    Utility::copy(src, dst.sliceSize(
        {std::size_t(offsets[i].z()),
         std::size_t(offsets[i].y()),
         std::size_t(offsets[i].x())}, src.size()));
}

Packing process

On every add(), the algorithm first makes all sizes the same orientation depending on AtlasLandfillFlag::RotatePortrait or RotateLandscape being set and sorts the sizes highest first and then depending on AtlasLandfillFlag::WidestFirst or NarrowestFirst being set.

A per-pixel array of currently filled heights, initially all 0, and a horizontal insertion cursor, initially 0, is maintained. An item of given size gets placed at a height that's max(heights[cursor], heights[cursor + size.x]), this range gets then set to height + size.y and the cursor is updated to cursor + size.x. If cursor reaches the edge that an item cannot fit there anymore, it's reset to 0 and the process continues again in the opposite direction, or the same direction if the previous row ended higher than it started. With the assumption that the texture sizes are uniformly distributed, this results in a fairly leveled out height. The process is aborted if the atlas height is bounded and the next item cannot fit there anymore.

The sort is performed using std::stable_sort(), which is usually , the actual atlasing is a single operation. Memory complexity is with being a sorted copy of the input size array and being a 16-bit integer for every pixel of atlas width times filled atlas depth. Additionally std::stable_sort() performs its own allocation.

Incremental population

It's possible to call add() multiple times in order to incrementally fill the atlas with new data as much as the atlas height (if bounded) allows. In an ideal scenario, if the previous fill resulted in an uniform height the newly added data will be added in an optimal way as well, but in practice calling add() with all data just once will always result in a more optimal packing than an incremental one.

In case of an array atlas, the incremental process always starts from the first slice, finding the first that can fit the first (sorted) item. Then it attempts to place as many items as possible and on overflow continues searching for the next slice that can fit the first remaining item. If all slices are exhausted, adds a new one for as long as the depth (if bounded) allows.

Constructors, destructors, conversion operators

AtlasLandfill(const Vector3i& size) explicit

Constructor.

AtlasLandfill(const Vector2i& size) explicit

Construct a non-array atlas.

AtlasLandfill(const AtlasLandfill&) deleted

Copying is not allowed.

AtlasLandfill(AtlasLandfill&&) noexcept

Move constructor.

Public functions

auto operator=(const AtlasLandfill&) -> AtlasLandfill& deleted

Copying is not allowed.

auto operator=(AtlasLandfill&&) -> AtlasLandfill& noexcept

Move assignment.

auto size() const -> Vector3i

Atlas size specified in constructor.

auto filledSize() const -> Vector3i

Currently filled size.

auto flags() const -> AtlasLandfillFlags

Behavior flags.

auto setFlags(AtlasLandfillFlags flags) -> AtlasLandfill&

Set behavior flags.

auto addFlags(AtlasLandfillFlags flags) -> AtlasLandfill&

Add behavior flags.

auto clearFlags(AtlasLandfillFlags flags) -> AtlasLandfill&

Clear behavior flags.

auto padding() const -> Vector2i

Padding around each texture.

auto setPadding(const Vector2i& padding) -> AtlasLandfill&

Set padding around each texture.

auto add(const Containers::StridedArrayView1D<const Vector2i>& sizes, const Containers::StridedArrayView1D<Vector3i>& offsets, Containers::MutableBitArrayView rotations) -> bool

Add textures to the atlas.

auto add(std::initializer_list<Vector2i> sizes, const Containers::StridedArrayView1D<Vector3i>& offsets, Containers::MutableBitArrayView rotations) -> bool

auto add(const Containers::StridedArrayView1D<const Vector2i>& sizes, const Containers::StridedArrayView1D<Vector3i>& offsets) -> bool

Add textures to the atlas with rotations disabled.

auto add(std::initializer_list<Vector2i> sizes, const Containers::StridedArrayView1D<Vector3i>& offsets) -> bool

auto add(const Containers::StridedArrayView1D<const Vector2i>& sizes, const Containers::StridedArrayView1D<Vector2i>& offsets, Containers::MutableBitArrayView rotations) -> bool

Add textures to a non-array atlas.

auto add(std::initializer_list<Vector2i> sizes, const Containers::StridedArrayView1D<Vector2i>& offsets, Containers::MutableBitArrayView rotations) -> bool

auto add(const Containers::StridedArrayView1D<const Vector2i>& sizes, const Containers::StridedArrayView1D<Vector2i>& offsets) -> bool

Add textures to a non-array atlas with rotations disabled.

auto add(std::initializer_list<Vector2i> sizes, const Containers::StridedArrayView1D<Vector2i>& offsets) -> bool

Function documentation