Legacy Events#

See the primary documentation on Events.

For Kit Kernel 107.0, transition has started to the Events 2.0 model for Kernel and RunLoop events. Other event streams may transition in future versions.

History (Events 1.0)#

Historically, the carb.events plugin was used to create IEventStream objects, which were then owned by the systems that created them. The IEventStream could function either as an instant event delivery system (using the dispatch() function), or as a message queue where events could be pushed into the event stream which would be pumped at a later time. Subscribers could be added to either the push- or pop-side of the queue.

IEventStream can be challenging to use effectively. Furthermore, its reliance on heap memory internally and carb.dictionary as a payload system can make it performance constrained. Due to ABI compatibility, some of these issues are not easily solved. It was proposed to re-evaluate our event system as a whole to see if performance and usability can be improved, while also maintaining backwards-compatibility for existing extensions and applications.

Events 2.0#

Events 2.0 is the realization of that work. Since most of the events currently in use were instant events, a new system called IEventDispatcher was created solely to deliver instant events. For situations where events must be queued, IMessageQueue was created to store those messages. And in order to maintain backwards compatibility, IEventsAdapter was created which implements the IEventStream interface but functions as an adapter layer to and from Events 1.0 to Events 2.0.

To depart from using carb.dictionary as a payload mechanism, an extensible system was created in a new carb.variant plugin. This allows Variant objects that are ABI-safe and can be extended with custom types.

There are two primary interfaces to manage Events 2.0: IEventDispatcher and IMessageQueue, both provided by the carb.eventdispatcher plugin.

An adapter is also provided by carb.events and can be created with the new IEventsAdapter interface.

IEventDispatcher#

Unlike IEventStream, IEventDispatcher is an instant-only event system. Like IEventStream’s dispatch() and pump() functions, events are dispatched from the calling thread. But since IEventDispatcher’s events are always instant, they can be created on the stack. In most cases, no heap memory is required for dispatching an instant event.

Two major differences from IEventStream is that IEventDispatcher events are name-based rather than integral hashes; and the event dispatcher is global. To subscribe to an event with the older IEventStream you would first have to get access to the IEventStream instance through the system that created it; there is no global registry of event streams. In contrast, with IEventDispatcher you observe an event by fully-qualified name. This does mean that event names typically must be longer and more descriptive to avoid collisions. For instance, many Kit Kernel events have the prefix "omni.kit.app:" or "omni.ext:" to indicate that they are events sent by those respective modules. See the recommendations for event names.

To provide a better payload interface than carb.dictionary, a new carb.variant plugin was created with better type conversion support to C++ (and Python) types. The carb.variant system can also be extended to support user types.

Both carb.eventdispatcher and carb.variant make heavy use of Carbonite’s RString registered string system. This allows strings to be compared for [in]equality very quickly and passed as 32-bit values (instead of C-style strings or heap-allocated strings). The event names mentioned above also use the RString system.

IMessageQueue#

The new component to perform queue-like functionality in Events 2.0 is IMessageQueue. This is a thread-safe queue to which events may be pushed, and later popped and processed. This can be combined with IEventDispatcher to dispatch all of the queued messages through the popAllAndDispatch() helper function. The push-side of the IMessageQueue can be either asynchronous, or synchronous (the pushing thread blocks until the message has been popped and processed).

All IMessageQueue instances are named and can be found through IMessageQueueFactory without having to track down the instance through the system that created it.

Bridging the gap#

It’s in our best interest to provide backwards compatibility for something as foundational as our event system. In order to do this, we have created an adapter layer. This allows transitioning to the more optimal Events 2.0 components as time allows, rather than forcing extensions to convert instantly.

Most of the effort here is handled within Kit Kernel–existing event streams, while deprecated, have been replaced with adapters that translate the old Events 1.0 model to the newer Events 2.0 model, both for subscribing to events as well as dispatching events. This is done by having the adapter use the same interface as IEventStream.

This adapter layer allows Events 2.0 observers to receive dispatches from Events 1.0, and allows Events 1.0 subscribers to receive dispatches from Events 2.0. More information below.

Converting Events 1.0 Subscriptions to Events 2.0#

