Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

10.6 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    Bench.cpp
 * @brief   The frame clock and its report. See Bench.hpp for what and why.
 *
 * @author  ESEngine Team
 * @date    2026
 *
 * @copyright Copyright (c) 2026 ESEngine Team
 *            Licensed under the Apache License, Version 2.0.
 */
#include "Bench.hpp"

#include <algorithm>
#include <cctype>
#include <cstring>
#include <utility>
#include <chrono>
#include <cstdlib>
#include <string>
#include <vector>

#if defined(_WIN32)
#ifndef WIN32_LEAN_AND_MEAN
#define WIN32_LEAN_AND_MEAN
#endif
// windows.h defines min/max as MACROS, and Types.hpp says
// numeric_limits<u32>::max() -- which then reads as ::(), and the compiler
// blames that line rather than this include. NOMINMAX is what turns them off.
#ifndef NOMINMAX
#define NOMINMAX
#endif
#include <windows.h>
#else
#include <ctime>
#endif

#include "Runtime.hpp"   // ESHOST_LOGI

#if defined(__ANDROID__)
#include <sys/system_properties.h>
#endif

namespace eshost {
namespace {

using Clock = std::chrono::steady_clock;

double msSince(const Clock::time_point& t0) {
    return std::chrono::duration<double, std::milli>(Clock::now() - t0).count();
}

/**
 * Milliseconds of CPU this thread has actually burned, or -1 where the platform
 * will not say. A frame that WAITED reads exactly like a frame that worked, and
 * this is the only thing in the report that tells the two apart.
 */
double threadCpuMs() {
#if defined(_WIN32)
    FILETIME creation, exit, kernel, user;
    if (GetThreadTimes(GetCurrentThread(), &creation, &exit, &kernel, &user) == 0) return -1.0;
    const auto ticks = [](const FILETIME& t) {
        return (static_cast<unsigned long long>(t.dwHighDateTime) << 32) | t.dwLowDateTime;
    };
    return static_cast<double>(ticks(kernel) + ticks(user)) / 1e4;  // 100 ns ticks
#elif defined(CLOCK_THREAD_CPUTIME_ID)
    timespec ts{};
    if (clock_gettime(CLOCK_THREAD_CPUTIME_ID, &ts) != 0) return -1.0;
    return static_cast<double>(ts.tv_sec) * 1e3 + static_cast<double>(ts.tv_nsec) / 1e6;
#else
    return -1.0;
#endif
}

/** A span's samples, and the three numbers worth reading off them. */
struct Span {
    std::vector<double> ms;
    Clock::time_point begun{};
    void begin() { begun = Clock::now(); }
    void end() { ms.push_back(msSince(begun)); }
};

struct BenchState {
    bool asked = false;
    bool reported = false;
    bool quitAfter = true;
    long warmup = 120;
    long frames = 0;
    double dt = 1.0 / 60.0;
    std::string label;
    long seen = 0;          // frames entered, warmup included
    Span update, pump, cpu, frame;
    /** CPU actually burned inside the timed `cpu` spans, against their wall. A
     *  frame throttled by the compositor spends its span waiting, and every other
     *  number in the report reads that wait as cost. */
    double busyCpuMs = 0.0, busyWallMs = 0.0, cpuAtSpanBegin = -1.0;
    unsigned draws = 0, sprites = 0;
    /** The adapter class Dawn reported, see benchNoteAdapter. */
    std::string adapter = "unknown";
    /** This frame's running totals, and the last timed frame's — the same shape
     *  `draws` has, so the report reads one frame rather than an average that
     *  hides a system which stopped being dispatched to halfway through. */
    unsigned aotCandidates = 0, aotCandidatesFrame = 0;
    unsigned aotPacked = 0, aotPackedFrame = 0;
};

/**
 * A bench switch: the environment variable, or — on Android, where an app is
 * started with no environment of its own — the system property it maps to:
 * ESTELLA_BENCH_FRAMES is `debug.estella.bench_frames`, which a shell can set
 * (`adb shell setprop debug.estella.bench_frames 300`) before the app starts.
 * The same bench then runs on a phone without a rebuilt package.
 */
const char* benchEnv(const char* name) {
    if (const char* v = std::getenv(name)) return v;
#if defined(__ANDROID__)
    static std::vector<std::pair<std::string, std::string>> read;
    for (const auto& [key, value] : read) if (key == name) return value.empty() ? nullptr : value.c_str();
    std::string prop = "debug.estella.";
    for (const char* c = name + std::strlen("ESTELLA_"); *c; ++c) {
        prop += static_cast<char>(std::tolower(static_cast<unsigned char>(*c)));
    }
    char value[PROP_VALUE_MAX] = {};
    __system_property_get(prop.c_str(), value);
    read.emplace_back(name, value);
    return read.back().second.empty() ? nullptr : read.back().second.c_str();
#else
    return nullptr;
#endif
}

long envLong(const char* name, long fallback) {
    const char* v = benchEnv(name);
    if (v == nullptr || v[0] == '\0') return fallback;
    const long n = std::strtol(v, nullptr, 10);
    return n >= 0 ? n : fallback;
}

BenchState& state() {
    static BenchState s = [] {
        BenchState init;
        const char* frames = benchEnv("ESTELLA_BENCH_FRAMES");
        init.frames = envLong("ESTELLA_BENCH_FRAMES", 0);
        init.asked = frames != nullptr && frames[0] != '\0' && init.frames > 0;
        init.warmup = envLong("ESTELLA_BENCH_WARMUP", 120);
        if (const char* dt = benchEnv("ESTELLA_BENCH_DT")) {
            const double v = std::strtod(dt, nullptr);
            if (v > 0.0) init.dt = v;
        }
        if (const char* label = benchEnv("ESTELLA_BENCH_LABEL")) init.label = label;
        if (const char* quit = benchEnv("ESTELLA_BENCH_QUIT")) init.quitAfter = quit[0] != '0';
        if (init.asked) {
            init.update.ms.reserve(static_cast<size_t>(init.frames));
            init.pump.ms.reserve(static_cast<size_t>(init.frames));
            init.cpu.ms.reserve(static_cast<size_t>(init.frames));
            init.frame.ms.reserve(static_cast<size_t>(init.frames));
        }
        return init;
    }();
    return s;
}

/** Whether this frame is one of the timed ones. Warmup frames run identically —
 *  they are simply not sampled — so nothing about the loop changes at the seam. */
bool timing() {
    const BenchState& s = state();
    return s.asked && !s.reported && s.seen > s.warmup;
}

/** Quantile by position on the sorted samples, no interpolation: these are
 *  timings, and the value at a position is one that was actually observed. */
double at(std::vector<double> v, double q) {
    if (v.empty()) return 0.0;
    std::sort(v.begin(), v.end());
    size_t i = static_cast<size_t>(q * static_cast<double>(v.size() - 1) + 0.5);
    if (i >= v.size()) i = v.size() - 1;
    return v[i];
}

/** One JSON line, because a runner has to parse this and a human has to read it. */
void report() {
    BenchState& s = state();
    s.reported = true;
    const double p50 = at(s.pump.ms, 0.5);
    const double c50 = at(s.cpu.ms, 0.5);
    // The share a compiler can reach, and it is `pump` over `cpu`: `update` only
    // schedules the tick. Against `cpu`, never against `frame` — a present sleeps
    // out the rest of the refresh interval, which measures the panel.
    const double share = c50 > 0.0 ? p50 / c50 : 0.0;
    // -1, not 0: "the platform would not say" and "the frame did nothing but
    // wait" are different answers and a consumer has to be able to refuse both.
    const double busy = s.busyWallMs > 0.0 ? s.busyCpuMs / s.busyWallMs : -1.0;
    ESHOST_LOGI("bench: {\"label\":\"%s\",\"warmup\":%ld,\"frames\":%zu,\"dt\":%.6f,"
                "\"update\":{\"min\":%.4f,\"p50\":%.4f,\"p90\":%.4f},"
                "\"pump\":{\"min\":%.4f,\"p50\":%.4f,\"p90\":%.4f},"
                "\"cpu\":{\"min\":%.4f,\"p50\":%.4f,\"p90\":%.4f},"
                "\"frame\":{\"min\":%.4f,\"p50\":%.4f,\"p90\":%.4f},"
                "\"draws\":%u,\"sprites\":%u,\"aotCandidates\":%u,\"aotPacked\":%u,"
                "\"tickShareOfCpu\":%.4f,\"busy\":%.4f,\"adapter\":\"%s\"}",
                // The FRAME span's count is the authority on how many frames were
                // sampled: a frame can be abandoned after it began and reach no other span.
                s.label.c_str(), s.warmup, s.frame.ms.size(), s.dt,
                at(s.update.ms, 0.0), at(s.update.ms, 0.5), at(s.update.ms, 0.9),
                at(s.pump.ms, 0.0), p50, at(s.pump.ms, 0.9),
                at(s.cpu.ms, 0.0), c50, at(s.cpu.ms, 0.9),
                at(s.frame.ms, 0.0), at(s.frame.ms, 0.5), at(s.frame.ms, 0.9),
                s.draws, s.sprites, s.aotCandidatesFrame, s.aotPackedFrame, share, busy,
                s.adapter.c_str());
}

}  // namespace

bool benchWanted() { return state().asked; }

double benchDelta(double wall) {
    const BenchState& s = state();
    // The fixed step covers the warmup too: a scene that spent its warmup moving at
    // one rate and its timed frames at another is two scenes.
    return (s.asked && !s.reported) ? s.dt : wall;
}

void benchFrameBegin() {
    BenchState& s = state();
    if (!s.asked || s.reported) return;
    // Reset before the frame, not after: several compiled systems each add to
    // these and the totals are what one frame did.
    s.aotCandidates = 0;
    s.aotPacked = 0;
    ++s.seen;
    if (timing()) {
        s.frame.begin();
        s.cpu.begin();
        s.cpuAtSpanBegin = threadCpuMs();
    }
}

void benchUpdateBegin() { if (timing()) state().update.begin(); }
void benchUpdateEnd() { if (timing()) state().update.end(); }
void benchPumpBegin() { if (timing()) state().pump.begin(); }
void benchPumpEnd() { if (timing()) state().pump.end(); }
void benchBeforePresent() {
    if (!timing()) return;
    BenchState& s = state();
    s.cpu.end();
    const double now = threadCpuMs();
    if (s.cpuAtSpanBegin >= 0.0 && now >= 0.0) {
        s.busyCpuMs += now - s.cpuAtSpanBegin;
        s.busyWallMs += s.cpu.ms.back();
    }
}

void benchNoteDraws(unsigned draws, unsigned sprites) {
    if (!timing()) return;
    state().draws = draws;
    state().sprites = sprites;
}

void benchNoteAdapter(const char* kind) {
    // Whether or not a bench was asked for: the adapter is known long before the
    // first timed frame, and there is nothing to time here.
    if (kind != nullptr && kind[0] != '\0') state().adapter = kind;
}

void benchNoteAotCandidates(unsigned candidates, unsigned packed) {
    BenchState& s = state();
    if (!s.asked || s.reported) return;
    s.aotCandidates += candidates;
    s.aotPacked += packed;
    // Kept even during warmup: cheap, and it means the report has numbers even
    // if the last timed frame happened to dispatch to nothing.
    s.aotCandidatesFrame = s.aotCandidates;
    s.aotPackedFrame = s.aotPacked;
}

bool benchFrameEnd() {
    BenchState& s = state();
    if (!s.asked || s.reported) return false;
    if (!timing()) return false;
    s.frame.end();
    if (static_cast<long>(s.frame.ms.size()) < s.frames) return false;
    report();
    return s.quitAfter;
}

}  // namespace eshost