World3DRenderer.cpp

Go to the documentation of this file.

#include "World3DRenderer.hpp"
 
#include "SequenceTransforms.hpp"
#include "World3DShaderUniforms.hpp"
#include "ModernPBRShaderUniforms.hpp"
 
#include <SDL3/SDL.h>
 
#include <algorithm>
#include <array>
#include <cmath>
#include <cstring>
#include <limits>
#include <utility>
 
namespace monopoly::engine
{
    namespace
    {
        constexpr std::uint32_t ShadowSize = 2048U;
        std::optional<sequence::Matrix3D> shadowProjection(const SequenceWorld3DSlot& slot,
            const std::array<float, 3>& direction)
        {
            using Vector = std::array<float, 3>;
            const auto dot = [](const Vector& a, const Vector& b)
            { return a[0]*b[0] + a[1]*b[1] + a[2]*b[2]; };
            const auto cross = [](const Vector& a, const Vector& b) -> Vector
            { return {a[1]*b[2]-a[2]*b[1], a[2]*b[0]-a[0]*b[2], a[0]*b[1]-a[1]*b[0]}; };
            const auto normalized = [&](Vector a) -> Vector
            { const float length = std::sqrt(dot(a,a)); for (auto& v : a) v /= length; return a; };
            if (!std::isfinite(dot(direction,direction)) || dot(direction,direction) < 0.000001F)
                return std::nullopt;
            const auto forward = normalized(direction);
            const auto right = normalized(cross(std::abs(forward[1]) > 0.95F
                ? Vector{0,0,1} : Vector{0,1,0}, forward));
            const auto up = cross(forward,right);
            Vector low{INFINITY, INFINITY, INFINITY}, high{-INFINITY,-INFINITY,-INFINITY};
            bool found = false;
            // Fit the actual evaluated asset bounds after the driven world
            // matrices, never a presentation-specific game-coordinate guess.
            for (const auto id : slot.visibleOrder())
            {
                const auto* object = slot.find(id);
                if (!object || !object->asset || object->asset->origin != data::MeshAssetOrigin::ModernGltf)
                    continue;
                const auto mesh = object->renderData ? object->renderData : object->asset->renderData;
                if (!mesh) continue;
                const auto& m = object->worldTransform.values;
                for (int corner = 0; corner < 8; ++corner)
                {
                    Vector local{};
                    for (int axis=0; axis<3; ++axis)
                        local[axis] = (corner & (1 << axis)) ? mesh->bounds.maximum[axis] : mesh->bounds.minimum[axis];
                    const Vector world{local[0]*m[0]+local[1]*m[4]+local[2]*m[8]+m[12],
                        local[0]*m[1]+local[1]*m[5]+local[2]*m[9]+m[13],
                        local[0]*m[2]+local[1]*m[6]+local[2]*m[10]+m[14]};
                    const Vector light{dot(world,right),dot(world,up),dot(world,forward)};
                    for (int axis=0; axis<3; ++axis)
                    { low[axis]=std::min(low[axis],light[axis]); high[axis]=std::max(high[axis],light[axis]); }
                    found = true;
                }
            }
            if (!found) return std::nullopt;
            Vector span{};
            for (int axis=0; axis<3; ++axis)
            {
                if (!std::isfinite(low[axis]) || !std::isfinite(high[axis])) return std::nullopt;
                const float margin = std::max((high[axis]-low[axis])*0.04F, 1.0F);
                low[axis]-=margin; high[axis]+=margin; span[axis]=high[axis]-low[axis];
            }
            auto result = sequence::identity3D();
            for (int axis=0; axis<3; ++axis)
            {
                result.values[axis*4] = right[axis]*2/span[0];
                result.values[axis*4+1] = up[axis]*2/span[1];
                result.values[axis*4+2] = forward[axis]/span[2];
            }
            result.values[12]=-(high[0]+low[0])/span[0];
            result.values[13]=-(high[1]+low[1])/span[1];
            result.values[14]=-low[2]/span[2];
            return result;
        }
        [[nodiscard]] std::array<float, 4> vector4(
            const std::array<float, 3>& value, float w = 0.0F) noexcept
        {
            return {value[0], value[1], value[2], w};
        }
 
        bool validViewport(const SDL_GPUViewport& viewport,
            std::uint32_t width, std::uint32_t height) noexcept
        {
            return std::isfinite(viewport.x) && std::isfinite(viewport.y) &&
                std::isfinite(viewport.w) && std::isfinite(viewport.h) &&
                viewport.x >= 0.0F && viewport.y >= 0.0F &&
                viewport.w > 0.0F && viewport.h > 0.0F &&
                viewport.x + viewport.w <= static_cast<float>(width) &&
                viewport.y + viewport.h <= static_cast<float>(height) &&
                viewport.min_depth >= 0.0F && viewport.max_depth <= 1.0F &&
                viewport.min_depth <= viewport.max_depth;
        }
 
        World3DRendererError rendererError(
            World3DRendererErrorCode code, const char* fallback)
        {
            World3DRendererError result;
            result.code = code;
            const char* sdl = SDL_GetError();
            result.detail = sdl != nullptr && *sdl != '\0' ? sdl : fallback;
            return result;
        }
 
