Kit Kernel Event System#

Applications built on Kit Kernel have a global name-based event distribution system based on the carb.eventdispatcher plugin. Events are a loose-coupling system that allows systems to be interconnected but depend on each other to the least practicable extent. This means that systems can communicate without needing to know anything about each other.

Example#

Imagine that we have an asset loading system, and we have a UI element that lists all resources currently being loaded. One approach to this might be to have the UI list query the asset system for a list of loading assets every UI update, but polling in this manner can be slow. Another option might be to have a means of registering callbacks for the asset system to notify when it starts and finishes loading an asset. This however introduces a dependency on the asset system. If we later have multiple asset providers, they may have a different method for communicating this information. The more dependent our UI system is on the asset system, the stronger the coupling and more work must go in to maintaining the coupling.

Enter our carb.eventdispatcher system for weak coupling. Now instead of the asset system having to maintain callbacks to call when it starts or finishes loading an asset, instead it simply dispatches an event through carb.eventdispatcher. No other systems may be listening to this event, or a hundred other systems may be listening. If no other system is listening, the dispatch is incredibly cheap.

Events are next to useless unless they can provide parameters, so naturally carb.eventdispatcher allows for parameters. In this case, the name of the asset being loaded would be an important parameter, but there could be others as well, such as who requested the asset, or which medium is providing the asset.

The other side of event dispatching is listening to an event or observing the event. When an event is observed, a callback is received whenever that event is dispatched. Our example UI system can observe the event and therefore receive a callback when an asset that we’re interested in is dispatched.

See the documentation for IEventDispatcher for observing and dispatching events.

Registration Example#

Registering for a global event is easily performed through IEventDispatcher since all events exist in the same global namespace.

        auto ed = carb::getCachedInterface<carb::eventdispatcher::IEventDispatcher>();

        // observeEvent() returns an ObserverGuard which we capture as m_updateSubscription. When the ObserverGuard is
        // reset or destroyed, the observer will no longer be notified of events.
        m_updateSubscription = ed->observeEvent(
            RStringKey("IApp InternalUpdate"),      // The observer name for debugging and profiling
            omni::kit::update::eKitInternalUpdate,  // The 'order' parameter, determining the global observer call order
            kGlobalEventPostUpdate,                 // The event to observe

            // The invocable to call when a dispatched event is observed
            [this](const carb::eventdispatcher::Event& event) {
                CARB_UNUSED(event);
                _internalUpdate(true);
            }
        );

Events 1.0 Backwards Compatibility#

Events 1.0 behavior is provided by maintaining adapters created through IEventsAdapter. This allows plugins and extensions that used IEventStream to continue functioning without explicit conversion to the Events 2.0 model.

The above example was expressed as Events 1.0 as follows:

m_updateSubscription = carb::events::createSubscriptionToPop(
    getRunLoop(nullptr)->postUpdate,        // The event stream to subscribe to

    // The invocable to call when an event is dispatched
    [this](carb::events::IEvent* event) {
        CARB_UNUSED(event);
        _internalUpdate(true);
    },
    omni::kit::update::eKitInternalUpdate,  // The 'order' parameter, determining the global subscriber call order
    "IApp InternalUpdate"                   // The name of the subscription for debugging and profiling
);

As you can see, the parameters are very similar. The most notable difference is that in Events 1.0 the IEventStream to subscribe to would need to be located and passed to the function that creates a subscription. With Events 2.0 since all events are referred to by name in a global namespace, this is no longer the case. Instead of having to chase pointers and call functions to find the proper event stream, use a RString wrapping the name of the event to observe.

Another difference is the name parameter. With Events 1.0 this was optional and often unspecified. With Events 2.0 it is required. It is also passed as a RStringKey to reduce memory and performance cost in copying the string.

Event List#

The following list serves as documentation for Kit Kernel events. Note that event names and parameter names are case-sensitive.

Event names are given as interned strings using the RString system. Parameters are passed via the NamedVariant type; the key is given as an interned string using the RStringKey system.

omni.kit.app App Lifecycle Events#

omni.kit.app:started#

Dispatched at application startup time by the omni.kit.app plugin immediately before omni::kit::IApp::startup() returns.

No parameters.

See omni::kit::kGlobalEventAppStarted (C++) and omni.kit.app.GLOBAL_EVENT_APP_STARTED (Python).

omni.kit.app:ready#

Dispatched by omni.kit.app once the application enters a ready state. After application startup, every call to omni::kit::IApp::update() after the first call will check for readiness. Readiness can be delayed by calling omni::kit::IApp::delayAppReady() which must be called during each main loop iteration to prevent the omni.kit.app:ready event from being dispatched. Once a run loop completes without any calls to delay readiness, the application is considered “ready” and omni.kit.app:ready is dispatched.

