texture_storage.h

Go to the documentation of this file.

#pragma once
 
#include <string>
#include <cstdint>
#include <bgfx/bgfx.h>
 
// ---------------------------------------------------------------------------
// BlamTextureRef
// ---------------------------------------------------------------------------
// Opaque handle to a texture managed by the storage system. Materials and
// other engine code reference textures via this type rather than via raw
// bgfx::TextureHandle. This indirection is what makes it possible to swap
// the underlying storage backend (currently: texture arrays grouped by size
// class) without rewriting every site that touches a texture.
//
// Layout is small and trivially copyable. Pass by value.
//
// Field meanings depend on the active backend:
//   ARRAY backend (current):
//     storage_id    = index of the size-class array (0=size class 64,
//                     1=size class 128, ... 6=size class 4096)
//     layer         = layer index within that array
//     sampler_flags = bgfx sampler flags to use when binding the array
//                     for fragments that sample THIS texture. Stored on
//                     the ref so the material doesn't have to know.
//
//   BINDLESS backend (future):
//     storage_id    = ignored (reserved for backend-specific bookkeeping)
//     layer         = global texture index in the bindless table
//     sampler_flags = same meaning
//
// An invalid ref has storage_id == BLAM_TEXTURE_REF_INVALID_STORAGE_ID.
struct BlamTextureRef
{
    uint32_t storage_id;
    uint32_t layer;
    uint32_t sampler_flags;
    uint32_t reserved;
};
 
#define BLAM_TEXTURE_REF_INVALID_STORAGE_ID 0xFFFFFFFFu
 
// Returns true if the ref points to a real texture in storage.
inline bool BlamTextureRef_IsValid(BlamTextureRef ref)
{
    return ref.storage_id != BLAM_TEXTURE_REF_INVALID_STORAGE_ID;
}
 
// Returns an invalid ref. Use for "no texture" / sentinel cases.
inline BlamTextureRef BlamTextureRef_MakeInvalid()
{
    BlamTextureRef ref;
    ref.storage_id = BLAM_TEXTURE_REF_INVALID_STORAGE_ID;
    ref.layer = 0;
    ref.sampler_flags = 0;
    ref.reserved = 0;
    return ref;
}
 
// ---------------------------------------------------------------------------
// Size classes
// ---------------------------------------------------------------------------
// Textures are bucketed into one of N size classes at upload time. Each size
// class has its own bgfx::Texture2DArray. Per-frame, all active arrays are
// bound to the gbuffer pass; per-draw nothing happens for textures.
//
// 7 classes covering 64x64 through 4096x4096. Anything smaller than 64
// gets padded up to 64. Anything larger than 4096 gets refused (with a
// log warning) - oversized textures should be downsized at import.
//
// IMPORTANT: this constant is mirrored in the gbuffer fragment shader as
// BLAM_TEXTURE_SIZE_CLASS_COUNT. If you add or remove a size class, update
// both. The shader has one SAMPLER2DARRAY per size class.
#define BLAM_TEXTURE_SIZE_CLASS_COUNT 7
 
// Edge resolutions per size class. Indexed by storage_id.
extern const int BLAM_TEXTURE_SIZE_CLASS_RESOLUTIONS[BLAM_TEXTURE_SIZE_CLASS_COUNT];
 
// Initial layers allocated per array. When a size class fills up, we
// allocate a second array of that size class (multi-array support).
// Starting at 64 layers gives us 64 * (size class memory) of pre-allocated
// VRAM per class. For the 4096 class that's 64 * 4096*4096*4 = 4 GB which
// is way too much - we use a smaller starting count for the larger classes.
extern const int BLAM_TEXTURE_INITIAL_LAYERS_PER_CLASS[BLAM_TEXTURE_SIZE_CLASS_COUNT];
 
// ---------------------------------------------------------------------------
// Storage API
// ---------------------------------------------------------------------------
namespace Blam
{
    namespace RenderingBGFX
    {
        namespace TextureStorage
        {
            // Initialize storage. Allocates the size-class arrays. Call once
            // at engine startup, after bgfx::init.
            void Initialize();
 
            // Tear down storage. Destroys all arrays. Call at engine shutdown,
            // before bgfx::shutdown.
            void Shutdown();
 
            // Upload a texture into storage. Picks an appropriate size class,
            // allocates a layer in the matching array, uploads the pixel data,
            // returns a ref.
            //
            // `tag_path` is recorded for invalidation tracking. Callers should
            // almost never call this directly - go through Textures::GetTextureRefFromTag
            // which handles tag association and reuse.
            //
            // `pixel_data` is COPIED (the array is independent of the source
            // buffer afterward).
            //
            // Returns an invalid ref on failure (texture too big, format
            // unsupported, etc).
            BlamTextureRef UploadFromTag(const char* tag_path,
                int width, int height,
                bgfx::TextureFormat::Enum format,
                uint32_t sampler_flags,
                const void* pixel_data,
                int pixel_data_size);
 
            // Update the pixels of an existing layer. Used for hot-reload:
            // when the source bitmap tag's pixel data changes, we update
            // the layer in place rather than reallocating.
            //
            // `width` and `height` must match the layer's size class.
            void UpdateLayer(BlamTextureRef ref,
                int width, int height,
                const void* pixel_data,
                int pixel_data_size);
 
            // Free a layer. Invalidates the ref. Subsequent uploads may
            // reuse the slot.
            //
            // Materials/raw-handle holders don't call this directly - it's
            // called from Textures::OnBitmapTagUnloading via the tag-path
            // reverse lookup.
            void Release(BlamTextureRef ref);
 
            // Per-frame: bind all active size-class arrays to the given view.
            // Call once at the start of the gbuffer pass (or any pass that
            // samples material textures).
            //
            // Each array gets bound to a contiguous range of sampler stages
            // starting at `first_stage`. Stage assignment:
            //   first_stage + 0 -> array for size class 0
            //   first_stage + 1 -> array for size class 1
            //   ...
            //
            // The shader expects samplers s_texArray0..s_texArrayN at these
            // stages. If a size class has no allocated array yet (no textures
            // of that size loaded), the stage is bound to a 1x1 fallback
            // to keep the sampler valid.
            void BindArraysForFrame(uint8_t first_stage);
 
            // Number of size classes. Equals BLAM_TEXTURE_SIZE_CLASS_COUNT.
            // Convenience for callers iterating size classes.
            int GetSizeClassCount();
        }
 
        namespace Textures
        {
            // New API: get the abstract ref for a bitmap tag's texture.
            // On first call, uploads to array storage. Subsequent calls return
            // the cached ref. Returns invalid ref if the tag doesn't exist or
            // the texture can't be uploaded.
            //
            // This is the call materials will use during their bake (in Phase 2).
            // In Phase 1 nothing in the engine calls it yet - it's available
            // for testing and future use.
            //
            // Custom shaders continue to use the existing GetTextureFromTag
            // (returns raw bgfx::TextureHandle).
            BlamTextureRef GetTextureRefFromTag(std::string tag_path);
 
            // Hook for the tag system. Call this from your tag unload path,
            // BEFORE the bitmap's pixel data goes away.
            //
            // Releases both forms of the texture (raw handle if created,
            // array ref if created) and removes them from the lookup map.
            //
            // Safe to call for any tag - if the tag isn't a bitmap or wasn't
            // uploaded, this is a no-op.
            void OnBitmapTagUnloading(std::string tag_path);
        }
 
        // NOTE: Materials::PrewarmMaterials will be added in Phase 2 when
        // the material bake learns to use BlamTextureRef. In Phase 1 it
        // would be a no-op so we don't declare it yet.
    }
}