Select the tab for your language.

An existing C++ use of an event stream might look like this:

auto app = carb::getFramework()->acquireInterface<omni::kit::IApp>();
m_updateEvtSub = carb::events::createSubscriptionToPop(
    app->getUpdateEventStream(),
    [this](carb::events::IEvents* e) {
        _update(carb::dictionary::getCachedDictionaryInterface()->get<float>(e->payload, "dt"));
    },
    carb::events::kDefaultOrder, "Menu update");

Converted to Events 2.0, this subscriber looks like this:

auto ed = carb::getCachedInterface<carb::eventdispatcher::IEventDispatcher>();
m_updateEvtSub = ed->observeEvent(
    carb::RStringKey("omni.kit.ui/Menu"),
    carb::eventdispatcher::kDefaultOrder,
    omni::kit::kGlobalEventUpdate,
    [this](const carb::eventdispatcher::Event& e) {
        const static carb::RStringKey kDt("dt");
        _update(e.getValueOr<float>(kDt, 0.f));
    });

Let’s break this down a bit. First, here’s the documentation for IEventStream for reference. Our Events 1.0 subscription used a helper function: carb::events::createSubscriptionToPop(). Here is the function prototype:

inline carb::ObjectPtr<carb::events::ISubscription> carb::events::createSubscriptionToPop(
    carb::events::IEventStream *stream,         // The event stream to use
    std::function<void(IEvent*)> onEventFn,     // The handler that will be invoked when the event occurs
    carb::events::Order order = kDefaultOrder,  // An optional order value to determine priority
    const char *subscriptionName = nullptr,     // The optional name for debugging and profiling
)

Now let’s look at using Events 2.0 with IEventDispatcher::observeEvent():

template<class Invocable, class ...Args>
carb::eventdispatcher::ObserverGuard carb::eventdispatcher::IEventDispatcher::observeEvent(
    carb::RStringKey observerName,      // The name of the observer for debugging and profiling
    carb::eventdispatcher::Order order, // The order value to determine priority
    carb::RString eventName,            // The name of the event to observe
    Invocable&& invocable,              // A Invocable object (lambda or function) that will be called
    Args&&... filterArgs,               // Optional filter arguments
)

Several of the items are similar:

  • order has the same meaning in both Events 1.0 and 2.0. It’s a (signed) priority order for calling events. The lowest order number is called first.

  • subscriptionName is now observerName and, due to its usefulness, now required. Note this is a RStringKey–a registered string so that the string is stored once and copied by value after that. RStringKey supports an index field too, which can be used to differentiate different instances with the same name. For example, carb::RStringKey(1, "Menu") has an index value of 1 and will be rendered "Menu_1" for debugging.

  • onEventFn is now invocable but essentially have the same meaning. However, the object passed to the event callback function is different. In Events 1.0 this was a non-const pointer to a ref-counted IEvent instance. This potentially allowed the event to be dangerously modified by an event handler. And the reference counting demanded that the object always be created on the heap. For Events 2.0, the parameter is now a const reference to Event. Modification is no longer possible, and the payload is easier to access. This Event is not reference counted so it can be ephemeral; it only exists while the event is dispatching. See the main guide below.

And some differences:

  • Instead of passing the instance of the IEventStream, now an eventName is given as a registered string (RString). Best practice is to use a constant value, such as omni::kit::kGlobalEventUpdate from our example above.

  • Events 2.0 has a powerful new feature: filterArgs. This optional argument allows specifying zero or more key/value arguments that the event must exactly match in order for the event to be passed to our observer callback. An example might be an event that is dispatched when a Window minimizes. The handler for that Window might observe the event filtering on the Window ID.

An existing Python use of an event stream might look like this:

def _on_event(self, e: carb.events.IEvent):
    dt = e.payload['dt']
    _update(dt)

def __init__(self):
    self._event_sub = omni.kit.app.get_app().get_update_event_stream().create_subscription_to_pop(
        self._on_event,
        name="Menu update"
    )

Converted to Events 2.0, this subscriber looks like this:

def _on_event(self, e: carb.eventdispatcher.Event):
    _update(e['dt'])