No parameters.

See omni::kit::kGlobalEventAppReady and omni.kit.app.GLOBAL_EVENT_APP_READY (Python).

omni.kit.app:post_quit#

Dispatched during the next update after omni::kit::IApp::postQuit() is called. Once postQuit is called, the next omni::kit::IApp::update() will start the shutdown sequence. The first step of this sequence is to dispatch omni.kit.app:post_quit. Any observers of this event may - DURING EVENT DISPATCH - call omni::kit::IApp::tryCancelShutdown() to abort the shutdown process, unless the posted quit request was un-cancellable. If the request to quit was not cancelled, omni.kit.app:pre_shutdown is then dispatched.

Parameters:

  • uncancellable (bool) - A true value indicates that the shutdown cannot be cancelled.

See omni::kit::kGlobalEventPostQuit and omni.kit.app.GLOBAL_EVENT_POST_QUIT (Python).

omni.kit.app:pre_shutdown#

Dispatched to indicate the start of shutdown.

No parameters.

See omni::kit::kGlobalEventPreShutdown and omni.kit.app.GLOBAL_EVENT_PRE_SHUTDOWN (Python).

omni.kit.app Scripting Events#

omni.kit.app:script_command and omni.kit.app:script_command:immmediate#

These events are dispatched when a script command is issued via omni::kit::IAppScripting::executeString() or omni::kit::IAppScripting::executeString().

The event with the :immediate suffix is sent immediately upon when the function is called, but the primary event is queued and dispatched during the omni::kit::IApp::update() function.

Parameters:

  • text (string) - A human-readable (possibly multi-line) text block.

See omni::kit::kGlobalEventScriptingCommand and omni::kit::kGlobalEventScriptingCommandImmediate (C++) or omni.kit.app.GLOBAL_EVENT_SCRIPT_COMMAND and omni.kit.app.GLOBAL_EVENT_SCRIPT_COMMAND_IMMEDIATE (Python).

omni.kit.app:script_stdout and omni.kit.app:script_stdout:immediate#

Dispatched when Python produces stdout stream output.

The event with the :immediate suffix is sent immediately upon when the output is generated, but the primary event is queued and dispatched during the omni::kit::IApp::update() function.

Events are dispatched per-line, so multi-line output may cause several events to be sent in succession.

Parameters:

  • text (string) - A human-readable (typically single-line) text block.

See omni::kit::kGlobalEventScriptingStdOut and omni::kit::kGlobalEventScriptingStdOutImmediate (C++) or omni.kit.app.GLOBAL_EVENT_SCRIPT_STDOUT and omni.kit.app.GLOBAL_EVENT_SCRIPT_STDOUT_IMMEDIATE (Python).

omni.kit.app:script_stderr and omni.kit.app:script_stderr:immediate#

Dispatched when Python produces stderr stream output.

The event with the :immediate suffix is sent immediately upon when the output is generated, but the primary event is queued and dispatched during the omni::kit::IApp::update() function.

Events are dispatched per-line, so multi-line output may cause several events to be sent in succession.

Parameters:

  • text (string) - A human-readable (typically single-line) text block.

See omni::kit::kGlobalEventScriptingStdErr and omni::kit::kGlobalEventScriptingStdErrImmediate (C++) or omni.kit.app.GLOBAL_EVENT_SCRIPT_STDERR and omni.kit.app.GLOBAL_EVENT_SCRIPT_STDERR_IMMEDIATE (Python).

Other omni.kit.app Events#

omni.kit.app:error_log and omni.kit.app:error_log:immediate#

Dispatched when a warning or error log occurs.

The event with the :immediate suffix is sent immediately upon when the output is generated, but the primary event is queued and dispatched during the omni::kit::IApp::update() function.

Parameters:

  • level (integer) - The log level. Will be carb::logging::kLevelWarn or higher.

  • message (string) - The log message.

  • source (string) - The plugin or log channel that emitted the log message (error logs only).

  • filename (string) - The source filename that emitted the log message (error logs only).

  • functionName (string) - The function that emitted the log message (error logs only).

  • lineNumber (integer) - The line number in the source filename that emitted the log message (error logs only).

See omni::kit::kGlobalEventErrorLog and omni::kit::kGlobalEventErrorLogImmediate (C++) or omni.kit.app.GLOBAL_EVENT_ERROR_LOG and omni.kit.app.GLOBAL_EVENT_ERROR_LOG_IMMEDIATE (Python).

