IApp.h#

// SPDX-FileCopyrightText: Copyright (c) 2020-2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: LicenseRef-NvidiaProprietary
//
// NVIDIA CORPORATION, its affiliates and licensors retain all intellectual
// property and proprietary rights in and to this material, related
// documentation and any modifications thereto. Any use, reproduction,
// disclosure or distribution of this material and related documentation
// without an express license agreement from NVIDIA CORPORATION or
// its affiliates is strictly prohibited.

#pragma once

#include "../../carb/Interface.h"
#include "../../carb/events/IEvents.h"
#include "../../carb/extras/Timer.h"
#include "../../carb/logging/ILogging.h"
#include "../../carb/RString.h"
#include "../String.h"

#include "AppTypes.h"

#define omni_kit_IApp_latest CARB_HEXVERSION(1, 5)
#ifndef omni_kit_IApp
#    define omni_kit_IApp CARB_HEXVERSION(1, 5)
#endif

// Forward declarations
namespace omni::ext
{
class ExtensionManager;
}

namespace omni::kit
{

// Forward declarations
class IRunLoopRunner;
class IAppScripting;

class IApp
{
public:
    CARB_PLUGIN_INTERFACE_EX("omni::kit::IApp", omni_kit_IApp_latest, omni_kit_IApp)

    virtual void startup(const AppDesc& desc) = 0;

    virtual void update() = 0;

    virtual bool isRunning() = 0;

    virtual int shutdown() = 0;

    int run(const AppDesc& desc);

    virtual void postQuit(int returnCode = 0) = 0;

    CARB_DEPRECATED("Use carb::eventdispatcher") virtual carb::events::IEventStream* getLogEventStream() = 0;

#if CARB_VERSION_ATLEAST(carb_logging_ILogging, 1, 3)
    CARB_DEPRECATED("Use replayLogMessages() instead")
    virtual void replayLogMessagesOld(carb::logging::Logger* target) = 0;
#else
    virtual void replayLogMessages(carb::logging::Logger* target) = 0;
#endif

    virtual void toggleLogMessageRecording(bool logMessageRecordingEnabled) = 0;

    virtual RunLoop* getRunLoop(const char* name = kRunLoopDefault) = 0;

    bool ensureRunLoop(const char* name = kRunLoopDefault);

    virtual bool isRunLoopAlive(const char* name = kRunLoopDefault) = 0;

    virtual void terminateRunLoop(const char* name, bool block) = 0;

    CARB_IGNOREWARNING_MSC_WITH_PUSH(4996) // deprecation warning
    CARB_IGNOREWARNING_GNUC_WITH_PUSH("-Wdeprecated-declarations")

    CARB_DEPRECATED("Use Events 2.0")
    carb::events::IEventStream* getPreUpdateEventStream(const char* runLoopName = kRunLoopDefault)
    {
        return getRunLoop(runLoopName)->preUpdate;
    }

    CARB_DEPRECATED("Use Events 2.0")
    carb::events::IEventStream* getUpdateEventStream(const char* runLoopName = kRunLoopDefault)
    {
        return getRunLoop(runLoopName)->update;
    }

    CARB_DEPRECATED("Use Events 2.0")
    carb::events::IEventStream* getPostUpdateEventStream(const char* runLoopName = kRunLoopDefault)
    {
        return getRunLoop(runLoopName)->postUpdate;
    }

    CARB_DEPRECATED("Use Events 2.0")
    carb::events::IEventStream* getMessageBusEventStream(const char* runLoopName = kRunLoopDefault)
    {
        return getRunLoop(runLoopName)->messageBus;
    }

    CARB_IGNOREWARNING_MSC_POP
    CARB_IGNOREWARNING_GNUC_POP

    virtual void setRunLoopRunner(IRunLoopRunner* runner) = 0;

    virtual omni::ext::ExtensionManager* getExtensionManager() = 0;

    virtual IAppScripting* getPythonScripting() = 0;

    virtual const char* getBuildVersion() = 0;

    virtual bool isDebugBuild() = 0;

    virtual PlatformInfo getPlatformInfo() = 0;

    virtual double getTimeSinceStart(carb::extras::Timer::Scale timeScale = carb::extras::Timer::Scale::eMilliseconds) = 0;

    virtual double getLastUpdateTime() = 0;

    virtual uint32_t getUpdateNumber() = 0;

    virtual void printAndLog(const char* message) = 0;

    CARB_DEPRECATED("Use carb::eventdispatcher") virtual carb::events::IEventStream* getShutdownEventStream() = 0;

    virtual bool tryCancelShutdown(const char* reason) = 0;

    virtual void postUncancellableQuit(int returnCode) = 0;

    CARB_DEPRECATED("Use carb::eventdispatcher") virtual carb::events::IEventStream* getStartupEventStream() = 0;

    virtual bool isAppReady() = 0;

    virtual void delayAppReady(const char* requesterName) = 0;

    virtual const BuildInfo& getBuildInfo() = 0;

    virtual const AppInfo& getAppInfo() = 0;

    virtual void restart(const char* const* args = nullptr,
                         size_t argCount = 0,
                         RestartArgsPolicy argsPolicy = RestartArgsPolicy::eAppend,
                         bool uncancellable = false) = 0;

#if CARB_VERSION_ATLEAST(omni_kit_IApp, 1, 4)
    virtual void reportAlive() = 0;
#endif

#if CARB_VERSION_ATLEAST(omni_kit_IApp, 1, 5)
#    if CARB_VERSION_ATLEAST(carb_logging_ILogging, 1, 3)
    virtual void replayLogMessages(carb::logging::Logger2* target) = 0;
#    else
    // Need to reserve the slot for this function given the version macros
    virtual void reservedReplayLogMessages(carb::logging::Logger2*) = 0;
#    endif
#endif
};

const auto kGlobalEventScriptingCommand = carb::RString("omni.kit.app:script_command");

const auto kGlobalEventScriptingCommandImmediate = carb::RString("omni.kit.app:script_command:immediate");

const auto kGlobalEventScriptingStdOut = carb::RString("omni.kit.app:script_stdout");

const auto kGlobalEventScriptingStdOutImmediate = carb::RString("omni.kit.app:script_stdout:immediate");

const auto kGlobalEventScriptingStdErr = carb::RString("omni.kit.app:script_stderr");

const auto kGlobalEventScriptingStdErrImmediate = carb::RString("omni.kit.app:script_stderr:immediate");

const auto kGlobalEventErrorLog = carb::RString("omni.kit.app:error_log");

const auto kGlobalEventErrorLogImmediate = carb::RString("omni.kit.app:error_log:immediate");

const carb::events::EventType kScriptingEventCommand = 0;

const carb::events::EventType kScriptingEventStdOut = 1;

const carb::events::EventType kScriptingEventStdErr = 2;

class IAppScripting
{
public:
    virtual bool executeString(const char* str, const char* commandName = nullptr, bool executeAsFile = false) = 0;

    virtual bool executeFile(const char* path, const char* const* args, size_t argCount) = 0;

    virtual bool addSearchScriptFolder(const char* path) = 0;

    virtual bool removeSearchScriptFolder(const char* path) = 0;

    CARB_DEPRECATED("Use carb::eventdispatcher") virtual carb::events::IEventStream* getEventStream() = 0;
};

//                                                Inline Functions                                                    //

inline int IApp::run(const AppDesc& desc)
{
    this->startup(desc);
    while (this->isRunning())
    {
        this->update();
    }
    return this->shutdown();
}

inline bool IApp::ensureRunLoop(const char* name)
{
    return this->getRunLoop(name) != nullptr;
}

} // namespace omni::kit