def __init__(self):
    self._event_sub = carb.eventdispatcher.get_eventdispatcher().observe_event(
        observer_name="omni.kit.ui/Menu",
        event_name=omni.kit.app.GLOBAL_EVENT_UPDATE,
        on_event=_on_event
    )

Let’s break this down a bit. First, here’s the documentation for IEventStream for reference. Our Events 1.0 subscription used the method: create_subscription_to_pop(). Here is the function definition:

create_subscription_to_pop(
    self: carb.events.IEventStream,
    fn: Callable[[carb.events.IEvent], None],
    order: int = 0,
    name: str = None,
) -> carb.events.ISubscription

Now let’s look at using Events 2.0 with observe_event():

observe_event(
    self: carb.eventdispatcher.IEventDispatcher,
    order: int = 0,
    event_name: str,
    on_event: Callable[[carb.eventdispatcher._eventdispatcher.Event], None],
    filter: handle = None,
    observer_name: str = '<python>'
) -> carb.eventdispatcher.ObserverGuard

Several of the items are similar:

  • order has the same meaning in both Events 1.0 and 2.0. It’s a (signed) priority order for calling events. The lowest order number is called first.

  • name is now observer_name. Providing this is highly recommended as it is useful in debugging and profiling.

  • fn is now on_event but essentially have the same meaning. However, the object passed to the event function is different. In Events 1.0 this was a IEvent and the payload was accessed through the payload attribute. For Events 2.0, the parameter is now a Event. The payload can be accessed directly through __getitem__ (i.e. event['key']). See the main guide below.

And some differences:

  • Events 2.0 requires the event_name to observe. It is highly recommended that this is a named value, such as omni.kit.app.GLOBAL_EVENT_UPDATE from the example.

  • Events 2.0 has a powerful new feature: filter. This optional argument allows specifying key/value arguments in a dict that the event must exactly match in order for the event to be passed to our observer callback. An example might be an event that is dispatched when a Window minimizes. The handler for that Window might observe the event filtering on the Window ID.

Since two strings must be passed to observe_event(), it is highly recommended to use keyword arguments.

Converting Events 1.0 Handler Functions to Events 2.0#

Select the tab for your language.

Let’s take a closer look at the subscriber callback function for Events 1.0. Typically it looked like this:

void MyClass::handleEvent(carb::events::IEvent* e)
{
    auto dict = carb::getCachedInterface<carb::dictionary::IDictionary>();
    if (p->type == (carb::events::EventType)kMyEventValue)
    {
        bool boolParam = dict->get<bool>(e->payload, "boolParam");
        const char* str = dict->get<const char*>(e->payload, "strParam");
        handleMyEvent(boolParam, str);
    }
    else if (p->type == (carb::events::EventType)kMyOtherEventValue)
    {
        double floatParam = dict->get<double>(e->payload, "floatParam");
        handleMyOtherEvent(floatParam);
    }
}

And the same function converted to Events 2.0:

// Typically better to have these defined as static variables per compilation unit
const static carb::RString kMyEventName(...), kMyOtherEventName(...);
const static carb::RStringKey kBoolParam("boolParam");
const static carb::RStringKey kStrParam("strParam");
const static carb::RStringKey kFloatParam("floatParam");

// ...

void MyClass::handleEvent(const carb::eventdispatcher::Event& e)
{
    if (e.eventName == kMyEventName)
    {
        bool boolParam = e.getValueOr<bool>(kBoolParam, false);
        const char* str = e.getValueOr<const char*>(kStrParam, nullptr);
        handleMyEvent(boolParam, str);
    }
    else if (e.eventName == kMyOtherEventName)
    {
        double floatParam = e.getValueOr<double>(kFloatParam, 0.0);
        handleMyOtherEvent(floatParam);
    }
}

Let’s note the changes:

Let’s take a closer look at the subscriber callback function for Events 1.0. Typically it looked like this:

def _handle_event(self, e: carb.events.IEvent):
    if e.type == int(MyEventEnum.EVENT_1):
        bool_param = e.payload["boolParam"]
        str_param = e.payload["strParam"]
        self._handle_event_1(bool_param, str_param)
    elif e.type == int(MyEventEnum.EVENT_2):
        float_param = e.payload["floatParam"]
        self._handle_event_2(float_param)