        std::expected<SDL_GPUTexture*, World3DRendererError>
        createWhiteTexture(SDL_GPUDevice* device)
        {
            SDL_GPUTextureCreateInfo textureInfo{};
            textureInfo.type = SDL_GPU_TEXTURETYPE_2D;
            textureInfo.format = SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM;
            textureInfo.usage = SDL_GPU_TEXTUREUSAGE_SAMPLER;
            textureInfo.width = 1U;
            textureInfo.height = 1U;
            textureInfo.layer_count_or_depth = 1U;
            textureInfo.num_levels = 1U;
            textureInfo.sample_count = SDL_GPU_SAMPLECOUNT_1;
            SDL_GPUTexture* texture = SDL_CreateGPUTexture(device, &textureInfo);
            if (texture == nullptr)
                return std::unexpected(rendererError(
                    World3DRendererErrorCode::FallbackTextureCreationFailed,
                    "could not create 1x1 white World3D fallback texture"));
 
            // 256-byte row pitch keeps the upload on SDL's direct D3D12 path.
            SDL_GPUTransferBufferCreateInfo transferInfo{};
            transferInfo.usage = SDL_GPU_TRANSFERBUFFERUSAGE_UPLOAD;
            transferInfo.size = 256U;
            SDL_GPUTransferBuffer* transfer =
                SDL_CreateGPUTransferBuffer(device, &transferInfo);
            if (transfer == nullptr)
            {
                SDL_ReleaseGPUTexture(device, texture);
                return std::unexpected(rendererError(
                    World3DRendererErrorCode::FallbackTextureUploadFailed,
                    "could not create fallback texture upload buffer"));
            }
 
            void* mapped = SDL_MapGPUTransferBuffer(device, transfer, false);
            if (mapped == nullptr)
            {
                SDL_ReleaseGPUTransferBuffer(device, transfer);
                SDL_ReleaseGPUTexture(device, texture);
                return std::unexpected(rendererError(
                    World3DRendererErrorCode::FallbackTextureUploadFailed,
                    "could not map fallback texture upload buffer"));
            }
            std::memset(mapped, 0, 256U);
            auto* pixel = static_cast<std::uint8_t*>(mapped);
            pixel[0] = pixel[1] = pixel[2] = pixel[3] = 255U;
            SDL_UnmapGPUTransferBuffer(device, transfer);
 
            SDL_GPUCommandBuffer* command = SDL_AcquireGPUCommandBuffer(device);
            if (command == nullptr)
            {
                SDL_ReleaseGPUTransferBuffer(device, transfer);
                SDL_ReleaseGPUTexture(device, texture);
                return std::unexpected(rendererError(
                    World3DRendererErrorCode::FallbackTextureUploadFailed,
                    "could not acquire fallback texture upload command buffer"));
            }
            SDL_GPUCopyPass* copy = SDL_BeginGPUCopyPass(command);
            if (copy == nullptr)
            {
                SDL_CancelGPUCommandBuffer(command);
                SDL_ReleaseGPUTransferBuffer(device, transfer);
                SDL_ReleaseGPUTexture(device, texture);
                return std::unexpected(rendererError(
                    World3DRendererErrorCode::FallbackTextureUploadFailed,
                    "could not begin fallback texture upload copy pass"));
            }
 
            SDL_GPUTextureTransferInfo source{};
            source.transfer_buffer = transfer;
            source.pixels_per_row = 64U;
            source.rows_per_layer = 1U;
            SDL_GPUTextureRegion destination{};
            destination.texture = texture;
            destination.w = 1U;
            destination.h = 1U;
            destination.d = 1U;
            SDL_UploadToGPUTexture(copy, &source, &destination, false);
            SDL_EndGPUCopyPass(copy);
 
            if (!SDL_SubmitGPUCommandBuffer(command))
            {
                SDL_ReleaseGPUTransferBuffer(device, transfer);
                SDL_ReleaseGPUTexture(device, texture);
                return std::unexpected(rendererError(
                    World3DRendererErrorCode::FallbackTextureUploadFailed,
                    "could not submit fallback texture upload"));
            }
            SDL_ReleaseGPUTransferBuffer(device, transfer);
            return texture;
        }
    }
 
    World3DRenderer::~World3DRenderer()
    {
        reset();
    }
 
    World3DRenderer::World3DRenderer(World3DRenderer&& other) noexcept
    {
        *this = std::move(other);
    }
 
