omni.kit.hydra_texture Event Reference#

All omni.kit.hydra_texture events are global events that can be observed using the carb::eventdispatcher::IEventDispatcher. These events are dispatched when significant changes occur to a IHydraTexture instance.

Since all events exist in a global namespace, HydraTexture event descriptors are composed as the following string:

omni.kit.hydra_texture:<event name>

The string <event name> is listed below for each event type.

For ease of generating the event names for use with carb::eventdispatcher::IEventDispatcher, there exist constants in both C++ and Python that can be used directly.

Warning

HydraTexture events have a global name, but typically listeners care about a specific HydraTexture instance. Therefore it is very important to specify a filter when observing an event, otherwise your observer will be called for all HydraTexture instances. IHydraTexture::getEventKey() (C++) and IHydraTexture.get_event_key() (Python) helper functions exist to provide easy means to filter these events.

HydraTexture Events#

The following events are available for observation:

Drawable Changed#

Sent when a new rendered frame is available for display.

  • C++ Constant: omni::hydratexture::kGlobalEventDrawableChanged

  • Python Constant: omni.hydratexture.GLOBAL_EVENT_DRAWABLE_CHANGED

  • String event name: omni.kit.hydra_texture:drawable_changed

Arguments:

  • handle (uintptr) - The IHydraTexture instance pointer, typically used as an event key.

  • viewport_handle (int) - The viewport handle identifier.

  • result_handle (uintptr) - Pointer to the render results (omni::usd::hydra::ViewportHydraRenderResults). WARNING: the pointer may only be dereferenced immediately in the observer function. Do not cache the pointer value and attempt to access it later.

  • resolution_x (uint) - The width of the rendered frame in pixels.

  • resolution_y (uint) - The height of the rendered frame in pixels.

  • format (int) - The format of the rendered texture (NOTE: currently always carb::graphics::Format::eRGBA8_UNORM).

  • presentation_key (uint, optional) - Presentation key for the frame. Absent if not available.

Hydra Engine Changed#

Sent when the Hydra rendering engine is changed for a viewport.

  • C++ Constant: omni::hydratexture::kGlobalEventHydraEngineChanged

  • Python Constant: omni.hydratexture.GLOBAL_EVENT_HYDRA_ENGINE_CHANGED

  • String event name: omni.kit.hydra_texture:hydra_engine_changed

Arguments:

  • handle (uintptr) - The IHydraTexture instance pointer, typically used as an event key.

  • viewport_handle (int) - The viewport handle identifier.

  • hydra_engine_name (string) - The name of the new Hydra engine (e.g., “rtx”, “iray”, “pxr”).

Render Settings Changed#

Sent when render settings such as camera, resolution, or engine settings are modified.

  • C++ Constant: omni::hydratexture::kGlobalEventRenderSettingsChanged

  • Python Constant: omni.hydratexture.GLOBAL_EVENT_RENDER_SETTINGS_CHANGED

  • String event name: omni.kit.hydra_texture:render_settings_changed

Arguments:

  • handle (uintptr) - The IHydraTexture instance pointer, typically used as an event key.

  • viewport_handle (int) - The viewport handle identifier.

  • resolution_x (uint) - The new width of the viewport in pixels.

  • resolution_y (uint) - The new height of the viewport in pixels.

  • camera_path (string) - The path to the camera being used for rendering.

  • hd_engine_name (string) - The name of the Hydra engine currently in use.

Usage Examples#

C++ Example#

#include <carb/eventdispatcher/IEventDispatcher.h>
#include <omni/hydratexture/IHydraTexture.h>

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