And the same function converted to Events 2.0:

def _handle_event(self, e: carb.eventdispatcher.Event):
    if e.event_name == GLOBAL_EVENT_1:
        bool_param = e["boolParam"]
        str_param = e["strParam"]
        self._handle_event_1(bool_param, str_param)
    elif e.event_name == GLOBAL_EVENT_2:
        float_param = e["floatParam"]
        self._handle_event_2(float_param)

Let’s note the changes:

  • carb.events.IEvent and carb.eventdispatcher.Event are different types with different usage.

  • IEvent has a type field that is of an integral type. Often this is 0 if an event stream sent only one event type. For other events it may correspond to an enum or it may be a string hash such as those generated by carb.events.type_from_string(). For Events 2.0, the Event class has an event_name string field.

  • IEvent (1.0) has a payload property that returns type carb::dictionary::Item. While Event (2.0) also has a payload property, it builds and returns a dict on the fly, so it is not as efficient to use. However, Event functions as a mapping type, so you can use [] operators on it directly. If the key does not exist, None is returned instead of raising an exception.

Message Bus#

The Message Bus historically was an IEventStream owned by each RunLoop. It was especially useful when a global event system was needed since Events 1.0 did not provide a global event system. The Message Bus would allow any event to be pushed into it and it would pump at the end of the RunLoop frame, delivering all of the queued events.

For Events 2.0, the omni::kit::RunLoop::messageBus remains as a special kind of adapter, but its use is no longer recommended.

Since events pushed to the Message Bus were generic, it isn’t feasible for an adapter to be created with a direct mapping of Events 1.0 EventType (integers, typically string hashes for the Message Bus) to Events 2.0 RString event names. Instead aliases must be registered.

In C++, registering an alias involves providing the EventType along with the immediate and deferred RString event names. This is done through the carb::events::registerEventAlias() function. The alias must be registered once prior to the event being dispatched, typically in a module startup function (carbOnPluginStartup() or omni::ext::IExt::onStartup() are good places).

constexpr carb::events::EventType kProgressEventType = CARB_EVENTS_TYPE_FROM_STR("omni.kit.window.status_bar@progress");
const auto kGlobalProgressEvent = RString("omni.kit.window.status_bar@progress");
const auto kGlobalProgressEventImmediate = RString("omni.kit.window.status_bar@progress:immediate");

// ...

carb::events::registerEventAlias(kProgressEventType, kGlobalProgressEventImmediate, kGlobalProgressEvent);

Python has a helper function (omni.kit.app.register_event_alias()) that defaults to :immediate being the immediate event suffix, making it very simple to register event aliases:

import carb.events
import omni.kit.app

PROGRESS_EVENT = carb.events.type_from_string("omni.kit.window.status_bar@progress")
GLOBAL_PROGRESS_EVENT: str = "omni.kit.window.status_bar@progress"

omni.kit.app.register_event_alias(PROGRESS_EVENT, GLOBAL_PROGRESS_EVENT)

Warning

The event alias must be registered before any of the involved events are dispatched!

Warning

It is also important that subscribers to the old event must now be by type, not generic subscriptions. In other words, they must use create_subscription_to_pop_by_type() instead of create_subscription_to_pop().

Otherwise using the Events 2.0 version of the Message Bus follows the guidelines from Message Events.

Using IEventsAdapter to convert event streams#

IEventsAdapter is used to generate implementations of IEventStream that function in an Events 2.0 manner.

Several different types of adapters can be created based on how IEventStream is used:

  • eDispatch - Simple dispatch-only adapter, to replace IEventStream that only did dispatch() and supported only pop-side subscribers.

  • ePushPump - The most common adapter, replaces IEventStream that did push() immediately followed by pump(), supporting both push- and pop-side subscribers.

  • eFull - To replace IEventStream instances that used the queue functionality.

  • eFullAlias - Specifically for Message Bus functionality. Instead of providing a mapping, aliases must be used to map Events 1.0 to 2.0.

Constructing an IEventsAdapter requires passing a descriptor and usually requires a mapping of Events 1.0 integral events to Events 2.0 event names. See the documentation for more information.