    World3DRenderer& World3DRenderer::operator=(World3DRenderer&& other) noexcept
    {
        if (this == &other) return *this;
        reset();
        device_ = std::exchange(other.device_, nullptr);
        pipeline_ = std::move(other.pipeline_);
        modernPipeline_ = std::move(other.modernPipeline_);
        modernPipelineAttempted_ = std::exchange(other.modernPipelineAttempted_, false);
        shaderDirectory_ = std::move(other.shaderDirectory_);
        colorFormat_ = std::exchange(other.colorFormat_, SDL_GPU_TEXTUREFORMAT_INVALID);
        meshCache_ = std::move(other.meshCache_);
        studioEnvironment_ = std::move(other.studioEnvironment_);
        studioEnvironmentEnabled_ = std::exchange(other.studioEnvironmentEnabled_, false);
        textureSampler_ = std::exchange(other.textureSampler_, nullptr);
        linearSampler_ = std::exchange(other.linearSampler_, nullptr);
        bilinearFiltering_ = std::exchange(other.bilinearFiltering_, false);
        whiteTexture_ = std::exchange(other.whiteTexture_, nullptr);
        depthTarget_ = std::exchange(other.depthTarget_, nullptr);
        depthWidth_ = std::exchange(other.depthWidth_, 0U);
        depthHeight_ = std::exchange(other.depthHeight_, 0U);
        lighting_ = other.lighting_;
        other.lighting_ = {};
        modernPresentation_ = std::exchange(other.modernPresentation_, false);
        presentationShadows_ = std::exchange(other.presentationShadows_, false);
        presentationAntialiasing_ = std::exchange(other.presentationAntialiasing_, false);
        shadowsActive_ = std::exchange(other.shadowsActive_, false);
        antialiasingActive_ = std::exchange(other.antialiasingActive_, false);
        depthSamples_ = std::exchange(other.depthSamples_, SDL_GPU_SAMPLECOUNT_1);
        multisampleColor_ = std::exchange(other.multisampleColor_, nullptr);
        multisampleWidth_ = std::exchange(other.multisampleWidth_, 0U);
        multisampleHeight_ = std::exchange(other.multisampleHeight_, 0U);
        multisampleLegacyPipeline_ = std::move(other.multisampleLegacyPipeline_);
        multisampleModernPipeline_ = std::move(other.multisampleModernPipeline_);
        shadowMap_ = std::exchange(other.shadowMap_, nullptr);
        shadowDepth_ = std::exchange(other.shadowDepth_, nullptr);
        shadowSampler_ = std::exchange(other.shadowSampler_, nullptr);
        shadowMapPipeline_ = std::move(other.shadowMapPipeline_);
        return *this;
    }
 
    void World3DRenderer::releaseDepthTarget() noexcept
    {
        if (device_ && depthTarget_)
            SDL_ReleaseGPUTexture(device_, depthTarget_);
        depthTarget_ = nullptr;
        depthWidth_ = 0U;
        depthHeight_ = 0U;
        depthSamples_ = SDL_GPU_SAMPLECOUNT_1;
    }
 
    void World3DRenderer::releasePresentationResources() noexcept
    {
        if (device_ && multisampleColor_) SDL_ReleaseGPUTexture(device_, multisampleColor_);
        if (device_ && shadowMap_) SDL_ReleaseGPUTexture(device_, shadowMap_);
        if (device_ && shadowDepth_) SDL_ReleaseGPUTexture(device_, shadowDepth_);
        if (device_ && shadowSampler_) SDL_ReleaseGPUSampler(device_, shadowSampler_);
        multisampleColor_ = shadowMap_ = shadowDepth_ = nullptr;
        shadowSampler_ = nullptr;
        multisampleWidth_ = multisampleHeight_ = 0U;
        multisampleLegacyPipeline_.reset();
        multisampleModernPipeline_.reset();
        shadowMapPipeline_.reset();
    }
 
    bool World3DRenderer::ensureShadowResources()
    {
        if (shadowMap_ && shadowDepth_ && shadowMapPipeline_ && shadowSampler_) return true;
        if (!SDL_GPUTextureSupportsFormat(device_, SDL_GPU_TEXTUREFORMAT_R32_FLOAT,
            SDL_GPU_TEXTURETYPE_2D, SDL_GPU_TEXTUREUSAGE_COLOR_TARGET | SDL_GPU_TEXTUREUSAGE_SAMPLER))
            return false;
        if (!shadowMapPipeline_)
        {
            auto pipeline = World3DPipeline::load(device_, shaderDirectory_, SDL_GPU_TEXTUREFORMAT_R32_FLOAT, true);
            if (!pipeline) return false;
            shadowMapPipeline_ = std::move(*pipeline);
        }
        SDL_GPUTextureCreateInfo info{};
        info.type = SDL_GPU_TEXTURETYPE_2D;
        info.width = info.height = ShadowSize;
        info.layer_count_or_depth = info.num_levels = 1U;
        info.sample_count = SDL_GPU_SAMPLECOUNT_1;
        if (!shadowMap_)
        {
            info.format = SDL_GPU_TEXTUREFORMAT_R32_FLOAT;
            info.usage = SDL_GPU_TEXTUREUSAGE_COLOR_TARGET | SDL_GPU_TEXTUREUSAGE_SAMPLER;
            shadowMap_ = SDL_CreateGPUTexture(device_, &info);
        }
        if (!shadowDepth_)
        {
            info.format = shadowMapPipeline_->depthFormat();
            info.usage = SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET;
            shadowDepth_ = SDL_CreateGPUTexture(device_, &info);
        }
        if (!shadowSampler_)
        {
            SDL_GPUSamplerCreateInfo sampler{};
            sampler.min_filter = sampler.mag_filter = SDL_GPU_FILTER_NEAREST;
            sampler.mipmap_mode = SDL_GPU_SAMPLERMIPMAPMODE_NEAREST;
            sampler.address_mode_u = sampler.address_mode_v = sampler.address_mode_w = SDL_GPU_SAMPLERADDRESSMODE_CLAMP_TO_EDGE;
            shadowSampler_ = SDL_CreateGPUSampler(device_, &sampler);
        }
        return shadowMap_ && shadowDepth_ && shadowSampler_;
    }
 
