atlas_inventory.hpp

Go to the documentation of this file.

#pragma once
 
// atlas_inventory.hpp — read-only GPU texture-atlas inventory.
//
// The render layer owns several shelf-packed texture atlases — the
// glyph atlas (SDF text), the image atlas, the gradient ramp atlas,
// and the path atlas (texture_atlas.hpp). Each one is a GPU texture
// page that small bitmaps are packed into; when an atlas fills up,
// rendering either thrashes (evict + re-pack churn) or spills to a
// fresh page. "Is my SDF atlas thrashing?" is a real perf question.
//
// `AtlasInventory` is the answer surface: a small, render-layer-owned
// collection of `AtlasInfo` snapshots that the inspector overlay's
// atlas viewer renders. It deliberately holds *value snapshots*, not
// pointers to live atlases — the inspector reads it on the UI thread
// while the render thread keeps mutating the real atlases, so a
// snapshot taken at a known point is the safe contract.
//
// What it surfaces is exactly what the Pulp-owned atlas classes can
// honestly report: per-atlas pixel dimensions, a shelf-packer
// occupancy estimate, the live entry (packed-region) count, and a
// page count. Skia manages its own internal SkStrike glyph cache
// separately and does not expose page-level introspection through a
// stable public API; this inventory does NOT fabricate numbers for
// it — it reports the atlases Pulp itself packs.
 
#include <pulp/render/texture_atlas.hpp>
 
#include <algorithm>
#include <cstddef>
#include <string>
#include <vector>
 
namespace pulp::render {

enum class AtlasKind {
    glyph,     
    image,     
    gradient,  
    path,      
};

inline const char* atlas_kind_name(AtlasKind kind) {
    switch (kind) {
        case AtlasKind::glyph:    return "glyph";
        case AtlasKind::image:    return "image";
        case AtlasKind::gradient: return "gradient";
        case AtlasKind::path:     return "path";
    }
    return "unknown";
}

struct AtlasInfo {
    AtlasKind kind = AtlasKind::image;
    std::string label;       
    int width = 0;           
    int height = 0;          
    int pages = 1;           
    std::size_t entries = 0; 
    float occupancy = 0.0f;  

    std::size_t texel_capacity() const {
        const int safe_width = width < 0 ? 0 : width;
        const int safe_height = height < 0 ? 0 : height;
        return static_cast<std::size_t>(safe_width) *
               static_cast<std::size_t>(safe_height) *
               static_cast<std::size_t>(pages < 1 ? 1 : pages);
    }

    int occupancy_percent() const {
        float clamped = occupancy;
        if (clamped < 0.0f) clamped = 0.0f;
        if (clamped > 1.0f) clamped = 1.0f;
        return static_cast<int>(clamped * 100.0f + 0.5f);
    }
};

class AtlasInventory {
public:
    template <typename Atlas>
    static AtlasInfo snapshot(const Atlas& atlas, AtlasKind kind,
                              std::string label = {}, int pages = 1) {
        AtlasInfo info;
        info.kind = kind;
        info.label = label.empty() ? atlas_kind_name(kind)
                                    : std::move(label);
        info.width = atlas.width();
        info.height = atlas.height();
        info.pages = pages < 1 ? 1 : pages;
        info.entries = atlas.entry_count();
        info.occupancy = atlas.occupancy();
        return info;
    }

    static AtlasInfo snapshot_gradient(const GradientAtlas& atlas,
                                       std::string label = {},
                                       int ramp_width = 256) {
        AtlasInfo info;
        info.kind = AtlasKind::gradient;
        info.label = label.empty() ? atlas_kind_name(AtlasKind::gradient)
                                    : std::move(label);
        info.width = ramp_width < 0 ? 0 : ramp_width;
        info.height = atlas.row_capacity();
        info.pages = 1;
        info.entries = atlas.entry_count();
        info.occupancy = atlas.occupancy();
        return info;
    }

    void add(AtlasInfo info) { atlases_.push_back(std::move(info)); }

    template <typename Atlas>
    void add_atlas(const Atlas& atlas, AtlasKind kind,
                   std::string label = {}, int pages = 1) {
        atlases_.push_back(snapshot(atlas, kind, std::move(label), pages));
    }

    void add_gradient(const GradientAtlas& atlas, std::string label = {},
                      int ramp_width = 256) {
        atlases_.push_back(
            snapshot_gradient(atlas, std::move(label), ramp_width));
    }

    void clear() { atlases_.clear(); }

    const std::vector<AtlasInfo>& atlases() const { return atlases_; }

    std::size_t size() const { return atlases_.size(); }

    bool empty() const { return atlases_.empty(); }

    int total_pages() const {
        int total = 0;
        for (const auto& a : atlases_)
            total += (a.pages < 1 ? 1 : a.pages);
        return total;
    }

    std::size_t total_entries() const {
        std::size_t total = 0;
        for (const auto& a : atlases_) total += a.entries;
        return total;
    }

    float average_occupancy() const {
        if (atlases_.empty()) return 0.0f;
        float sum = 0.0f;
        for (const auto& a : atlases_) {
            float o = a.occupancy;
            if (o < 0.0f) o = 0.0f;
            if (o > 1.0f) o = 1.0f;
            sum += o;
        }
        return sum / static_cast<float>(atlases_.size());
    }
 
private:
    std::vector<AtlasInfo> atlases_;
};
 
} // namespace pulp::render