Conversion Guide#

This intends to serve as a conversion guide for old event streams to their Events 2.0 counterparts. Ideally one can search this guide for the old event stream function to get the name of the new event to use.

Note that the Legacy Event and New Event Name are constants typically within the same namespace (or, for Python, within the same module). Strings are indicated by "<event name>".

In some cases, the New Event shows [Immediate] or [_IMMEDIATE] to indicate that a variation is available for an immediate event. For Legacy Event Streams that would defer events until the IEventStream was later pumped, subscribers could be created to either the push-side of the stream or the pop-side. The new terminology is immediate and deferred. The push-side of the legacy event stream corresponds to the immediate event and is selected by using the Immediate/_IMMEDIATE suffix constant name. The pop-side of the legacy event stream corresponds to the deferred event. Since the deferred events are generally recommended, their constants do not have a suffix.

Conversion Examples#

Use the tab to select C++ or Python examples.

See detailed conversion documentation above.

Say you are converting code that used omni::kit::IApp::getUpdateEventStream(). Looking at the table below you see this record:

Legacy Event Stream

Legacy EventType

New Event Constant/Name

Notes

…

omni::kit::IApp::getUpdateEventStream

0

kGlobalEventUpdate (default RunLoop only)

For non default RunLoops use event name "runloop:<name>:update"

…

Your old code looks something like this:

auto app = carb::getFramework()->acquireInterface<omni::kit::IApp>();
m_updateEvtSub = carb::events::createSubscriptionToPop(
    app->getUpdateEventStream("rendering_0"),
    [this](carb::events::IEvents* e) {
        _update(carb::dictionary::getCachedDictionaryInterface()->get<float>(e->payload, "dt"));
    },
    carb::events::kDefaultOrder, "My update");

The EventType for the getUpdateEventStream() stream is always 0, hence it being listed in the table. Some event streams had different EventType values and code could use createSubscriptionToPopByType() to listen for them specifically.

The other thing we notice is that our table says (default RunLoop only) for the event constant and the Notes column gives a directive about non-default RunLoops. Our code above is using a specific (non-default) RunLoop: "rendering_0", so we will need to craft our event name. We also no longer need IApp since IEventDispatcher is global.

static carb::RString eventName("runloop:rendering_0:update"); // crafted based on the Note in the table
static carb::RStringKey kDt("dt");
m_updateObserver = carb::getCachedInterface<carb::eventdispatcher::IEventDispatcher>()->observeEvent(
    carb::RStringKey("My update"),
    carb::eventdispatcher::kDefaultOrder,
    eventName,
    [this](const carb::eventdispatcher::Event& e) {
        _update(e.getValueOr<float>(kDt, 0.f));
    }
);

See detailed conversion documentation above.

Say you are converting code that used omni.kit.app.IApp.get_update_event_stream(). Looking at the table below you see this record:

Legacy Event Stream

Legacy EventType

New Event Constant/Name

Notes

…

omni.kit.app.IApp.get_update_event_stream

0

GLOBAL_EVENT_UPDATE (default RunLoop only)

For non default RunLoops use event name "runloop:<name>:update"

…

Your old code looks something like this:

def _on_event(self, e: carb.events.IEvent):
    dt = e.payload['dt']
    _update(dt)

def __init__(self):
    self._event_sub = omni.kit.app.get_app().get_update_event_stream("rendering_0").create_subscription_to_pop(
        self._on_event,
        name="Menu update"
    )

The EventType for the get_update_event_stream() stream is always 0, hence it being listed in the table. Some event streams had different EventType values and code could use create_subscription_to_pop_by_type() to listen for them specifically.

The other thing we notice is that our table says (default RunLoop only) for the event constant and the Notes column gives a directive about non-default RunLoops. Our code above is using a specific (non-default) RunLoop: "rendering_0", so we will need to craft our event name. We also no longer need IApp since IEventDispatcher is global.

def _on_event(self, e: carb.eventdispatcher.Event):
    _update(e['dt'])