    bool World3DRenderer::ensurePresentationTargets(std::uint32_t width, std::uint32_t height)
    {
        if (!SDL_GPUTextureSupportsSampleCount(device_, colorFormat_, SDL_GPU_SAMPLECOUNT_4) ||
            !SDL_GPUTextureSupportsSampleCount(device_, pipeline_.depthFormat(), SDL_GPU_SAMPLECOUNT_4))
            return false;
        if (!multisampleLegacyPipeline_)
        {
            auto pipeline = World3DPipeline::load(device_, shaderDirectory_, colorFormat_, false, SDL_GPU_SAMPLECOUNT_4);
            if (!pipeline) return false;
            multisampleLegacyPipeline_ = std::move(*pipeline);
        }
        if (!multisampleModernPipeline_)
        {
            auto pipeline = World3DPipeline::load(device_, shaderDirectory_, colorFormat_, true, SDL_GPU_SAMPLECOUNT_4);
            if (!pipeline) return false;
            multisampleModernPipeline_ = std::move(*pipeline);
        }
        if (multisampleColor_ && multisampleWidth_ == width && multisampleHeight_ == height) return true;
        SDL_GPUTextureCreateInfo info{};
        info.type = SDL_GPU_TEXTURETYPE_2D;
        info.format = colorFormat_;
        info.usage = SDL_GPU_TEXTUREUSAGE_COLOR_TARGET;
        info.width = width; info.height = height;
        info.layer_count_or_depth = info.num_levels = 1U;
        info.sample_count = SDL_GPU_SAMPLECOUNT_4;
        auto* replacement = SDL_CreateGPUTexture(device_, &info);
        if (!replacement) return false;
        if (multisampleColor_) SDL_ReleaseGPUTexture(device_, multisampleColor_);
        multisampleColor_ = replacement;
        multisampleWidth_ = width; multisampleHeight_ = height;
        return true;
    }
 
    void World3DRenderer::releaseSamplingResources() noexcept
    {
        if (device_ && whiteTexture_)
            SDL_ReleaseGPUTexture(device_, whiteTexture_);
        if (device_ && textureSampler_)
            SDL_ReleaseGPUSampler(device_, textureSampler_);
        if (device_ && linearSampler_)
            SDL_ReleaseGPUSampler(device_, linearSampler_);
        whiteTexture_ = nullptr;
        textureSampler_ = nullptr;
        linearSampler_ = nullptr;
    }
 
    void World3DRenderer::reset() noexcept
    {
        releaseDepthTarget();
        releasePresentationResources();
        if (meshCache_) meshCache_->clear();
        meshCache_.reset();
        studioEnvironment_.reset();
        studioEnvironmentEnabled_ = false;
        releaseSamplingResources();
        pipeline_.reset();
        modernPipeline_.reset();
        modernPipelineAttempted_ = false;
        shaderDirectory_.clear();
        colorFormat_ = SDL_GPU_TEXTUREFORMAT_INVALID;
        device_ = nullptr;
        lighting_ = {};
        bilinearFiltering_ = false;
        modernPresentation_ = presentationShadows_ = presentationAntialiasing_ = false;
        shadowsActive_ = antialiasingActive_ = false;
    }
 
    bool World3DRenderer::ensureDepthTarget(
        std::uint32_t width, std::uint32_t height, SDL_GPUSampleCount samples) noexcept
    {
        if (depthTarget_ && depthWidth_ == width && depthHeight_ == height && depthSamples_ == samples)
            return true;
 
        SDL_GPUTextureCreateInfo info{};
        info.type = SDL_GPU_TEXTURETYPE_2D;
        info.format = pipeline_.depthFormat();
        info.usage = SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET;
        info.width = width;
        info.height = height;
        info.layer_count_or_depth = 1U;
        info.num_levels = 1U;
        info.sample_count = samples;
        SDL_GPUTexture* replacement = SDL_CreateGPUTexture(device_, &info);
        if (!replacement) return false;
 
        releaseDepthTarget();
        depthTarget_ = replacement;
        depthWidth_ = width;
        depthHeight_ = height;
        depthSamples_ = samples;
        return true;
    }
 
