SimulationBackend.h

浏览该文件的文档.

#pragma once
 
#include "common/Export.h"
#include "common/Result.h"
#include "common/Time.h"
 
#include <cstdint>
#include <memory>
#include <ostream>
#include <string_view>
 
class b2World;
 
namespace eve::physics {
 
enum class SimulationBackendKind {
    Cpu,
    Gpu,
    MockAccelerator,
};
 
enum class SimulationBackendDomain {
    World2D,
    World3D,
    Cloth2D,
    Cloth3D,
    Rope3D,
    SoftBody3D,
    SurfaceFluid,
};
 
[[nodiscard]] constexpr std::string_view simulationBackendDomainName(SimulationBackendDomain domain) noexcept {
    switch (domain) {
        case SimulationBackendDomain::World2D: return "world2d";
        case SimulationBackendDomain::World3D: return "world3d";
        case SimulationBackendDomain::Cloth2D: return "cloth2d";
        case SimulationBackendDomain::Cloth3D: return "cloth3d";
        case SimulationBackendDomain::Rope3D: return "rope3d";
        case SimulationBackendDomain::SoftBody3D: return "softbody3d";
        case SimulationBackendDomain::SurfaceFluid: return "surface_fluid";
    }
    return "unknown";
}
 
enum class SimulationDeterminism {
    BitExact,
    ToleranceBounded,
    ExplicitlyNondeterministic,
};
 
[[nodiscard]] constexpr std::string_view simulationBackendKindName(SimulationBackendKind kind) noexcept {
    switch (kind) {
        case SimulationBackendKind::Cpu: return "cpu";
        case SimulationBackendKind::Gpu: return "gpu";
        case SimulationBackendKind::MockAccelerator: return "mock_accelerator";
    }
    return "unknown";
}
 
[[nodiscard]] constexpr std::string_view simulationDeterminismName(SimulationDeterminism determinism) noexcept {
    switch (determinism) {
        case SimulationDeterminism::BitExact: return "bit_exact";
        case SimulationDeterminism::ToleranceBounded: return "tolerance_bounded";
        case SimulationDeterminism::ExplicitlyNondeterministic: return "explicitly_nondeterministic";
    }
    return "unknown";
}
 
inline std::ostream& operator<<(std::ostream& stream, SimulationBackendKind kind) {
    return stream << simulationBackendKindName(kind);
}
 
inline std::ostream& operator<<(std::ostream& stream, SimulationDeterminism determinism) {
    return stream << simulationDeterminismName(determinism);
}
 
using SimulationStep = eve::SimulationStep;
 
struct SimulationSettings {
    int velocityIterations = 8;
    int positionIterations = 3;
    int subStepCount = 4;
};
 
struct SimulationObservation {
    std::uint64_t stepCount = 0;
    eve::SimulationTick lastTick = eve::SimulationTick::zero();
    eve::Duration simulatedDuration = eve::Duration::zero();
    double simulatedSeconds = 0.0;
    float lastDeltaSeconds = 0.f;
};
 
class ISimulationBackend {
public:
    virtual ~ISimulationBackend() = default;
 
    [[nodiscard("check the step outcome or explicitly ignore it")]]
    virtual eve::Result<void> step(const eve::SimulationStep& step, const SimulationSettings& settings) = 0;
 
    [[nodiscard("inspect simulation progress or explicitly ignore it")]]
    virtual SimulationObservation observation() const noexcept = 0;
 
    [[nodiscard]] virtual SimulationBackendKind kind() const noexcept = 0;
 
    [[nodiscard]] virtual SimulationDeterminism determinism() const noexcept = 0;
 
    [[nodiscard("check backend observation restore")]]
    virtual eve::Result<void> restoreObservation(const SimulationObservation& /*observation*/) {
        return eve::Result<void>::failure(eve::Diagnostic::error(
            eve::DiagnosticCode::Unsupported, "This simulation backend does not support observation restore",
            "physics.simulationBackend.restoreObservation"));
    }
};
 
class IAcceleratorBackendProvider {
public:
    static constexpr const char* capabilityName = "eve.physics.IAcceleratorBackendProvider";
 
    virtual ~IAcceleratorBackendProvider() = default;
 
    [[nodiscard]] virtual bool supports(SimulationBackendDomain domain) const noexcept = 0;
 
    [[nodiscard("inspect provider creation or explicitly fall back")]]
    virtual eve::Result<std::unique_ptr<ISimulationBackend>> create(SimulationBackendDomain domain, void* state) = 0;
};
 
class EVENGINE_API_BACKENDS AcceleratorBackendProviderRegistration {
public:
    [[nodiscard("retain and check the accelerator provider registration")]]
    static eve::Result<AcceleratorBackendProviderRegistration> registerProvider(
        IAcceleratorBackendProvider& provider, int priority = 0);
 
    ~AcceleratorBackendProviderRegistration();
 
    AcceleratorBackendProviderRegistration(const AcceleratorBackendProviderRegistration&)            = delete;
    AcceleratorBackendProviderRegistration& operator=(const AcceleratorBackendProviderRegistration&) = delete;
 
    AcceleratorBackendProviderRegistration(AcceleratorBackendProviderRegistration&& other) noexcept;
    AcceleratorBackendProviderRegistration& operator=(AcceleratorBackendProviderRegistration&& other) noexcept;
 
    void reset() noexcept;
 
private:
    AcceleratorBackendProviderRegistration() = default;
    IAcceleratorBackendProvider* provider_ = nullptr;
};
 
struct SimulationBackendSelection {
    std::unique_ptr<ISimulationBackend> backend;
    SimulationBackendKind requestedKind = SimulationBackendKind::Cpu;
    SimulationBackendKind actualKind = SimulationBackendKind::Cpu;
    bool usedFallback = false;
};
 
using SimulationStepCallback = void (*)(void* context, const eve::SimulationStep& step,
                                        const SimulationSettings& settings) noexcept;
 
namespace detail {
 
[[nodiscard("check simulation-step validation")]]
EVENGINE_API_BACKENDS eve::Result<void> validateSimulationStep(const eve::SimulationStep&   step,
                                                               const SimulationSettings&    settings,
                                                               const SimulationObservation& observation);
 
[[nodiscard("check observation advancement")]]
EVENGINE_API_BACKENDS eve::Result<SimulationObservation> advanceSimulationObservation(
    const SimulationObservation& current, const eve::SimulationStep& step);
 
[[nodiscard("check observation validation")]]
EVENGINE_API_BACKENDS eve::Result<void> validateSimulationObservation(const SimulationObservation& observation,
                                                                      const char*                  path);
 
[[nodiscard("retain the backend until its borrowed world is destroyed")]]
EVENGINE_API_BACKENDS std::unique_ptr<ISimulationBackend> makeBox2DSimulationBackend(b2World* world);
 
[[nodiscard("retain the backend while its callback state is live")]]
EVENGINE_API_BACKENDS std::unique_ptr<ISimulationBackend> makeCallbackSimulationBackend(
    void* context, SimulationStepCallback callback, SimulationBackendKind kind, SimulationDeterminism determinism);
 
[[nodiscard("retain the mock backend for contract execution")]]
EVENGINE_API_BACKENDS std::unique_ptr<ISimulationBackend> makeMockAcceleratorBackend();
 
[[nodiscard("inspect the selected backend and fallback diagnostics")]]
EVENGINE_API_BACKENDS eve::Result<SimulationBackendSelection> selectSimulationBackend(
    SimulationBackendDomain domain, std::unique_ptr<ISimulationBackend> cpuBackend, void* state,
    bool preferAccelerator = true);
 
}  // namespace detail
}  // namespace eve::physics