def __init__(self):
    self._event_sub = carb.eventdispatcher.get_eventdispatcher().observe_event(
        observer_name="omni.kit.ui/Menu",
        event_name="runloop:rendering_0:update",
        on_event=_on_event
    )

Kit Kernel (C++)#

Legacy Event Stream

Legacy EventType

New Event Constant/Name

Notes

omni::kit::RunLoop::preUpdate

0

kGlobalEventPreUpdate (default RunLoop only)

For non default RunLoops use event name "runloop:<name>:preUpdate"

omni::kit::RunLoop::update

0

kGlobalEventUpdate (default RunLoop only)

For non default RunLoops use event name "runloop:<name>:update"

omni::kit::RunLoop::postUpdate

0

kGlobalEventPostUpdate (default RunLoop only)

For non default RunLoops use event name "runloop:<name>:postUpdate"

omni::kit::RunLoop::messageBus

See the section on message bus

omni::kit::IApp::getPreUpdateEventStream

0

kGlobalEventPreUpdate (default RunLoop only)

For non default RunLoops use event name "runloop:<name>:preUpdate"

omni::kit::IApp::getUpdateEventStream

0

kGlobalEventUpdate (default RunLoop only)

For non default RunLoops use event name "runloop:<name>:update"

omni::kit::IApp::getPostUpdateEventStream

0

kGlobalEventPostUpdate (default RunLoop only)

For non default RunLoops use event name "runloop:<name>:postUpdate"

omni::kit::IApp::getMessageBusEventStream

See the section on message bus

omni::kit::IApp::getStartupEventStream

kEventAppStarted

kGlobalEventAppStarted

kEventAppReady

kGlobalEventAppReady

omni::kit::IApp::getShutdownEventStream

kPostQuitEventType

kGlobalEventPostQuit

kPreShutdownEventType

kGlobalEventPreShutdown

omni::kit::IApp::getLogEventStream

0

kGlobalEventErrorLog[Immediate]

omni::kit::IAppScripting::getEventStream

kScriptingEventCommand

kGlobalEventScriptingCommand[Immediate]

kScriptingEventStdOut

kGlobalEventScriptingStdOut[Immediate]

kScriptingEventStdErr

kGlobalEventScriptingStdErr[Immediate]

omni::ext::IExtensions::getChangeEventStream

kEventScriptChanged

kGlobalEventScriptChanged[Immediate]

kEventFolderChanged

kGlobalEventFolderChanged[Immediate]

Legacy Event Stream

Legacy EventType

New Event Constant/Name

Notes

omni.kit.app.IApp.get_pre_update_event_stream

0

GLOBAL_EVENT_PRE_UPDATE (default RunLoop only)

For non default RunLoops use event name "runloop:<name>:preUpdate"

omni.kit.app.IApp.get_update_event_stream

0

GLOBAL_EVENT_UPDATE (default RunLoop only)

For non default RunLoops use event name "runloop:<name>:update"

omni.kit.app.IApp.get_post_update_event_stream

0

GLOBAL_EVENT_POST_UPDATE (default RunLoop only)

For non default RunLoops use event name "runloop:<name>:postUpdate"

omni.kit.app.IApp.get_message_bus_event_stream

See the section on message bus

omni.kit.app.IApp.get_startup_event_stream

EVENT_APP_STARTED

GLOBAL_EVENT_APP_STARTED

EVENT_APP_READY

GLOBAL_EVENT_APP_READY

omni.kit.app.IApp.get_shutdown_event_stream

POST_QUIT_EVENT_TYPE

GLOBAL_EVENT_POST_QUIT

PRE_SHUTDOWN_EVENT_TYPE

GLOBAL_EVENT_PRE_SHUTDOWN

omni.kit.app.IApp.get_log_event_stream

0

GLOBAL_EVENT_ERROR_LOG[_IMMEDIATE]

omni.kit.app.IAppScripting.get_event_stream

APP_SCRIPTING_EVENT_COMMAND

GLOBAL_EVENT_SCRIPT_COMMAND[_IMMEDIATE]

APP_SCRIPTING_EVENT_STDOUT

GLOBAL_EVENT_SCRIPT_STDOUT[_IMMEDIATE]

APP_SCRIPTING_EVENT_STDERR