    std::expected<World3DRenderer, World3DRendererError> World3DRenderer::load(
        SDL_GPUDevice* device,
        const std::filesystem::path& shaderDirectory,
        SDL_GPUTextureFormat colorFormat,
        const std::filesystem::path& studioEnvironmentPath)
    {
        if (!device)
            return std::unexpected(World3DRendererError{
                World3DRendererErrorCode::MissingDevice,
                "missing SDL GPU device", {}, {}});
 
        auto pipeline = World3DPipeline::load(device, shaderDirectory, colorFormat);
        if (!pipeline)
            return std::unexpected(World3DRendererError{
                World3DRendererErrorCode::PipelineLoadFailed,
                pipeline.error().detail, pipeline.error(), {}});
 
        auto whiteTexture = createWhiteTexture(device);
        if (!whiteTexture) return std::unexpected(whiteTexture.error());
 
        auto environment = StudioEnvironmentGPU::blackFallback(device);
        if (!environment)
        {
            SDL_ReleaseGPUTexture(device, *whiteTexture);
            return std::unexpected(World3DRendererError{
                World3DRendererErrorCode::FallbackTextureCreationFailed,
                environment.error().detail, {}, {}});
        }
        bool environmentEnabled = false;
        if (!studioEnvironmentPath.empty())
        {
            auto data = readStudioEnvironment(studioEnvironmentPath);
            auto uploaded = data ? StudioEnvironmentGPU::upload(device, *data) :
                std::expected<StudioEnvironmentGPU, StudioEnvironmentError>{std::unexpected(data.error())};
            if (uploaded)
            {
                environment = std::move(uploaded);
                environmentEnabled = true;
            }
            else SDL_LogWarn(SDL_LOG_CATEGORY_RENDER,
                "Optional studio environment disabled: %s", uploaded.error().detail.c_str());
        }
 
        SDL_GPUSamplerCreateInfo samplerInfo{};
        // Source/PC3D/pc3d.cpp: retail filters are POINT/POINT/NONE.
        samplerInfo.min_filter = SDL_GPU_FILTER_NEAREST;
        samplerInfo.mag_filter = SDL_GPU_FILTER_NEAREST;
        samplerInfo.mipmap_mode = SDL_GPU_SAMPLERMIPMAPMODE_NEAREST;
        samplerInfo.address_mode_u = SDL_GPU_SAMPLERADDRESSMODE_REPEAT;
        samplerInfo.address_mode_v = SDL_GPU_SAMPLERADDRESSMODE_REPEAT;
        samplerInfo.address_mode_w = SDL_GPU_SAMPLERADDRESSMODE_REPEAT;
        samplerInfo.min_lod = 0.0F;
        samplerInfo.max_lod = 0.0F;
        SDL_GPUSampler* sampler = SDL_CreateGPUSampler(device, &samplerInfo);
        if (sampler == nullptr)
        {
            SDL_ReleaseGPUTexture(device, *whiteTexture);
            return std::unexpected(rendererError(
                World3DRendererErrorCode::SamplerCreationFailed,
                "could not create retail-compatible World3D point sampler"));
        }
 
        // RenderSettings.inl toggles stage-0 MIN/MAG only; preserve wrap and
        // disabled mipmapping for both samplers. The 2D overlay is unaffected.
        samplerInfo.min_filter = samplerInfo.mag_filter = SDL_GPU_FILTER_LINEAR;
        auto* linearSampler = SDL_CreateGPUSampler(device, &samplerInfo);
        if (!linearSampler)
        {
            SDL_ReleaseGPUSampler(device, sampler);
            SDL_ReleaseGPUTexture(device, *whiteTexture);
            return std::unexpected(rendererError(World3DRendererErrorCode::SamplerCreationFailed,
                "could not create World3D bilinear sampler"));
        }
        World3DRenderer result;
        result.device_ = device;
        result.whiteTexture_ = *whiteTexture;
        result.textureSampler_ = sampler;
        result.linearSampler_ = linearSampler;
        result.studioEnvironment_ = std::move(*environment);
        result.studioEnvironmentEnabled_ = environmentEnabled;
        result.pipeline_ = std::move(*pipeline);
        result.shaderDirectory_ = shaderDirectory;
        result.colorFormat_ = colorFormat;
        result.meshCache_ = std::make_unique<MeshGPUCache>(device);
        return result;
    }
 