omni.ext Events#

omni.ext:script_changed and omni.ext:script_changed:immediate#

Dispatched when the extension model changes, such as when an extension is started or stopped, or when the extension registry changes.

The event with the :immediate suffix is sent during the first omni::ext::ExtensionManager::processAndApplyAllChanges(), call when a change occurs, but the primary event is queued and dispatched during the omni::kit::IApp::update() function.

The event should be sent a maximum of once per frame.

No parameters.

See omni::ext::kGlobalEventScriptChanged and omni::ext::kGlobalEventScriptChangedImmediate (C++) or omni.ext.GLOBAL_EVENT_SCRIPT_CHANGED and omni.ext.GLOBAL_EVENT_SCRIPT_CHANGED_IMMEDIATE (Python).

omni.ext:folder_changed and omni.ext:folder_changed:immediate#

Dispatched when extension paths change, such as when omni::ext::ExtensionManager::addPath() or omni::ext::ExtensionManager::removePath() is called. The event with the :immediate suffix is sent during the function call that changes the extension paths, but the primary event is queued and dispatched during the next omni::kit::IApp::update() function call.

The event should be sent a maximum of once per frame.

No parameters.

See omni::ext::kGlobalEventFolderChanged and omni::ext::kGlobalEventFolderChangedImmediate (C++) or omni.ext.GLOBAL_EVENT_FOLDER_CHANGED and omni.ext.GLOBAL_EVENT_FOLDER_CHANGED_IMMEDIATE (Python).

omni.ext:registry_refresh_begin#

Dispatched when registry refresh is about to begin.

No parameters.

See omni::ext::kGlobalEventRegistryRefreshBegin (C++) or omni.ext.GLOBAL_EVENT_REGISTRY_REFRESH_BEGIN (Python).

omni.ext:registry_refresh_end#

Dispatched when registry refresh has ended.

Parameters:

  • success (bool) - true if the registry was successfully refreshed; false otherwise.

See omni::ext::kGlobalEventRegistryRefreshEnd (C++) or omni.ext.GLOBAL_EVENT_REGISTRY_REFRESH_END (Python).

omni.ext:extension_pull_begin#

Dispatched when an extension package is about to be pulled.

Parameters:

See omni::ext::kGlobalEventExtensionPullBegin (C++) or omni.ext.GLOBAL_EVENT_EXTENSION_PULL_BEGIN (Python).

omni.ext:extension_pull_end#

Dispatched when an extension package pull has ended.

Parameters:

  • packageId (carb::RString) - The name of the extension package.

  • success (bool) - true if the extension was pulled successfully; false otherwise.

See omni::ext::kGlobalEventExtensionPullEnd (C++) or omni.ext.GLOBAL_EVENT_EXTENSION_PULL_END (Python).

Main RunLoop Events#

The main RunLoop is created via omni::kit::IApp::getRunLoop() and is typically managed by omni::kit::IRunLoopRunner.

preUpdate / update / postUpdate#

Each main loop during omni::kit::IApp::update() omni.kit.app will call the registered omni::kit::IRunLoopRunner’s update function. This function will dispatch preUpdate, followed by update, followed by postUpdate.

Typically, each update event will have the following parameters. However, this is up to the omni::kit::IRunLoopRunner implementation.

  • dt (double) - Effectively the length of time (in seconds) of the previous frame. The first frame is 1.0 / 60.0.

  • SWHFrameNumber (int64) - The frame number beginning at 0.

See omni::kit::app::kGlobalEventPreUpdate, omni::kit::app::kGlobalEventUpdate and omni::kit::app::kGlobalEventPostUpdate (C++), or omni.kit.app.GLOBAL_EVENT_PRE_UPDATE, omni.kit.app.GLOBAL_EVENT_UPDATE and omni.kit.app.GLOBAL_EVENT_POST_UPDATE (Python).

Other RunLoop Events#

omni::kit::RunLoop instances that are created with omni::kit::IApp::getRunLoop() with names other than main will also issue preUpdate, update, and postUpdate events, but they will be prefixed as follows:

runloop:<name>:<event>

For instance, a RunLoop named animation would dispatch the following events in order: runloop:animation:preUpdate, runloop:animation:update, and runloop:animation:postUpdate.

Typically, each update event will have the following parameters. However, this is up to the omni::kit::IRunLoopRunner implementation.

  • dt (double) - Effectively the length of time (in seconds) of the previous frame. The first frame is typically 1.0 / 60.0.

Note

As these events are composed, there are no constants that already define them. It is recommended to create constants referencing the various runloop events when a runloop is created.

On this page