// Subscribe to drawable changed events
auto subscription = dispatcher->observeEvent(
    carb::RStringKey("My observer name for debugging/profiling"),
    carb::eventdispatcher::kDefaultOrder,
    omni::hydratexture::kGlobalEventDrawableChanged,
    [](const carb::eventdispatcher::Event& event) {
        auto viewportHandle = event.getValueOr<int>("viewport_handle", -1);
        auto resultHandle = event.getValueOr<uintptr_t>("result_handle", 0);
        auto resolutionX = event.getValueOr<unsigned>("resolution_x", 0);
        auto resolutionY = event.getValueOr<unsigned>("resolution_y", 0);
        
        // Handle the new drawable...
    },
    pHydraTexture->getEventKey() // very important to specify this for filtering
);

Python Example#

import carb.eventdispatcher
import omni.hydratexture

def on_drawable_changed(event):
    viewport_handle = event.get("viewport_handle", -1)
    result_handle = event.get("result_handle", 0)
    resolution_x = event.get("resolution_x", 0)
    resolution_y = event.get("resolution_y", 0)
    presentation_key = event.get("presentation_key", 0)
    
    # Handle the new drawable...

# Subscribe to drawable changed events
subscription = carb.eventdispatcher.get_eventdispatcher().observe_event(
    observer_name="My observer name for debugging/profiling",
    event_name=omni.hydratexture.GLOBAL_EVENT_DRAWABLE_CHANGED,
    filter=hydra_texture.get_event_key(), # very important to specify this for filtering
    on_event=on_drawable_changed
)

Legacy Events#

Previously, each event type was sent through a separate Event Stream via IHydraTexture::getEventStream(). While still currently supported, this is now deprecated in favor of the global events described above.

Converting from Legacy Events#

Old C++:

auto eventStream = hydraTexture->getEventStream();
auto subscription = carb::events::createSubscriptionToPushByType(
    eventStream,
    omni::hydratexture::kEventTypeDrawableChanged,
    [this](carb::events::IEvents* event) { this->onDrawableChanged(event); },
    carb::events::kDefaultOrder,
    "My subscription name"
);

New C++:

auto dispatcher = carb::getCachedInterface<carb::eventdispatcher::IEventDispatcher>();
auto subscription = dispatcher->observeEvent(
    carb::RStringKey("My observer name"),
    carb::eventdispatcher::kDefaultOrder,
    omni::hydratexture::kGlobalEventDrawableChanged,
    [this](const carb::eventdispatcher::Event& event) { this->onDrawableChanged(event); },
    pHydraTexture->getEventKey() // very important to specify this for filtering
);

Old Python:

event_stream = hydra_texture.get_event_stream()
subscription = event_stream.create_subscription_to_push_by_type(
    omni.hydratexture.EVENT_TYPE_DRAWABLE_CHANGED,
    on_event,
    carb.events.DEFAULT_ORDER,
    "My subscription name"
)

New Python:

subscription = carb.eventdispatcher.get_eventdispatcher().observe_event(
    observer_name="My observer name",
    event_name=omni.hydratexture.GLOBAL_EVENT_DRAWABLE_CHANGED,
    filter=hydra_texture.get_event_key(), # very important to specify this for filtering
    on_event=on_event
)

Event Filtering#

All global events include an event key that can be used for filtering. The event key is specific to each HydraTexture instance and can be obtained using IHydraTexture::getEventKey() in C++ or IHydraTexture.get_event_key() in Python.

If a filter key is not specified, your observer will receive events about all IHydraTexture instances.

// Filter events for a specific HydraTexture instance
auto subscription = dispatcher->observeEvent(
    carb::RStringKey("My observer name"),
    carb::eventdispatcher::kDefaultOrder,
    omni::hydratexture::kGlobalEventDrawableChanged,
    [](const carb::eventdispatcher::Event& event) { /* handle event */ },
    hydraTexture->getEventKey()  // Filter by specific texture
);

# Filter events for a specific HydraTexture instance
subscription = carb.eventdispatcher.get_eventdispatcher().observe_event(
    observer_name="My observer name",
    event_name=omni.hydratexture.GLOBAL_EVENT_DRAWABLE_CHANGED,
    on_event=on_event,
    filter=hydra_texture.get_event_key()  # Filter by specific texture
)