    std::expected<World3DRenderStats, World3DRendererError>
    World3DRenderer::render(
        SDL_GPUCommandBuffer* commandBuffer,
        SDL_GPUTexture* colorTarget,
        std::uint32_t targetWidth,
        std::uint32_t targetHeight,
        const SDL_GPUViewport& viewport,
        const SequenceWorld3DSlot& slot)
    {
        if (!commandBuffer)
            return std::unexpected(World3DRendererError{
                World3DRendererErrorCode::MissingCommandBuffer,
                "missing SDL GPU command buffer", {}, {}});
        if (!colorTarget)
            return std::unexpected(World3DRendererError{
                World3DRendererErrorCode::MissingColorTarget,
                "missing World3D color target", {}, {}});
        if (targetWidth == 0U || targetHeight == 0U ||
            !validViewport(viewport, targetWidth, targetHeight))
            return std::unexpected(World3DRendererError{
                World3DRendererErrorCode::InvalidTargetSize,
                "invalid World3D target or viewport", {}, {}});
        if (!slot.view())
            return std::unexpected(World3DRendererError{
                World3DRendererErrorCode::MissingView,
                "World3D slot has no configured camera/view", {}, {}});
 
        auto batches = buildWorld3DGPUScene(slot, *meshCache_);
        if (!batches)
            return std::unexpected(World3DRendererError{
                World3DRendererErrorCode::SceneBuildFailed,
                batches.error().detail, {}, batches.error()});
 
        const bool needsModernPipeline = std::any_of(batches->begin(), batches->end(),
            [](const World3DGPUIndexedBatch& batch)
            {
                return !batch.legacyShadow &&
                    batch.material.model == data::MeshMaterialModel::MetallicRoughness;
            });
        if (needsModernPipeline && !modernPipelineAttempted_)
        {
            modernPipelineAttempted_ = true;
            auto modern = World3DPipeline::load(device_, shaderDirectory_, colorFormat_, true);
            if (modern)
                modernPipeline_ = std::move(*modern);
            else
                SDL_LogWarn(SDL_LOG_CATEGORY_RENDER,
                    "Modern PBR pipeline unavailable; drawing modern meshes with legacy diffuse: %s",
                    modern.error().detail.c_str());
        }
 
        shadowsActive_ = antialiasingActive_ = false;
        World3DRenderStats stats;
        const auto lightProjection = presentationShadows_ && lighting_.sun.enabled && modernPipeline_
            ? shadowProjection(slot, lighting_.sun.direction) : std::nullopt;
        if (lightProjection && ensureShadowResources())
        {
            SDL_GPUColorTargetInfo shadowColor{};
            shadowColor.texture = shadowMap_;
            shadowColor.clear_color = {1,0,0,1};
            shadowColor.load_op = SDL_GPU_LOADOP_CLEAR;
            shadowColor.store_op = SDL_GPU_STOREOP_STORE;
            shadowColor.cycle = true;
            SDL_GPUDepthStencilTargetInfo shadowDepth{};
            shadowDepth.texture = shadowDepth_;
            shadowDepth.clear_depth = 1;
            shadowDepth.load_op = SDL_GPU_LOADOP_CLEAR;
            shadowDepth.store_op = SDL_GPU_STOREOP_DONT_CARE;
            shadowDepth.stencil_load_op = SDL_GPU_LOADOP_DONT_CARE;
            shadowDepth.stencil_store_op = SDL_GPU_STOREOP_DONT_CARE;
            shadowDepth.cycle = true;
            auto* shadowPass = SDL_BeginGPURenderPass(commandBuffer, &shadowColor, 1U, &shadowDepth);
            if (!shadowPass)
                return std::unexpected(rendererError(World3DRendererErrorCode::RenderPassCreationFailed,
                    "could not begin presentation shadow pass"));
            const SDL_GPUViewport shadowViewport{0,0,static_cast<float>(ShadowSize),static_cast<float>(ShadowSize),0,1};
            SDL_SetGPUViewport(shadowPass, &shadowViewport);
            SDL_BindGPUGraphicsPipeline(shadowPass, shadowMapPipeline_->doubleSidedHandle());
            for (const auto& batch : *batches)
            {
                if (batch.legacyShadow || batch.material.model != data::MeshMaterialModel::MetallicRoughness)
                    continue;
                ModernPBRVertexUniforms vertex;
                vertex.world = batch.worldTransform.values;
                vertex.worldViewProjection = sequence::multiply(batch.worldTransform,*lightProjection).values;
                ModernPBRFragmentUniforms fragment;
                fragment.baseColor = batch.material.diffuse;
                fragment.metallicRoughness[3] = batch.material.alphaMode == data::ModernAlphaMode::Mask ? 1.0F : 0.0F;
                fragment.mapFlags[0] = batch.material.baseColorTexture ? 1.0F : 0.0F;
                fragment.mapParameters[3] = batch.material.alphaCutoff;
                fragment.shadowParameters[0] = -1.0F;
                SDL_PushGPUVertexUniformData(commandBuffer,0U,&vertex,static_cast<Uint32>(sizeof(vertex)));
                SDL_PushGPUFragmentUniformData(commandBuffer,0U,&fragment,static_cast<Uint32>(sizeof(fragment)));
                const SDL_GPUBufferBinding vertices{batch.vertexBuffer,0U}, indices{batch.indexBuffer,0U};
                SDL_BindGPUVertexBuffers(shadowPass,0U,&vertices,1U);
                SDL_BindGPUIndexBuffer(shadowPass,&indices,SDL_GPU_INDEXELEMENTSIZE_32BIT);
                std::array<SDL_GPUTextureSamplerBinding,7> textures{};
                for (auto& texture : textures) texture = {whiteTexture_,linearSampler_};
                if (batch.modernTextures[0].texture) textures[0]=batch.modernTextures[0];
                textures[5]={studioEnvironment_.texture(),studioEnvironment_.sampler()};
                SDL_BindGPUFragmentSamplers(shadowPass,0U,textures.data(),static_cast<Uint32>(textures.size()));
                SDL_DrawGPUIndexedPrimitives(shadowPass,batch.indexCount,1U,batch.firstIndex,0,0U);
                ++stats.shadowBatches;
                stats.shadowTriangles += batch.indexCount/3U;
            }
            SDL_EndGPURenderPass(shadowPass);
            shadowsActive_ = stats.shadowBatches > 0;
        }
        const bool fullTarget = viewport.x == 0 && viewport.y == 0 &&
            viewport.w == static_cast<float>(targetWidth) && viewport.h == static_cast<float>(targetHeight);
        antialiasingActive_ = presentationAntialiasing_ && needsModernPipeline && modernPipeline_ && fullTarget &&
            ensurePresentationTargets(targetWidth,targetHeight);
        stats.sampleCount = presentationSampleCount();
        if (!ensureDepthTarget(targetWidth, targetHeight, antialiasingActive_ ? SDL_GPU_SAMPLECOUNT_4 : SDL_GPU_SAMPLECOUNT_1))
            return std::unexpected(World3DRendererError{
                World3DRendererErrorCode::DepthTargetCreationFailed,
                SDL_GetError(), {}, {}});
 
        SDL_GPUColorTargetInfo color{};
        color.texture = colorTarget;
        color.load_op = SDL_GPU_LOADOP_LOAD;
        color.store_op = SDL_GPU_STOREOP_STORE;
        color.cycle = false;
        if (antialiasingActive_)
        {
            color.texture = multisampleColor_;
            color.clear_color = {0.035F,0.04F,0.05F,1.0F};
            color.load_op = SDL_GPU_LOADOP_CLEAR;
            color.store_op = SDL_GPU_STOREOP_RESOLVE;
            color.resolve_texture = colorTarget;
            color.cycle = true;
        }
 
        SDL_GPUDepthStencilTargetInfo depth{};
        depth.texture = depthTarget_;
        depth.clear_depth = 1.0F;
        depth.load_op = SDL_GPU_LOADOP_CLEAR;
        depth.store_op = SDL_GPU_STOREOP_DONT_CARE;
        depth.stencil_load_op = SDL_GPU_LOADOP_DONT_CARE;
        depth.stencil_store_op = SDL_GPU_STOREOP_DONT_CARE;
        depth.cycle = true;
        SDL_GPURenderPass* pass = SDL_BeginGPURenderPass(
            commandBuffer, &color, 1U, &depth);
        if (!pass)
            return std::unexpected(World3DRendererError{
                World3DRendererErrorCode::RenderPassCreationFailed,
                SDL_GetError(), {}, {}});
 
        SDL_SetGPUViewport(pass, &viewport);
 
        SDL_GPUGraphicsPipeline* boundPipeline = nullptr;
        stats.objects = slot.visibleOrder().size();
        stats.batches = batches->size();
        const auto& projection = *slot.view();
 
        for (const auto& batch : *batches)
        {
            const bool modern = modernPipeline_ && !batch.legacyShadow &&
                batch.material.model == data::MeshMaterialModel::MetallicRoughness;
            const auto& legacyPipeline = antialiasingActive_ ? *multisampleLegacyPipeline_ : pipeline_;
            const auto* modernPipeline = antialiasingActive_ ? &*multisampleModernPipeline_ :
                (modernPipeline_ ? &*modernPipeline_ : nullptr);
            SDL_GPUGraphicsPipeline* desiredPipeline = batch.legacyShadow
                ? legacyPipeline.shadowHandle()
                : modern ? (batch.material.doubleSided
                    ? modernPipeline->doubleSidedHandle() : modernPipeline->handle())
                : legacyPipeline.handle();
            if (desiredPipeline != boundPipeline)
            {
                SDL_BindGPUGraphicsPipeline(pass, desiredPipeline);
                boundPipeline = desiredPipeline;
            }
 
            const auto worldView = sequence::multiply(
                batch.worldTransform, projection.view);
            const auto worldViewProjection = sequence::multiply(
                worldView, projection.rasterProjection);
 
            World3DVertexUniforms vertexUniforms;
            vertexUniforms.worldViewProjection = worldViewProjection.values;
            vertexUniforms.world = batch.worldTransform.values;
            vertexUniforms.materialDiffuse = batch.material.diffuse;
 
            World3DFragmentUniforms fragmentUniforms;
            fragmentUniforms.materialDiffuse = batch.material.diffuse;
            vertexUniforms.sceneAmbient = vector4(lighting_.ambient, 1.0F);
            vertexUniforms.boardReflectionColorEnabled = vector4(
                lighting_.boardReflection.color,
                lighting_.boardReflection.enabled ? 1.0F : 0.0F);
            vertexUniforms.boardReflectionDirection = vector4(
                lighting_.boardReflection.direction);
            vertexUniforms.sunColorEnabled = vector4(
                lighting_.sun.color, lighting_.sun.enabled ? 1.0F : 0.0F);
            vertexUniforms.sunDirection = vector4(lighting_.sun.direction);
            vertexUniforms.spotlightColorEnabled = vector4(
                lighting_.spotlight.color,
                lighting_.spotlight.enabled ? 1.0F : 0.0F);
            vertexUniforms.spotlightPositionRange = vector4(
                lighting_.spotlight.position, lighting_.spotlight.range);
            vertexUniforms.spotlightDirectionFalloff = vector4(
                lighting_.spotlight.direction, lighting_.spotlight.falloff);
            vertexUniforms.spotlightAttenuationTheta = vector4(
                lighting_.spotlight.attenuation, lighting_.spotlight.theta);
            vertexUniforms.spotlightPhi =
                {lighting_.spotlight.phi, 0.0F, 0.0F, 0.0F};
 
            if (modern)
            {
                ModernPBRVertexUniforms modernVertex;
                modernVertex.worldViewProjection = worldViewProjection.values;
                modernVertex.world = batch.worldTransform.values;
                ModernPBRFragmentUniforms modernFragment;
                modernFragment.baseColor = batch.material.diffuse;
                const bool targetSRGB = colorFormat_ == SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM_SRGB ||
                    colorFormat_ == SDL_GPU_TEXTUREFORMAT_B8G8R8A8_UNORM_SRGB;
                modernFragment.metallicRoughness = {batch.material.metallic,
                    batch.material.roughness, targetSRGB ? 1.0F : 0.0F,
                    batch.material.alphaMode == data::ModernAlphaMode::Mask ? 1.0F : 0.0F};
                modernFragment.emissiveStrength = vector4(
                    batch.material.emissive, batch.material.emissiveStrength);
                modernFragment.cameraPosition = vector4(projection.camera.location, 1.0F);
                modernFragment.sceneAmbient = vertexUniforms.sceneAmbient;
                modernFragment.sceneAmbient[3] = studioEnvironmentEnabled_ ? 1.0F : 0.0F;
                modernFragment.boardReflectionColorEnabled = vertexUniforms.boardReflectionColorEnabled;
                modernFragment.boardReflectionDirection = vertexUniforms.boardReflectionDirection;
                modernFragment.sunColorEnabled = vertexUniforms.sunColorEnabled;
                modernFragment.sunDirection = vertexUniforms.sunDirection;
                modernFragment.spotlightColorEnabled = vertexUniforms.spotlightColorEnabled;
                modernFragment.spotlightPositionRange = vertexUniforms.spotlightPositionRange;
                modernFragment.spotlightDirectionFalloff = vertexUniforms.spotlightDirectionFalloff;
                modernFragment.spotlightAttenuationTheta = vertexUniforms.spotlightAttenuationTheta;
                modernFragment.spotlightPhi = vertexUniforms.spotlightPhi;
                modernFragment.mapFlags = {
                    batch.material.baseColorTexture ? 1.0F : 0.0F,
                    batch.material.metallicRoughnessTexture ? 1.0F : 0.0F,
                    batch.material.normalTexture ? 1.0F : 0.0F,
                    batch.material.emissiveTexture ? 1.0F : 0.0F};
                modernFragment.mapParameters = {
                    batch.material.occlusionTexture ? 1.0F : 0.0F,
                    batch.material.normalTexture ? batch.material.normalTexture->scale : 1.0F,
                    batch.material.occlusionTexture ? batch.material.occlusionTexture->scale : 1.0F,
                    batch.material.alphaCutoff};
                if (lightProjection) modernFragment.shadowViewProjection = lightProjection->values;
                modernFragment.shadowParameters = {shadowsActive_ ? 1.0F : 0.0F,
                    1.0F/static_cast<float>(ShadowSize),0.00025F,modernPresentation_ ? 1.0F : 0.0F};
                SDL_PushGPUVertexUniformData(commandBuffer, 0U,
                    &modernVertex, static_cast<Uint32>(sizeof(modernVertex)));
                SDL_PushGPUFragmentUniformData(commandBuffer, 0U,
                    &modernFragment, static_cast<Uint32>(sizeof(modernFragment)));
            }
            else
            {
                SDL_PushGPUVertexUniformData(commandBuffer, 0U,
                    &vertexUniforms, static_cast<Uint32>(sizeof(vertexUniforms)));
                SDL_PushGPUFragmentUniformData(commandBuffer, 0U,
                    &fragmentUniforms, static_cast<Uint32>(sizeof(fragmentUniforms)));
            }
 
            const SDL_GPUBufferBinding vertexBinding{batch.vertexBuffer, 0U};
            const SDL_GPUBufferBinding indexBinding{batch.indexBuffer, 0U};
            SDL_BindGPUVertexBuffers(pass, 0U, &vertexBinding, 1U);
            SDL_BindGPUIndexBuffer(pass, &indexBinding,
                SDL_GPU_INDEXELEMENTSIZE_32BIT);
 
            const SDL_GPUTextureSamplerBinding textureBinding{
                batch.gpuTexture != nullptr ? batch.gpuTexture : whiteTexture_,
                bilinearFiltering_ ? linearSampler_ : textureSampler_};
            if (modern)
            {
                std::array<SDL_GPUTextureSamplerBinding, 7> maps{};
                std::copy(batch.modernTextures.begin(), batch.modernTextures.end(), maps.begin());
                for (std::size_t map = 0; map < 5U; ++map)
                {
                    auto& binding = maps[map];
                    if (!binding.texture) binding = {whiteTexture_, linearSampler_};
                }
                maps[5] = {studioEnvironment_.texture(), studioEnvironment_.sampler()};
                maps[6] = shadowsActive_ ? SDL_GPUTextureSamplerBinding{shadowMap_,shadowSampler_}
                    : SDL_GPUTextureSamplerBinding{whiteTexture_,linearSampler_};
                SDL_BindGPUFragmentSamplers(pass, 0U, maps.data(),
                    static_cast<Uint32>(maps.size()));
            }
            else SDL_BindGPUFragmentSamplers(pass, 0U, &textureBinding, 1U);
 
            SDL_DrawGPUIndexedPrimitives(pass,
                batch.indexCount, 1U, batch.firstIndex, 0, 0U);
            stats.triangles += batch.indexCount / 3U;
        }
 
        SDL_EndGPURenderPass(pass);
        return stats;
    }
}