GLOBAL_EVENT_SCRIPT_STDERR[_IMMEDIATE]

omni.ext.ExtensionManager.get_change_event_stream

EXTENSION_EVENT_SCRIPT_CHANGED

GLOBAL_EVENT_SCRIPT_CHANGED[_IMMEDIATE]

EXTENSION_EVENT_FOLDER_CHANGED

GLOBAL_EVENT_FOLDER_CHANGED[_IMMEDIATE]

omni.appwindow#

See primary documentation.

C++ objects are under the omni::kit namespace. Python objects are in the omni.appwindow module.

Legacy Event Stream

Legacy EventType

New Event Constant/Name

Notes

IAppWindowFactory::getWindowCreationEventStream()

kEventTypeWindowCreated

kGlobalEventFactoryWindowCreated[Immediate]

kEventTypeWindowDestroyed

kGlobalEventFactoryWindowDestroyed[Immediate]

kEventTypeWindowStartup

kGlobalEventFactoryWindowStartup[Immediate]

kEventTypeWindowShutdown

kGlobalEventFactoryWindowShutdown[Immediate]

IAppWindow::getWindowResizeEventStream()

0

kGlobalEventWindowResize[Immediate]

Use IAppWindow::getEventKey() filter

IAppWindow::getWindowMoveEventStream()

0

kGlobalEventWindowMove[Immediate]

Use IAppWindow::getEventKey() filter

IAppWindow::getWindowContentScaleEventStream()

0

kGlobalEventWindowContentScale[Immediate]

Use IAppWindow::getEventKey() filter

IAppWindow::getWindowDropEventStream()

0

kGlobalEventWindowDrop[Immediate]

Use IAppWindow::getEventKey() filter

IAppWindow::getWindowFocusEventStream()

0

kGlobalEventWindowFocus[Immediate]

Use IAppWindow::getEventKey() filter

IAppWindow::getWindowMinimizeEventStream()

0

kGlobalEventWindowMinimize[Immediate]

Use IAppWindow::getEventKey() filter

IAppWindow::getWindowCloseEventStream()

0

kGlobalEventWindowClose

Use IAppWindow::getEventKey() filter

Legacy Event Stream

Legacy EventType

New Event Constant/Name

Notes

IAppWindow.get_window_resize_event_stream()

0

GLOBAL_EVENT_WINDOW_RESIZE[_IMMEDIATE]

Use IAppWindow.get_event_key() filter

IAppWindow.get_window_move_event_stream()

0

GLOBAL_EVENT_WINDOW_MOVE[_IMMEDIATE]

Use IAppWindow.get_event_key() filter

IAppWindow.get_window_content_scale_event_stream()

0

GLOBAL_EVENT_WINDOW_CONTENT_SCALE[_IMMEDIATE]

Use IAppWindow.get_event_key() filter

IAppWindow.get_window_drop_event_stream()

0

GLOBAL_EVENT_WINDOW_DROP[_IMMEDIATE]

Use IAppWindow.get_event_key() filter

IAppWindow.get_window_focus_event_stream()

0

GLOBAL_EVENT_WINDOW_FOCUS[_IMMEDIATE]

Use IAppWindow.get_event_key() filter

IAppWindow.get_window_minimize_event_stream()

0

GLOBAL_EVENT_WINDOW_MINIMIZE[_IMMEDIATE]

Use IAppWindow.get_event_key() filter

IAppWindow.get_window_close_event_stream()

0

GLOBAL_EVENT_WINDOW_CLOSE

Use IAppWindow.get_event_key() filter

omni.kit.renderer.core#

See primary documentation.

C++ objects are under the omni::kit::renderer namespace. Python objects are in the omni.kit.renderer.bind module.

Legacy Event Stream

Legacy EventType

New Event Constant/Name

Notes

IRenderer::getPreBeginFrameEventStream

0

getRendererEventName(RendererEventType::ePreBeginFrame)

Requires IAppWindow*

IRenderer::getPreBeginRenderPassEventStream

0

getRendererEventName(RendererEventType::ePreBeginRenderPass)

Requires IAppWindow*

IRenderer::getRenderFrameEventStream

0

getRendererEventName(RendererEventType::eRenderFrame)

Requires IAppWindow*

IRenderer::getPostEndRenderPassEventStream

0

getRendererEventName(RendererEventType::ePostEndRenderPass)

Requires IAppWindow*

IRenderer::getPostEndRenderFrameEventStream

0

getRendererEventName(RendererEventType::ePostEndRenderFrame)

Requires IAppWindow*

IRenderer::getPresentRenderFrameEventStream

0

getRendererEventName(RendererEventType::ePresentRenderFrame)

Requires IAppWindow*

IRenderer::getPostPresentFrameBufferEventStream

0

getRendererEventName(RendererEventType::ePostPresentFrameBuffer)

Requires IAppWindow*

Legacy Event Stream

Legacy EventType

New Event Constant/Name

Notes

IRenderer.get_pre_begin_frame_event_stream

0

get_renderer_event_name(RendererEventType.PRE_BEGIN_FRAME)

Requires IAppWindow instance

IRenderer.get_pre_begin_render_pass_event_stream

0

get_renderer_event_name(RendererEventType.PRE_BEGIN_RENDER_PASS)

Requires IAppWindow instance

IRenderer.get_render_frame_event_stream

0

get_renderer_event_name(RendererEventType.RENDER_FRAME)

Requires IAppWindow instance

IRenderer.get_post_end_render_pass_event_stream

0

get_renderer_event_name(RendererEventType.POST_END_RENDER_PASS)

Requires IAppWindow instance

IRenderer.get_post_end_render_frame_event_stream

0

get_renderer_event_name(RendererEventType.POST_END_RENDER_FRAME)

Requires IAppWindow instance

IRenderer.get_present_render_frame_event_stream

0

get_renderer_event_name(RendererEventType.PRESENT_RENDER_FRAME)

Requires IAppWindow instance

IRenderer.get_post_present_frame_buffer_event_stream

0

get_renderer_event_name(RendererEventType.POST_PRESENT_FRAME_BUFFER)

Requires IAppWindow instance

omni.timeline#

See primary documentation.

C++ objects are under the omni::timeline namespace. Python objects are in the omni.timeline module.

Legacy Event Stream

Legacy EventType

New Event Constant/Name

Notes

Timeline::getTimelineEventStream()

TimelineEventType enum

kGlobalEvent-prefix with similar suffix to enum name

TimelineEventType::eCurrentTimeChanged

NONE

Deprecated event, no longer dispatched.

TimelineEventType::eFastModeChanged

kGlobalEventPlayEveryFrameChanged

eFastModeChanged is an old name for `ePlayEveryFrameChanged

Legacy Event Stream

Legacy EventType

New Event Constant/Name

Notes

Timeline::get_timeline_event_stream()

TimelineEventType enum

GLOBAL_EVENT_-prefix with similar suffix to enum name

TimelineEventType.CURRENT_TIME_CHANGED

NONE

Deprecated event, no longer dispatched.

TimelineEventType.FAST_MODE_CHANGED

GLOBAL_EVENT_PLAY_EVERY_FRAME_CHANGED

FAST_MODE_CHANGED is an old name for PLAY_EVERY_FRAME_CHANGED

omni.usd#

See primary documentation.

C++ objects are under the omni::usd namespace. Python objects are in the omni.usd module.

Legacy Event Stream

Legacy EventType

New Event Constant/Name

Notes

UsdContext::getStageEventStream()

StageEventType enum

Pass StageEventType enumerator to UsdContext::stageEventName()

Event names have the context name encoded within them.

UsdContext::getRenderingEventStream()

StageRenderingEventType enum

Pass StageRenderingEventType enumerator to UsdContext::stageRenderingEventName()

Event names have the context name encoded within them.

Legacy Event Stream

Legacy EventType

New Event Constant/Name

Notes

UsdContext.get_stage_event_stream()

StageEventType enum

Pass StageEventType enumerator to UsdContext.stage_event_name()

Event names have the context name encoded within them.

UsdContext.get_rendering_event_stream()

StageRenderingEventType enum

Pass StageRenderingEventType enumerator to UsdContext.stage_rendering_event_name()

Event names have the context name encoded within them.